VSC-MCP

VSC-MCP

此项目提供了可将语言服务器协议（LSP）功能作为 MCP（Model Context Protocol） 工具公开的工具。它使 AI 客户端能够通过标准化的 MCP 工具调用，以编程方式分析和编辑代码。

项目最初只是一个专注于使用 TypeScript 编码的简单项目，后来发展为功能齐全的 MCP 服务，可支持 VS Code 支持的任何语言。

有关最新变更以及迁移到无头 VC Code 的完整详情，请参阅此处

Docker 模式与 VS Code LSP 集成

VSC-MCP 可以以两种模式运行：

• 独立模式：它会启动本地 typescript-language-server，仅为 TypeScript/JavaScript 提供 LSP 支持。
• Docker 模式：利用 Gitpod 提供的无头 VS Code 版本，即 OpenVSCode Server，在 Docker 中运行，以提供更丰富的 LSP 支持，适用于 VS Code 支持的任何语言，例如 Rust、Go、C#、Python 等。

为什么选择 Docker 模式？

• 统一的 LSP：无需为每种语言分别启动本地语言服务器。
• 丰富的扩展生态：继承 VS Code 的扩展支持和 API，以提供高级语言功能。
• 实时编辑：打开 http://localhost:3000，即可实时查看 AI Agent 通过 MCP 交互时所做的编辑。
• 无需 IDE 即可使用：我们可以在不打开任何 IDE 的情况下编写和分析代码。

工作原理

1. OpenVSCode Server 在 Docker 内运行，公开端口 3000（IDE UI）和 5007（LSP 桥接）。
2. 预装所需的 VS Code 扩展（例如 rust-analyzer、pyright、eslint 和 VSC-MCP 扩展）。
3. VSC-MCP 扩展在 MCP 与 VS Code 后端之间创建 WebSocket 通道。
4. 文件 I/O 工具直接访问文件；LSP 工具使用 VS Code 的内部语言服务器。

安装

先决条件

• Docker（用于运行 VS Code 服务）
• Bun（用于启动 MCP）

设置

1. 克隆仓库并进入其中。
2. 安装依赖项

   bun install
   

3. 构建并启动 OpenVSCode Server（将项目挂载到容器中）

   PROJECT_PATH=/path/to/your/project docker-compose up
   

4. 在 AI 客户端中注册 MCP（示例 settings.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"
         }
       }
     }
   }
   

环境变量

变量	用途
USE_VSCODE_LSP	设置为 true 以启用 Docker/VS Code LSP 模式。 MCP 会将 LSP 请求转发到 VS Code（端口 5007），而不是启动本地语言服务器。
ALLOWED_DIRECTORIES	将直接文件操作限制在指定目录内。
LOG_DIR	MCP 写入调试日志的位置。

注意： 默认情况下，USE_VSCODE_LSP 为 false（独立模式）。将其设置为 true 即可使用 Docker/VS Code LSP 集成。

推荐的 AI 客户端配置

Claude Desktop

目前，最佳工作流是将 Claude Desktop 用作 AI 客户端。它支持 MCP 服务，并提供每月 20 美元的套餐。借助 VSC-MCP 工具，我们可以通过“聊天”来处理代码库。

• 在 MacOS 上：~/Library/Application Support/Claude/claude_desktop_config.json
• 在 Windows 上：%APPDATA%/Claude/claude_desktop_config.json

将以下配置添加到配置文件的 mcp_servers 部分：

{
  "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"
      }
    }
  }
}

我们建议添加 repomix MCP 服务依赖。要了解原因，请阅读这篇博客文章。

将 <vsc_mcp_cloned_dir> 替换为克隆的 vsc-mcp 目录的实际路径。

安全功能

Docker 工作区限制

启动 Docker 时，需要指定工作区目录。

PROJECT_PATH=/path/to/your/project docker-compose up

VSC-MCP 工具只能访问工作区目录中的文件。

路径限制

VSC-MCP 工具包含一项安全功能，可将操作系统文件操作（读取和写入磁盘上的文件）限制在指定目录内：

• ALLOWED_DIRECTORIES：一个环境变量，用于指定允许执行文件操作的目录列表，目录之间以逗号分隔。

  示例：

  ALLOWED_DIRECTORIES=/home/user/projects,/tmp/workspace
  

• 如果未设置此环境变量，操作默认仅限于当前工作目录。

• 所有文件操作（读取、写入、编辑）都会检查目标路径是否位于允许的目录中。

• 尝试访问允许目录之外的文件会导致“Access denied”错误。

此功能有助于防止未经授权地访问系统中的敏感文件和目录。

可用工具

目前可用的工具如下：

• edit_symbol：使用 LSP，按名称和类型编辑指定文件中的符号（函数、类、方法等）。

  • 支持多种符号类型：函数、方法、类、接口、变量、常量、属性、字段
  • 使用 LSP 的 workspace/symbol 和 textDocument/documentSymbol 请求查找符号
  • 直接将编辑应用到文件

• read_symbol：使用 LSP，按名称和类型读取指定文件中的符号（函数、类、方法等）。

  • 支持与 editSymbol 相同的符号类型
  • 使用 LSP 定位符号并提取其内容
  • 返回符号内容及其位置信息

• read_file：读取文件内容。

  • 根据文件扩展名，以适当的 MIME 类型返回文件内容
  • 支持多种文件格式，包括代码、文本和配置文件
  • 为常见问题（文件不存在、目录访问等）提供详细错误信息

• write_file：使用提供的内容创建新文件或覆盖现有文件。

  • 如果父目录不存在，则会创建这些目录
  • 支持任意文件类型
  • 返回有关文件操作的信息（创建/覆盖、文件大小）

• search_replace_file：在文件中搜索内容并将其替换为新内容。

  • 搜索时忽略空白差异（空格、制表符、换行符）
  • 支持灵活匹配内容模式
  • 返回执行的替换次数

• get_errors：使用 LSP 的 textDocument/diagnostic API，获取指定文件中的代码错误和问题。

  • 提供详细的诊断信息，包括错误消息、严重程度和位置
  • 使用 VS Code 扩展的 diagnostics API 验证代码
  • 返回结构化的代码问题信息

• find_references：使用 LSP，按名称和类型查找指定文件中某个符号（函数、类等）的所有引用。

  • 支持多种符号类型：函数、方法、类、接口、变量、常量、属性、字段
  • 使用 LSP 的 textDocument/reference API 查找某个符号的所有引用
  • 返回包含文件路径和位置的引用列表
  • 有助于代码分析、重构和理解代码用法