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: 0 in tool
• Column 1 in editor = character: 0 in tool

How to Calculate Character Position:

Given this code line:

const greeting = "Hello";
0123456789...

• Position at c in const → character: 0
• Position at o in const → character: 1
• Position at g in greeting → character: 6
• Position at H in "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:

1. Environment variable:

   export PROJECT_ROOT="/path/to/your/project"
   uv run python server.py
   

2. Current directory (default):

   cd /path/to/your/project
   uv run python /path/to/w3-mcp-server-lsp/server.py
   

3. 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

1. Initialization

   • Send: initialize request
   • Receive: server capabilities
   • Send: initialized notification

2. Document Opening

   • Send: textDocument/didOpen notification
   • Content provided inline

3. Queries

   • Send: textDocument/definition, textDocument/hover, etc.
   • Receive: results from language server

4. 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 --stdio directly

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

• Language Server Protocol
• Model Context Protocol
• TypeScript Language Server
• FastMCP

License

MIT