Metadata-Version: 2.4
Name: w3-mcp-server-lsp
Version: 0.1.1
Summary: MCP server wrapping TypeScript Language Server for JavaScript/TypeScript
Author: W3 Labs
License: MIT
Project-URL: Homepage, https://github.com/famtong8-dev/w3-mcp-server-lsp
Project-URL: Repository, https://github.com/famtong8-dev/w3-mcp-server-lsp
Project-URL: Documentation, https://github.com/famtong8-dev/w3-mcp-server-lsp/blob/main/README.md
Project-URL: Issues, https://github.com/famtong8-dev/w3-mcp-server-lsp/issues
Project-URL: Changelog, https://github.com/famtong8-dev/w3-mcp-server-lsp/releases
Keywords: mcp,lsp,typescript,javascript
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Dynamic: license-file

# 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!)

```bash
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

```bash
# 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

```bash
# 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

```bash
# Start MCP Inspector (interactive web UI)
uv run mcp dev server.py
```

Opens URL like:

```text
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:

```bash
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

```bash
# Run server (stdio mode)
uv run python server.py
```

### Option C: Claude Code Integration

Edit `.claude/settings.json`:

```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:**

```json
{
  "file_path": "fixtures/sample.js",
  "line": 4,
  "character": 9
}
```

**Output:**

```text
/path/to/fixtures/sample.js:5:9
```

---

### lsp_hover

Get type information and documentation for symbol.

**Input:**

```json
{
  "file_path": "fixtures/sample.js",
  "line": 5,
  "character": 10
}
```

**Output:**

```typescript
(parameter) a: any
```

---

### lsp_find_references

Find all references/usages of symbol.

**Input:**

```json
{
  "file_path": "fixtures/sample.js",
  "line": 4,
  "character": 9
}
```

**Output:**

```text
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:**

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

2. **Current directory (default):**

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

3. **In .claude/settings.json:**
   ```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

```text
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

```text
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)

```bash
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

```bash
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

```bash
# Install
npm install -g typescript typescript-language-server

# Verify
which typescript-language-server
```

### MCP module not found

```bash
# 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

```bash
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

```bash
uv run python server.py
```

For debugging, check logs output in terminal.

## References

- [Language Server Protocol](https://microsoft.github.io/language-server-protocol/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [TypeScript Language Server](https://github.com/typescript-language-server/typescript-language-server)
- [FastMCP](https://github.com/anthropics/mcp-fastmcp)

## License

MIT
