chrome-devtools-mcp 贡献指南开发环境搭建、Evals 测试、发布流程与 JSON Schema 约束【免费下载链接】chrome-devtools-mcpChrome DevTools for coding agents项目地址: https://gitcode.com/GitHub_Trending/chr/chrome-devtools-mcpchrome-devtools-mcpChrome DevTools for coding agents是一个让编码智能体通过 MCP 协议控制并检查实时 Chrome 浏览器的开源项目。这篇指南基于仓库的 CONTRIBUTING.md 完整展开覆盖从签署 CLA、搭建本地开发环境、构建并测试 MCP 服务器到 Conventional Commits 规范、功能发布清单、Lighthouse 依赖更新、Evals 评测场景编写直至工具 JSON Schema 的硬性约束——帮助你在动手提交 PR 之前完整掌握该项目的开发流程与工程约定。贡献前准备签署贡献者许可协议CLA向该项目提交代码必须附带一份 Google CLAContributor License Agreement。版权仍归贡献者或其雇主所有CLA 只是授予项目使用和再分发代码的许可。如果本人或现雇主已签署过 Google CLA哪怕是针对其他项目通常无需重复签署。社区准则项目遵循 Google 开源社区行为准则。所有提交包括项目成员自己的提交都需要评审统一通过 GitHub Pull Request 进行。本地开发环境搭建文档明确要求先确认使用的 Node 版本与 .nvmrc 一致再执行克隆与构建。当前 .nvmrc 中指定的版本为v24而 package.json 的engines字段声明的兼容范围是^20.19.0 || ^22.12.0 || 23——开发时以 .nvmrc 声明的 v24 为准。git clone https://github.com/ChromeDevTools/chrome-devtools-mcp.git cd chrome-devtools-mcp npm ci npm run build从 package.json 的 scripts 定义可以看到构建的完整构成npm run build实际执行tsc node scripts/post-build.ts即 TypeScript 编译加后处理项目声明了两个可执行入口bin字段chrome-devtools-mcpMCP 服务器指向./build/src/bin/chrome-devtools-mcp.js和chrome-devtoolsCLI指向./build/src/bin/chrome-devtools.js另有npm run typechecktsc --noEmit、npm run test先构建再经 scripts/test.js 运行并跳过 THIRD_PARTY_NOTICES 相关测试等配套脚本。运行与测试构建出的服务器使用 MCP Inspector构建完成后可以直接用官方 Inspector 连接本地服务器npx modelcontextprotocol/inspector node ./build/src/bin/chrome-devtools-mcp.js这个命令与 package.jsonbin字段声明的chrome-devtools-mcp入口完全对应。注意 scripts/eval_gemini.ts 中也以build/src/bin/chrome-devtools-mcp.js作为被测服务路径如果该文件不存在会直接报错并提示先执行npm run build——这说明先构建、再运行是所有本地验证流程的前置条件。配置到真实 MCP 客户端也可以把本地构建产物直接挂到任意 MCP 客户端的配置里{ mcpServers: { chrome-devtools: { command: node, args: [ /path-to-chrome-devtools-mcp/build/src/bin/chrome-devtools-mcp.js ] } } }将args指向自己 checkout 后的build/src/bin/chrome-devtools-mcp.js绝对路径即可。这与 README.md 中面向用户发布的npx -y chrome-devtools-mcplatest方式形成对照前者用于开发验证后者用于生产使用。VS Code SSH 远程场景的端口转发当通过 VS Code SSH 远程开发并运行modelcontextprotocol/inspector时Inspector 会拉起两个服务分别监听6274和6277端口。VS Code 通常能自动检测并转发6274但往往检测不到6277需要手动添加转发否则 Inspector 页面无法正常连接。调试日志把调试日志写到工作目录下的log.txtnpx modelcontextprotocol/inspector node ./build/src/bin/chrome-devtools-mcp.js --log-file/your/desired/path/log.txt日志类别控制沿用惯例的DEBUG环境变量package.json 中的start-debug脚本即采用NODE_DEBUGmcp:* npm run build node build/src/bin/chrome-devtools-mcp.js的方式聚焦 MCP 相关日志类别。文档与 CLI 的自动生成新增工具、或修改工具的名称/描述后必须运行npm run gen重新生成工具参考文档。从 package.json 可以看到该脚本的完整组成npm run gen # 等价于 # npm run build npm run cli:generate npm run docs:generate npm run update-metrics npm run format即构建 → 生成 CLIscripts/generate-cli.ts→ 生成文档scripts/generate-docs.ts产物即 docs/tool-reference.md 等参考文档→ 更新指标scripts/update_metrics.ts→ 统一格式化。这意味着工具定义是单一事实来源文档不是手写的改完src/tools/下的定义后必须走一遍gen流程。提交与功能发布规范Conventional CommitsPR 标题和 commit 标题需遵循 Conventional Commits 规范如feat:、fix:、chore:等前缀。这一规范同时服务于自动化发布流程见下文。功能发布清单Feature release checklist尚未对用户开放的不完整功能提交时统一使用chore:前缀当功能准备发布时再开一个feat:前缀的 PR 将其启用。发布前必须满足以下四条标准直接引自 CONTRIBUTING.md功能文档保持最新例如 README 和 tools reference 已同步更新功能在 Chrome stable 上可用否则需在文档中明确版本限制如需要对应的 skills 已更新或新增了新的 skill仓库的 skills/ 目录即为这些技能文件所在位置功能必须能独立或结合现有功能完成真实用例——项目明确要避免提供了一组工具却无法真正调试出东西的半成品功能。自动化发布流程chrome-devtools-mcp的版本发布由 GitHub Actions 自动化基于 release-please配置见 release-please-config.json。发布一个新版本的步骤是查找标题为chore(main): release chrome-devtools-mcp的 PR对它进行评审、测试并合并即可。当 main 分支上有会出现在 changelog 中的变更时该 release PR 会被自动创建当前的发布版本记录在 .release-please-manifest.json历史变更见 CHANGELOG.md。更新 Lighthouse 依赖chrome-devtools-mcp把 Lighthouse 打包成内部 bundle 供 Lighthouse 相关工具使用bundle 位于 src/third_party/lighthouse-devtools-mcp-bundle.js因此升级流程比普通的npm install复杂更新 package.json 中的 Lighthouse 版本并执行npm install。当前版本为13.4.1npm 版本目前仅用于获取类型定义将对应的 Lighthouse 仓库版本检出到兄弟目录../lighthouse运行npm run update-lighthouse对应 scripts/update-lighthouse.ts。注意 Lighthouse 本身要求使用 yarn提交生成的 bundle。若 bundle 引入了新依赖需同步更新 tests/third_party_notices.test.ts——该测试用于校验第三方许可声明notices与依赖清单的一致性配套脚本还有 scripts/append-lighthouse-notices.ts。为 Evals 贡献评测场景项目使用 Gemini 对 MCP 服务器工具做端到端评测场景文件放在 scripts/eval_scenarios/如 navigation_test.ts、network_test.ts 等 20 多个场景。每个场景是一个 TypeScript 文件导出实现TestScenario接口的scenario对象。TestScenario接口的完整定义位于 scripts/eval_result.tsexport interface TestScenario { prompt: string; // 发送给模型的提示词 maxTurns: number; // 最大对话轮次 expectations: (result: Result) void; // 验证模型发起的工具调用 htmlRoute?: { // 可选为测试提供自定义 HTML path: string; htmlContent: string; }; serverArgs?: string[]; // 可选传给 MCP 服务器的额外 CLI 参数 }其中htmlRoute用于在测试中于指定路径提供自定义 HTML 内容scripts/eval_gemini.ts 在执行时会将 prompt 中的TEST_URL占位符替换为该路由的真实地址。serverArgs可以注入如--no-page-id-routing之类的额外服务参数。一个典型场景示例摘自 CONTRIBUTING.mdimport {TestScenario} from ../eval_gemini.js; export const scenario: TestScenario { prompt: Navigate to example.com, maxTurns: 2, expectations: calls { // 检查至少有一次 browse_page 调用 const navigation calls.find(c c.name browse_page); if (!navigation) throw new Error(Model did not browse the page); // 校验核心参数 if (navigation.args.url ! http://example.com) { throw new Error(Wrong URL: ${navigation.args.url}); } }, };评测框架的实际断言能力比示例更丰富。expectations接收的是Result对象scripts/eval_result.ts它按顺序消费模型产生的工具调用序列提供assertNextCall(name, expectedArgs?)断言下一次调用的名称与关键参数deepStrictEqual逐字段比较consumePageNavigation()跳过开头/结尾的list_pages样板调用断言发生了new_page或navigate_page并推断出活动页的pageIdhasPageIdRouting根据服务参数中是否含--no-page-id-routing判断路由模式让同一断言兼容两种模式。以 navigation_test.ts 为例expectations: result { if (result.hasPageIdRouting) { result.assertNextCall(list_pages); } assert.ok(result.remainingCalls.length 1); result.assertNextCall(navigate_page, { url: https://developers.chrome.com, pageId: result.hasPageIdRouting ? 1 : undefined, }); },场景设计原则引自 CONTRIBUTING.md验证工具被正确使用但断言不要过严。对可能变化的参数如自然语言推理产生的措辞避免断言精确值但必须确保 URL、选择器等核心参数正确。运行评测的入口是npm run evalpackage.json 中定义为npm run build node scripts/eval_gemini.ts。从 scripts/eval_gemini.ts 的实现可以看到运行时细节以--isolated启动服务器非调试时加--headless、强制设置CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICStrue关闭统计采集、向 prompt 追加随机queryid以避免缓存干扰。若启用 skill 前缀模式还会把 skills/chrome-devtools/SKILL.md 的内容拼接到 prompt 之前。工具 JSON Schema 的硬性约束CONTRIBUTING.md 对src/tools/下所有工具定义的 Zod schema 提出了两条硬性限制并说明由local/enforce-zod-schemaESLint 规则强制检查禁止.nullable()禁止.object()类型复杂对象应表示为简短的格式化字符串。这条规则的实际实现在 scripts/eslint_rules/enforce-zod-schema-rule.js规则扫描工具 schema 文件中的方法调用出现.nullable()即报noNullable建议使用.optional()替代出现zod.object()或z.object()调用即报noObject建议用格式化字符串表达复杂对象。它有意不区分调用者是否为 ZodObject——即拦截所有.nullable()调用。规则在 eslint.config.js 中以error级别应用于src/tools/**/*.ts{ name: Tools definitions, files: [src/tools/**/*.ts], rules: { local/enforce-zod-schema: error, }, },这条约束的工程动机从工具面向 LLM 消费者的定位可以推断嵌套对象和 nullable 类型对模型的参数生成不友好扁平化、字符串化的参数设计能降低模型出错概率。此外同目录的 check-license-rule.js 与 no-direct-third-party-imports-rule.js 分别强制许可证头与第三方导入收口src/下只允许经由 src/third_party/index.ts 引入依赖这些自定义规则与 schema 规则共同构成了项目的 lint 防线。测试、格式化与代码风格日常提交前的验证组合从 package.json 的 scripts 可以整理为npm test构建后通过 scripts/test.js 运行测试默认跳过 THIRD_PARTY_NOTICES 测试许可声明测试单独由npm run test:notices执行npm run test:update-snapshots用于刷新快照快照文件分布在tests/各目录如 tests/tools/console.test.js.snapshotnpm run format/npm run check-formatESLint含上文自定义规则加 Prettier 的格式化与检查npm run typecheck仅做类型检查npm run profile/npm run test:memory基于 scripts/profile/ 的性能剖析与内存泄漏测试对应.github/workflows中的test-memory-leaks.yml等 CI 流程。eslint.config.js 中还定义了若干值得注意的全局约束local/check-license为 error 级别、import/no-cycle禁止循环依赖、第三方导入只能经由devtools-frontend/mcp/mcp.js的出口no-restricted-imports规则、typescript-eslint/consistent-type-imports等贡献代码时保持一致的风格能显著减少评审往返。小结chrome-devtools-mcp的贡献流程可以归纳为一条清晰的主线以 .nvmrc 声明的 Node 版本npm ci npm run build完成本地构建用 Inspector 或真实 MCP 客户端验证行为必要时用--log-file与DEBUG定位问题未完成的工具用chore:提交、成熟后按四条发布清单走feat:启用改动工具定义后必须npm run gen同步文档与 CLI工具 schema 遵守无 nullable、无 object、复杂参数字符串化的 ESLint 硬约束Evals 场景以TestScenario四字段描述提示词 轮次上限 宽松但核心的断言版本发布交给 release PR 自动化。遵循这些约定你的补丁才能顺利通过该项目的评审、CI 与自动化发布链路。【免费下载链接】chrome-devtools-mcpChrome DevTools for coding agents项目地址: https://gitcode.com/GitHub_Trending/chr/chrome-devtools-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考