MCP 服务AI Agent浏览器控制GUI 自动化工具调用人工智能AI 应用【免费下载链接】mcp-chromeChrome 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 ProtocolMCP服务器它把浏览器的窗口、标签页、点击、填表、网络请求、语义搜索等能力以工具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.js20构建与运行扩展、native serverpnpm 或 npm最新版依赖管理与脚本执行仓库为 pnpm workspace推荐 pnpmChrome/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:sharedpnpm --filter chrome-mcp-shared dev以 watch 模式构建 packages/shared 共享包dev:nativepnpm --filter mcp-chrome-bridge dev构建并注册 native messaging hostapp/native-serverdev:extensionpnpm --filter chrome-mcp-server dev以开发模式启动 WXT增量构建扩展buildpnpm -r build顺序构建除 wasm 外的所有子包build:wasmpnpm --filter chrome-mcp/wasm-simd build pnpm run copy:wasm编译 Rust 为 WASM 并拷贝产物到扩展的 workers 目录lint/lint:fixpnpm -r lint全仓 ESLint 检查 / 自动修复formatpnpm -r format全仓 Prettier 格式化typecheckpnpm -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 serverStreamable HTTP 传输层 │ └── src/agent/ # Agent 相关服务会话、项目、工具桥接 ├── packages/ │ ├── shared/ # 共享类型与工具 schemachrome-mcp-shared │ └── wasm-simd/ # SIMD 优化的 WebAssembly 数学库Rust └── docs/ # 架构、贡献、安装、FAQ 等文档关键理解工具 Schema 的“事实来源”在packages/shared工具实现则在 extension 的 background tools 目录。packages/shared/src/tools.ts中定义了TOOL_NAMES工具名常量与TOOL_SCHEMASMCP 工具的 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_pageREAD_PAGE在 tools.ts 中为每个参数都写了面向 LLM 的说明filter可选interactive只返回可交互元素、depth控制遍历深度、refId聚焦某个元素子树chrome_computerCOMPUTER更是定义了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): PromiseToolResult { // 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.tssendMessageToTab(tabId, message, frameId?)向标签页发送消息识别{ error }响应并抛出base-browser.tsgetActiveTabOrThrow()/getActiveTabInWindow(windowId?)获取当前活动标签页可按窗口过滤base-browser.tsensureFocus(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 testvitest或根目录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自动修复。Prettierpnpm 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-stagedprepare阶段注册 husky 钩子提交时对*.{js,ts,vue}自动执行eslint --fixprettier --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:重构不改变行为引擎层代码重组、执行器抽象推送并创建 PRgit 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 HTTPhttp://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、WXTapp/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 等集成测试的写法性能测试基准测试与性能回归检测用户测试真实场景下的功能验证十、贡献者认可与许可项目珍视每一份贡献无论大小。贡献者将获得以下形式的认可README 致谢名单、版本发布说明中的感谢、GitHub 个人页的贡献者徽章以及社区讨论中的特别致谢。按 docs/CONTRIBUTING.md 的约定向 Chrome MCP Server 贡献代码即表示同意您的贡献以 MIT 许可证授权仓库根目录 LICENSE 为 MIT 协议确保社区可以自由使用与改进这些代码。感谢每一位贡献者的参与——正是社区的共同投入让这个项目持续演进。赞分享MCP 服务AI Agent浏览器控制GUI 自动化工具调用人工智能AI 应用【免费下载链接】mcp-chromeChrome 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点击查看免费下载相关推荐如何为RedditOS贡献代码开发者完整指南如何为RedditOS贡献代码开发者完整指南 RedditOS是一个使用SwiftUI构建的macOS原生Reddit客户端专为macOS Big Sur设终极指南如何用dadb库无需ADB直接连接Android设备终极指南如何用dadb库无需ADB直接连接Android设备 dadb是一个革命性的Kotlin/Java开源库它让开发者能够直接与Android设备通信开发工具移动开发如何为normalize.css贡献代码开发者完整指南如何为normalize.css贡献代码开发者完整指南 normalize.css是一个现代化的CSS重置库它通过规范化HTML元素的默认样式为开发者提供前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 为 Chrome MCP Server 项目贡献代码：完整贡献者指南与开发实战
MCP 服务AI Agent浏览器控制GUI 自动化工具调用人工智能AI 应用【免费下载链接】mcp-chromeChrome 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 ProtocolMCP服务器它把浏览器的窗口、标签页、点击、填表、网络请求、语义搜索等能力以工具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.js20构建与运行扩展、native serverpnpm 或 npm最新版依赖管理与脚本执行仓库为 pnpm workspace推荐 pnpmChrome/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:sharedpnpm --filter chrome-mcp-shared dev以 watch 模式构建 packages/shared 共享包dev:nativepnpm --filter mcp-chrome-bridge dev构建并注册 native messaging hostapp/native-serverdev:extensionpnpm --filter chrome-mcp-server dev以开发模式启动 WXT增量构建扩展buildpnpm -r build顺序构建除 wasm 外的所有子包build:wasmpnpm --filter chrome-mcp/wasm-simd build pnpm run copy:wasm编译 Rust 为 WASM 并拷贝产物到扩展的 workers 目录lint/lint:fixpnpm -r lint全仓 ESLint 检查 / 自动修复formatpnpm -r format全仓 Prettier 格式化typecheckpnpm -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 serverStreamable HTTP 传输层 │ └── src/agent/ # Agent 相关服务会话、项目、工具桥接 ├── packages/ │ ├── shared/ # 共享类型与工具 schemachrome-mcp-shared │ └── wasm-simd/ # SIMD 优化的 WebAssembly 数学库Rust └── docs/ # 架构、贡献、安装、FAQ 等文档关键理解工具 Schema 的“事实来源”在packages/shared工具实现则在 extension 的 background tools 目录。packages/shared/src/tools.ts中定义了TOOL_NAMES工具名常量与TOOL_SCHEMASMCP 工具的 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_pageREAD_PAGE在 tools.ts 中为每个参数都写了面向 LLM 的说明filter可选interactive只返回可交互元素、depth控制遍历深度、refId聚焦某个元素子树chrome_computerCOMPUTER更是定义了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): PromiseToolResult { // 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.tssendMessageToTab(tabId, message, frameId?)向标签页发送消息识别{ error }响应并抛出base-browser.tsgetActiveTabOrThrow()/getActiveTabInWindow(windowId?)获取当前活动标签页可按窗口过滤base-browser.tsensureFocus(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 testvitest或根目录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自动修复。Prettierpnpm 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-stagedprepare阶段注册 husky 钩子提交时对*.{js,ts,vue}自动执行eslint --fixprettier --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:重构不改变行为引擎层代码重组、执行器抽象推送并创建 PRgit 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 HTTPhttp://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、WXTapp/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 等集成测试的写法性能测试基准测试与性能回归检测用户测试真实场景下的功能验证十、贡献者认可与许可项目珍视每一份贡献无论大小。贡献者将获得以下形式的认可README 致谢名单、版本发布说明中的感谢、GitHub 个人页的贡献者徽章以及社区讨论中的特别致谢。按 docs/CONTRIBUTING.md 的约定向 Chrome MCP Server 贡献代码即表示同意您的贡献以 MIT 许可证授权仓库根目录 LICENSE 为 MIT 协议确保社区可以自由使用与改进这些代码。感谢每一位贡献者的参与——正是社区的共同投入让这个项目持续演进。赞分享MCP 服务AI Agent浏览器控制GUI 自动化工具调用人工智能AI 应用【免费下载链接】mcp-chromeChrome 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点击查看免费下载相关推荐如何为RedditOS贡献代码开发者完整指南如何为RedditOS贡献代码开发者完整指南 RedditOS是一个使用SwiftUI构建的macOS原生Reddit客户端专为macOS Big Sur设终极指南如何用dadb库无需ADB直接连接Android设备终极指南如何用dadb库无需ADB直接连接Android设备 dadb是一个革命性的Kotlin/Java开源库它让开发者能够直接与Android设备通信开发工具移动开发如何为normalize.css贡献代码开发者完整指南如何为normalize.css贡献代码开发者完整指南 normalize.css是一个现代化的CSS重置库它通过规范化HTML元素的默认样式为开发者提供前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考