W3 MCP LSP Server
Python MCP server wrapping TypeScript Language Server for JavaScript/TypeScript code intelligence.
Status: ✅ Working with real LSP protocol (not mock)
Features
- lsp_goto_definition - Jump to symbol definition location
- lsp_hover - Get type information and documentation
- lsp_find_references - Find all references/usages of symbol
Supports JavaScript and TypeScript files via TypeScript Language Server.
Quick Start
1. Clean Setup (Important!)
cd /path/to/w3-mcp-server-lsp
# Remove old lockfile and venv
rm -rf uv.lock .venv venv
# Unset old environment variable
unset VIRTUAL_ENV
2. Install Dependencies
# Install TypeScript Language Server
npm install -g typescript typescript-language-server
# Install Python dependencies (using uv)
uv sync
# Install MCP CLI dependencies
uv pip install 'mcp[cli]'
3. Verify Installation
# Check typescript-language-server
which typescript-language-server
typescript-language-server --version
# Check Python env
uv run python -c "from mcp.server.fastmcp import FastMCP; print('✓ MCP ready')"
4. Test with MCP Inspector
# Start MCP Inspector (interactive web UI)
uv run mcp dev server.py
Opens URL like:
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=...
Features:
- ✅ Available tools listed in sidebar
- ✅ Test each tool interactively with JSON input
- ✅ Real-time request/response viewing
- ✅ Server logs and debugging
- ✅ No extra dependencies needed
Usage
Option A: MCP Inspector (Development)
Best way to test and debug:
cd /path/to/w3-mcp-server-lsp
# Start inspector
uv run mcp dev server.py
Opens web UI at http://localhost:5173:
- See available tools
- Test each tool with JSON input
- View request/response in real-time
- See server logs
Option B: Direct Python
# Run server (stdio mode)
uv run python server.py
Option C: Claude Code Integration
Method 1: From PyPI (Recommended)
Install from PyPI:
pip install w3-mcp-server-lsp
# or
uv pip install w3-mcp-server-lsp
Edit ~/.claude/claude_config.json or ~/.mcp.json:
{
"mcpServers": {
"w3-lsp": {
"type": "stdio",
"command": "uv",
"args": ["run", "--with", "w3-mcp-server-lsp", "w3-mcp-server-lsp"],
"env": {
"PROJECT_ROOT": "/path/to/your/project"
}
}
}
}
Advantages:
- ✅ No need to clone the repo
- ✅ Easy version management
- ✅ Automatic dependency isolation
Method 2: From Local Source
Edit ~/.claude/claude_config.json:
{
"mcpServers": {
"w3-lsp": {
"type": "stdio",
"command": "uv",
"args": ["run", "server.py"],
"cwd": "/path/to/w3-mcp-server-lsp",
"env": {
"PROJECT_ROOT": "/path/to/your/project"
}
}
}
}
Then restart Claude Code.
Tools Documentation
⚠️ IMPORTANT: 0-Indexed Line and Character Numbers
All tools use 0-indexed positioning (start from 0, not 1):
| Editor Display | Tool Input | Formula |
|---|---|---|
| Ln 5, Col 10 | line: 4 | lsp_value = editor_value - 1 |
| Ln 1, Col 1 | line: 0 | character: 0 |
| Ln 10, Col 5 | line: 9 | character: 4 |
Quick Reference:
- Line 1 in editor =
line: 0in tool - Column 1 in editor =
character: 0in tool
How to Calculate Character Position:
Given this code line:
const greeting = "Hello";
0123456789...
- Position at
cinconst→character: 0 - Position at
oinconst→character: 1 - Position at
gingreeting→character: 6 - Position at
Hin"Hello"→character: 18
In VSCode:
- Click on a character
- Look at status bar:
Ln X, Col Y - Use:
line: X-1, character: Y-1
lsp_goto_definition
Jump to definition of symbol at specified position.
Input:
{
"file_path": "fixtures/sample.js",
"line": 4,
"character": 9
}
Output:
/path/to/fixtures/sample.js:5:9
lsp_hover
Get type information and documentation for symbol.
Input:
{
"file_path": "fixtures/sample.js",
"line": 5,
"character": 10
}
Output:
(parameter) a: any
lsp_find_references
Find all references/usages of symbol.
Input:
{
"file_path": "fixtures/sample.js",
"line": 4,
"character": 9
}
Output:
Found 2 references:
/path/to/fixtures/sample.js:5:9
/path/to/fixtures/sample.js:14:22
Configuration
PROJECT_ROOT
Specifies the root directory of your project. Files paths in tool calls are relative to this.
Set via:
-
Environment variable:
export PROJECT_ROOT="/path/to/your/project" uv run python server.py
-
Current directory (default):
cd /path/to/your/project uv run python /path/to/w3-mcp-server-lsp/server.py
-
In .claude/settings.json:
"env": { "PROJECT_ROOT": "/path/to/your/project" }
Line and Character Numbers (0-indexed)
LSP uses 0-indexed positions:
- VSCode shows:
Ln 5, Col 10 - LSP needs:
line: 4, character: 9
Formula: lsp_value = vscode_value - 1
Project Structure
w3-mcp-server-lsp/
├── server.py # MCP server entry point
├── lsp_client.py # LSP protocol implementation
├── pyproject.toml # Project config
├── fixtures/
│ └── sample.js # Sample file for testing
├── test_mcp_server.py # Integration test
├── test_lsp_debug.py # Debug test with logging
└── README.md
How It Works
Architecture
MCP Client (Claude, IDE, etc.)
↓
MCP Server (server.py)
↓
LSP Client (lsp_client.py)
↓
TypeScript Language Server (subprocess)
LSP Protocol Flow
-
Initialization
- Send:
initializerequest - Receive: server capabilities
- Send:
initializednotification
- Send:
-
Document Opening
- Send:
textDocument/didOpennotification - Content provided inline
- Send:
-
Queries
- Send:
textDocument/definition,textDocument/hover, etc. - Receive: results from language server
- Send:
-
Details
- Communication: JSON-RPC over stdin/stdout
- Binary mode: Avoids text encoding issues
- Notification handling: Skip server notifications, match message IDs
Testing
Interactive Testing (Recommended)
uv run mcp dev server.py
Web UI opens at http://localhost:5173:
- Test tools visually
- See real-time results
- View server logs
Direct Server
uv run python server.py
Runs in stdio mode, ready to connect from Claude Code or other MCP clients.
Troubleshooting
TypeScript Language Server not found
# Install
npm install -g typescript typescript-language-server
# Verify
which typescript-language-server
MCP module not found
# Install dependencies
pip install -e .
# Or manually
pip install mcp pydantic
Server hangs on startup
- Check if TypeScript Language Server is installed
- Check terminal for error messages
- Try:
typescript-language-server --stdiodirectly
Tool returns None or error
- Verify file path is relative to PROJECT_ROOT
- Check line/character numbers are 0-indexed
- Check server logs output in terminal
- Use MCP Inspector (
uv run mcp dev server.py) to see requests/responses
Future Enhancements
- Go support (gopls language server)
- Python support (pylsp/pyright)
- Multiple language servers in single MCP server
- Caching of responses
- Batch operations
Development
Testing with MCP Inspector
uv run mcp dev server.py
Web UI at http://localhost:5173 shows:
- Available tools and schemas
- Real-time request/response
- Server logs
- Interactive testing
Running Directly
uv run python server.py
For debugging, check logs output in terminal.
References
License
MIT
Metadata
Release files for w3-mcp-server-lsp 0.1.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| w3_mcp_server_lsp-0.1.5.tar.gz | 12.8 kB | Without provenance | Details for w3_mcp_server_lsp-0.1.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| w3_mcp_server_lsp-0.1.5-py3-none-any.whl | Python 3 | none | any | Details for w3_mcp_server_lsp-0.1.5-py3-none-any.whl |
Total release size: 23.6 kB
Release files / w3_mcp_server_lsp-0.1.5.tar.gz
| Download URL | w3_mcp_server_lsp-0.1.5.tar.gz |
|---|---|
| Size | 12.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bbab81245cfa8291a0ba93b12e0c977ac00223cf24df1dd89fdfb503d4d03906
|
|
BLAKE2b-256 checksum How to use checksums |
1b8d9b89fcae695cc723c0d7e57915d7bfa5c42b852e7b8b90918e466da4f5d6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.1
|
Release files / w3_mcp_server_lsp-0.1.5-py3-none-any.whl
| Download URL | w3_mcp_server_lsp-0.1.5-py3-none-any.whl |
|---|---|
| Size | 10.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1f751a69a2f7bf3f46607162ae5dd7901959118a553a6da0a6a380dd1bfc9493
|
|
BLAKE2b-256 checksum How to use checksums |
00cf871112e6b598ec7ce41f9838ae7f695c17e3ca2e5c70849405f4738bb724
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.1
|
Security for w3-mcp-server-lsp 0.1.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.