# Sansan Chrome MCP

通过 MCP (Model Context Protocol) 让 AI 助手控制你的 Chrome 浏览器。

## 工作原理

```
┌──────────────┐     HTTP/SSE      ┌──────────────────┐    Native Messaging    ┌──────────────────┐
│  AI 助手      │ ◄──────────────► │  Native Server    │ ◄──────────────────►  │  Chrome 扩展      │
│  Claude/等    │   localhost:2733  │  sansan-chrome-   │   com.sansan.chrome   │  Sansan Chrome MCP│
└──────────────┘                   │  bridge           │                      └──────────────────┘
                                   └──────────────────┘
```

AI 助手通过 MCP 协议调用工具 → Native Server 转发请求 → Chrome 扩展执行浏览器操作 → 返回结果。

## 快速开始

### 1. 安装 Native Server

```bash
npm install -g sansan-chrome-bridge
```

安装后 postinstall 会自动注册 Native Messaging host。如注册失败,可手动执行:

```bash
sansan-chrome-bridge register       # 用户级注册(推荐)
sansan-chrome-bridge register --system  # 系统级注册(需管理员权限)
```

### 2. 安装 Chrome 扩展

1. 下载最新的 [sansan-chrome-mcp.zip](../../releases) (或从源码构建,见下方)
2. 解压后在 Chrome 中打开 `chrome://extensions/`
3. 开启「开发者模式」→ 点击「加载已解压的扩展程序」→ 选择解压目录

### 3. 配置 AI 客户端

**Claude Code / kscc:**

在 MCP 配置文件中添加:

```json
{
  "mcpServers": {
    "chrome": {
      "url": "http://127.0.0.1:2733/mcp"
    }
  }
}
```

**Stdio 方式(备选):**

```json
{
  "mcpServers": {
    "chrome": {
      "command": "sansan-chrome-stdio"
    }
  }
}
```

### 4. 验证

```bash
sansan-chrome-bridge doctor
```

该命令会自动检测安装状态、注册表、扩展连接等,并给出修复建议。

## 支持的工具

| 工具 | 说明 |
|------|------|
| `browser_get_windows_and_tabs` | 获取所有窗口和标签页信息 |
| `browser_read_page` | 读取页面内容 |
| `browser_computer` | 鼠标/键盘操控(点击、滚动、输入等) |
| `browser_navigate` | 导航到指定 URL |
| `browser_screenshot` | 页面截图 |
| `browser_close_tabs` | 关闭标签页 |
| `browser_switch_tab` | 切换标签页 |
| `browser_web_fetcher` | 抓取网页内容 |
| `browser_network_request` | 发送网络请求(携带浏览器 Cookie) |
| `browser_network_capture` | 捕获网络请求/响应 |
| `browser_handle_download` | 处理浏览器下载 |
| `browser_history` | 搜索浏览历史 |
| `browser_bookmark_search` | 搜索书签 |
| `browser_bookmark_add` | 添加书签 |
| `browser_bookmark_delete` | 删除书签 |
| `browser_javascript` | 在页面中执行 JavaScript |
| `browser_click` | 点击页面元素 |
| `browser_fill` | 填写表单 |
| `browser_request_element_selection` | 请求用户手动选择元素 |
| `browser_keyboard` | 模拟键盘输入 |
| `browser_console` | 捕获控制台输出 |
| `browser_file_upload` | 上传文件 |
| `browser_handle_dialog` | 处理浏览器对话框(alert/confirm/prompt) |

## CLI 命令

```bash
sansan-chrome-bridge register [--system]    # 注册 Native Messaging host
sansan-chrome-bridge fix-permissions        # 修复执行权限
sansan-chrome-bridge update-port <port>     # 更新 stdio 模式端口
sansan-chrome-bridge doctor [--fix]         # 诊断安装问题(可选自动修复)
sansan-chrome-bridge report                 # 导出诊断报告(用于提交 Issue)
```

## 从源码构建

### 环境要求

- Node.js >= 20
- pnpm >= 10

### 构建

```bash
git clone https://github.com/yourname/chrome-mcp.git
cd chrome-mcp

pnpm install
pnpm build
```

### 开发

```bash
# 同时启动 shared + native-server + extension 开发模式
pnpm dev
```

### 打包扩展

```bash
cd app/chrome-extension
pnpm zip
# 产物在 .output/ 目录下
```

## 项目结构

```
chrome-mcp/
├── packages/
│   └── shared/              # 共享类型、工具定义、常量
│       └── src/
│           ├── constants.ts # HOST_NAME、默认端口等
│           ├── types.ts     # 消息类型、工具类型
│           └── tools.ts     # 所有 MCP 工具 schema
├── app/
│   ├── native-server/       # Native Messaging host (npm: sansan-chrome-bridge)
│   │   └── src/
│   │       ├── cli.ts       # CLI 入口
│   │       ├── mcp/         # MCP Server 实现
│   │       ├── server/      # Fastify HTTP 服务
│   │       ├── native-messaging-host.ts  # Chrome Native Messaging 通信
│   │       └── scripts/     # 注册、诊断、构建脚本
│   └── chrome-extension/    # Chrome 扩展 (Vue 3 + WXT)
│       └── src/
│           ├── entrypoints/ # background、popup、content scripts
│           ├── common/      # 通用工具
│           └── inject-scripts/ # 注入页面的脚本
├── pnpm-workspace.yaml
└── package.json
```

## 发布

详见 [docs/PUBLISHING.md](docs/PUBLISHING.md)

## 故障排除

运行诊断工具:

```bash
sansan-chrome-bridge doctor
```

常见问题:

| 问题 | 解决方案 |
|------|----------|
| `Permission denied` / `Native host has exited` | `sansan-chrome-bridge fix-permissions` |
| Windows 注册表未写入 | 以管理员身份运行 `sansan-chrome-bridge register` |
| 扩展无法连接 | 确认扩展已安装且 Chrome 已重启 |
| 端口冲突 | `sansan-chrome-bridge update-port <新端口>` |

更多排查步骤见 [app/native-server/install.md](app/native-server/install.md)

## 致谢

本项目基于 [mcp-chrome](https://github.com/hangwin/mcp-chrome) 修改而来，感谢原作者 [@hangwin](https://github.com/hangwin) 的工作。

## License

MIT