HAI-MCP

HAI-MCP · MCP によるモデル非依存のコントロールプレーン Human Agent Interface（HAI） のアプローチ向け

---

このリポジトリが存在する理由

エージェントは今やシェル、エディター、ブラウザー、CIを操作しています。その多くは、人間が状況を把握できなくなるほど長い間、人間が介在しない状態で動作します。HAI、すなわち Human Agent Interface は、エージェントによる作業を 可視化し、範囲を限定し、オーナーの承認を必須とし、復旧可能にする ための、独自の見解に基づくエビデンス重視のアプローチです。エージェントが作業しているときも、人間がその作業の 責任者 であり続けられます。

HAI-MCP は、このアプローチを実装したオープンソースのモデル非依存ソフトウェアです。Samuel Fleig の HAI スタックを構成する要素のひとつであり、その背後にどの LLM があっても、Model Context Protocol に対応するあらゆるクライアントが接続できます。

公式サイト：https://www.human-agent-interface.com/ · Samuel について：https://www.human-agent-interface.com/samuel/

---

ここでいう「MCP コントロールプレーン」とは

MCP、つまり Model Context Protocol は、ツールサーバーが LLM を基盤とするクライアント（Claude Code、Codex、Cursor、Grok、OpenCode、Hermes、…）に ツール、リソース、プロンプト を提供できる、標準化された JSON-RPC インターフェースです。クライアントはサーバーのツールを検出し、会話中に呼び出します。モデルから見れば、サーバーはステートレスです。

コントロールプレーン サーバーは、それ自体では作業を 実行せず、作業の承認、範囲設定、記録、および人間への引き継ぎ方法を管理します。具体的には、MCP コントロールプレーンは次の機能を提供します。

対象	HAI-MCP が提供するもの
ミッション契約	hai_open_mission、hai_get_contract、hai_recontract
セッションのリース	hai_authorize_session — 時間制限付き、契約バージョン管理付き
アクティビティの分類	hai_check_activity / hai_drift_check — 契約内か契約外か
フォーカスとレーン	hai_set_focus、hai_status — ACTIVE レーンは最大 2 つ
オーナーの承認ゲート	accept / recontract / abandon 用の、帯域外のワンタイム nonce（HAI_OWNER_HOME または ntfy）、もしくは macOS の Touch ID
エビデンスとクローズ	hai_proof、hai_close_mission、hai_stop
受信箱とインテーク	hai_intake、hai_distill、hai_park、hai_park_item
復旧	hai_checkpoint、hai_recover

HAI-MCP は意図的に エージェントランタイムではありません。LLM を呼び出すことも、シェルを実行することも、git にプッシュすることも、ファイルを削除することもありません。HAI-MCP は審判役です。エージェントは 「実行してよいですか？」 と確認し、「実行しました」 と記録するために HAI-MCP を呼び出します。

---

機能

• 1つの状態エンジン、23個のツール — 3つのインターフェース（レガシー制御プレーン、ミッションのライフサイクル、日常ループのラッパー）が、強化された1つのコアを共有します。
• 厳格なフェイルクローズ境界 — 入力は型付けされ、強制変換されるのではなく拒否されます。Integer フィールドに String "2" を指定すると拒否されます。型が黙って改変されることなく、サーバーへの接続は維持されます。
• バージョン管理されたミッション契約 — すべてのミッションは単調増加するバージョンの契約を持ちます。契約を再作成すると、フィールド単位の差分が表示され、既存のリースはすべて無効になります。
• 時間制限付きセッションリース — hai_authorize_session は、リースをミッション ID、契約バージョン、期間、ロール、貢献内容、申告された基準セットに紐付けます。
• 決定論的なドリフトチェック — hai_check_activity は、LLM を一切呼び出すことなく、計画中または観測されたアクティビティを契約に照らして分類します。
• 2者によるオーナーゲート：
  • デフォルト（nonce）： サーバーはオーナーのチャネル（HAI_OWNER_HOME / file、または ntfy）にワンタイムコードを送信します。クライアントにコードが表示されることはありません。コードは特定の変更に紐付けられ、一度だけ使用でき、有効期限があります。HAI_HOME に保存されるのはハッシュのみです。
  • touchid（macOS）： サーバープロセスは、該当する変更に対する Touch ID プロンプトを表示します。コードはありません。エージェントによる後続の呼び出しで変更が適用されます。クライアントが自分自身を承認することはできません。
  • ack_legacy： 従来の自己申告式 owner_ack フラグです。信頼に委ねられていることが hai_health で明示されます。
• マウントテーブル — hai_bind_project は、owner_ack + reason の確認を経て、論理的な project_id をデバイス上のディレクトリに紐付けます。
• モデル非依存 — 同じバイナリ、同じツール、同じ契約です。ガバナンスを書き換えることなく LLM を切り替えられます。
• 2種類のトランスポート — stdio（デフォルト）と、任意のベアラートークン紐付けに対応する streamable-http（デフォルトではループバックのみ）。
• チェックポイントと復旧 — hai_checkpoint はコンテキストのスナップショットを作成し、hai_recover は復旧に必要な最小限の次のアクションを返します。
• 203件のテストが成功 — エンジンはテストで網羅されています。このスライスは、学習予算とオーナー計測機能の後続対応に向けて引き続き作業中です。

---

インストールと実行

Python ≥ 3.12 と uv が必要です。

git clone https://github.com/smlfg/hai-mcp.git
cd hai-mcp
uv sync --all-extras
uv run hai-mcp          # stdio transport, default

Streamable-HTTP トランスポート：

HAI_TRANSPORT=streamable-http \
HAI_HTTP_HOST=127.0.0.1 \
HAI_HTTP_PORT=8765 \
HAI_HTTP_TOKEN="$(openssl rand -hex 32)" \
uv run hai-mcp

HAI_HTTP_TOKEN が設定されていない場合、ループバック以外のホストへの HTTP バインドは拒否されます。docs/OWNER_GATE.md と --help の出力を参照してください。

---

使用例 — サーバーをクライアントに接続する

サーバーはトランスポートに依存しません。すべての MCP クライアントで同じ23個のツールを利用できます。スニペットをクライアントの MCP 設定に追加して、再起動してください。

Claude Code / Claude Desktop

{
  "mcpServers": {
    "hai": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/hai-mcp",
        "hai-mcp"
      ],
      "env": {
        "HAI_HOME": "/home/you/.hai",
        "HAI_OWNER_HOME": "/home/you/.hai-owner"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "hai": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/hai-mcp",
        "hai-mcp"
      ],
      "env": {
        "HAI_HOME": "/home/you/.hai",
        "HAI_OWNER_HOME": "/home/you/.hai-owner"
      }
    }
  }
}

Codex / Hermes / 任意の MCP stdio クライアント

同様に、uv run --directory … hai-mcp コマンドを指定し、2つの環境変数を渡します。その他のスニペットは docs/client-snippets/ にあります。

---

使用例 — プロトコルを動作させる

一般的なエージェントのループでは、行動の前と後に HAI-MCP を呼び出します。

1. 範囲を限定したミッションを開始する

hai_mission_start(
  problem   = "Refactor the evaluator harness to be deterministic.",
  artifact  = "Pull request titled 'evaluator: deterministic harness'.",
  done_criteria = [
    {"id": "C1", "description": "Two A/B cases produce identical verdicts on three reruns."},
    {"id": "C2", "description": "Harness runs offline; no live network calls."},
  ],
  owner             = "samuel",
  time_limit_hours  = 6,
  non_goals         = ["Do not touch the MCP server.", "Do not change contract shapes."],
  constraints       = {"python": ">=3.12", "branch": "slice/eval-determinism"},
)

2. セッションリースを承認する

hai_authorize_session(
  mission_id         = "<from open>",
  contract_version   = 1,
  agent_identity     = "codex-cli",
  role               = "implementer",
  contribution       = "Deterministic A/B harness",
  expected_result    = "Green pytest with frozen inputs.",
  duration_minutes   = 90,
  criterion_ids      = ["C1", "C2"],
  device_id          = "mbp-mirgraatin",
  harness_id         = "codex-cli/0.45",
)

3. アクティビティの実行前に確認する

hai_check_activity(
  session_id     = "<from lease>",
  activity_step  = "Replace random.seed with a seeded fixture in tests/test_eval_ab.py",
  criterion_id   = "C1",
  affected_paths = ["tests/test_eval_ab.py", "tests/fixtures/ab/case1.json"],
)
# → {"verdict": "on_contract", ...}

4. 証拠を添えて終了する

hai_proof(
  mission_id        = "<from open>",
  contract_version  = 1,
  outcome_summary   = "A/B cases produce identical verdicts on three reruns; harness offline.",
  evidence          = {
    "C1": {"command": "pytest tests/test_eval_ab.py -q", "exit_code": 0,
           "reruns": [0, 0, 0]},
    "C2": {"command": "pytest tests/test_eval_ab.py -q --offline", "exit_code": 0},
  },
)

5. 所有者承認による昇格

hai_accept_next_step、hai_recontract、またはミッションの放棄では、owner_code を指定せずに最初の呼び出しを行うと、所有者に別の経路で確認を求めます。

• file / ntfy: 一度限りのコードが HAI_OWNER_HOME または ntfy トピックに送信されます。コードを owner_code=<code> として返すと、操作が完了します。クライアントがコードを見ることはありません。HAI_HOME に保存されるのはコードのハッシュだけです。
• touchid（macOS）： サーバーで HAI_OWNER_CHANNEL=touchid を設定します。サーバーに Touch ID のプロンプトが表示され、status: owner_approved が返されます。同じツールを同じ引数（コードなし）で再度呼び出すと、その変更が適用されます。オプション：HAI_OWNER_TOUCHID_TIMEOUT（デフォルトは 60）、HAI_OWNER_TOUCHID_HELPER（コンパイル済みバイナリ）、および Touch ID を実行できない場合に限る HAI_OWNER_TOUCHID_FALLBACK=file。

承認は特定の変更に紐づけられ、一度だけ使用できます。Mac では、uv run python scripts/manual_touchid.py prompt と … gate で実際のセンサーをテストできます。CI ではヘルパーをモックします。詳細： docs/OWNER_GATE.md。

---

状態の配置

• グローバル： $HAI_HOME — デフォルトは ~/.hai
• 所有者チャネル： $HAI_OWNER_HOME — デフォルトは ~/.hai-owner（エージェントが読み取れないよう、意図的に HAI_HOME の外部に配置します）
• プロジェクトごと： <project_path>/Projek-Managment/（レガシー）、または project_id が紐づけられている場合はデバイスのマウントと相対プレフィックス
• マウントテーブル： HAI_HOME/core/projects.json

すべての書き込みは、これらのルート内に解決され、制限されます。

---

プロジェクトの構成

hai-mcp/
├── docs/
│   ├── TOOL_CONTRACT.md      # normative tool contract (gates, errors, schemas)
│   ├── OWNER_GATE.md         # nonce + ack_legacy owner-gate spec
│   ├── BUILD_HANDOFF.md
│   ├── client-snippets/      # ready-to-paste mcp.json snippets
│   ├── eval/                 # A/B harness contract
│   ├── plans/                # dated design slices
│   └── visuals/              # mission-lifecycle banner assets
├── scripts/                  # stdio smoke + impact-eval runner
├── src/hai_mcp/              # the server
└── tests/                    # 203 tests

---

制限事項

HAI-MCP の範囲は意図的に限定されています。以下は行いません。

• LLM を呼び出しません。 サーバーは意図的に機能を持たない設計です。ガバナンスは生成とは別の関心事です。
• コードの実行、シェルの起動、git へのプッシュ、ファイルの削除は行いません。 「commit & push」、「run pytest」、「rm -rf」 のようなツールは拒否します。エージェントはこれらを実行し、hai_check_activity / hai_proof で報告することを想定しています。
• hai-intake パッケージとは統合しません。 インテークパイプラインは別のスタックです。共存は可能ですが、統合はしません。
• UI は提供しません。 ダッシュボードはありません。コントロールプレーンは MCP で通信し、JSON を書き込みます。可視化はクライアント側の役割です。
• 複数ミッションの同時実行には対応しません。 グローバルにアクティブなミッションは常に 1 つです。前のミッションを終了（完了または放棄）してから、新しいミッションを開始してください。
• デバイスをまたぐ書き込みには対応しません。 各デバイスから見えるのは、そのデバイス自身のマウントだけです。マウントテーブルはデバイスごとですが、契約はグローバルです。
• MCP のメジャーアップデートとの前方互換性はありません。 サーバーは mcp>=1.9.0,<2 に固定されています。MCP v2 には、別途移行スライスが必要です。
• 失効リスト / キルスイッチ API はありません。 リースの無効化は、recontract、ミッションの終了、または hai_stop によって行われます。*「今すぐすべてを取り消す」*ための別経路のツールはありません。
• 破損した HAI_HOME からの自動復旧はありません。 グローバル状態ディレクトリが破損すると、サーバーは設計どおりフェイルクローズします。復旧は手動で行います（hai_recover を参照）。

ゲートマトリクスの全容については docs/TOOL_CONTRACT.md を、所有者ゲートの契約については docs/OWNER_GATE.md を参照してください。

---

テスト

uv run pytest                       # full suite
uv run python scripts/stdio_smoke.py  # stdio round-trip smoke

Touch ID 所有者チャネルのスライス時点で、リポジトリには203 件のテストがすべて成功した状態で含まれています。CI のステータスは、リポジトリの GitHub Actions ページで確認できます。

---

貢献

コントロールプレーンは意図的に小規模に保たれています。追加は契約スライスを通じて行います。

1. docs/TOOL_CONTRACT.md を読みます。
2. ツール / ゲート / 状態の変更内容を説明する issue を作成します。
3. テストと docs/plans/ 内の計画を含む fail-closed スライスとして取り込みます。

ゲート、スキーマ、またはマウントテーブルを変更するプルリクエストに対応する計画がない場合は、同じ手順に従うよう依頼します。

---

ライセンス

MIT — LICENSE を参照してください。Copyright © 2026 Samuel Fleig.

---

謝辞

HAI-MCP は、Samuel Fleig の HAI スタックの一部です。以下を基盤としています。

• Model Context Protocol の仕様、
• mcp Python SDK（mcp>=1.9.0,<2）、
• および、このサーバーが制御プレーンの作業で置き換える、従来の ~/.config/hai-agent-mcp Hermes ブリッジ。共存に対応しており、ブリッジは必須ではありません。

HAI の公式サイト： https://www.human-agent-interface.com/ · Samuel Fleig について： https://www.human-agent-interface.com/samuel/