web-bridge — AIエディタから任意の静的Webページを操作するMCPツール

web-bridge は MCP Server（Node 単一プロセス、二つのインターフェース）です。AIエディタから client.js を導入した静的Webページ上で JavaScript の実行、コンソールの読み取り、クリック / 入力のシミュレーションができます。クロスブラウザ、複数タブのローカル連携に適しており、外部サーバーへのデプロイ（--transport http、下記「リモートデプロイ」参照）にも対応しています。

   AI 编辑器                ┌───────────────────┐              浏览器页面
┌──────────────┐           │    MCP Server     │           ┌──────────────────┐
│  MCP Client  │           │  （Node 单进程）    │           │ <script src=     │
│              │ stdio 或   │ · 接口B: MCP       │  WebSocket │  :3210/client.js">│
│  AI 只到这里  │◄─────────►│   (stdio / http)  │◄──────────►│  client.js       │
└──────────────┘  Streamable│ · 接口A: WebSocket │  接口A     │  （eval 执行/     │
      HTTP(远程)           │ · HTTP /client.js │            │   console 捕获）  │
                           └───────────────────┘            └──────────────────┘

AIエディタとブラウザは互いに直接接続しません。2つの接続はどちらも MCP Server（server.js）で終端され、AI はツール呼び出しを通じて間接的にページを操作します。

クイックスタート

cd web-bridge
npm install          # 首次

1. 静的Webページにスクリプトを導入します（任意のページ、任意のポートでOK。クロスオリジンは許可済み）：

   <script src="http://127.0.0.1:3210/client.js"></script>

2. MCPサービスをAIエディタに設定します：mcp.json 内の <REPO>/server.js をこのリポジトリの絶対パスに置き換え、下記のエディタに応じた方法で貼り付けます。エディタが server.js を起動すると同時に、WebSocketサービス（デフォルト 127.0.0.1:3210）が利用可能になります。

3. AIに指示します：「web-bridge の list_pages で接続中のページを確認して、eval_js で #btn をクリックして、コンソールを読んでください」

導入順の補足：ページ側で先に導入しても問題ありません。client.js が自動的に再接続します（1s→2s→5s→10s のバックオフ）。エディタ起動後にページは自動的に再接続されます。hub ステータスページ：http://127.0.0.1:3210/

MCP ツール

pageId のルール：接続ページが1つだけの場合は省略可能です。複数ページ接続時に指定しないと、ツールはエラーとページ一覧を返すので、AI が pageId を補って再試行します。

各エディタでの接続

以下の例はすべてリポジトリの絶対パスが /path/to/web-bridge であることを前提としています。必要に応じて置き換えてください。

ZCode / Claude Code（プロジェクトルートの .mcp.json、または claude mcp add）：

{
  "mcpServers": {
    "web-bridge": {
      "command": "node",
      "args": ["/path/to/web-bridge/server.js"],
      "env": { "PORT": "3210" }
    }
  }
}

Cursor（.cursor/mcp.json）：形式は上記と同じ。

Claude Desktop（claude_desktop_config.json）：形式は上記と同じ。

コマンドライン引数：node server.js --port 3210 --host 127.0.0.1 --token <secret>（環境変数 PORT / HOST / TOKEN も使用可能）。

リモートデプロイ（外部サーバー）

デフォルトの stdio モードではエディタがローカルでプロセスを起動する必要があります。web-bridge を外部サーバーにデプロイする場合は、HTTP トランスポートモードに切り替え、エディタはMCP設定にurlを1つ記入するだけです：

1. サーバー上で起動（systemd / pm2 での管理を推奨。公網ではトークンの有効化が必須）：

node server.js --transport http --host 0.0.0.0 --port 3210 --token <secret>

2. エディタ設定（Claude Code / Cursor / ZCode など。元の設定箇所に貼り付け）：

{
  "mcpServers": {
    "web-bridge": {
      "type": "http",
      "url": "https://your-domain.com/mcp",
      "headers": { "Authorization": "Bearer <secret>" }
    }
  }
}

直接接続（リバースプロキシ/TLSなし）の場合、url は http://<服务器IP>:3210/mcp にします。注：Claude Desktop はローカル stdio モードのみ対応しており、リモート url には対応していません。

3. ページ側スクリプトをサーバーに向けます：

<script src="https://your-domain.com/client.js?token=<secret>"></script>

説明：

• HTTPSページは https/wss にのみ接続できます（mixed content の制限）。nginx / caddy などのリバースプロキシで TLS を終端し、本サービスに転送することを推奨します。client.js は配信時に X-Forwarded-Proto / X-Forwarded-Host を自動認識し、正しい wss:// 接続アドレスを生成するため、追加設定は不要です。caddy の例（証明書の自動取得）：

  your-domain.com {
    reverse_proxy 127.0.0.1:3210
  }

• /mcp エンドポイントはトークン有効化後、3種類の認証方法に対応します：Authorization: Bearer <secret>（推奨。エディタ設定の headers に記入）、X-Web-Bridge-Token: <secret>、url パラメータ ?token=。

• HTTP トランスポートは公式の Streamable HTTP プロトコル（stateless モード）です。各リクエストは独立して処理され、同じ hub を共有するため、複数のエディタが同時に接続できます。

• 公網デプロイ時の注意：--token を設定し、TLS を使用し、ファイアウォールでは必要なポートのみ許可してください。

セキュリティについて

• デフォルトでは 127.0.0.1 のみをリッスンします。このマシンで開かれている任意のWebページ（閲覧中の第三者サイトを含む）はローカルポートへの接続を試みることができます。デフォルトのトークンなしモードでは、それらのページは AI が送信したコードを受け取ったり、結果を偽装したりできます。

• 信頼できないネットワーク環境、またはスマートフォンなどの LAN デバイスを接続したい場合（--host 0.0.0.0）は、必ず --token を有効にしてください。この場合、client.js の取得には ?token=<secret> が必要で、WebSocket の最初のパケットでもトークンが検証されます。

WebSocket メッセージプロトコル（内部参考）

ブラウザと MCP Server 間の WS メッセージはすべて JSON テキストフレームです。lib/hub.mjs / client.js をメンテナンスする際の参考：

eval の実行仕様（client.js）：まず式として async () => ( code ) にラップします。SyntaxError の場合は文ブロックにフォールバックします（return 使用可）。$ / $$ をあらかじめ定義。タイムアウトは hub 側で計測（デフォルト 30秒、上限 120秒）。結果は安全にシリアライズされた文字列プレビューとして返します（Error→stack、DOM→outerHTML の要約、循環参照のマーク、深さ ≤ 6、≤ 50k 文字）。

開発

• テスト：npm test（Node e2e：プロセス起動 + ページシミュレーション + stdio/HTTP 両トランスポートでツール呼び出し）；npm run test:browser（Playwright 実ブラウザ経路：Chromium で test/test-page.html を読み込み、実際の WebSocket で6つのツールを検証。初回の前に npx playwright install chromium を実行）。実ブラウザ経路はテストページを開いて手動で検証することもできます。

• 依存：ws（WebSocket）、@modelcontextprotocol/sdk（MCP）、zod（パラメータ検証）。開発依存は @playwright/test。Node ≥ 18。