# VSC-MCP

This project provides tools that expose Language Server Protocol (LSP) functionality as **MCP (Model Context Protocol)** tools. It enables AI clients to programmatically analyze and edit code through standardized MCP tool calls.

It started as a simple project focused on coding only with TypeScript, then evolved to a full-featured MCP server that supports any language supported by VS Code.

Full details about latest changes and migration to headless VC Code can be found [here](https://thomasgazzoni.com/coding/enhance-vsc-mcp-capabilities-with-headless-vscode-part-three/)

## Docker Mode & VS Code LSP Integration

VSC-MCP can run in two modes:
- **Standalone Mode**: It spawn a local [typescript-language-server](https://github.com/typescript-language-server/typescript-language-server) to provide LSP support ONLY for TypeScript/JavaScript.
- **Docker Mode**: Leverages a headless VS Code port by Gitpod, namely [OpenVSCode Server](https://github.com/gitpod-io/openvscode-server), running in Docker to provide richer LSP support, for any languages supported by VC Code like Rust, Go, C#, Python, etc.

### Why Docker Mode?
- **Unified LSP**: Avoids the hassle of launching separate local language servers for each language.
- **Rich Extension Ecosystem**: Inherits VS Code's extension support and APIs for advanced language features.
- **Live Editing**: Open http://localhost:3000 to watch edits in real time as your AI agent interacts with MCP.
- **Works without IDE**: we can write and analyze code without opening any IDE.

### How It Works
1. **OpenVSCode Server** runs inside Docker, exposing port `3000` (IDE UI) and `5007` (LSP bridge).
2. Required VS Code extensions are pre-installed (e.g., _rust-analyzer_, _pyright_, _eslint_, and the VSC-MCP extension).
3. The **VSC-MCP extension** creates a WebSocket channel between MCP and the VS Code back-end.
4. File I/O tools use direct access; LSP tools use VS Code's internal language servers.

## Installation

### Prerequisites
- [Docker](https://www.docker.com/) (for running the VS Code server)
- [Bun](https://bun.sh/) (for launching MCP)

### Setup
1. **Clone the repository** and `cd` into it.
2. **Install dependencies**
   ```bash
   bun install
   ```
3. **Build and start OpenVSCode Server** (mount your project into the container)
   ```bash
   PROJECT_PATH=/path/to/your/project docker-compose up
   ```
4. **Register MCP in your AI client** (example `settings.json`)
   ```json
   {
     "mcpServers": {
       "vsc-mcp": {
         "command": "bun",
         "args": ["<vsc_mcp_cloned_dir>/src/index.ts"],
         "env": {
           "USE_VSCODE_LSP": "true",
           "LOG_DIR": "<vsc_mcp_cloned_dir>/logs",
           "ALLOWED_DIRECTORIES": "/path/to/your/project"
         }
       }
     }
   }
   ```

#### Environment Variables
| Variable              | Purpose                                                                                                  |
| --------------------- | -------------------------------------------------------------------------------------------------------- |
| `USE_VSCODE_LSP`      | **Set to `true` to enable Docker/VS Code LSP mode.** MCP will forward LSP requests to VS Code (port 5007) instead of spawning a local language server. |
| `ALLOWED_DIRECTORIES` | Restricts direct-file manipulation to the specified directories.                                         |
| `LOG_DIR`             | Where MCP writes logs for debugging.                                                                     |

> **Note:** By default, `USE_VSCODE_LSP` is `false` (standalone mode). Set it to `true` to use Docker/VS Code LSP integration.

## Suggested AI Client Configurations

### Claude Desktop

For now the best workflow is to use Claude Desktop as AI Client, it support MCP servers and it provide a monthly plan for 20$/month, and by using the VSC-MCP tools, we can "chat" and work with our codebase.

- On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- On Windows: `%APPDATA%/Claude/claude_desktop_config.json`

Add the following configurations to the `mcp_servers` section of the config file:

```json
{
  "mcpServers": {
    "repomix": {
      "command": "npx",
      "args": [
        "-y",
        "repomix",
        "--mcp"
      ]
    },
    "vsc-mcp": {
      "command": "bun",
      "args": [
        "<vsc_mcp_cloned_dir>/src/index.ts"
      ],
      "env": {
        "USE_VSCODE_LSP": "true",
        "LOG_DIR": "<vsc_mcp_cloned_dir>/logs",
        "ALLOWED_DIRECTORIES": "/path/to/your/project"
      }
    }
  }
}
```

We suggest to add the `repomix` mcp server dependency, to know why, you can read [this blog post](https://thomasgazzoni.com/coding/use-vsc-mcp-to-add-new-tools-part-two/).

Replace `<vsc_mcp_cloned_dir>` with the actual path to your vsc-mcp cloned directory.

## Security Features

### Docker Workspace Restriction

When we start docker we need to specify the workspace directory.
```bash
PROJECT_PATH=/path/to/your/project docker-compose up
```

VSC-MCP tools will only be able to access files in the workspace directory.

### Path Restriction

The VSC-MCP tools include a security feature to restrict OS file operations (read and write files on disk) to specific directories:

- **ALLOWED_DIRECTORIES**: An environment variable that specifies a comma-separated list of directories where file operations are permitted.
  
  Example:
  ```
  ALLOWED_DIRECTORIES=/home/user/projects,/tmp/workspace
  ```

- If this environment variable is not set, operations default to the current working directory only.
- All file operations (read, write, edit) will check if the target path is within the allowed directories.
- Attempting to access files outside allowed directories will result in an "Access denied" error.

This feature helps prevent unauthorized access to sensitive files and directories on the system.

## Available Tools

Currently, the following tools are available:

- `edit_symbol`: Edits a symbol (function, class, method, etc.) by name and type in a given file using LSP.
  - Supports various symbol types: function, method, class, interface, variable, constant, property, field
  - Uses LSP's workspace/symbol and textDocument/documentSymbol requests to find symbols
  - Applies edits directly to files

- `read_symbol`: Reads a symbol (function, class, method, etc.) by name and type in a given file using LSP.
  - Supports the same symbol types as editSymbol
  - Uses LSP to locate the symbol and extract its content
  - Returns the symbol content along with its location information

- `read_file`: Reads the content of a file.
  - Returns the file content with appropriate MIME type based on file extension
  - Handles various file formats including code, text, and configuration files
  - Provides detailed error messages for common issues (file not found, directory access, etc.)

- `write_file`: Creates a new file or overwrites an existing file with the provided content.
  - Creates parent directories if they don't exist
  - Supports any file type
  - Returns information about the file operation (created/overwritten, file size)

- `search_replace_file`: Searches for content in a file and replaces it with new content.
  - Ignores whitespace differences when searching (spaces, tabs, newlines)
  - Supports flexible matching of content patterns
  - Returns the number of replacements made
  
- `get_errors`: Fetches code errors and issues for a specific file using the LSP textDocument/diagnostic API.
  - Provides detailed diagnostics including error messages, severity, and location
  - Uses the VS Code extension's diagnostics api to validate code
  - Returns structured information about code issues

- `find_references`: Finds all references to a symbol (function, class, etc.) by name and type in a given file using LSP.
  - Supports various symbol types: function, method, class, interface, variable, constant, property, field
  - Uses LSP's textDocument/reference API to find all references to a symbol
  - Returns a list of references with file paths and positions
  - Helps with code analysis, refactoring, and understanding code usage