Hatun MCP - Governed Agent Gateway

---

title: Hatun MCP — Governed Agent Gateway emoji: 🪢 colorFrom: indigo colorTo: blue sdk: docker app_port: 7860 pinned: false license: apache-2.0 short_description: 署名付きガバナンスレシートを備えた、ソースに結び付けられたMCPゲートウェイ

正式なランタイムソースです。 このリポジトリは、Python ゲートウェイ、ガバナンス対象のツールカタログ、Streamable HTTP トランスポート、およびコンテナ契約を管理します。独立した Hatun Hugging Face パブリッシャーは2026年9月3日に廃止されました。hf-deployを再作成してはなりません。 公開されている製品体験はHatun Gatewayです。ただし、これ自体は、このパッケージの/mcp/エンドポイントや新たに追加されたツールがデプロイ済みであることの証明ではありません。 サーフェス契約を参照してください。モノレポ内のplatform/packages/hatun-mcpは、ここを指すCANONICAL.mdを含む非正式な埋め込みコピーです。ローカルインポート用により小規模なツールセットを公開しますが、このサーバーの契約から逸脱してはなりません。 platform のコピーを統合するのは後の創業者の作業です。このリポジトリでリポジトリが削除されることはありません。Λ = 予想1（参考情報）は原文のまま保持されています。

行動の前に制御を。行動の後に証拠を。

製品 · 証明 · GitHub 組織

---

これは何か

公式のmcp Python SDK（mcp.server.fastmcp.FastMCP）を基盤とする、実際に稼働するModel Context Protocol サーバーです。すべてのツール呼び出しは、次の PURIQ 式に従ってガバナンスされます。

1. クライアントを認証します（SZL API キー → client_id）。匿名の呼び出しは拒否されます。
2. 入力に対してYuyay-13 ゲートを適用します（入力をデータとして扱う方式。OWASP MCP06 インジェクション防御）。
3. レピュテーション係数Hatun_MCP(client) ∈ [0,1]を適用します。
4. 状態を変更するツール（例：killinchu_cue、halt_drone）には2人による Yuyay ゲートを適用します。
5. レイテンシ予算内で実際の器官バックエンドを呼び出します。
6. 成功時および失敗時にKhipu レシートを発行します（追記専用の sha256 DAG）。
7. DSSE 署名付きレスポンスを返します。クライアントはレシートハッシュを受け取ります。

ルートを選ぶ

対象者	まずはこちら	エビデンスの範囲
開発者	ローカルで実行してから、tools/listを確認します	ローカルでの起動によって確認できるのはローカルプロセスのみです。バックエンドへの到達可能性は別途確認が必要です
インテグレーター	MCP クライアントのセットアップ	チェックイン済みのクライアント設定はサンプルであり、認証情報は含まれていません
評価者	ホスト環境のヘルスチェック契約を確認してから、テストを実施します	/healthzは稼働状態を示します。/readyzは署名済みリリースの準備状態を示します。いずれも稼働時間の保証ではありません

KANCHAY のステータス契約

• LIVE：ソースと観測時刻を伴う、ランタイムに基づいたルートです。継続的な可用性を意味するものではありません。
• PARTIAL：Hatun はローカルで準備できていますが、必須の上流オルガンの観測のうち、欠落しているもの、古くなっているもの、または劣化しているものがあります。
• SAMPLE：再利用できるようチェックインされた設定、ペイロード、またはトランスクリプトです。ランタイムで観測されたエビデンスではありません。
• SIMULATED：モックされたバックエンド、または隔離されたテスト用フィクスチャです。外部サービスによってテストの再現性が損なわれる場合、CI では意図的にこれらを使用します。
• UNAVAILABLE：依存先または準備状態のチェックから、利用可能な結果を得られません。理由を保持し、サンプルデータで代用しないでください。

公開されるツール

• 静的ツール 26 個はインポート時に登録されます（確認方法：HATUN_MCP_DISABLE_DYNAMIC=trueの場合、tools/listは26個を返します）。
  • szl_*ツール 20 個 — szl_a11oy_code_chat、szl_a11oy_operator_reason、szl_a11oy_sentinel_scan、 szl_anatomy_3d_render、szl_doctrine_lookup、szl_drone_lookup、 szl_formula_evaluate、szl_github_estate_snapshot、szl_khipu_verify、szl_killinchu_cue、 szl_killinchu_detect、szl_lean_verify、szl_puriq_evaluate、 szl_companion_reason、szl_immune_scan、szl_thesis_query、szl_wayra_recent、 szl_yachay_dome_predict、szl_yuyay_score、および szl_lambda_quorum（ビザンチン Λ 判定）。

    2 つのツールは、オルガンの名称を正確に反映するよう2026-06-16 に名称変更されました — szl_immune_scan（廃止されたコードネームのスキャンツール）および szl_companion_reason（廃止されたコードネームの推論ツール）。旧名から新名への対応は DEPRECATED.mdを参照してください。旧名は 提供されません（tools/listには登録されていません）。

  • ガバナンスツール 6 個 — yuyay_gate_check、khipu_append_and_verify、 dsse_sign、mesh_quorum_status、puriq_master_tool、governance_pacbayes_bound。
• 各バックエンドサービスの/api/<service>/v1/mcp/toolsにあるライブカタログから、起動時に動的に登録されるサービス由来のツールです。名前は<service>_<tool>です。 動的なツール数はプローブの結果に依存します。到達可能なサービスが公開するツール数に26を加えた数となり、動的登録が無効の場合、またはすべてのサービスに到達できない場合、追加分は0個です。

公開 GitHub エステートの証拠

szl_github_estate_snapshot を {} で呼び出すと、固定された公開 szl-holdings 組織を観測します。これは構造的なインベントリツールであり、LLM による回答やマージボットではありません。組織、URL、トークン、カーソル、その他の引数は受け付けません。GitHub へのアクセスには、固定オリジンへのトークンなし・リダイレクト無効の GET を使用します。このクライアントは、環境の認証情報やプロキシを引き継ぎません。

オブザーバーは、リポジトリの識別情報とデフォルトブランチ名、上限付きのオープン PR のベース／ヘッド SHA、ドラフト状態、およびそれらの正確なヘッド SHA を指定してクエリしたチェック実行を報告します。引用には、リクエストパスとパラメーター、レスポンスのバイト長と SHA-256 ダイジェストが含まれます。正規スナップショットのダイジェストは Khipu レシートとその DSSE ペイロードに含まれ、設定された P-256 キーがそのレシートに署名します。キーがない場合、エンベロープは署名なしの明示的な PLACEHOLDER のままです。ダイジェストや完全なインベントリは、独立した証人でも暗号署名でもありません。

呼び出しごとの厳格な上限：15 秒、20 リクエスト、リポジトリページ 3 ページ（300 レコード）、オープン PR の検索結果 50 件、PR ごとのチェック実行 100 件、レスポンスごとに受け入れるレスポンス本文データ 1 MiB、呼び出し全体で受け入れるデータ 4 MiB。上限に達すると、キュー内のリクエストとそれ以降の本文の受け入れを停止します。これらはアプリケーションでの受け入れ上限であり、ワイヤー上のトラフィックやトランスポートの先読みを測定するものではありません。すでに配信済みでも受け入れられなかったバイトは、受け入れ済みとして数えません。オーバーフロー、タイムアウト、レート制限、不正なレコード、古い PR 検索の証拠、チェック結果の欠落または未認識は、明示的なギャップと INCOMPLETE または UNAVAILABLE を生じさせます。チェックがゼロ件の場合は UNKNOWN であり、成功ではありません。COMPLETE は宣言された観測範囲が網羅されたことを意味します。CI が失敗していても、完全に観測されている場合があります。エステートが稼働している、またはマージしても安全であるという意味ではありません。

この v1 は意図的に、プライベートリポジトリ、解決済みのデフォルトブランチヘッド、レガシーなコミットステータスコンテキスト、レビュー、保護ルール、マージ可否、HF での公開、モデルの品質／トレーニング、デプロイ済みランタイムの健全性を証明しません。複数のリクエストは、プロバイダーのアトミックなスナップショットではありません。各レスポンスは入力データであり、指示ではありません。通常の Hatun 認証とレシートの取り扱いは引き続き適用され、オペレーターが任意で設定する SZL_RECEIPT_SINK への転送もその対象です。GitHub オブザーバーはプロバイダーに変更を加えません。

命名に関する注記。 以前コードネームで呼ばれていた 3 つのバックエンドは削除されました。それらの機能は現在、a-11-oy.com の稼働中の正直な a11oy 器官が直接提供しています。具体的には、免疫器官（エグレスポリシー／ゲートのインスペクター — Hukulla）、コンパニオン器官（オペレーター／推論コンソール）、llm 器官（オープン LLM のティアルーター）です。Hatun-MCP は、これらの正直な役割名でアクセスします。稼働中のルートは /openapi.json で公開されています。

記録済みの到達可能性スナップショット（チェックリストより誠実さを優先）

以下の表は、2026-06-16時点のリポジトリの証拠を記録したものです。現在の稼働状況を確認するプローブではありません。/healthz と /readyz で確認できるのは、Hatun のローカルプロセス、レシートチェーン、および署名者のみです。上流の各機能にはプローブを行いません。いずれかの行を現在 LIVE として提示する前に、その行に記載されたルート（または文書化済みの非変更型の準備状況確認ルート）に対して、別途、範囲を限定した読み取り専用プローブを実施し、応答ステータス、ソース、観測タイムスタンプを記録してください。POST 専用または状態を変更するサーフェスには、事前承認済みの非変更型コントラクトプローブか、タイムスタンプ付きレシートを使用してください。可用性を主張するためだけにアクションを実行してはいけません。必要な上流の観測が欠落している、古くなっている、または使用できない場合は、その行を PARTIAL または UNAVAILABLE として提示してください。

バックエンド機能	カタログルート	記録された状態（2026-06-16）
a11oy — llm オープン LLM ティアルーター	GET /api/a11oy/v1/llm/tiers	LIVE (200) — llm_tiers はライブのティアカタログから派生
killinchu	/api/killinchu/v1/mcp/tools	LIVE — 4 つのツール（cue/halt_drone は 2 人承認）
a11oy — companion オペレーター／推論コンソール	/api/a11oy/v1/companion/{ask,act,recommend}	LIVE (200) — ライブのアクションルートから派生した 3 つのツール（JSON /v1/mcp/tools カタログはなし）
a11oy — immune（Hukulla）送信ポリシーインスペクター	GET /api/a11oy/v1/immune/gates	LIVE (200, gates-derived) — ゲートと screen／verdict。immune の screen は署名付きの /immune/verdict ルートです（独立した /screen はありません）
a11oy — command／フラッグシップ	/api/a11oy/v1/mcp/tools	JSON カタログが公開されている場合は a11oy-flagship ツールを登録し、公開されていない場合は誠実な a11oy_status ツールを 1 つ登録します。カタログが 200 を返せば、次回のサーバー再起動時に自己修復します。コード変更も、捏造したスタブもありません。

パージに関する注記（2026-06-16）。 以前コードネームで呼ばれていた 3 つのバックエンドはパージ済みです （旧ルートは現在 404 を返します）。Hatun-MCP は、上記の稼働中で誠実な a11oy の同等機能に向け直され、接続前に 200 を確認済みです。 404 を返すルートにツールを向けることはありません。サブルートが存在しない場合（例：/immune/screen）、ツールは最も近い実在ルート（/immune/verdict）にマッピングされ、その対応関係はアダプターの docstring とカタログの reason で開示されます。

ビザンチン・クォーラム＋BLS 集約

szl_lambda_quorum は、ガバナンス上重要な Λ 判定を 5 つのバックエンドサービスに振り分け、**ビザンチン n ≥ 3f+1 クォーラム（n=5、f=1）**に基づいて判定します。4 つ以上のサービスに到達でき、3 つ以上が合意する必要があります。参加するレシートは BLS12-381 で集約されます（py_ecc。BLS バックエンドがない場合は、誠実な sha256 Merkle ルートにフォールバックします）。いずれかの機能のポリシールートが稼働していない場合、クォーラムは適切に縮退します（n=4 でも n ≥ 3f+1 を満たします）。縮退したことは governance.quorum で開示されます。

---

ローカルで実行（stdio）

pip install -r requirements.txt
python -m hatun_mcp.server          # stdio mode for Claude Desktop / Codex

ホスト環境で実行（Streamable HTTP）

uvicorn hatun_mcp.server_http:app --host 0.0.0.0 --port 7860
# MCP endpoint:  http://127.0.0.1:7860/mcp   (legacy SSE at /sse)
# Process liveness: http://127.0.0.1:7860/healthz
# Signed-release readiness: http://127.0.0.1:7860/readyz

DSSE 署名鍵は、オペレーターが管理するシークレット HATUN_MCP_SIGNING_KEY（PEM）を通じて実行時に注入されます。鍵がない場合、署名者は誠実な PLACEHOLDER モードで動作します（明確に表示され、偽の署名は生成しません）。

/healthz で確認できるのは、プロセスとローカルのレシートチェーンが応答できることです。/readyz は、投資家およびデプロイメント向けのフェイルクローズ契約です。レシートチェーンが検証され、プレースホルダーではない署名鍵が有効な場合に限り 200 を返します。それ以外の場合は、失敗したチェック名を含む 503 を返します。公開サーバーカードには、このサーバーが実際に実装している API キー方式のみが記載されます。

MCP マニフェストのアテステーション

GET /.well-known/mcp-manifest-attestation は、GET /.well-known/mcp が配信する正確な生バイト列（すべてのサーバーカードのエイリアスは同じバイト列を配信します）に対する、キャッシュされた整合性の紐付けを返します。これには、SHA-256 のサブジェクトダイジェストとカスタム述語タイプ https://szlholdings.com/attestations/mcp-manifest/v1を含む、決定論的なhttps://in-toto.io/Statement/v1が含まれます。既存の P-256 署名鍵が設定されている場合、このステートメントはpayloadTypeがapplication/vnd.in-toto+jsonの実際の DSSE エンベロープに格納されます。この鍵がない場合、レスポンスではsigning.state=UNSIGNEDおよびdsseEnvelope=nullが明示され、空の署名が署名済みとして提示されることはありません。

このアーティファクトはプロセスの起動時に一度だけ構築され、呼び出し元が署名対象のペイロードを指定することはできません。Khipu レシートは発行しません。対象範囲はバイト列の整合性のみです。ランタイムのツールの同等性、アップストリームの可用性、カードの背後にある動作はアテストしません。MCP サーバーカードとこの well-known ルートは SZL によるドラフト拡張であり、批准済みの MCP ディスカバリー標準を主張するものではありません。keyidはヒントにすぎず、検証者は P-256 公開鍵の信頼性を別経路で確立する必要があります（同一オリジンの/pubkeyルートは独立した信頼アンカーではありません）。透明性ログへの登録は明示的に利用できません。

ホストされたコントラクトを評価する

curl -i http://127.0.0.1:7860/healthz
curl -i http://127.0.0.1:7860/readyz
curl -s http://127.0.0.1:7860/api/console-state

/api/console-state（hatun_mcp/state.py）は、/にある人間向けコンソールの読み取り元です。上記のコマンドは、ローカルで起動したサーバーを対象とします。デプロイ環境では、廃止されたスタンドアロンの Space ホストではなく、運用者から提供され、承認されたオリジンを使用してください。このデータはリクエスト時にこのプロセスのみから組み立てられます。ツールカタログは手動管理のリストではなく、稼働中の FastMCP レジストリから列挙され、レシートの深さとヘッドハッシュは稼働中の Khipu チェーンから取得されます。また、card_parityは公開済みサーバーカードとそのランタイムレジストリとの比較結果を測定済みとして報告します。読み取れない情報には、数値を添えず、正直なラベル（UNAVAILABLE）が付けられます。事前入力されたスナップショットはないため、読み取りに失敗した場合、コンソールには古い値ではなくUNAVAILABLEが表示されます。レシートは発行せず、読み取り結果そのものを超える内容をアテストすることもありません。

レスポンスのステータスと観測時刻を記録してください。healthz=200は Hatun プロセスの稼働状態のみを示すものとして報告してください。readyz=200は、Hatun で定義されたローカルのレシートチェーンおよび署名者の準備状態のみを示すものとして報告してください。これらのチェックでは、killinchu または a11oy organ の可用性は確認できません。アップストリームの行に稼働中のラベルを付ける前に、記載されたルート（または文書化された非変更型の準備状態確認ルート）に対して、別途、上限時間を設けた読み取り専用のプローブを実行し、ルート、レスポンスのステータス、ソース、観測タイムスタンプを記録してください。POST のみのサーフェスや状態を変更するサーフェスについては、操作を実行するのではなく、事前に承認された非変更型のコントラクトプローブまたはタイムスタンプ付きレシートを必須とします。Hatun の準備が整っていても、アップストリームの観測が欠落している、古くなっている、または使用できない場合、その行は一部利用可能または利用不可として報告してください。サンプルのクライアント設定にフォールバックしてはいけません。

---

MCP クライアントのセットアップ

Claude Desktop

以下のスニペットはローカルサーバー用の設定例です。まず HTTP サーバーを起動し、受け付けられる API キーを設定して、szl_YOUR_KEYを置き換えてください。リモート環境にデプロイする場合は、運用者から提供され、承認された HTTPS MCP URL に置き換えてください。 examples/claude-desktop-config.jsonを ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）／ %APPDATA%\Claude\claude_desktop_config.json（Windows）に配置し、szl_YOUR_KEYを置き換えてください。

{
  "mcpServers": {
    "hatun-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote",
        "http://127.0.0.1:7860/mcp/",
        "--header", "Authorization: Bearer szl_YOUR_KEY"]
    }
  }
}

Codex（~/.codex/config.toml）

[mcp_servers.hatun-mcp]
command = "npx"
args = ["-y", "mcp-remote", "http://127.0.0.1:7860/mcp/",
        "--header", "Authorization: Bearer szl_YOUR_KEY"]

Continue（~/.continue/config.json）

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "mcp-remote",
            "http://127.0.0.1:7860/mcp/",
            "--header", "Authorization: Bearer szl_YOUR_KEY"]
        }
      }
    ]
  }
}

---

テスト

HATUN_MCP_DISABLE_DYNAMIC=true python -m pytest tests/ -q
# tests/test_server.py    — list tools, call a tool, assert response shape
# tests/test_github_estate_snapshot.py — bounded public GitHub observer, mocked provider
# tests/test_quorum.py    — quorum math + threshold edge cases + BLS aggregate
# tests/test_adapters.py  — mocked organ endpoints, adapter wiring + honest gaps
# tests/test_governance.py— Khipu chain, Yuyay gate, PURIQ factor (pre-existing)
# tests/test_http_routes.py — exact-byte card attestation + public HTTP contracts

サーバーのテストでは、既存の明示的ファイル指定によるホスト型 CI ゲートでこのテストも実行されるよう、estate 回帰テストクラスもインポートしています。実際のインメモリ MCP の検出と呼び出し、引数の拒否、正規ダイジェストのバインディング、一時的な P-256 署名を検証します。これらのテストにおけるプロバイダーの応答はシミュレーションです。テストに合格しても、新しいツールが公開されたり、現在の GitHub／HF の稼働状況が確認されたりするわけではありません。

python tests/proof_inmemory.py は、実際のインメモリ MCP プロトコルを実行し、静的なランタイム名とサーバーカード名が完全に一致することを確認します。この検証では、独自のプロセス内で動的カタログのプローブとレシートシンクへの転送を無効にします。CI では、ドキュメントに記載された直接実行コマンドを検証するため、無関係な作業ディレクトリからも実行します。

Ouroboros ループ（ドクトリンへの相互参照）

hatun-mcp 自体は、estate の Ouroboros 有界再帰カーネルを実装していません。その PURIQ オーケストレーターは、再帰ではなく、ツール呼び出しごとに 1 回だけ実行する有界フローです。このセクションは、ドクトリンへの相互参照であり、このフローがレシートで閉じたアイデンティティ（receipts.in ≡ receipts.out。この README にすでに記載）をどのように体現するかについて、正直に説明するものです。

正規の定義は、レシートで閉じたカーネル szl-holdings/ouroboros → src/loop-kernel.ts（runLoop）です。これは、収束を測定可能な有界再帰であり、次の 4 つの終了条件のいずれかで必ず終了し、すべての実行についてガバナンスレシートを生成する必要があります。converged | consistent | aborted | budgetExhausted トレースこそが成果物です。

hatun-mcp がこのプリミティブをどのように体現するか（hatun_mcp/puriq.py）：

• 有界で、必ず終了します。 各ツール呼び出しは有限のパイプラインです。Yuyay-13 ゲート → メッシュクォーラム（ビザンチン耐性 n ≥ 3f+1）→ HUKLLA トリップワイヤー → Khipu 追記 → DSSE 署名 → マスターフォーミュラのスカラー合成を経て、レイテンシ予算内に必ず終了し、レシートハッシュを返します。有界でないループはありません。
• レシートで閉じています。 すべての呼び出しで、追記専用の sha256 DAG に Khipu リンクが生成され、クライアントはレシートハッシュを受け取ります。これが、このリポジトリにおけるヘッダーのアイデンティティ receipts.in ≡ receipts.out の実際の実装です。これは、各署名済みレシートが監査可能な入力として DAG にフィードバックされるという**比喩（数式ではなくドクトリン）**です。

誠実性（Doctrine v11 · 749/14/163）： ここで Λ は [0,1] の入力スカラーとして使用され、予想 1です。参考情報であり、証明された定理では決してありません。これは有界で、必ず終了するガバナンスフローであり、永久機関やゼロコストを一切主張しません。

---

Doctrine v11 LOCKED — 749 / 14 / 163 · Λ = 予想 1（定理ではありません）· SLSA L1 は正直に記載 · L2 の検証済み来歴はロードマップ上（L3 は主張していません） receipts.in ≡ receipts.out

Signed-off-by: Yachay <[email protected]> Co-Authored-By: Perplexity Computer Agent <[email protected]>