herdr-mcpソースバージョン v1.1.0-rc.2

ブラウザ JSON ブリッジ

ネイティブ Connector のない Web AI にローカル MCP ツールを与える。

役割： 実験的な JSON → MCP 互換ブリッジの上級リファレンス。ほとんどのユーザーはこのページを必要としません。

ChatGPT はカスタム MCP Connector を通じて herdr-mcp を呼び出せます。しかし、すべての Web AI 製品が同等の統合点を公開しているわけではありません。z.ai と DeepSeek はブラウザ内で推論できますが、ローカルの Herdr ツールカタログを登録するための同じ標準経路を提供していません。

JSON → MCP ブリッジは、その隙間のための互換層です。

対象サイトがネイティブに MCP をサポートしているふりはしませんし、ワークステーションの資格情報をページの JavaScript に公開することもありません。Web モデルは制約された JSON ツール要求を出力し、拡張と信頼されたローカルホストが実際の MCP 呼び出しを行います。

エンドツーエンドの経路#

ユーザータスク
  ↓
z.ai / DeepSeek Web model
  │ 制約された JSON tool call
  ▼
content bridge
  ↓
extension service worker
  ↓ Chrome Native Messaging
native host
  ↓ local Unix socket (0600)
herdr-mcp /mcp
  ↓
Herdr + files / Git / shell
  │
  └─ TOOL_RESULT を Web 会話へ返す

Cloudflare Edge はこの経路の一部ではありません。

なぜページの JavaScript から localhost を直接呼ばないのか#

ページ → 127.0.0.1 を直接つなぐ設計には、いくつかの問題があります。

  • ブラウザの origin とローカルネットワークの権限境界
  • ワークステーションの bearer がページや拡張のストレージに露出するリスク
  • 任意のページスクリプトが特権的なローカル endpoint を再利用しようとする
  • 会話 identity とイベントストリームを扱う単一の制御層が存在しない

主要なアーキテクチャは Chrome Native Messaging を使います。ブラウザ側のコードが制約された request/stream メッセージをネイティブホストへ送り、ネイティブホストが 0600 の Unix socket を通じて herdr-mcp に到達します。

つまり：

  • ページの JavaScript は Herdr bearer を一切見ません
  • extension service worker がその bearer を永続化する必要もありません
  • ローカル runtime がツールスキーマと権限ゲートの権威であり続けます
  • 公開 OAuth とローカル IPC は別々の信頼境界のままです

Web モデルに見えるもの#

ブリッジはローカル runtime から live な tools/list カタログを読み、該当する型付きスキーマを Web モデルが従えるプロトコルへ変換します。

ツール要求は次の形です。

{"tool":"herdr_inspect","args":{}}

または：

{"tool":"herdr_git","args":{"root":"/path/to/project","action":"status"}}

ブリッジは要求を検証し、実際の MCP tools/call を実行し、TOOL_RESULT を同じ会話へ返します。その後 Web モデルは別のツールを呼ぶか、通常の回答を生成します。

境界付きのツールループ#

ブリッジはブラウザを無制限の自律 Agent にはしません。

assistant の JSON 呼び出し
      ↓
検証
      ↓
MCP ツールを実行
      ↓
TOOL_RESULT を返す
      ↓
assistant が再度推論
      ↓
JSON 呼び出し または通常の回答

同じバッチ内の独立した呼び出しは並列実行できます。依存関係のあるステップは逐次のままです。ツールが成功したと見なされるのは、実際の MCP 結果が返った後だけです。

結果のサニタイズ#

MCP の結果には、長いターミナル出力、画像／バイナリのペイロード、構造化コンテンツ、大きな base64 フィールドが含まれ得ます。

ブリッジはツール結果を Web モデルへ返す前に、再帰的なサニタイズとサイズ制限を適用します。大きなバイナリ／base64 コンテンツは省略または要約され、一つのツール結果がブラウザのコンテキスト全体を消費しないようにします。

これは提示の仕方を変えるものであり、背後のツールの真実を変えるものではありません。

プロトコルメッセージの折り畳み#

JSON ツール要求と TOOL_RESULT メッセージは有用な機械間の調整情報ですが、人間が読むにはノイズです。対応サイトのアダプタはこれらの内部メッセージを折り畳み、会話がユーザーの目的と意味のある進捗を中心に保たれるようにします。

折り畳みは提示だけに影響し、背後の会話メッセージを消すものではありません。

会話 identity#

ブリッジは、どのチャットがツールループを所有しているかを正確に知る必要があります。

z.ai#

安定した /c/<chat_id> URL が永続的な会話 identity です。ルートの / は新規チャットの起動状態です。一時的な binding/Auto 状態は、その新しいチャットが最初に /c/<chat_id> になったときに一度だけ移行できます。

その後 /c/A から /c/B へ切り替えても、workspace binding や自動化の設定がチャット間で持ち越されることはありません。

DeepSeek#

同様に、サイトアダプタが抽出した安定した会話 identity によって状態が分離されます。ブラウザのタブ identity は永続的なチャット識別子とは扱われません。

リロード後に未完了の JSON ツール呼び出しを復旧する#

ブラウザのリロードで過去の JSON をすべて再生してはいけません。

復旧が適格となるのは、最後の実会話メッセージがまだ未完了の Herdr ツール呼び出しターンのように見え、かつ以前のブリッジコンテキストがそのメッセージを active なプロトコルシーケンスに属すると証明できる場合だけです。

mutation を行うツールは herdr-mcp の delivery/冪等性セマンティクスに従います。delivery が不明であることは、ページ更新後に同じ mutation を二度実行する理由には決してなりません。

ブラウザ continuity との関係#

JSON → MCP と continuity は拡張と Native Messaging の transport を共有しますが、解く問題は異なります。

能力 方向 目的
JSON → MCP ブラウザ → ワークステーション Connector を持たない Web AI にローカルツールを与える
progress / settled ワークステーション → ブラウザ 長時間のローカル作業の後に再開する
recovery / handoff ブラウザ内 止まったビューを復旧し、長い会話を切り替える

したがって z.ai の会話は、通常のツールに JSON ブリッジを使いつつ、progress/settled イベントのために Herdr workspace へ binding されることもできます。

z.ai / DeepSeek の会話 Auto は、ChatGPT 固有の stale-view 復旧や自動 Project ロールオーバーを有効にするものではありません。

handoff 制御メッセージが JSON タスクラッパーを迂回する理由#

handoff のサマリと seed メッセージは会話そのものを制御するものであり、コーディングタスクではありません。

z.ai ではこれらのメッセージが JSON ツールラッパーを迂回する raw な経路を使います。そうしなければ、「handoff packet を生成せよ」という要求がもう一つの Herdr コーディングタスクとして再解釈され、誤った再帰ループを作り得ます。

セキュリティ境界#

ブリッジはいくつかの明示的な規則に従います。

  • 対応サイトに対してのみ有効化される
  • 実行前にサイトと会話の identity を確認する
  • ツールカタログは、手書きで乖離していくコピーではなく実際のローカル runtime から取得する
  • MCP 呼び出しは信頼されたローカル IPC を使う
  • ブラウザのコードは Herdr bearer を保持しない
  • managed root、readonly、shell の能力について herdr-mcp が最終的な権威であり続ける
  • 拡張のトラフィックは不必要に公開 Cloudflare Edge を経由させない
  • 対象サイトが公式の OAuth MCP サポートを持つかのようには表現しない

いつ使うか#

別の開発バックエンドを作ることなく、z.ai や DeepSeek のような Web AI に同じ Herdr ワークステーションと同じ公開 18-tool 契約のセマンティクスを操作させたいときに、このブリッジを使います。

クライアントがすでに信頼できるネイティブ MCP Connector を提供している場合は、ネイティブの標準経路を優先してください。JSON → MCP は互換層であり、直接の MCP 統合の置き換えではありません。

検証#

最小限の実 UAT は次を証明すべきです。

  1. ブリッジが現在のローカル tools/list を読む
  2. Web モデルが有効な herdr_inspect 要求を生成する
  3. ネイティブホストがその MCP ツールを実行する
  4. TOOL_RESULT が正しい会話へ返る
  5. モデルが別のツールまたは通常の回答で続行できる
  6. リロードが完了済みの mutation を重複させない
  7. workspace binding と progress continuity がツールループと並行して動作できる

セレクタの詳細とバージョンごとの実装履歴はテストと CHANGELOG に属します。このページは現在の挙動とセキュリティ境界を記述します。

ドキュメント

herdr-mcp を検索

入力してドキュメントを検索します。