为 Chrome MCP Server 项目贡献代码：完整贡献者指南与开发实战-平芜编程栈

MCP 服务
AI Agent
浏览器控制
GUI 自动化
工具调用
人工智能
AI 应用

【免费下载链接】mcp-chrome

Chrome MCP Server is a Chrome extension-based Model Context Protocol (MCP) server that exposes your Chrome browser functionality to AI assistants like Claude, enabling complex browser automation, content analysis, and semantic search.

项目地址：https://gitcode.com/gh_mirrors/mc/mcp-chrome

点击查看免费下载

Chrome MCP Server 是一个基于 Chrome 扩展的 Model Context Protocol（MCP）服务器，它把浏览器的窗口、标签页、点击、填表、网络请求、语义搜索等能力以工具（Tool）的形式暴露给 Claude 等 AI 助手。本文以仓库中的 docs/CONTRIBUTING.md 为骨架，结合 monorepo 内的源码、配置与测试，系统讲解从环境搭建、工具开发、代码规范到提交流程的完整协作方式，读完你将具备在本仓库中独立实现一个新浏览器工具、并通过测试与 PR 流程合入的能力。

一、贡献形式：从 Bug 报告到功能开发

项目欢迎多种形式的贡献，按参与深度从轻到重可分为：

贡献类型	说明	典型例子
🐛 Bug 报告与修复	提交可复现的问题描述，或直接提交修复补丁	某个工具在 iframe 场景下点击失效
✨ 新功能与新工具	在 MCP 工具层新增浏览器能力	新增`chrome_history`、`chrome_bookmark_search`等
📚 文档改进	修正错误、补充示例、完善 docs 目录	更新 README_zh.md
🧪 测试与性能优化	补单元/集成测试、优化执行路径	为 record-replay 引擎补充契约测试
🌐 翻译与国际化	维护 app/chrome-extension/_locales 下各语言包	完善 zh_TW、ko、ja 的 messages.json
💡 想法与建议	在 Discussions 中提出方向性建议	新交互模式、新 MCP 资源类型

不同规模的贡献对应不同的协作路径：小到一条 issue 的复现步骤，大到一次横跨 extension 与 native-server 两个子包的架构改进，都遵循同一套流程，即“Fork → 开发 → 测试 → PR”。

二、开发环境准备

2.1 前置依赖

依赖	版本要求	用途
Node.js	20+	构建与运行扩展、native server
pnpm 或 npm	最新版	依赖管理与脚本执行（仓库为 pnpm workspace，推荐 pnpm）
Chrome/Chromium	最新稳定版	扩展加载与功能测试
Git	任意较新版本	版本控制
Rust	可选	packages/wasm-simd 的 WASM SIMD 开发
TypeScript 知识	——	绝大多数源码使用严格 TypeScript 编写

2.2 Fork 与克隆

git clone https://github.com/YOUR_USERNAME/chrome-mcp-server.git cd chrome-mcp-server

本仓库为镜像仓库（gh_mirrors/mc/mcp-chrome），如需在本地基于上游开发，可git clone对应的上游地址后进入目录操作。

2.3 安装依赖

仓库根目录是 pnpm workspace（见 pnpm-workspace.yaml），一键安装全部子包依赖：

pnpm install

安装完成后，根 package.json 提供了一组与贡献者强相关的脚本，常用几个：

脚本	命令	作用
`dev:shared`	`pnpm --filter chrome-mcp-shared dev`	以 watch 模式构建 packages/shared 共享包
`dev:native`	`pnpm --filter mcp-chrome-bridge dev`	构建并注册 native messaging host（app/native-server）
`dev:extension`	`pnpm --filter chrome-mcp-server dev`	以开发模式启动 WXT，增量构建扩展
`build`	`pnpm -r build`	顺序构建除 wasm 外的所有子包
`build:wasm`	`pnpm --filter @chrome-mcp/wasm-simd build && pnpm run copy:wasm`	编译 Rust 为 WASM 并拷贝产物到扩展的 workers 目录
`lint`/`lint:fix`	`pnpm -r lint`	全仓 ESLint 检查 / 自动修复
`format`	`pnpm -r format`	全仓 Prettier 格式化
`typecheck`	`pnpm -r exec tsc --noEmit`	全仓 TypeScript 类型检查

2.4 启动与加载扩展

由于共享包是扩展与 native server 共同依赖的，推荐从根目录按依赖顺序启动：

# 方式一：根目录并行开发（会先构建 shared，再并行 watch 各子包） pnpm dev # 方式二：分步启动，先起共享包 pnpm dev:shared # 再起扩展（另一终端） pnpm dev:extension

扩展启动后，WXT 会把产物输出到.output/目录（WXT 的默认输出目录，可在 app/chrome-extension/wxt.config.ts 中确认相关配置）。然后在 Chrome 中加载：

打开chrome://extensions/
开启右上角“开发者模式”（Developer mode）
点击“加载已解压的扩展程序”（Load unpacked），选择app/chrome-extension/.output/chrome-mv3（开发模式下 WXT 生成的 Manifest V3 产物目录）
点击扩展图标，打开弹窗并连接，即可看到 MCP 配置信息

需要说明的是：原文档中“选择your/extension/dist”是一般性描述，在本仓库实际开发环境中产物位于 app/chrome-extension 下的.output目录（WXT 约定），以实际生成的目录名为准。

另外，扩展的 Manifest 在 app/chrome-extension/wxt.config.ts 中通过defineConfig声明，开发模式下 WXT 会自动处理 dev server 的资源加载；生产构建才启用cross_origin_embedder_policy: require-corp、自定义 CSP 等安全策略（见该文件第 112-122 行），调试时注意区分两种模式的行为差异。

三、项目结构：Monorepo 全景

原文档给出了仓库的结构骨架，对照当前仓库可进一步细化为一张“贡献者视角”的目录地图：

chrome-mcp-server/（monorepo 根） ├── app/ │ ├── chrome-extension/ # Chrome 扩展（WXT + Vue 3） │ │ ├── entrypoints/ # background / popup / content / sidepanel 等入口 │ │ │ └── background/tools/ # 浏览器 MCP 工具实现（browser/、record-replay/ 等） │ │ ├── utils/ # 向量数据库、模型缓存、语义相似度等工具 │ │ ├── inject-scripts/ # 注入页面运行的辅助脚本（点击、表单、录制等） │ │ ├── workers/ # AI 处理相关 Web Worker（含 wasm 产物） │ │ ├── _locales/ # i18n 多语言包（de/en/ja/ko/zh_CN/zh_TW） │ │ └── tests/ # vitest 测试（record-replay、web-editor-v2 等） │ └── native-server/ # Native Messaging 宿主（Node + Fastify） │ ├── src/mcp/ # MCP 协议实现（stdio 与 HTTP 两种入口） │ ├── src/server/ # HTTP server（Streamable HTTP 传输层） │ └── src/agent/ # Agent 相关服务（会话、项目、工具桥接） ├── packages/ │ ├── shared/ # 共享类型与工具 schema（chrome-mcp-shared） │ └── wasm-simd/ # SIMD 优化的 WebAssembly 数学库（Rust） └── docs/ # 架构、贡献、安装、FAQ 等文档

关键理解：工具 Schema 的“事实来源”在packages/shared，工具实现则在 extension 的 background tools 目录。packages/shared/src/tools.ts中定义了TOOL_NAMES（工具名常量）与TOOL_SCHEMAS（MCP 工具的 JSON Schema 列表），它们同时被扩展端和 native 端引用：

扩展端：app/chrome-extension/entrypoints/background/tools/browser/index.ts 把clickTool、fillTool、screenshotTool等实现统一导出；
native 端：app/native-server/src/mcp/mcp-server-stdio.ts 直接import { TOOL_SCHEMAS } from 'chrome-mcp-shared'注册ListTools处理器（第 78 行），通过 Streamable HTTP 客户端把工具调用转发给扩展端。

因此，修改或新增工具时，共享包的tools.ts是必须同步的第一个文件。

四、核心开发流程：新增一个浏览器工具

原文档给出了“定义 Schema → 实现 → 导出 → 测试”四步流程，下面结合源码逐条展开为可直接照做的清单。

4.1 第一步：在共享包定义工具 Schema

编辑 packages/shared/src/tools.ts，先在TOOL_NAMES.BROWSER中登记工具名，再向TOOL_SCHEMAS追加完整的 MCP 工具定义。参考仓库中已有的READ_PAGE工具写法：

{ name: TOOL_NAMES.BROWSER.YOUR_NEW_TOOL, description: 'Description of what your tool does', inputSchema: { type: 'object', properties: { // 定义参数：type、description、enum、default 等 }, required: ['param1'], }, }

真实 Schema 通常比示例更精细。例如chrome_read_page（READ_PAGE）在 tools.ts 中为每个参数都写了面向 LLM 的说明：filter可选"interactive"只返回可交互元素、depth控制遍历深度、refId聚焦某个元素子树；chrome_computer（COMPUTER）更是定义了action枚举（left_click、right_click、scroll、type、fill_form、wait、screenshot等十余种）与ref/coordinates/startCoordinates等完整交互参数（tools.ts）。

实践要点：description 与参数注释是给 AI 看的“使用说明书”，写得越具体，模型调用工具的准确率越高。仓库中COMPUTER的描述甚至包含“点击时把光标尖端对准元素中心、不要点击边缘”这类操作指引。

4.2 第二步：实现工具执行器

在 app/chrome-extension/entrypoints/background/tools/browser/ 下新建实现文件，继承基础类：

class YourNewTool extends BaseBrowserToolExecutor { name = TOOL_NAMES.BROWSER.YOUR_NEW_TOOL; async execute(args: YourToolParams): Promise<ToolResult> { // Implementation } }

BaseBrowserToolExecutor定义在 app/chrome-extension/entrypoints/background/tools/base-browser.ts，它基于 app/chrome-extension/common/tool-handler.ts 的ToolExecutor接口，提供了一组开箱即用的受保护方法：

方法	作用	源码位置
`injectContentScript(tabId, files, ...)`	先向标签页 ping 探测脚本是否已注入，未注入再执行`chrome.scripting.executeScript`，带 300ms 超时保护	base-browser.ts
`sendMessageToTab(tabId, message, frameId?)`	向标签页发送消息，识别`{ error }`响应并抛出	base-browser.ts
`getActiveTabOrThrow()`/`getActiveTabInWindow(windowId?)`	获取当前活动标签页（可按窗口过滤）	base-browser.ts
`ensureFocus(tab, { activate, focusWindow })`	可选地聚焦窗口/激活标签页，避免工具调用抢焦点	base-browser.ts

仓库中ClickTool与FillTool就是继承该基类的真实范例（见 app/chrome-extension/entrypoints/background/tools/browser/interaction.ts 第 32、172 行），它们内部通过injectContentScript注入 inject-scripts/click-helper.js 等辅助脚本，再经由内容脚本与页面交互——这是本仓库“background 工具 + 注入脚本”的典型实现模式。

4.3 第三步：导出工具

在 app/chrome-extension/entrypoints/background/tools/browser/index.ts 中追加一行导出，例如：

export { yourNewTool } from './your-new-tool';

该文件目前导出了 20 余个工具（navigate、screenshot、click、fill、read-page、computer、network-capture、history、bookmark、userscript、performance 等），新工具加入后会自动成为 MCP 可发现能力的一部分。

4.4 第四步：编写测试

测试目录与源码结构一一对应：

扩展端单元/集成测试位于 app/chrome-extension/tests，例如 record-replay/high-risk-actions.integration.test.ts、record-replay-v3/queue.contract.test.ts；
运行测试：pnpm --filter chrome-mcp-server test（vitest）或根目录pnpm test；
测试环境由 app/chrome-extension/vitest.config.ts 与 app/chrome-extension/tests/vitest.setup.ts 提供：使用 jsdom 环境，fake-indexeddb/auto提供 IndexedDB polyfill，并内置一套 mock 的chrome全局对象（tabs、storage、debugger、webRequest、contextMenus 等），保证测试可以在无浏览器环境下运行。

4.5 验证 MCP 兼容性

用 MCP Inspector 或任意 MCP 客户端（Claude Desktop、CherryStudio 等）连接扩展，确认新工具的 Schema 能被正确枚举；
验证工具返回结构符合 MCP 的CallToolResult规范。可参考 native 端代理的兜底实现 app/native-server/src/mcp/mcp-server-stdio.ts（错误时返回isError: true的文本结果），理解协议层对工具返回的约束；
手工在 Chrome 中跑一遍真实场景（打开页面、点击、填表、截图），确认注入脚本与 background 的通信链路正常。

五、代码风格与质量门槛

原文档要求如下，这里补充仓库中的具体落实方式：

TypeScript 严格模式：根 tsconfig 及各子包 tsconfig 均启用严格检查；合入前建议跑pnpm typecheck全仓类型检查。
ESLint：规则配置见 eslint.config.js（根）与 app/chrome-extension/eslint.config.js，执行pnpm lint检查、pnpm lint:fix自动修复。
Prettier：pnpm format统一格式；pnpm format:check只检查不修改。
命名与注释：工具类采用XxxTool命名（ClickTool、FillTool），工具名常量统一登记在TOOL_NAMES；公开 API 尽量补充 JSDoc，仓库中大量工具实现（如 base-browser.ts 的每个方法）都带说明性注释。
错误处理：工具执行不得静默失败。参考BaseBrowserToolExecutor.injectContentScript在注入失败时抛出带ERROR_MESSAGES.TOOL_EXECUTION_FAILED前缀的异常（base-browser.ts）。
提交前自动检查：根 package.json 配置了 husky + lint-staged，prepare阶段注册 husky 钩子，提交时对*.{js,ts,vue}自动执行eslint --fix+prettier --write，对*.{json,md,yaml,html,css}执行 prettier 格式化。

六、Pull Request 流程与提交规范

原文档的 PR 流程为：建分支 → 改代码 → 测试 → 提交 → 推送 → 提 PR，逐条细化如下：

创建功能分支

git checkout -b feature/your-feature-name

完成修改并补充测试与文档：新功能必须带测试；涉及行为变化的要同步更新 docs 下相关文档（如 TOOLS.md、CHANGELOG.md）。
测试与手工验证：运行相关子包的测试套件（vitest / jest），在 Chrome 中手工复测，并确认与 MCP 协议兼容。
按 Conventional Commits 规范提交

git add . git commit -m "feat: add your feature description"

提交信息类型与仓库约束保持一致。仓库根目录的 commitlint.config.cjs 继承@commitlint/config-conventional，即提交信息必须符合 Conventional Commits 规范，否则会被 commitlint 拦截。常用的类型前缀：

前缀	用途	仓库内示例
`feat:`	新功能 / 新工具	新增浏览器工具、新增 record-replay 能力
`fix:`	Bug 修复	修复元素定位、网络捕获等缺陷
`docs:`	文档变更	更新 README_zh.md 或 docs 各篇
`test:`	新增/修改测试	新增契约测试、集成测试
`refactor:`	重构（不改变行为）	引擎层代码重组、执行器抽象

推送并创建 PR

git push origin feature/your-feature-name

创建 PR 时请在描述中说明：改动动机、影响范围、测试方式、以及是否涉及 Schema 变更（Schema 变更意味着 MCP 客户端可见能力发生变化，需格外审慎）。

七、Bug 报告与功能建议模板

7.1 报告 Bug 时应提供的信息

环境：操作系统、Chrome 版本、Node.js 版本
复现步骤：清晰、可逐步操作的过程描述
预期行为：应当发生什么
实际行为：实际发生了什么
截图/日志：如有则附上
MCP 客户端：使用的客户端类型（Claude Desktop 等）

诊断时可以参考仓库的调试基础设施：扩展端可在 background 的 console 观察工具执行日志；native 端使用 pino 日志（依赖见 app/native-server/package.json）。此外 docs/TROUBLESHOOTING.md 与 docs/TROUBLESHOOTING_zh.md 汇总了常见问题排查路径，报告前建议先对照检查。

7.2 提交功能建议时应提供的信息

使用场景（Use case）：为什么需要该功能
方案设想（Proposed solution）：预期的工作方式
替代方案（Alternatives）：考虑过的其他思路
补充上下文：截图、示例等

八、开发技巧与进阶调试

8.1 WASM SIMD 包的开发与构建

packages/wasm-simd 是使用 Rust 编写的 SIMD 数学库，用于语义搜索中的余弦相似度等向量运算，其核心实现在 packages/wasm-simd/src/lib.rs（通过wide::f32x4实现 4 路 SIMD，并提供cosine_similarity、batch_similarity、similarity_matrix等导出函数）。开发该包需要：

cd packages/wasm-simd # 安装 Rust 工具链与 wasm-pack（如未安装） curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh cargo install wasm-pack # 构建 WASM 包（构建脚本见 packages/wasm-simd/package.json） pnpm build

构建产物（simd_math.js与simd_math_bg.wasm）随后会被复制到 app/chrome-extension/workers 目录。根目录也提供了聚合脚本：

pnpm build:wasm # = pnpm --filter @chrome-mcp/wasm-simd build && pnpm run copy:wasm

仓库已内置构建后的产物文件（workers/simd_math.js、workers/simd_math_bg.wasm），普通功能开发无需重编；只有修改了 Rust 源码才需要走上述流程。WASM 加载依赖 Web Worker，相关调度与用法可在 app/chrome-extension/workers/similarity.worker.js 与 app/chrome-extension/utils/simd-math-engine.ts 中查阅。

8.2 Chrome 扩展调试

使用 Chrome DevTools 调试 popup 与 background 脚本（background 作为 MV3 service worker，可在chrome://extensions/中点击“Service Worker”链接打开其 DevTools）
在chrome://extensions/页面检查扩展错误与权限状态
用console.log输出关键调用链（扩展代码本身大量使用了这一方式，例如 base-browser.ts 中每个注入步骤都有日志）
监控 background 中 native messaging 连接的状态，确认扩展与 app/native-server 宿主的握手是否正常

8.3 MCP 协议测试

使用 MCP Inspector 进行协议级调试（枚举工具、调用工具、观察原始请求/响应）
用不同 MCP 客户端（Claude Desktop、CherryStudio、自定义客户端）交叉验证，特别关注 Streamable HTTP（http://127.0.0.1:12306/mcp）与 STDIO 两种连接方式下的行为一致性，配置示例见 README.md 与 app/native-server/src/mcp/stdio-config.json
核对工具 Schema 与返回结构与 MCP 规范一致

九、面向新老贡献者的建议

新贡献者起步路径

从小任务开始：优先认领标记为good first issue的问题（Bug 修复、文档补充、测试补齐）
通读代码：先读 docs/ARCHITECTURE.md 与 docs/ARCHITECTURE_zh.md 建立整体认知，再沿着“packages/shared/src/tools.ts→background/tools/browser/*→inject-scripts/*”这条工具链路精读
大胆提问：在 GitHub Discussions 或 issue 中提问，说明你的探索结论
熟悉工具链：Git、GitHub、TypeScript、WXT（app/chrome-extension 的扩展框架）、Vue 3 与 pnpm workspace

经验丰富贡献者的进阶方向

架构改进：提出跨模块的系统级设计（如 record-replay 引擎 app/chrome-extension/entrypoints/background/record-replay-v3 与 v2 的关系梳理）
性能优化：定位并消除瓶颈（向量检索、大页面 DOM 分析、长流程回放等）
复杂新功能：设计与实现跨扩展端/native 端的新能力（如新的 MCP Resources 或 Prompts 能力）
指导新人：帮助新贡献者完成第一个 PR

文档类贡献

API 文档：完善工具文档与示例（docs/TOOLS.md、docs/TOOLS_zh.md）
教程：编写使用指南与最佳实践（参考 docs/VisualEditor.md 这类专题文档的写法）
翻译：维护 docs 下的中英双语文档与 app/chrome-extension/_locales 的多语言包
演示内容：录制演示视频与操作教程

测试类贡献

单元测试：为工具执行器与工具函数补充用例
集成测试：覆盖组件间的交互（参考 app/chrome-extension/tests/record-replay/hybrid-actions.integration.test.ts 等集成测试的写法）
性能测试：基准测试与性能回归检测
用户测试：真实场景下的功能验证