MCP VS Code

MCP VS Code

MCP VS Code 会在 MCP 服务旁运行可自托管的 Code OSS/OpenVSCode 工作台，让人类和模型使用同一个工作区、打开的编辑器、诊断信息、命令、扩展和终端会话。 这不是对单独安装的桌面 VS Code 进行远程控制。受支持的发行版自带 OpenVSCode 运行时和桥接扩展。由于 Microsoft 托管的 vscode.dev 不允许嵌入框架，因此不会使用它。

简明说明

整个方案由四部分组成：

1. MCP 宿主——例如 FLUJO 或 Claude Desktop，负责外层沙箱及其安全策略。
2. MCP App 文档请求宿主授权访问工作台源，并在默认模式下将其嵌入框架。
3. mcp-vscode 网关仅开放访问私有运行时所需的路由。
4. OpenVSCode 进程在 MCP 服务所在的机器上运行，绑定到回环地址，打开已配置的工作区，并通过桥接扩展连接回 MCP 服务。

flowchart LR
    H["MCP host"] <-->|"stdio or Streamable HTTPS"| S["mcp-vscode server"]
    H --> A["sandboxed MCP App"]

    A -->|"default: allowed frameDomains"| I["OpenVSCode iframe"]
    A <-->|"opt-in: authenticated /stream WebSocket"| C["pixel canvas"]
    A -->|"honest fallback: openLink"| X["separate browser tab"]

    I --> G["browser-reachable gateway origin"]
    X --> G
    C <-->|"JPEG frames + input"| B["server-side system Chromium"]
    B --> O["loopback OpenVSCode"]
    G --> O
    O <-->|"authenticated /bridge WebSocket"| S
    S --> W["confined workspace and PTYs"]
    O --> W

默认的 iframe 和浏览器标签页路径会直接呈现 OpenVSCode。实验性的流式传输会在服务端启动已有的 Edge、Chrome 或 Chromium，将其指向同一个 OpenVSCode 运行时，再传输画面像素和用户输入。画布是远程显示画面，并非另一种编辑器实现。

渲染模式

模式	选择方式	所需宿主能力	用户看到的内容
embedded	默认模式；宿主批准声明的工作台源且探活检查成功时使用	为嵌套文档设置 frameDomains	MCP App 中的原生 OpenVSCode
stream	仅在 MCP_VSCODE_RENDER_MODE=stream 时使用	可通过 connectDomains 访问的 WebSocket；无需授予嵌套框架权限	由服务端 Chromium 渲染的原生 OpenVSCode，以像素形式绘制在 MCP App 中
browser	请求的内嵌模式被拒绝、无法访问或不可用时的明确回退模式	宿主支持 openLink，或在调试页面中显示普通链接	在单独标签页中打开的同一个原生 OpenVSCode 工作台

probing 是临时 UI 状态，不属于渲染器。

默认行为：iframe 或浏览器

未设置渲染模式环境变量时，App 会：

1. 等待打包的 OpenVSCode 运行时启动；
2. 在宿主提供有效 frameDomains 信息时，将工作台源与其进行比较；
3. 如果宿主明确拒绝该源，则立即跳过 iframe 导航；
4. 否则导航到 iframe，并等待注入的 mcp-vscode:workbench-alive 消息；
5. 仅在收到这一肯定信号后才进入 embedded 模式；或
6. 显示 browser 卡片，并说明具体的策略、网络或运行时原因。

被 CSP 阻止的 iframe 可能既不会触发有用的 load 事件，也不会触发 error 事件，因此不会将普通 iframe 事件视为成功。探活超时可以避免页面永久空白。

MCP 服务的 CSP 声明是权限请求，并不能凌驾于宿主之上。宿主可以批准、限制或拒绝该请求。mcp-vscode 上的 CORS 标头无法修复外层宿主作出的 frame-src 决策。

实验性流式传输

设置：

MCP_VSCODE_RENDER_MODE=stream

流式传输会有意替代该进程的 iframe 方案；它不是自动回退选项。如果流式传输无法启动，App 会报告失败，并转而提供明确的浏览器选项，而不会悄悄改用其他编辑器。

服务端会：

• 查找现有的 Microsoft Edge、Google Chrome 或 Chromium 安装，或使用 MCP_VSCODE_STREAM_BROWSER；
• 以无头模式启动浏览器，并使用专用的临时用户数据目录；
• 当以 root 身份运行的 POSIX 服务端启用了 Chromium 沙箱时，从 /etc/passwd 读取固定的 node 账户，将该私有配置文件的所有权转交给该账户，并仅将 Chromium 子进程降权至其非零 uid/gid；
• 将 Chromium 的工作目录、HOME、TMPDIR 和 XDG 目录指向同一个临时配置文件，而不是继承服务端账户的路径；
• 仅将 Chrome DevTools Protocol 监听器绑定到 127.0.0.1；
• 导航至由服务端选择的内部 OpenVSCode URL——App 无法控制 Chromium 的导航，也不能发出任意 DevTools 命令；
• 以最高每秒 12 帧的速度发送 JPEG 屏幕录制帧；
• 接受有界的调整大小、指针、滚轮、键盘和文本输入消息；并且
• 仅允许一个活动查看者。

/stream WebSocket 使用独立的随机 256 位持有者令牌。带令牌的流 URL 和高熵 /ide/<key> URL 均不会出现在模型可见的工具文本和 structuredContent 中；它们仅通过工具结果 _meta 传递给 MCP App。日志中不会包含流令牌。

当宿主允许 connectDomains，但拒绝 frameDomains 时，流式传输很有用。在 上游报告草稿中记录的测试显示，使用本地配置的 Claude Desktop stdio 连接器时观察到了这种行为。

流式传输仍处于实验阶段：

• JPEG 帧会消耗更多 CPU 和带宽，响应速度也不如直接使用 iframe。
• 不支持音频，且仅允许一个查看者。
• 基本的鼠标、键盘、滚轮和粘贴输入均可使用；剪贴板复制和复杂的 IME 组合输入尚不完整。
• 还需要预先安装系统级 Chromium 系浏览器。此模式下，项目不会下载或捆绑浏览器。
• 网关 WebSocket 必须可由浏览器访问。流式传输无法让私有 Fly Machine 端口自动变为可访问。

失败就是失败

所有三种显示结果都对应真实的 OpenVSCode 运行时。如果该运行时缺失或发生故障，就没有可显示的编辑器界面。在适用的情况下，文件、Git 和终端 MCP 工具仍可运行；但依赖实时桥接的编辑器、诊断、命令和扩展工具会明确报告失败。

macOS 上没有特殊的编辑器回退方案：如果没有 OpenVSCode Server 运行时，嵌入、流式传输和外部浏览器视图都无法提供工作台。

配置

面向用户的环境变量

变量	默认值	用途
MCP_VSCODE_WORKSPACE	进程工作目录	工作区根目录的绝对路径。建议显式设置。--workspace 的优先级更高。
MCP_VSCODE_OPENVSCODE_ROOT	平台运行时包或捆绑的运行时	覆盖 OpenVSCode 运行时目录。--openvscode-root 的优先级更高。
MCP_VSCODE_RENDER_MODE	default	仅设置为 stream 才能启用实验性的真实工作台像素流传输。设置为 default、留空或不设置时，使用 iframe／浏览器行为。其他值会导致启动失败。
MCP_VSCODE_STREAM_BROWSER	自动发现	用于流传输的 Edge、Chrome 或 Chromium 的绝对路径。
MCP_VSCODE_STREAM_NO_SANDBOX	0	仅当受限容器无法运行 Chromium 自带的沙箱时，才将其设置为 1 或 true，作为明确的最后手段。在 POSIX 系统上，root 身份运行的 mcp-vscode 进程默认只会将 Chromium 降权到安全的 node 账户。

由 FLUJO 管理的托管子进程还可能会接收 FLUJO_MCP_APP_RUNTIME_REGISTER_URL 和 FLUJO_MCP_APP_RUNTIME_REGISTER_TOKEN。这些是短期有效的内部代理凭据，不是用户设置。mcp-vscode 会证明自己持有这些凭据，注册允许列表中的路由清单，并在 OpenVSCode 启动前清除这两个变量，绝不会向工作台暴露 bearer 凭据。

Claude Desktop 示例

默认模式会如实回退到浏览器，因为经测试的 Claude Desktop 宿主拒绝了本地回环 frameDomains 请求：

{
  "mcpServers": {
    "vscode": {
      "command": "npx",
      "args": ["-y", "@mario.andreschak/[email protected]", "--stdio"],
      "env": {
        "MCP_VSCODE_WORKSPACE": "C:\\path\\to\\repository"
      }
    }
  }
}

若要测试真正的内联流传输，请执行：

{
  "mcpServers": {
    "vscode": {
      "command": "npx",
      "args": ["-y", "@mario.andreschak/[email protected]", "--stdio"],
      "env": {
        "MCP_VSCODE_WORKSPACE": "C:\\path\\to\\repository",
        "MCP_VSCODE_RENDER_MODE": "stream",
        "MCP_VSCODE_STREAM_BROWSER": "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe"
      }
    }
  }
}

如果发现已安装的浏览器，则无需覆盖浏览器路径。宿主行为会随时间变化；请针对确切的 Claude Desktop 版本重新运行手动测试矩阵，不要将当前观察结果视为永久不变。

FLUJO 和 Fly.io 部署

用户可以访问 try.flujo.com.co 这样的面向用户的网站，同时浏览器会在后台使用其他安全来源。沙盒化的 MCP App 及其嵌套工作台无法仅为了让部署看起来更简单，就安全地合并到同一个字面上的浏览器来源。

对于由 FLUJO 管理的 stdio 子进程，运行时代理握手解决了私有端口问题：

1. FLUJO 向子进程提供一次性环回注册凭据。
2. mcp-vscode 证明其持有该凭据，并且只注册随机的 /ide/<key> 前缀，包括工作台的 HTTP 和 WebSocket 流量。
3. 启用流式传输后，还会额外注册且仅注册精确的 /stream WebSocket 路由。
4. 代理返回浏览器可访问的、按 App 独立分配的 HTTPS 来源。mcp-vscode 会在 MCP App CSP 元数据和仅用于 App 的结果元数据中使用该来源，而不是向访客公布 127.0.0.1。
5. 外部代理会将 /mcp、/bridge、/healthz、/app、/session.json 和临时证明路由保持为私有。

托管部署仍需要：

• 为按 App 分配的来源方案配置通配符 DNS 和 TLS；
• 为随机 OpenVSCode 前缀代理 HTTP 和 WebSocket 流量；
• 启用实验性流式传输时，为 /stream 代理 WebSocket 流量；
• 保留沙盒和工作台所需的 Upgrade、Host、Origin 和 Referer 行为；以及
• 配置浏览器可访问的 https: 来源，以便对应的流 URL 为 wss:。

在 Fly 上启用流式传输时，请在 Machine 镜像中安装 Edge、Chrome 或 Chromium。优先以非特权用户身份运行整个容器。如果 FLUJO 必须以 root 身份运行 mcp-vscode，镜像必须恰好包含一个 node 账户，且其 uid 和 gid 均为非零值，并且具有安全的共享 /tmp（归 root 所有、可遍历；在组或所有用户可写时带有粘滞位）；mcp-vscode 会在该目录下创建高熵配置文件，仅更改配置文件的所有者，并在保留沙盒的情况下仅以 node 身份启动浏览器。缺少账户或临时目录数据，或者这些数据不安全时，会显示流式传输不可用错误。它绝不会静默添加 --no-sandbox。MCP_VSCODE_STREAM_NO_SANDBOX=1 仍是安全性上的最后手段权衡，并非普通部署配置。

如果在没有 FLUJO 代理的情况下远程部署 mcp-vscode，--public-url 必须指定一个等效的、浏览器可访问的网关来源，反向代理必须转发相同的工作台 HTTP/WebSocket 流量以及可选的 /stream WebSocket 流量。仅靠 CORS 设置无法替代路由。

网关 HTTP 接口

本地网关提供以下服务：

路由	身份验证/暴露范围	用途
GET /healthz	本地部署策略	存活状态以及 OpenVSCode/bridge 状态
GET /session.json	配置了 --auth-token 时需要 ?token=	调试浏览器会话负载
GET /app	配置了 --auth-token 时需要 ?token=	MCP App 文档的调试版本
ALL /mcp	配置了令牌时需要 Authorization: Bearer	可流式传输的 HTTP MCP 传输
HTTP/WS /ide/<random>/...	每个进程独立的高熵路径；在 FLUJO 中通过代理进行严格限定	代理真实的 OpenVSCode 工作台、资源、API 和套接字
WS /bridge	经过身份验证的代理握手	OpenVSCode bridge 扩展 JSON-RPC 通道；FLUJO 不会公开代理此路由
WS /stream	查询参数中包含独立令牌；仅允许一个查看者；仅在启用时提供	实验性的 JPEG 帧和输入通道
GET /.well-known/flujo/mcp-app-runtime	临时的一次性 FLUJO 证明；随后禁用	仅用于托管运行时注册

通过代理公开的来源只会暴露为 MCP App 明确注册的路由，而不是这里列出的整个本地接口。

功能

• 真正可自托管的 Code OSS/OpenVSCode 工作台。
• 支持人工编辑、导航、源代码管理、命令、扩展、Webview 和终端交互。
• 通过 OpenVSCode 桥接器，MCP 工具可以查看实时编辑器状态、选区、未保存缓冲区、诊断信息和文件更改。
• 共享终端会话；有可用的目标平台原生 PTY 时使用该 PTY，否则使用基于管道的备用方案。
• 工作区限制，并防止路径遍历和通过符号链接逃逸。
• 使用 SHA-256 版本哈希实现安全的文件写入，避免冲突。
• 同一可执行文件支持 stdio 和 Streamable HTTP/HTTPS 传输。
• 通用的 vscode_execute_command 逃生口，用于执行实时工作台中注册的命令。

服务通过以下类别提供 27 个工具：

类别	工具
应用/会话	vscode_open、workspace_status
文件	fs_list、fs_read、fs_write、fs_delete、fs_move、fs_search
编辑器	editor_open、editor_state、editor_set_selection、editor_apply_edits
语言服务	diagnostics_get
命令	vscode_list_commands、vscode_execute_command
扩展	extensions_list、extensions_install、extensions_uninstall
终端	terminal_create、terminal_list、terminal_read、terminal_write、terminal_resize、terminal_kill
Git	git_status、git_diff、git_run

编辑器、诊断、命令和扩展工具始终通过真正的 OpenVSCode 桥接器操作。破坏性工具和开放世界工具都带有注释，以便兼容的 MCP 主机应用其审批策略。

安装独立发行版

下载并解压适用于你平台的发行版归档文件。

Windows x64：

.\bin\mcp-vscode.cmd --stdio --workspace C:\path\to\repository

Linux x64 或 ARM64：

./bin/mcp-vscode --stdio --workspace /absolute/path/to/repository

归档文件包含自带的 Node.js 和 OpenVSCode 运行时。默认的 iframe/浏览器运行方式无需 VS Code、Node.js、Docker 或系统范围的程序包安装。实验性流式传输还需要安装 Chromium 系浏览器。

从 npm 运行

使用 Node.js 22 或更高版本时，npx 会在 Windows x64、Linux x64 和 Linux ARM64 上启动内置的 stdio 服务端：

npx -y @mario.andreschak/[email protected] --stdio --workspace "C:\path\to\repository"

npx -y @mario.andreschak/[email protected] --stdio --workspace "/path/to/repository"

请明确指定工作区。未设置 --workspace 或 MCP_VSCODE_WORKSPACE 时，服务会使用其进程工作目录，并在 stderr 中报告此选择。请勿意外暴露主目录、卷根目录或无关的检出目录。

@mario.andreschak/mcp-vscode 声明了适用于 Windows x64、Linux x64 和 Linux ARM64 的可选平台程序包，因此 npm 只会下载匹配的 OpenVSCode 运行时。未发布 Darwin 运行时程序包。

调用 vscode_open 会打开 MCP App。全屏按钮会请求主机进入全屏显示模式；是否允许由主机决定。

通过 HTTPS 运行

./bin/mcp-vscode \
  --http \
  --https \
  --host 0.0.0.0 \
  --port 8443 \
  --workspace /work/my-repository \
  --public-url https://editor.example.com:8443 \
  --auth-token "$MCP_VSCODE_TOKEN" \
  --cert /run/secrets/tls.crt \
  --key /run/secrets/tls.key

MCP 端点为 https://editor.example.com:8443/mcp。除非同时配置 TLS 和 bearer token，否则不允许绑定到 loopback 以外的地址。也可以使用终止 TLS 的反向代理，将请求转发到 loopback 上的 HTTP 子进程，但必须确保其公共 URL 和 WebSocket 路由配置正确。

MCP 主机要求

主机必须支持稳定版 MCP Apps 扩展 io.modelcontextprotocol/ui 和 text/html;profile=mcp-app 资源。

对于默认的内嵌模式，主机必须遵循声明的 frameDomains，并允许被嵌入的工作台使用自身脚本、worker、service worker、资源和 WebSocket。当前 MCP App 程序包是自包含的，因此不会请求 resourceDomains；该授权仅覆盖 App 直接加载的资源，无法授权嵌套的工作台框架。如果主机限制了框架授权，App 会报告此决定并提供浏览器方式。

对于实验性流式传输，主机必须通过 connectDomains 允许声明的网关 WebSocket，保留 App 所需的工具结果 _meta，并支持常规的 canvas 图像解码。流式传输不需要 frameDomains。

从源代码构建

开发要求：Node.js 22+。系统中的 Chromium 系浏览器为可选项；如果存在，仅用于真实流式集成测试。

npm ci
npm run check

常用命令：

npm run dev -- --http --port 3001 --workspace . --ide-url http://127.0.0.1:3999
npm run dev:mock-ide -- --port 3999
npm run runtime:fetch -- linux-x64
npm run runtime:build -- win32-x64
npm run package:standalone -- linux-x64
npm run package:standalone -- win32-x64
npm run npm:platform-package -- linux-x64

npm run typecheck 会检查 Node 服务、MCP App 浏览器代码和桥接扩展。npm test 会运行单元测试和安全策略测试，而 npm run test:integration 会运行网关测试和真实系统浏览器屏幕录制冒烟测试（未安装浏览器时会跳过）。

运行时获取器固定使用 OpenVSCode 1.109.5，并在解压前验证上游 Linux SHA-256 摘要。Windows 构建会固定使用已配置的上游提交，并调用 Code OSS 的 Windows 远程 Web 构建目标。运行时和独立输出目录会被 Git 忽略。

发布自动化

Release Please 会根据约定式提交（fix:、feat: 和包含重大变更的 type!:）维护一个发布拉取请求。合并该拉取请求会创建下一个 v* 标签和 GitHub Release。该标签会启动 Release CI，通过 npm 可信发布先发布各平台运行时包，再发布平台无关的分发器。常规发布无需本地产物、npm 令牌、npm login 或浏览器身份验证。

Release Please 使用仓库范围的 GitHub App，以便它创建的标签能够触发 Release CI。为该 App 一次性配置 Contents、Issues 和 Pull requests 的读写权限，仅将其安装在此仓库中，然后添加：

• 仓库变量 RELEASE_APP_CLIENT_ID — App 的 Client ID；
• 仓库密钥 RELEASE_APP_PRIVATE_KEY — App 的 PEM 私钥。

如果缺少这些值，Release Please 工作流会显示配置提示并成功退出，不执行任何发布操作。npm 端不需要密钥：每个包都信任 flujo-app/mcp-vscode-mcpapp 中的 .github/workflows/release.yml，并限制在 npm-publish 环境中。

常规发布流程：

1. 使用约定式合并提交标题，将常规变更合并到 main。
2. 审核并合并自动维护的 Release Please 拉取请求。
3. 按照标签触发的 Release 工作流操作；它会创建并上传各平台归档文件，并通过带签名的来源证明发布到 npm。

手动恢复 npm 发布

npm run npm:publish 仅用于验证或恢复之前已构建的 GitHub Release 产物。它不会构建或下载这些产物：

gh release download v0.2.4 \
  --dir release-artifacts-v0.2.4 \
  --pattern '*.npm.tgz*'
npm run npm:publish -- release-artifacts-v0.2.4 --dry-run
npm run npm:publish -- release-artifacts-v0.2.4

常用身份验证命令：

npm run npm:whoami
npm run npm:login
npm run npm:publish:wait -- release-artifacts-v0.2.4
npm run npm:publish -- release-artifacts-v0.2.4 --no-login

发布脚本会在身份验证前验证产物哈希以及包内的名称和版本。只有当 tarball 完整性完全匹配时，它才会跳过对应的注册表版本，因此中断的运行可以继续；它不会重新构建已审核的 tarball。如果在较新版本发布失败后重试旧版本，它还会拒绝将 latest 或 beta 之类的 dist-tag 回退。

发布到 MCP Registry

MCP Registry 仅存储元数据，因此 npm 包必须先发布：

npm run mcp:validate
npm run mcp:publish

脚本会在上传前检查 package.json、server.json、已发布的 npm 元数据、命名空间授权以及固定版本的发布者二进制文件。注册表中的版本不可变；除非传入 --force，否则会跳过已存在的版本。

身份验证选项包括：

npm run mcp:publish -- --login github-oidc
npm run mcp:publish -- --login dns --domain example.com --private-key <hex>
npm run mcp:publish -- --relogin
npm run mcp:publish -- --token <github-pat>
npm run mcp:publish -- --no-login
npm run mcp:publish -- --registry http://localhost:8080

安全模型

• 每个文件路径都会解析到一个已配置的工作区根目录下；访问前会对现有符号链接进行规范化。
• 无法通过 MCP 工具删除工作区根目录。
• OpenVSCode 仅监听环回地址，并通过随机的高熵路径对外提供访问。
• OpenVSCode 桥接使用单独的随机令牌，并且只接受一个活动桥接连接。
• 流式传输通道使用独立的随机令牌，不公开 DevTools 端点，只允许一个查看者，并将凭据保存在仅供应用使用的结果元数据中。
• 服务端流式传输 Chromium 使用环回 DevTools 监听器和临时配置文件；在关闭或崩溃时会移除该配置文件。
• 在 POSIX root 部署中，仅以非特权 node uid/gid 启动启用沙箱的 Chromium；其 HOME 和 XDG 路径仅限于该临时配置文件。
• 远程监听器必须使用 HTTPS 和 bearer 身份验证；流式传输的像素和输入必须通过可信的 TLS/WSS 路由传输。
• MCP_VSCODE_STREAM_NO_SANDBOX=1 会削弱纵深防御，不应作为容器配置问题的默认解决方案。
• git_run 会禁用 Git 钩子；任意 VS Code 命令、扩展安装和 Shell 输入仍然具有很强的能力，应要求主机审批。
• 不要仅仅因为浏览器 UI 已沙箱化就禁用 MCP 主机审批。终端和扩展主机都在服务端执行。

有关报告和部署指南，请参阅 SECURITY.md。

上游项目与商标

OpenVSCode Server 和 Code OSS 是采用 MIT 许可证的上游项目。MCP VS Code 是独立项目，与 Microsoft 或 Gitpod 无关联，也未获得其认可。“Visual Studio Code”和“VS Code”是 Microsoft Corporation 的商标。

许可证

MIT。请参阅 LICENSE 和 THIRD_PARTY_NOTICES.md。