内容
<p align="center">
<img src="extension/icons/icon-128.png" alt="BrowserMCP" width="96" height="96">
</p>
<h1 align="center">BrowserMCP</h1>
<p align="center">
<strong>通过模型上下文协议远程控制浏览器标签页</strong>
</p>
<p align="center">
<a href="#-features"><img src="https://img.shields.io/badge/tools-40-6366f1" alt="40 Tools"></a>
<a href="#-resources"><img src="https://img.shields.io/badge/resources-6-22c55e" alt="6 Resources"></a>
<a href="#-prompts"><img src="https://img.shields.io/badge/prompts-5-f59e0b" alt="5 Prompts"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-64748b" alt="MIT License"></a>
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-339933" alt="Node >=18"></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-1.0-8b5cf6" alt="MCP 1.0"></a>
</p>
<p align="center">
<a href="#-quick-start">快速开始</a> •
<a href="#-tools">工具</a> •
<a href="#-resources">资源</a> •
<a href="#-prompts">提示</a> •
<a href="#-project-structure">结构</a> •
<a href="#-configuration">配置</a> •
<a href="#-security">安全</a>
</p>
---
BrowserMCP 通过 SSE 传输暴露了 **40 个 Chrome 自动化工具**、**6 个资源** 和 **5 个提示**，适用于任何 MCP 客户端（Claude、opencode、Cursor、自定义代理）。导航页面、提取内容、填写表单、截图等，所有操作都可以通过浏览器扩展完成。
## 架构
```
┌──────────────┐ SSE :3101 ┌──────────────────┐
│ MCP 客户端 │◄──────────────────►│ Node MCP 服务器 │
│ (Claude, │ │ index.js + src/ │
│ opencode) │ └────────┬─────────┘
└──────────────┘ │
WS :3100
│
┌────────────▼─────────┐
│ Chrome 扩展程序 │
│ 服务工作线程 │
│ 弹出式 UI │
└──────────────────────┘
```
| 层级 | 技术 | 端口 | 角色 |
|-------|------|------|------|
| **MCP 服务器** | Node.js + `@modelcontextprotocol/sdk` | `3101` | 工具/资源/提示注册、验证、错误边界 |
| **WebSocket 桥接** | `ws` | `3100` | MCP 服务器和扩展程序之间的消息中继 |
| **Chrome 扩展程序** | 清单 V3、扩展程序 API | — | 执行 CDP 命令（导航、点击、截图等） |
## 功能
- **40 个工具** — 标签页管理、页面内容、交互、JS 执行、视觉、元素查询、实用工具
- **6 个资源** — 实时标签页列表、页面文本/HTML/标题/链接、截图
- **5 个提示** — 抓取、填写表单、调试、总结、提取数据
- **SSE 传输** — 标准 MCP 协议，与任何 MCP 客户端兼容
- **标签页范围** — 限制操作到所有标签页或选定的子集
- **权限切换** — 从弹出式窗口启用/禁用单个工具
- **优雅关闭** — SIGTERM/SIGINT 排空待处理请求后退出
- **错误边界** — 类型错误类别（`[ValidationError]`、`[ConnectionError]`、`[AccessError]`）
- **DI 模式** — 桥接注入处理程序，易于单元测试
## 快速开始
### 1. 安装
```bash
git clone <your-repo-url>
cd BrowserMCP-Extentions
npm install
```
### 2. 启动服务器
```bash
npm start
```
```
[MCP] HTTP 服务器在端口 3101 上启动（SSE 传输）
```
### 3. 加载扩展程序
1. 打开 `chrome://extensions`
2. 启用 **开发者模式** （右上角）
3. 点击 **加载解压** → 选择 `extension/` 目录
4. 扩展程序自动连接到 `ws://127.0.0.1:3100`
### 4. 配置 MCP 客户端
```json
{
"mcpServers": {
"browser": {
"type": "sse",
"url": "http://localhost:3101/mcp"
}
}
}
```
健康检查：
```bash
curl http://localhost:3101/health
```
```json
{ "ok": true, "connected": true }
```
### 5. 验证
打开扩展程序弹出窗口 — 您应该看到带有绿色徽章的 **在线**。运行一个工具：
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_tabs",
"arguments": {}
}
}
```
## 工具
<details>
<summary><strong>标签页管理</strong> (7 个工具)</summary>
| 工具 | 描述 |
|------|-------------|
| `list_tabs` | 列出所有打开的标签页 |
| `get_active_tab` | 获取当前活动的标签页 |
| `navigate` | 导航到 URL |
| `create_tab` | 打开新标签页 |
| `close_tab` | 关闭标签页 ID |
| `switch_to_tab` | 切换到标签页 |
| `reload_tab` | 重新加载标签页 |
</details>
<details>
<summary><strong>页面内容</strong> (9 个工具)</summary>
| 工具 | 描述 |
|------|-------------|
| `get_page_text` | 获取页面文本内容 |
| `get_page_html` | 获取完整页面 HTML |
| `get_page_title` | 获取文档标题 |
| `get_selected_text` | 获取用户文本选择 |
| `get_links` | 提取所有链接 |
| `get_images` | 提取所有图像 |
| `get_forms` | 列出表单字段 |
| `get_meta_tags` | 提取元标签 |
| `get_page_dimensions` | 页面滚动/视口大小 |
</details>
<details>
<summary><strong>交互</strong> (10 个工具)</summary>
| 工具 | 描述 |
|------|-------------|
| `click` | 按 CSS 选择器点击元素 |
| `fill` | 设置输入值 |
| `select_option` | 选择下拉选项 |
| `hover` | 悬停在元素上 |
| `focus` | 焦点元素 |
| `press_key` | 分派键盘事件 |
| `scroll` | 滚动到 x,y 位置 |
| `scroll_to_element` | 滚动元素到视图中 |
| `scroll_to_bottom` | 滚动到页面底部 |
| `scroll_to_top` | 滚动到页面顶部 |
</details>
<details>
<summary><strong>JS 和数据</strong> (4 个工具)</summary>
| 工具 | 描述 |
|------|-------------|
| `execute_js` | 运行任意 JavaScript |
| `get_cookies` | 获取页面 cookie |
| `get_local_storage` | 获取 localStorage 内容 |
| `get_session_storage` | 获取 sessionStorage 内容 |
</details>
<details>
<summary><strong>视觉</strong> (3 个工具)</summary>
| 工具 | 描述 |
|------|-------------|
| `screenshot` | 捕获可见标签页为 PNG |
| `highlight_element` | 在元素上高亮显示 |
| `inject_css` | 将自定义 CSS 注入页面 |
</details>
<details>
<summary><strong>元素查询</strong> (6 个工具)</summary>
| 工具 | 描述 |
|------|-------------|
| `get_element_text` | 获取元素文本内容 |
| `get_element_html` | 获取元素外部 HTML |
| `get_element_rect` | 获取元素边界矩形 |
| `get_element_attribute` | 读取元素属性 |
| `set_element_attribute` | 写入元素属性 |
| `get_elements_count` | 计算匹配元素 |
</details>
<details>
<summary><strong>实用工具</strong> (1 个工具)</summary>
| 工具 | 描述 |
|------|-------------|
| `wait` | 等待 N 毫秒 |
</details>
## 资源
| URI | 模式 | 描述 |
|-----|--------|-------------|
| `chrome://tabs` | `text/plain` | 实时标签页列表为 JSON |
| `chrome://page/text` | `text/plain` | 当前页面文本内容 |
| `chrome://page/html` | `text/plain` | 当前页面 HTML |
| `chrome://page/title` | `text/plain` | 页面标题 |
| `chrome://page/links` | `text/plain` | 所有页面链接为 JSON |
| `chrome://page/screenshot` | `text/plain` | Base64 编码的 PNG 截图 |
> 资源返回纯文本 — MCP 客户端适当地渲染它。
## 提示
| 提示 | 输入 | 输出 |
|--------|-------|--------|
| `scrape_page` | 选择器？ | 提取代理：获取文本、链接、图像 → 格式化摘要 |
| `fill_form` | 选择器、值 | 填充代理：查找表单字段、填充值、提交 |
| `debug_page` | — | 诊断代理：标题、URL、元标签、控制台状态、表单 |
| `summarize_page` | — | 摘要代理：提取和压缩页面内容 |
| `extract_data` | 模式 | 提取代理：拉取匹配模式的结构化数据 |
## 扩展程序弹出窗口
Chrome 扩展程序弹出窗口提供对 MCP 服务器的完全控制：
- **连接状态** — 绿色/灰色/红色徽章指示器
- **服务器 URL** — 可配置的 WebSocket 端点
- **标签页信息** — 当前标签页标题、URL、图标
- **范围切换** — `所有` 标签页或 `选定` 子集
- **搜索** — 按名称过滤 40 个工具（去抖动）
- **可折叠类别** — 7 个组和工具计数
- **批量操作** — 启用所有、禁用所有、展开所有、折叠
## 项目结构
```
BrowserMCP-Extentions/
├── index.js # 入口点：HTTP + SSE，DI 连接
├── package.json
│
├── src/
│ ├── bridge.js # WS 工厂、权限状态、待处理队列
│ ├── tools.js # 40 个工具定义 + validateArgs + 错误边界
│ ├── resources.js # 6 个资源处理程序 + 错误边界
│ ├── prompts.js # 5 个提示模板
│ ├── lifecycle.js # 优雅关闭（SIGTERM/SIGINT）
│ └── config.js # 端口和超时常量
│
├── extension/
│ ├── manifest.json # 清单 V3
│ ├── background.js # 服务工作线程：WS 桥接、40 个工具实现
│ ├── content.js # 内容脚本
│ ├── popup.html # 现代弹出式 UI
│ ├── popup.js # 弹出式逻辑
│ └── icons/ # 扩展程序图标（16、48、128）
│
├── scripts/
│ └── generate-icons.cjs # 图标生成（sharp）
│
└── README.md
```
## 配置
`src/config.js` 中的所有常量：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `EXT_WS_PORT` | `3100` | 扩展程序桥接的 WebSocket 端口 |
| `HTTP_PORT` | `3101` | SSE 传输的 HTTP 端口 |
| `EXT_TIMEOUT` | `60000` | 扩展程序响应超时（毫秒） |
## 安全
- **仅限本地** — 扩展程序在您的本地浏览器中运行；无远程访问
- **标签页范围** — `selected` 模式限制哪些标签页工具可以操作
- **权限同步** — 从弹出窗口到服务器通过 `update_allowlist` 的工具启用/禁用状态同步
- **输入验证** — 每个工具在执行前验证必需参数
- **错误边界** — 故障分类为 `[ValidationError]`、`[ConnectionError]` 或 `[AccessError]`
- **优雅关闭** — SIGTERM/SIGINT 拒绝待处理承诺，清理所有连接
## 开发
```bash
# 语法检查
node --check index.js
node --check src/*.js
node --check extension/popup.js
# 重新生成图标
node scripts/generate-icons.cjs
# 需求
# Node.js >= 18
# Chrome （用于扩展程序）
```
## 许可证
MIT
