内容
# webmcp-bridge-mcp
Antigravity CLI（或其他MCP客户端）允许在Chrome上打开的WebMCP支持页面上调用工具的MCP服务器。
```
Antigravity CLI <--stdio(MCP)--> webmcp-bridge-mcp <--WebSocket--> webmcp-bridge-extension <--content/injected script--> Web Page
```
该服务器本身并不直接与页面的DOM交互。它仅作为Chrome扩展程序（[webmcp-bridge-extension](../webmcp-bridge-extension)）之间的桥梁/注册中心/路由。即使没有预先安装扩展程序，该服务器也可以启动，但工具调用需要扩展程序的连接。
## 安装
```bash
bun install
```
## 开发启动
```bash
bun run dev
```
- MCP服务器通过 **stdio** 监听（假设从Antigravity CLI启动）。
- 同时，WebSocket服务器在 `ws://127.0.0.1:8787` 启动（仅绑定到 `127.0.0.1`，外部无法连接）。
- 所有日志都输出到 **stderr** （stdout仅用于MCP的JSON-RPC通信）。
可以通过环境变量 `WS_PORT` 修改WebSocket的端口。
```bash
WS_PORT=9000 bun run dev
```
## 构建/生产环境启动
```bash
bun run build
bun run start
```
## 测试
```bash
bun test
```
`test/bridge.test.ts` 启动实际的MCP服务器（`src/index.ts`）作为子进程，并连接实际的`@modelcontextprotocol/sdk`的`Client`（类似于Antigravity CLI的LLM代理，代替脚本直接调用工具的“模拟代理”）。Chrome扩展程序代替`FakeExtension`类使用相同的WebSocket协议连接，实现在无浏览器的情况下，验证连接状态、`tabs/list`的实时查询、`discover_tools`的缓存/强制刷新、工具调用的并发执行和断开时的清理。
扩展程序本身（overlay显示，涉及DOM操作的工具执行等）的验证在[webmcp-bridge-extension](../webmcp-bridge-extension)的Playwright测试中进行。
## Antigravity CLI注册示例
如果已发布到npm，可以在无需事先`bun install`或指定路径的情况下，仅使用`bunx`/`npx`启动（首次执行时自动下载并缓存）。
```json
{
"mcpServers": {
"webmcp-bridge": {
"command": "bunx",
"args": ["-y", "webmcp-bridge-mcp"]
}
}
}
```
使用`npx`也可以正常运行（`bin`入口在纯Node.js环境中已验证）。
```json
{
"mcpServers": {
"webmcp-bridge": {
"command": "npx",
"args": ["-y", "webmcp-bridge-mcp"]
}
}
}
```
如果您想从此存储库直接使用源码运行（开发中/未发布），请像以前一样指定`cwd`。
```json
{
"mcpServers": {
"webmcp-bridge": {
"command": "bun",
"args": ["run", "dev"],
"cwd": "/absolute/path/to/webmcp-bridge-mcp"
}
}
}
```
### 关于npm发布的准备
`package.json`中已准备好`bin`入口（`dist/index.js`，带`#!/usr/bin/env node`），并且`bun run build`使用`--target node`进行构建，因此可以在`node`/`bun`上运行。已确认`npm pack --dry-run`仅包含`dist/index.js`和`README.md`。
## WebSocket URL
```
ws://127.0.0.1:8787
```
（可以通过`WS_PORT`环境变量修改）。Chrome扩展程序在启动时将连接此URL。
## 可用的MCP工具
| 工具 | 说明 |
| --- | --- |
| `webmcp_get_status` | 返回扩展程序的连接状态、已知标签页数和活动标签页ID |
| `webmcp_list_tabs` | 返回扩展程序已知的WebMCP标签页列表（扩展程序的实时查询） |
| `webmcp_discover_tools` | 检测指定标签页（默认为活动标签页）的WebMCP工具。默认返回缓存结果，`forceRefresh: true`时重新扫描 |
| `webmcp_call_tool` | 指定标签页的WebMCP工具，执行`toolId`/`args`。可以通过`timeoutMs`（默认为30秒）调整等待时间 |
| `webmcp_ping` | 与扩展程序的通信确认（延迟测量）。不执行页面操作 |
### 输入/输出示例
`webmcp_discover_tools`
```json
// 输入
{ "tabId": 123, "forceRefresh": true }
// 输出（content[0].text的JSON）
{ "tabId": 123, "tools": [ { "id": "reserve_hotel", "name": "reserve_hotel", "source": "imperative", ... } ] }
```
`webmcp_call_tool`
```json
// 输入
{ "toolId": "reserve_hotel", "args": { "city": "Osaka" } }
// 输出
{ "ok": true, "result": { "ok": true, "city": "Osaka", "confirmationId": "RES-12345" } }
```
`source`表示[WebMCP规范](https://webmachinelearning.github.io/webmcp/)的检测来源（`"imperative"` = `document.modelContext.registerTool()`，`"declarative"` = 带注释的`<form>`）。详情请参阅[webmcp-bridge-extension的README](../webmcp-bridge-extension/README.md#webmcp%E5%BB%93%E6%B8%AC%E8%A7%84%E6%A0%87)。
如果扩展程序未连接，所有工具调用仅返回错误（`ok: false`或错误消息），服务器不会崩溃或挂起。
> **注意：** `webmcp_discover_tools`的结果中，如果`requiresUserGesture: true`（无`toolautosubmit`的声明式表单），实际测试结果表明，在用户实际点击提交按钮之前，`webmcp_call_tool`可能不会返回响应（取决于浏览器原生实现）。在自动执行的上下文中调用此类工具时，请设置足够长的`timeoutMs`或提示用户操作。
> **注意：** `result`是工具的`execute()`返回值的直接中继。实际测试中，如果页面返回类似`{ ok: true, city }`的对象，可能会在浏览器侧序列化为JSON字符串后传递（因为WebMCP规范的`execute`原本是为代理返回字符串摘要而设计的）。此服务器不对`result`进行任何处理直接传递，因此MCP客户端需要自行判断是字符串还是结构化数据。
## 动作确认（在无扩展程序的情况下验证通信）
使用[MCP Inspector](https://github.com/modelcontextprotocol/inspector)可以在无扩展程序的情况下验证服务器的通信。
```bash
bunx @modelcontextprotocol/inspector bun run src/index.ts
```
调用`webmcp_get_status`/`webmcp_ping`，如果返回`extensionConnected: false`/`{"ok":false,"error":"Extension not connected."}`，则表示正常。
