README.md•7.18 kB
# VSCode Language Server MCP Extension
Exposes VSCode Language Server Protocol features via MCP (Model Context Protocol) for use with Claude Code.
## Overview
This VSCode extension runs an MCP server that provides access to VSCode's Language Server APIs, enabling Claude Code to:
- Get document symbol outlines
- Find all references to symbols
- Rename symbols with full reference tracking
- Get symbol definitions
- Get hover information (types, docs)
## Features
**MCP Tools Provided:**
- `vscode_ls_get_symbols` - Get complete symbol outline of a file
- `vscode_ls_find_references` - Find all references to a symbol
- `vscode_ls_rename` - Safely rename symbols with reference tracking
- `vscode_ls_get_definition` - Get definition location for a symbol
- `vscode_ls_get_hover` - Get type information and documentation
**Benefits:**
- Language-aware symbol renaming (not just find/replace)
- Cross-file reference tracking
- Type information from TypeScript/JavaScript language server
- Scope-aware analysis
- Battle-tested VSCode rename functionality
## Installation
### Step 1: Install Dependencies
```bash
cd ~/source/vscode-mcp-language-server
npm install
```
### Step 2: Compile TypeScript
```bash
npm run compile
```
### Step 3: Install Extension in VSCode
**Option A: Development Mode**
1. Open this directory in VSCode
2. Press `F5` to launch Extension Development Host
3. The extension will be active in the new window
**Option B: Install Locally**
```bash
npm run package
code --install-extension vscode-mcp-language-server-0.1.0.vsix
```
## Configuration
The extension can be configured in VSCode settings:
```json
{
"vscodeMcpLs.enabled": true,
"vscodeMcpLs.port": 3100,
"vscodeMcpLs.logLevel": "info"
}
```
**Settings:**
- `enabled` - Enable/disable the MCP server
- `port` - Port number for MCP server (default: 3100)
- `logLevel` - Logging level: debug, info, warn, error
## Usage
### Check Extension Status
Use the status bar item (bottom-right) or command palette:
- `VSCode MCP LS: Show Status` - Display current status
- `VSCode MCP LS: Restart Server` - Restart the MCP server
### Connecting from Claude Code
Add to your project's MCP configuration in `~/.claude.json`:
```json
{
"projects": {
"/your/project/path": {
"mcpServers": {
"vscode-language-server": {
"type": "http",
"url": "http://localhost:3100"
}
}
}
}
}
```
Or use the CLI (note: manual configuration is currently required as `claude mcp add` doesn't support custom HTTP servers yet):
```bash
# Test the connection first
curl http://localhost:3100
# Should return: {"name":"vscode-mcp-language-server","version":"0.1.0","status":"running","transport":"http"}
```
### Using with Unminification Plugin
The unminification plugin skills will automatically use these tools when available:
```markdown
# In analyze-minified-symbols skill:
### Step 2: Query VSCode for symbol outline
Use MCP tool:
\`\`\`
mcp__vscode_language_server__vscode_ls_get_symbols({
"uri": "file:///path/to/minified.js"
})
\`\`\`
Returns:
\`\`\`json
{
"symbols": [
{
"name": "Fbr",
"kind": "Variable",
"range": { "start": { "line": 49, "character": 6 }, ... },
"children": []
}
]
}
\`\`\`
```
## MCP Tools Reference
### vscode_ls_get_symbols
Get document symbol outline.
**Parameters:**
```json
{
"uri": "file:///absolute/path/to/file.js"
}
```
**Returns:**
```json
{
"symbols": [
{
"name": "functionName",
"kind": "Function",
"range": { "start": { "line": 10, "character": 0 }, "end": {...} },
"selectionRange": {...},
"children": [...]
}
]
}
```
### vscode_ls_find_references
Find all references to a symbol.
**Parameters:**
```json
{
"uri": "file:///path/to/file.js",
"line": 49,
"character": 6
}
```
**Returns:**
```json
{
"references": [
{
"uri": "file:///path/to/file.js",
"range": { "start": { "line": 49, "character": 6 }, "end": {...} }
}
]
}
```
### vscode_ls_rename
Rename symbol with full reference tracking.
**Parameters:**
```json
{
"uri": "file:///path/to/file.js",
"line": 49,
"character": 6,
"newName": "isWindowsPlatform"
}
```
**Returns:**
```json
{
"success": true,
"changesCount": 15,
"changes": [
{
"uri": "file:///path/to/file.js",
"range": {...},
"newText": "isWindowsPlatform"
}
]
}
```
### vscode_ls_get_definition
Get definition location for a symbol.
**Parameters:**
```json
{
"uri": "file:///path/to/file.js",
"line": 100,
"character": 10
}
```
**Returns:**
```json
{
"definitions": [
{
"uri": "file:///path/to/file.js",
"range": { "start": { "line": 49, "character": 6 }, "end": {...} }
}
]
}
```
### vscode_ls_get_hover
Get type information and documentation.
**Parameters:**
```json
{
"uri": "file:///path/to/file.js",
"line": 100,
"character": 10
}
```
**Returns:**
```json
{
"hover": {
"contents": [
{
"kind": "markdown",
"value": "```typescript\nconst isWindowsPlatform: boolean\n```"
}
],
"range": {...}
}
}
```
## Development
### Build
```bash
npm run compile
```
### Watch Mode
```bash
npm run watch
```
### Debug
1. Open in VSCode
2. Press `F5` to launch Extension Development Host
3. Set breakpoints in source files
4. Extension runs with debugger attached
### Testing
Test the MCP server manually:
```bash
# Start VSCode with extension
# In another terminal, test connection:
wscat -c ws://localhost:3100
# Send test request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}
```
## Architecture
```
VSCode Extension
├── extension.ts # Entry point, activation
├── mcpServer.ts # MCP HTTP server
├── languageServerTools.ts # VSCode API wrappers
└── logger.ts # Logging utility
VSCode Language Server APIs
↓ accessed via vscode.commands.executeCommand
├── vscode.executeDocumentSymbolProvider
├── vscode.executeReferenceProvider
├── vscode.executeDocumentRenameProvider
├── vscode.executeDefinitionProvider
└── vscode.executeHoverProvider
MCP Protocol
↓ exposed via HTTP on port 3100
Claude Code
└── Uses tools via MCP client
```
## Troubleshooting
### Extension Not Starting
Check VSCode Output panel:
1. View → Output
2. Select "VSCode MCP Language Server" from dropdown
3. Check for error messages
### MCP Server Not Responding
1. Check extension is enabled: `vscodeMcpLs.enabled`
2. Check port is not in use: `lsof -i :3100`
3. Restart server: Command Palette → "VSCode MCP LS: Restart Server"
### Symbol Operations Not Working
1. Ensure language server is active (TypeScript/JavaScript files)
2. Check file is saved and indexed
3. Verify file URI format: `file:///absolute/path`
## Future Enhancements
- [ ] Support for more language servers (Python, Go, etc.)
- [ ] Workspace-wide symbol search
- [ ] Code actions and quick fixes
- [ ] Signature help
- [ ] Completion provider access
- [ ] Authentication for MCP connections
## Contributing
Issues and pull requests welcome!
## License
MIT