w3-mcp-server-lsp 0.1.0

MCP server wrapping TypeScript Language Server for JavaScript/TypeScript

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

Edit .claude/settings.json:

{
  "mcpServers": {
    "w3-lsp": {
      "command": "uv",
      "args": ["run", "mcp", "dev", "server.py"],
      "cwd": "/path/to/w3-mcp-server-lsp",
      "env": {
        "PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

Then restart Claude Code.

Note: Make sure to run uv pip install 'mcp[cli]' first for the mcp dev command to work.

Tools Documentation

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