Positron 仓库中的 VS Code 自动化 MCP 服务器:`test/mcp` 架构、配置与实战指南

原创2026-10-15 23:17:491,912 阅读
文章标签:IDE开发工具代码编辑器数据科学数据分析桌面应用插件系统数据可视化AI 应用

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 才能启用视频录制。

  1. 调用 vscode_automation_evidence_start,可传入所需的启动前 userSettings(以及其他可选参数:scenarioId、title、source(须为 HTTP/HTTPS 的测试计划问题链接)、scenarioPath、workspacePath、extraArgs)
  2. 在每个动作之前调用 vscode_automation_evidence_step 并传入 started 状态
  3. 用相关自动化工具执行并验证动作
  4. 调用 vscode_automation_evidence_step 并传入 passed、failed 或 skipped 状态
  5. 调用 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 的入口代码可以还原完整调用链:

  1. stdio.ts:创建 StdioServerTransport(来自 @modelcontextprotocol/sdk),实例化 ApplicationService,调用 getServer(appService) 取得服务器,若 opts.autostart 为真则预先启动 VS Code,最后 server.connect(transport) 挂载 stdio 传输并启动消息循环。任何启动错误都会关闭 transport 并以非零码退出。
  2. automation.ts:基于 McpServer(SDK 提供)构建名为 VS Code Automation Server 的服务器实例,声明 logging 能力;注册 vscode_automation_start 与证据工具,然后调用 applyAllTools 注册全部自动化工具,并根据应用实例是否存在动态启用/禁用工具。
  3. automationTools/ 各模块:每个模块导出一个 applyXxxTools(server, appService) 函数,使用 zod schema(z.string()、z.number()、z.boolean()、z.enum([...]) 等)声明工具参数并校验输入,工具处理器内部通过 appService.getOrCreateApplication() 获取应用实例,再调用 app.workbench.* 上的 Playwright 驱动方法完成真实 UI 操作。
  4. 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 中给出贡献约定:

  1. 遵循既有的 TypeScript 编码规范
  2. 尽可能在多个 MCP 客户端中测试
  3. 新增能力时同步更新本 README
  4. 确保完善的错误处理与日志输出

本项目采用 MIT 许可证,详见仓库根目录的 LICENSE.txt。如果你正在为 Positron/Code - OSS 编写 UI 自动化测试或希望让 AI 助手直接驱动 VS Code 完成验证,test/mcp 提供的这套 MCP 服务器是值得优先尝试的入口。

登录后查看全文
positron