# 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