kro-bridge-mcp

把用户 Edge 里的 Kro Browser Bridge 扩展接到 Claude Code 的本地 MCP 适配层。

它自己不做任何智能决策，也不调用 LLM：

• 对扩展：扮演兼容的 bridge 服务端（HTTP ping + WebSocket），监听 127.0.0.1:17323。

• 对 Claude Code：扮演 MCP server（stdio），把浏览器动作暴露成工具 browser_bridge。

Kro 扩展（用户 Edge）
        │  WS  ws://127.0.0.1:17323/chrome-bridge/ws?token=...
        │  HTTP GET/HEAD /chrome-bridge/ping
        ▼
  kro-bridge-mcp（本进程）
        │  MCP over stdio
        ▼
  Claude Code

决策始终在 Claude Code 这侧；本项目只转发命令和回包。

前置条件

• Windows 11（其他平台理论可用，未验证）。

• Node.js >= 20（开发机为 v24）。

• Edge 已安装 Kro Browser Bridge 扩展。

• 运行期间 不要同时运行其他占用 17323 的 bridge 服务端，否则会端口冲突。

• 首次 npm install 需要联网。

Related MCP server: Browser Tools for Claude Code

安装

cd <path-to-repo>
npm install

<path-to-repo> 指克隆后的仓库根目录。无构建步骤，纯 JavaScript ESM。

启动与自检

手动启动（用于自检；Claude Code 通过 MCP 注册直接拉起 node server.js）：

npm start

stderr 应看到：

[kro-bridge] listening on 127.0.0.1:17323
[kro-bridge] MCP stdio connected; tool browser_bridge registered

另开终端验证 ping（PowerShell 的 curl 是 Invoke-WebRequest 别名，使用 curl.exe）：

curl.exe -H "X-Kro-Client-Sig: 52a6681f244444dd5d603b204b6616ccdb738f6e59e8e53942876030a3c82e99" http://127.0.0.1:17323/chrome-bridge/ping

期望返回：

{"ok":true,"server":"krow-browser-bridge","instanceId":"...","protocolVersion":"1.0","wsPath":"/chrome-bridge/ws","token":"..."}

instanceId 和 token 每个进程重新生成，不持久化。

注册到 Claude Code（用户级）

claude mcp add --scope user kro-bridge -- node "<path-to-repo>/server.js"

• 把 <path-to-repo> 换成克隆后的仓库绝对路径（Windows 可用正斜杠）。

• 注册后需要重启 Claude Code 会话才会加载 MCP 工具。

• 工具列表里应出现 browser_bridge。

• 如果 node 不在 Claude Code 的 PATH（例如 nvm-windows 切换过版本），把命令里的 node 换成 node.exe 的绝对路径。

• npm start 只用于自检；不要让 Claude Code 通过 npm start 启动，否则可能多一层 shell/日志干扰。

连接 Edge 扩展

1. 确认没有其他 bridge 服务端占用 17323：netstat -ano | findstr :17323 应无监听。

2. 点 Edge 工具栏的 Kro Browser Bridge 扩展图标。

3. Port 选 Auto detect，或手动填 17323。

4. 点 Reconnect，直到状态显示 Connected。

5. 如果服务端重启过，token 会变化，扩展通常需要再点一次 Reconnect。

使用流程

Claude Code 使用 browser_bridge 时的推荐顺序：

1. extension_status → ready=false 立即停止，告诉用户“扩展未连接”，不要猜。

2. list_sessions → 拿 browser_id。

3. list_pages → 优先复用用户已打开的 tab；需要时 focus_page。

4. 需要新页时 open_tab。

5. read_state → 拿到元素编号。

6. 按编号 click / hover / dblclick / rightclick / type / press / scroll。

7. 每次操作后重新 read_state；DOM 一变编号立即作废。

8. 不主动 close_tab，除非用户明确要求。

硬性纪律：

• 登录、验证码、短信/邮箱验证、支付、“同意条款”一律交还用户手动完成。

• 不要对用户已登录的敏感网站做超出请求范围的操作。

• page_id 失效时不要盲重试，重新 list_pages。

• 扩展重连后 session_id / browser_id 可能变化，重新 list_sessions。

Action 表

extension_status / list_sessions / list_pages 由本进程直接回答，不发扩展。

execute_script 硬约束

不遵守时扩展可能静默返回 null，无法诊断：

1. 单行、无换行、无缩进；语句用 ; 分隔。

2. IIFE + 显式 return：(function(){...return X;})()。

3. 只用单引号；对象字面量 key 不加引号。

4. 返回体控制在 KB 级；大列表分批 slice(0, 10)。

5. 返回 null 一次先 wait_for 2 秒重试；仍 null 就停下报告。

测试

npm test

使用 node:test + 模拟扩展，不需要真实浏览器。当前覆盖：

• 协议常量、签名、ping GET/HEAD/403/OPTIONS CORS

• WS 错误 token → 4401；hello / hello_ack / browser_id 重索引

• page 事件（直接与 type:"event" 两种形状）、page_id 稳定复用、关闭删除、断线清理、重连防误删

• 命令信封、result/error、乱序回包、迟到 id、坏 JSON、ping 心跳

• 30 秒默认超时（测试注入短超时）、断线立即 reject、pending 清理

• 20 个 action 的参数映射与校验

• 32 KiB 截断（ASCII / 中文 / emoji）

• MCP 工具注册、schema、stdio 洁净、server.js 启停

协议摘要

PingClientID    = "kro-browser-bridge"
PingSalt        = "kro-2026"
PingSigHeader   = "X-Kro-Client-Sig"
PingPath        = "/chrome-bridge/ping"
WSPath          = "/chrome-bridge/ws"
ServerName      = "krow-browser-bridge"
ProtocolVersion = "1.0"
WSCloseAuthFailed = 4401
PingSignature   = 52a6681f244444dd5d603b204b6616ccdb738f6e59e8e53942876030a3c82e99

• GET ping 校验签名；HEAD ping 不校验，用于探活。

• WS 错误 token：先 upgrade，再以 close code 4401（reason auth failed）关闭。

• 帧为 JSON 文本。扩展 → 服务端：hello、page_updated、page_closed、page_removed、result、error、ping。

• 服务端 → 扩展：hello_ack、command。

• 命令信封：

{
  "type": "command",
  "id": "<uuid>",
  "session_id": "<session uuid>",
  "timestamp": 1700000000000,
  "payload": { "tool": "browser_read_state", "arguments": { } }
}

• 命令默认 30 秒超时；任一连接断开时立即 reject 所有 pending。

• page_id 由本服务生成，形如 page_ + 8 位十六进制，对应 (browser_id, tab_id)；同一 tab 更新复用，tab 关闭删除。

• 单次转发结果超过 32 KiB 时返回 {truncated:true, action, original_size_bytes, kept_size_bytes, note, preview_json}。

安全与隐私

• 只监听 127.0.0.1，不绑定 0.0.0.0。

• token 每个进程重新生成，不持久化、不记录。

• 日志只记会话/动作元信息；不记录 token、Cookie、完整 URL 查询串、页面正文、脚本内容。

• 不实现任意 HTTP 代理，不向外部网络转发数据。

• 这是用户的真实浏览器：不主动关闭用户 tab，不做超出请求范围的操作。

已知限制

• 没有截图：bridge 协议没有 screenshot 动作，不要用截图能力承诺任务。

• 单实例：同一时间只能跑一个 server；第二个会 EADDRINUSE。这也意味着同一时间只有一个 Claude Code 会话能使用 browser_bridge；要切换会话，先结束占用 17323 的那个会话。

• 端口冲突：其他 bridge 服务端也可能监听 17323，运行前先停掉它。

• 扩展需手动连接：Auto detect 扫不到时，手动填 17323 再 Reconnect。

• 服务重启后 token 变化：扩展可能需要再次 Reconnect。

• wait_for 有效上限约 30 秒：超过会先触发命令超时。

• press 使用合成键盘事件：某些浏览器默认行为（例如 Tab 切换焦点）可能不触发；按键动作本身会成功返回。

• 断线 reject 所有 pending：多浏览器时，一个连接断开会影响另一浏览器的在途命令（对齐参考实现，v1 限制）。

• open_tab 回包可能没有 page_id：等 page_updated 后 list_pages 按 URL/最新 tab 匹配。

• close_tab 的页面移除是事件驱动：list_pages 可能短暂看到已关闭 tab。

• 登录/验证码/支付/条款：一律由用户手动完成。

故障排查

验收状态

自动化测试：43/43 通过（npm test，协议 + MCP 层，无需真实浏览器）。

真实 Edge 联调：已完成（2026-11-08）。

• 真实扩展 Connected，extension_status.ready === true（browser_id 28bf…00906，extension 0.0.6）

• list_sessions / list_pages 拿到真实 browser_id / page_id

• open_tab → read_state → execute_script 读 document.title 成功（example.com）

• click / type / extract 各成功一次（example.com 链接、httpbin 表单）

• 重启 Claude Code / server 后扩展能重连

• 未关闭用户已有 tab

真实环境记录：

开发结构

server.js              MCP 入口：起 bridge → 注册工具 → stdio；信号与关闭
src/protocol.js        协议常量、签名、帧构造/解析
src/bridge.js          HTTP ping + WS + Registry + pending 命令表
src/tools.js           action 校验、参数构造、32 KiB 截断、MCP 注册
test/fake-extension.js 模拟扩展 WS 客户端
test/bridge.test.js    协议级测试
test/mcp.test.js       MCP 工具与 server.js 启停测试

MCP SDK 版本：@modelcontextprotocol/sdk@^1.32.2；zod@^4.6.7；ws@^8.22.1。

License

MIT