Positron 仓库中的 VS Code 自动化 MCP 服务器:`test/mcp` 架构、配置与实战指南
Positron 仓库中的 VS Code 自动化 MCP 服务器:test/mcp 架构、配置与实战指南
本指南系统讲解 Positron 开源仓库中 test/mcp 目录下的 Model Context Protocol(MCP)服务器:它通过标准化的 MCP 协议把 Code - OSS(VS Code)的自动化测试基础设施暴露给 AI 助手,支持启动/停止编辑器实例、操作编辑器与终端、管理调试会话、驱动界面元素以及录制带视频证据的 UI 验证场景。读完本文,你将掌握该服务器的快速启动方式、启动参数、工具集构成、场景证据录制工作流,以及基于仓库源码的底层实现原理与故障排查方法。
MCP 是什么,以及它在此仓库中的作用
Model Context Protocol(MCP)是一个开放标准,允许 AI 助手安全地连接到外部数据源和工具。test/mcp 中的这个 MCP 服务器专门提供 VS Code 自动化能力,使 AI 助手能够:
- 启动、停止和重启 VS Code 实例
- 与编辑器、终端和 UI 元素交互
- 执行命令(Command Palette)与按键绑定(keybindings)
- 在资源管理器(Explorer)、搜索(Search)、调试(Debug)等视图(viewlet)中导航
- 管理扩展、设置与按键绑定
- 操作 Notebook 与聊天(Chat)功能
在 Positron 的测试基础设施语境下,这意味着 AI 助手可以通过统一的工具接口驱动本地构建的 VS Code 进行 UI 行为验证——这与仓库中基于 Playwright 的 test/e2e 基础设施 相辅相成,共同构成 Code - OSS 开发与回归测试的自动化能力。
快速开始(Stdio 模式)
1. 安装依赖
首先确保在仓库根目录执行依赖安装:
npm i
2. 启动服务器
有两种方式启动:
-
方式一(命令面板):打开命令面板(
Ctrl+Shift+P),依次执行:MCP: List Servers → vscode-automation-mcp → Start Server -
方式二(配置文件):打开仓库根目录下的 .vscode/mcp.json,从配置中启动
vscode-automation-mcp服务器。
完成上述任一步骤后,服务器会自动编译所有必要内容,无需额外手工编译。
仓库中的实际配置内容如下(.vscode/mcp.json):
{
"servers": {
"vscode-automation-mcp": {
"type": "stdio",
"command": "npm",
"args": [
"run",
"start-stdio"
],
"cwd": "${workspaceFolder}/test/mcp"
},
"component-explorer": {
"type": "stdio",
"command": "npm",
"args": [
"exec",
"--no",
"--",
"component-explorer",
"mcp",
"-p",
"./test/componentFixtures/component-explorer.json",
"--use-daemon",
"-vv"
]
}
},
"inputs": []
}
注意:component-explorer 服务器与本主题无关,它是用于组件探索的另一套 MCP 服务,不要与 vscode-automation-mcp 混淆。
start-stdio 脚本定义在 test/mcp/package.json 中,其完整执行链为:
"start-stdio": "echo 'Starting vscode-automation-mcp... For customization and troubleshooting, see ./test/mcp/README.md' && npm ci && npm run -s compile && node ./out/stdio.js"
即依次执行:输出提示信息 → npm ci 安装锁定依赖 → npm run -s compile 编译 TypeScript → node ./out/stdio.js 启动服务器进程。这也是调试时 args: ["run", "start-stdio"] 的本质含义。
启动参数(Arguments)
打开 .vscode/mcp.json,修改 vscode-automation-mcp 的 args 字段即可控制启动方式:
args 配置 |
效果 |
|---|---|
["run", "start-stdio"] |
打开 Electron 窗口(默认桌面模式) |
["run", "start-stdio", "--", "--web"] |
打开 Chromium 窗口(Web 模式) |
["run", "start-stdio", "--", "--headless"] |
打开无头(headless)窗口 |
注意:
--web模式要求先从仓库根目录执行npm run install-playwright安装 Playwright 浏览器依赖。仓库根 package.json 中提供了playwright-install(npm exec playwright install)等 Playwright 相关脚本,e2e 测试也大量依赖 Playwright(参见 test/e2e/infra/playwrightBrowser.ts)。
此外,test/mcp/scripts/start-stdio.sh 展示了另一种启动方式——它进入 test/mcp 目录后执行:
npm run start-stdio -- --video --autostart
其中 --autostart 会被 test/mcp/src/stdio.ts 中的 opts.autostart 读取:当其为真时,服务器在连接传输层之前就通过 appService.getOrCreateApplication() 预先启动 VS Code 实例:
if (opts.autostart) {
await appService.getOrCreateApplication();
}
调试服务器
你可以修改 .vscode/mcp.json 以直接调试服务器进程,配置示例如下:
"vscode-automation-mcp": {
"type": "stdio",
"command": "node",
"args": ["./out/stdio.js"],
"cwd": "${workspaceFolder}/test/mcp",
"dev": {
"watch": "test/mcp/**/*.ts",
"debug": {
"type": "node"
}
}
}
该配置要点:
command改为node、args改为["./out/stdio.js"],跳过 npm 包装层直接启动已编译产物;cwd保持为test/mcp,确保相对路径解析正确;dev.watch监听test/mcp/**/*.ts的变更,配合watch-mcp/watch-scenario脚本(见 test/mcp/package.json)可实现改代码后自动重编译;dev.debug声明使用 Node 调试器,可在 VS Code 中附加断点逐步排查。
服务器提供的工具集
MCP 服务器通过协议暴露了一整套 VS Code 自动化工具。工具注册集中在 test/mcp/src/automationTools/index.ts,applyAllTools 依次调用各功能模块的注册函数;据源码统计,当前共注册了 120 余个 vscode_automation_* 工具。下面按功能域列出核心工具(名称与参数以源码为准)。
应用管理(Application Management)
vscode_automation_start:启动 VS Code,可选recordVideo与workspacePath参数;启动后自动开始 tracing(见 test/mcp/src/automation.ts)vscode_automation_restart:重启 VS Code,支持传入工作区路径workspaceOrFolder与附加命令行参数extraArgs(见 test/mcp/src/automationTools/core.ts)vscode_automation_stop:停止 VS Code 并结束 tracing- 打开工作区/文件夹、录制带步骤覆盖层(step overlays)的场景证据、截图、视频、trace 与 HTML 报告
编辑器工具(Editor Tools)
见 test/mcp/src/automationTools/editor.ts,包括:
vscode_automation_editor_open_file:打开文件vscode_automation_editor_type_text:向当前激活编辑器输入文本(源码注释指出这是关键工具,因为 Playwright 在 Monaco 中键入有困难,它通过app.workbench.editor.waitForTypeInEditor实现)vscode_automation_editor_save_file、vscode_automation_editor_new_untitled_file、vscode_automation_editor_select_tab、vscode_automation_editor_wait_for_tab、vscode_automation_editor_wait_for_focus- 代码导航类:
vscode_automation_editor_go_to_definition、vscode_automation_editor_peek_definition、vscode_automation_editor_find_references、vscode_automation_editor_rename_symbol
终端工具(Terminal Tools)
见 test/mcp/src/automationTools/terminal.ts,支持创建与管理终端实例、向终端发送命令、读取终端输出。
调试工具(Debug Tools)
见 test/mcp/src/automationTools/debug.ts,包括:
vscode_automation_debug_open:打开调试视图vscode_automation_debug_set_breakpoint:在指定行设置断点(参数lineNumber)vscode_automation_debug_start/vscode_automation_debug_stop:启动/停止调试会话vscode_automation_debug_continue、vscode_automation_debug_step_in、vscode_automation_debug_step_out、vscode_automation_debug_step_over:控制执行流
搜索工具(Search Tools)
见 test/mcp/src/automationTools/search.ts,包括 vscode_automation_search_for_text、vscode_automation_search_set_files_to_include、vscode_automation_search_submit、vscode_automation_search_clear_results 等,用于搜索文件与文本并导航结果。
扩展工具(Extension Tools)
见 test/mcp/src/automationTools/extensions.ts,包括 vscode_automation_extensions_search、vscode_automation_extensions_open、vscode_automation_extensions_install、vscode_automation_extensions_close,参数如 extensionId(例如 "ms-python.python")。
UI 交互(UI Interaction)
按源码模块(test/mcp/src/automationTools/ 下的各文件)划分:
- Quick Access / 命令面板(
quickAccess.ts):vscode_automation_command_run(按名称执行命令,支持exactMatch精确匹配)、vscode_automation_quick_open_file、vscode_automation_quick_input_type、vscode_automation_quick_input_select_item - 资源管理器(
explorer.ts):vscode_automation_explorer_open等 - 活动栏(
activityBar.ts):如vscode_automation_activitybar_wait_for_position - 源代码管理(
scm.ts):vscode_automation_scm_open、vscode_automation_scm_stage、vscode_automation_scm_unstage、vscode_automation_scm_commit、vscode_automation_scm_refresh、vscode_automation_scm_wait_for_change、vscode_automation_scm_open_change - 状态栏(
statusbar.ts):vscode_automation_statusbar_click等 - 问题面板(
problems.ts):vscode_automation_problems_show、vscode_automation_problems_hide、vscode_automation_problems_wait_for_view、vscode_automation_problems_get_selector_in_editor等 - 设置与按键绑定(
settings.ts、keybindings.ts):vscode_automation_settings_add_user_setting(s)、vscode_automation_settings_open_user_file、vscode_automation_settings_search_ui、vscode_automation_keybindings_update - Notebook(
notebook.ts):vscode_automation_notebook_open、vscode_automation_notebook_insert_cell、vscode_automation_notebook_edit_cell、vscode_automation_notebook_execute_active_cell、vscode_automation_notebook_wait_for_cell_contents、vscode_automation_notebook_focus_first_cell等 - Chat(
chat.ts):vscode_automation_chat_send_message等 - 任务(
task.ts)与性能剖析(profiler.ts):vscode_automation_profiler_info等 - 多窗口支持(
windows.ts):vscode_automation_list_windows(列出所有打开的窗口及其索引与 URL)、vscode_automation_switch_window(按索引或 URL 模式切换窗口)、vscode_automation_get_current_window - 本地化(
localization.ts):vscode_automation_localization_get_locale_info、vscode_automation_localization_get_localized_strings
工具注册与启停机制
值得注意的实现细节:在 test/mcp/src/automation.ts 中,所有工具注册后并不会立即全部启用——服务器会根据 ApplicationService 当前是否有应用实例来决定 enable()/disable() 这批工具,并监听 onApplicationChange 事件动态切换。也就是说,VS Code 实例未启动时,依赖实例的自动化工具会被禁用,实例启动后自动启用。这一机制保证了工具调用的时序安全。
场景证据(Scenario Evidence)工作流
场景证据(evidence)是这套 MCP 服务器最具特色的能力:它允许为每次 UI 验证录制完整的视频、trace、截图与 HTML 报告,作为测试通过/失败的凭证。其实现位于 test/mcp/src/evidenceTools.ts。
官方推荐的工作流是:在启动 VS Code 之前先开始证据录制,这样 Playwright 才能启用视频录制。
- 调用
vscode_automation_evidence_start,可传入所需的启动前userSettings(以及其他可选参数:scenarioId、title、source(须为 HTTP/HTTPS 的测试计划问题链接)、scenarioPath、workspacePath、extraArgs) - 在每个动作之前调用
vscode_automation_evidence_step并传入started状态 - 用相关自动化工具执行并验证动作
- 调用
vscode_automation_evidence_step并传入passed、failed或skipped状态 - 调用
vscode_automation_evidence_finish结束录制
对应工具的参数与语义(来自 evidenceTools.ts):
vscode_automation_evidence_start:启动带视频与 trace 录制的 VS Code。参数含scenarioId(稳定场景标识)、title(人类可读标题)、source(HTTP/HTTPS 来源 URL)、scenarioPath(Markdown 场景定义路径)、workspacePath、userSettings(VS Code 启动前预置的用户设置,任意 JSON 值)、extraArgs(附加命令行参数)vscode_automation_evidence_step:在视频中标记一个场景步骤并保存当前 VS Code 窗口截图。参数含id(稳定步骤标识)、title(步骤标题)、status(枚举:started/passed/failed/skipped)、details(验证结果或失败详情)。该工具会同时返回截图路径与 Base64 编码的 PNG 图片内容vscode_automation_evidence_finish:结束 UI 验证场景、停止 VS Code 并写出证据报告。参数含outcome(枚举:passed/failed/aborted)与notes(运行摘要或阻塞条件)
产物写入 .build/vscode-playwright-mcp/evidence/<run-id>/ 目录。每次证据运行都使用独立的用户 profile 与内存级密钥存储(in-memory secret storage),并且把访问过的每一个 Playwright 页面分别录制为独立的视频文件。仓库根目录的 .gitignore 中也将 .playwright-mcp 相关产物排除在版本控制之外,避免测试产物污染仓库。
手动设置(进阶)与项目结构
如果你倾向于手动运行服务器(不通过 VS Code 的 MCP 客户端),可以按以下步骤:
# 进入 MCP 目录
cd test/mcp
# 安装依赖
npm install
# 编译 TypeScript
npm run compile # 或 watch(增量编译)
# 启动服务器
npm start
注意:compile 脚本会先编译 ../scenario(即 test/scenario)再编译 test/mcp 自身,因此源码层面依赖 ApplicationService、EvidenceService 等来自 test/scenario 的公共模块(参见 stdio.ts 与 automation.ts 的 import 语句)。
实际仓库中的目录结构如下(与 README 中的示意图一致,且以源码为准):
test/mcp/
├── scripts/
│ └── start-stdio.sh # 便捷启动脚本(--video --autostart)
├── src/
│ ├── stdio.ts # stdio 传输层入口点
│ ├── automation.ts # 创建 MCP 服务器并注册所有自动化工具
│ ├── evidenceTools.ts # 场景证据(evidence)工具实现
│ └── automationTools/ # 按功能域组织的工具实现
│ ├── index.ts # 工具注册总入口
│ ├── core.ts # 核心应用工具(start/restart/stop)
│ ├── editor.ts # 编辑器工具
│ ├── terminal.ts # 终端工具
│ ├── debug.ts # 调试工具
│ ├── search.ts # 搜索工具
│ ├── extensions.ts # 扩展工具
│ ├── quickAccess.ts # 命令面板/快速访问
│ ├── explorer.ts # 资源管理器
│ ├── activityBar.ts # 活动栏
│ ├── scm.ts # 源代码管理
│ ├── statusbar.ts # 状态栏
│ ├── problems.ts # 问题面板
│ ├── settings.ts # 设置编辑器
│ ├── keybindings.ts # 按键绑定编辑器
│ ├── notebook.ts # Notebook 支持
│ ├── chat.ts # Chat 功能
│ ├── task.ts # 任务
│ ├── profiler.ts # 性能剖析
│ ├── localization.ts # 本地化
│ └── windows.ts # 多窗口管理
├── package.json # 依赖与脚本
├── tsconfig.json # TypeScript 配置
└── README.md # 本文档
(注:README 中示意性的 application.ts、options.ts、utils.ts 在当前的仓库快照中已整合/调整,实际以 src/ 下现有文件为准。)
架构:从入口到工具的调用链
服务器采用简洁的分层架构,从 test/mcp/src/stdio.ts 的入口代码可以还原完整调用链:
- stdio.ts:创建
StdioServerTransport(来自@modelcontextprotocol/sdk),实例化ApplicationService,调用getServer(appService)取得服务器,若opts.autostart为真则预先启动 VS Code,最后server.connect(transport)挂载 stdio 传输并启动消息循环。任何启动错误都会关闭 transport 并以非零码退出。 - automation.ts:基于
McpServer(SDK 提供)构建名为VS Code Automation Server的服务器实例,声明logging能力;注册vscode_automation_start与证据工具,然后调用applyAllTools注册全部自动化工具,并根据应用实例是否存在动态启用/禁用工具。 - automationTools/ 各模块:每个模块导出一个
applyXxxTools(server, appService)函数,使用 zod schema(z.string()、z.number()、z.boolean()、z.enum([...])等)声明工具参数并校验输入,工具处理器内部通过appService.getOrCreateApplication()获取应用实例,再调用app.workbench.*上的 Playwright 驱动方法完成真实 UI 操作。 - ApplicationService(来自
test/scenario):负责 VS Code 应用生命周期管理(启动、停止、重启),EvidenceService负责场景证据录制,二者通过appService.onApplicationChange与工具启停联动。
这套设计的好处:新增能力只需在 automationTools/ 下新增一个模块并在 index.ts 中注册一行;参数校验统一由 zod 完成;所有 UI 操作复用既有 test/e2e 的 Playwright 自动化基础设施(如 app.workbench.editor、app.workbench.debug 等),不重复造轮子。
故障排查(Troubleshooting)
服务器无法启动(Server Won't Start)
- 确保 Code - OSS 已经至少构建并运行过一次(通过 F5 调试或
code.sh启动) - 确认依赖已用
npm install(或npm ci)完整安装
自动化异常(Automation Issues)
- 确保 Code - OSS 已经至少构建并运行过一次(通过 F5 或
code.sh) - 检查服务器日志中的错误信息
- 确认工作区路径(
workspacePath)配置正确
结合源码再补充两点排查建议:
- 若工具返回"未启用"或实例相关错误,请确认 VS Code 应用是否已启动——工具启停与
ApplicationService实例状态绑定(见 automation.ts) - 若
--web模式无法打开浏览器,先确认已在仓库根执行 Playwright 浏览器安装(README 要求的npm run install-playwright)
贡献与许可
该 MCP 服务器是 Code - OSS 开发基础设施的一部分。仓库在 test/mcp/README.md 中给出贡献约定:
- 遵循既有的 TypeScript 编码规范
- 尽可能在多个 MCP 客户端中测试
- 新增能力时同步更新本 README
- 确保完善的错误处理与日志输出
本项目采用 MIT 许可证,详见仓库根目录的 LICENSE.txt。如果你正在为 Positron/Code - OSS 编写 UI 自动化测试或希望让 AI 助手直接驱动 VS Code 完成验证,test/mcp 提供的这套 MCP 服务器是值得优先尝试的入口。