webmcp-bridge-mcp

Antigravity CLI（や他の MCP クライアント）から、Chrome 上で開いている WebMCP 対応ページの tool を呼び出せるようにする MCP サーバーです。

Antigravity CLI <--stdio(MCP)--> webmcp-bridge-mcp <--WebSocket--> webmcp-bridge-extension <--content/injected script--> Web Page

このサーバー自身はページの DOM には一切触れません。あくまで Chrome Extension （webmcp-bridge-extension）との間の Bridge / Registry / Router です。 拡張機能を先にインストールしていなくても起動できますが、tool 呼び出しには拡張機能の接続が必要です。

インストール

bun install

開発起動

bun run dev

• MCP サーバーは stdio で待受けます（Antigravity CLI から起動されるのを想定）。
• 同時に WebSocket サーバーが ws://127.0.0.1:8787 に起動します（127.0.0.1 のみ bind、外部からは接続不可）。
• ログはすべて stderr に出力されます（stdout は MCP の JSON-RPC 通信専用のため）。

環境変数 WS_PORT で WebSocket のポートを変更できます。

WS_PORT=9000 bun run dev

ビルド / 本番起動

bun run build
bun run start

テスト

bun test

test/bridge.test.ts が実際の MCP サーバー（src/index.ts）を子プロセスとして起動し、実際の @modelcontextprotocol/sdk の Client（＝ Antigravity CLI のような LLM エージェントの代わりに、 スクリプトで直接 tool を呼ぶ「モックされたエージェント」）を接続します。Chrome Extension の代わりに FakeExtension クラスが同じ WebSocket プロトコルを喋って接続することで、ブラウザ無しに 接続状態・tabs/list の live 問い合わせ・discover_tools のキャッシュ / forceRefresh・ tool 呼び出しの並行実行・切断時のクリーンアップまで、ブリッジのロジック全体を検証します。

拡張機能自体（overlay の表示、DOM 操作を伴う tool 実行など）の検証は webmcp-bridge-extension 側の Playwright テストで行っています。

Antigravity CLI への登録例

npm に公開済みの場合、事前の bun install やパスの指定なしに bunx / npx だけで起動できます （初回実行時に自動でダウンロード・キャッシュされます）。

{
  "mcpServers": {
    "webmcp-bridge": {
      "command": "bunx",
      "args": ["-y", "webmcp-bridge-mcp"]
    }
  }
}

npx でも同様に動きます（bin エントリはプレーンな Node.js 上での動作を確認済みです）。

{
  "mcpServers": {
    "webmcp-bridge": {
      "command": "npx",
      "args": ["-y", "webmcp-bridge-mcp"]
    }
  }
}

このリポジトリから直接ソースで動かしたい場合（開発中・未公開の場合）は、従来どおり cwd を指定してください。

{
  "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 だけになることを確認済みです。 実際に公開する場合は npm publish（または bun publish）を実行してください。

WebSocket URL

ws://127.0.0.1:8787

（WS_PORT 環境変数で変更可）。Chrome Extension 側は起動時にこの URL へ接続しにいきます。

利用できる MCP tools

tool	説明
webmcp_get_status	Extension の接続状態、既知タブ数、アクティブタブ ID を返す
webmcp_list_tabs	Extension が把握している WebMCP 対応タブ一覧を返す（Extension への live 問い合わせ）
webmcp_discover_tools	指定タブ（省略時はアクティブタブ）の WebMCP tool を検出する。デフォルトはキャッシュを返し、forceRefresh: true で再スキャンする
webmcp_call_tool	指定タブの WebMCP tool を toolId / args を指定して実行する。timeoutMs（デフォルト30秒）で待ち時間を調整可能
webmcp_ping	Extension との疎通確認（レイテンシ計測）。ページ操作は行わない

入出力の例

webmcp_discover_tools

// input
{ "tabId": 123, "forceRefresh": true }
// output (content[0].text の JSON)
{ "tabId": 123, "tools": [ { "id": "reserve_hotel", "name": "reserve_hotel", "source": "imperative", ... } ] }

webmcp_call_tool

// input
{ "toolId": "reserve_hotel", "args": { "city": "Osaka" } }
// output
{ "ok": true, "result": { "ok": true, "city": "Osaka", "confirmationId": "RES-12345" } }

source は WebMCP 仕様 準拠の検出元を表します （"imperative" = document.modelContext.registerTool()、"declarative" = annotated <form>）。 詳細は webmcp-bridge-extension の README を参照してください。

Extension が未接続の場合、すべての tool 呼び出しはエラー（ok: false またはエラーメッセージ）を 返すだけで、サーバーがクラッシュしたりハングしたりすることはありません。

注: webmcp_discover_tools の結果で requiresUserGesture: true になっている tool （toolautosubmit の無い宣言型フォーム）は、実機検証の結果、人間が実際に送信ボタンを押すまで webmcp_call_tool が応答を返さないことがあります（ブラウザのネイティブ実装依存）。人が操作しない 自動実行の文脈でこの手の tool を呼ぶ場合は、timeoutMs を十分長く設定するか、そもそも呼び出さずに 人間へ操作を促す設計にしてください。

注: result は tool の execute() が返した値をそのまま中継したものです。実機の document.modelContext.executeTool() で検証したところ、ページ側が { ok: true, city } のような オブジェクトを返しても、ブラウザ側で JSON 文字列化されて渡ってくるケースがありました（WebMCP 仕様の execute は元々「エージェント向けの文字列サマリ」を返す想定のため）。このサーバーは result を 一切加工せず素通しするので、MCP クライアント側で文字列か構造化データかを判定してください。

動作確認（拡張機能なしで疎通だけ見る場合）

MCP Inspector を使うと拡張機能なしでも サーバー自体の疎通を確認できます。

bunx @modelcontextprotocol/inspector bun run src/index.ts

webmcp_get_status / webmcp_ping を呼び、extensionConnected: false / {"ok":false,"error":"Extension not connected."} が返ってくれば正常です。