内容
# 浏览器反馈 MCP for Claude 代码
一款模型上下文协议（MCP）服务器，能够直接在 Claude 代码中启用可视化浏览器反馈收集。用户可以指向浏览器中的元素并发送带注释的反馈，Claude 可以立即采取行动。
## 工作原理
```
┌─────────────────────────────────────────────────────────────────┐
│ 您的 Web 应用程序（localhost:3000） │
│ │
│ [由浏览器扩展程序提供的部件] │
│ │
│ ┌──────────────────┐ │
│ 您的应用程序 UI │ 添加注释 │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
WebSocket
▼
┌─────────────────────────────────────────────────────────────────┐
│ browser-feedback-mcp 服务器（localhost:9877） │
└─────────────────────────────────────────────────────────────────┘
│
MCP 协议
▼
┌─────────────────────────────────────────────────────────────────┐
│ Claude 代码 │
│ │
│ "让我注释" → 安装部件 → 等待 → 接收反馈 │
└─────────────────────────────────────────────────────────────────┘
```
## 安装
### 1. 安装 MCP 服务器
```bash
# 克隆仓库
git clone https://github.com/itk-dev/mcp-claude-code-browser-feedback.git
cd mcp-claude-code-browser-feedback
# 安装依赖项
npm install
```
### 2. 添加到 Claude 代码
```bash
claude mcp add --scope user browser-feedback node /path/to/mcp-claude-code-browser-feedback/src/server.js
```
或手动添加到您的 Claude 代码 MCP 配置中：
```json
{
"mcpServers": {
"browser-feedback": {
"command": "node",
"args": ["/path/to/mcp-claude-code-browser-feedback/src/server.js"],
"env": {
"FEEDBACK_PORT": "9877"
}
}
}
}
```
### 3. 安装浏览器扩展程序
该扩展程序将部件交付到任何具有单个切换按钮的标签页，无需更改您的项目文件。让 Claude 运行 `setup_extension` 工具，该工具打开扩展程序文件夹并显示说明，或手动安装：
#### Chrome
1. 导航到 `chrome://extensions`
2. 启用 **开发者模式** （右上角的切换按钮）
3. 点击 **加载解包**
4. 选择此仓库中的 `extension/` 文件夹
#### Firefox
1. 导航到 `about:debugging#/runtime/this-firefox`
2. 点击 **加载临时加载项...**
3. 从此仓库中选择 `extension/manifest.json`
## 使用
### 基本工作流程
通过扩展程序在您的应用程序的标签页中打开部件：
1. 点击浏览器工具栏中的扩展程序图标
2. 在当前标签页中切换部件 ON - “添加注释”按钮出现，无需更改文件
3. 切换 OFF 以干净地删除部件
扩展程序默认连接到 `http://localhost:9877` 处的 MCP 服务器（可在弹出窗口中配置），并通过项目 URL 自动匹配标签页到您的 Claude 代码会话。
然后告诉 Claude 您想给它展示某些内容：
```
您：结账按钮有一个错误，让我给您看看
Claude：[调用：wait_for_browser_feedback]
点击浏览器中的“添加注释”，然后点击有问题的元素。
--- 您使用浏览器部件选择按钮 ---
Claude：我收到了您的反馈！我可以看到：
📸 截图已捕获
🎯 元素：<button class="checkout-btn" disabled>
📝 您的描述：“即使购物车中有物品，按钮仍保持禁用状态”
🔴 控制台错误：“TypeError: Cannot read property 'items' of null”
让我查看结账代码并修复这个问题...
```
### 多个注释
您可以一次提交多个反馈项：
```
您：我有几个问题要给您看
Claude：[调用：wait_for_multiple_feedback]
提交所有注释，然后点击完成。
--- 您提交 3 个反馈项，然后点击完成 ---
Claude：我收到了 3 个反馈项。让我逐一解决...
```
### 离线导出
部件无需服务器连接即可工作。离线时，反馈存储在本地，可以导出：
- **导出 Markdown** - 点击“待处理”以打开队列，然后点击“导出 Markdown”下载 `.md` 文件
- **创建 GitHub 问题** - 点击“创建 GitHub 问题”在浏览器中打开一个预填充的问题（您将被提示在首次使用时输入仓库，存储在 localStorage 中）
## 可用的 MCP 工具
| 工具 | 描述 |
|------|-------------|
| `setup_extension` | 帮助安装浏览器扩展程序（打开文件夹 + 说明） |
| `wait_for_browser_feedback` | 阻止直到用户提交单个反馈 |
| `wait_for_multiple_feedback` | 等待多个反馈项（用户点击完成时完成） |
| `get_pending_feedback` | 获取已提交的任何反馈 |
| `preview_pending_feedback` | 预览待处理反馈摘要而不消耗它们 |
| `delete_pending_feedback` | 通过 ID 删除特定的待处理反馈项 |
| `get_connection_status` | 检查浏览器客户端是否连接 |
| `request_annotation` | 提示用户注释特定内容 |
| `open_in_browser` | 在默认浏览器中打开项目 URL（自动从配置文件中检测） |
| `install_widget` | **已弃用** - 自动将部件脚本注入您的应用程序的 HTML 中 |
| `uninstall_widget` | **已弃用** - 删除注入的部件脚本 |
| `get_widget_snippet` | **已弃用** - 获取用于手动安装的脚本标签 |
### 脚本安装（已弃用）
> **已弃用：** 脚本安装会修改您的项目的 HTML，这会产生 git 噪音并存在意外提交的风险。请改用浏览器扩展程序。此路径仅为真正阻止安装浏览器扩展程序的环境保留，将在未来的主要版本中删除（[#48](https://github.com/itk-dev/mcp-claude-code-browser-feedback/issues/48)）。
将此脚本标签添加到您的 HTML 中：
```html
<script src="http://localhost:9877/widget.js"></script>
```
`install_widget` / `uninstall_widget` 工具仍然可以自动注入和删除标签（通过 `dev_only` / `allowed_hostnames` 进行主机名门控，并自动检测常见的入口点，如 `public/index.html`），而 `get_widget_snippet` 返回带有您的会话 ID 的标签。
## 部件功能
- **可拖动的对话框** - 将反馈面板移动到屏幕上的任意位置
- **可最小化** - 将面板折叠到仅标题栏
- **可折叠的元素详细信息** - 默认隐藏技术信息
- **截图捕获** - 使用 html2canvas（捆绑）自动捕获视口
- **控制台日志捕获** - 包括最近的控制台消息
- **多反馈模式** - 在发送到 Claude 之前提交多个注释
- **影子 DOM 隔离** - 部件样式与主机页面 CSS 隔离
- **离线模式** - 即使没有服务器连接，也可以注释元素；反馈存储在本地
- **导出到 Markdown** - 下载待处理反馈为结构化的 Markdown 文件
- **导出到 GitHub 问题** - 直接从部件打开预填充的 GitHub 问题
## 配置
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `FEEDBACK_PORT` | `9877` | HTTP/WebSocket 服务器端口 |
## 截图捕获
部件使用 html2canvas 自动捕获视口截图，该库与 MCP 服务器捆绑并按需加载。无需额外设置。
## 故障排除
### 部件显示“断开连接”（灰色按钮）
- 确保 MCP 服务器正在运行（在 Claude 代码中检查 `/mcp`）
- 检查端口（9877）是否未被另一个进程占用
- 尝试重新启动 Claude 代码
### 端口已被占用
服务器优雅地处理此问题 - MCP 工具仍将起作用，但您需要为浏览器部件释放端口：
```bash
# 查找并杀死占用端口 9877 的进程
lsof -i :9877
kill <PID>
```
或使用不同的端口：
```bash
FEEDBACK_PORT=9878 node src/server.js
```
### 没有收到反馈
- 检查浏览器控制台中的 WebSocket 错误
- 确保部件脚本正确加载
- 验证 MCP 服务器日志中的连接信息
## 安全说明
- 部件仅连接到 `localhost`
- 无数据发送到外部服务器
- 所有通信均在您的机器上进行
- **注意：** HTTP/WebSocket 服务器默认监听所有接口（`0.0.0.0`）。如果您需要限制此行为，请使用防火墙或通过反向代理绑定到特定接口。
## 开发
```bash
npm test # 单元测试（vitest）
npm run test:e2e # 部件端到端测试（需要 Playwright Chromium）
```
端到端测试驱动部件在无头浏览器中运行，以覆盖单元测试无法实现的注释模式行为（iframe 选择、Escape 处理、影子 DOM 焦点）。它查找 Playwright 浏览器缓存中的 Chromium；运行 `npx playwright install chromium` 一次，或将 `PLAYWRIGHT_CHROMIUM` 指向浏览器可执行文件。
## 许可证
MIT
