Chrome MCP Server开发环境搭建：pnpm workspace与monorepo配置

【免费下载链接】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前需安装Node.js(≥14.0.0)和pnpm包管理器。使用以下命令克隆项目代码库：

git clone https://gitcode.com/gh_mirrors/mc/mcp-chrome.git
cd mcp-chrome

monorepo架构概览

项目采用pnpm workspace实现monorepo架构，通过pnpm-workspace.yaml定义工作区范围：

packages:
  - 'app/*'
  - 'packages/*'

该配置将app/和packages/目录下的所有子目录识别为工作区包，实现跨包依赖管理和统一脚本执行。项目主要包含三类工作包：

• 应用层：Chrome扩展和原生服务器
• 共享层：类型定义和WASM模块
• 工具链：根目录配置文件与脚本

pnpm workspace配置详解

根目录配置

package.json定义了跨包脚本和开发依赖，关键配置包括：

{
  "private": true,
  "type": "module",
  "scripts": {
    "build:shared": "pnpm --filter chrome-mcp-shared build",
    "build:native": "pnpm --filter mcp-chrome-bridge build",
    "build:extension": "pnpm --filter chrome-mcp-server build",
    "dev": "pnpm --filter chrome-mcp-shared build && pnpm -r --parallel dev"
  }
}

使用--filter参数指定包范围，-r参数递归执行所有子包脚本，--parallel实现并行开发构建。

工作区包依赖关系

各子包通过workspace:*协议声明内部依赖，如Chrome扩展依赖共享类型包：

{
  "dependencies": {
    "chrome-mcp-shared": "workspace:*"
  }
}

这种依赖声明方式确保始终使用工作区内的最新代码，避免版本冲突。依赖关系如图所示：

开发环境初始化

安装依赖

在项目根目录执行以下命令安装所有依赖：

pnpm install

pnpm会自动创建工作区依赖链接，避免重复安装。安装完成后生成pnpm-lock.yaml锁定依赖版本。

构建共享模块

共享类型包需要优先构建，因其被其他包依赖：

pnpm build:shared

该命令执行packages/shared/package.json中的构建脚本：

{
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --dts --clean"
  }
}

并行开发工作流

启动所有开发服务的并行构建：

pnpm dev

该命令会并行执行以下开发任务：

1. 共享包监听：packages/shared使用tsup监听文件变化
2. 扩展开发模式：app/chrome-extension启动WXT开发服务器
3. 原生服务器：app/native-server启动Fastify开发服务

开发过程中，代码变更会触发自动构建和热更新，实现全链路开发体验。

构建与部署

全项目构建

执行以下命令构建所有生产产物：

pnpm build

构建流程包括：

1. 编译TypeScript源码至JavaScript
2. 打包Chrome扩展为zip文件
3. 构建WASM SIMD模块
4. 复制产物至目标目录

产物结构

构建完成后生成以下关键产物：

• app/chrome-extension/dist/: Chrome扩展打包文件
• app/native-server/dist/: 原生服务器可执行文件
• packages/wasm-simd/pkg/: WebAssembly模块
• releases/chrome-extension/latest/: 扩展发布包

常见问题解决

依赖安装失败

若出现依赖冲突或安装失败，可尝试清理缓存后重新安装：

pnpm store prune
pnpm install

跨包类型问题

TypeScript类型检查失败时，确保共享包已构建：

pnpm build:shared

扩展调试配置

wxt.config.ts提供Chrome扩展调试配置，默认禁用自动启动，可根据开发需求调整runner设置。

项目资源

• 架构设计：docs/ARCHITECTURE_zh.md
• 开发指南：CONTRIBUTING_zh.md
• 工具文档：TOOLS_zh.md
• 故障排除：TROUBLESHOOTING_zh.md

【免费下载链接】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