guardian-mcp

@odingard/guardian-mcp

エージェントのツール呼び出しを Guardian 経由でルーティングする MCP サーバーです。Guardian は自律型 AI のための人間の権限基盤です。すべてのツール呼び出しは、実行前に決定論的な ALLOW / ASK / DENY 判定を受けます。DENY の場合、アクションは実行されず、ASK の場合、人間が承認するまで保留されます。

インストール

npm i -g @odingard/guardian-mcp

MCP クライアントの設定

{
  "mcpServers": {
    "guardian": {
      "command": "guardian-mcp",
      "env": {
        "GUARDIAN_BASE_URL": "https://guardian-api.odingard.com",
        "GUARDIAN_AGENT_CREDENTIAL": "gak_…",
        "GUARDIAN_CONNECTION_ID": "con_…"
      }
    }
  }
}

GUARDIAN_ADAPTER_ID を設定すると、ツールアダプターを任意で上書きできます。

ツール

ツール	機能
guardian_invoke_tool	ツール呼び出しを提案します。ALLOW の場合は実行してレシートを返し、ASK の場合は人間の承認待ちとなる requestId を返し、DENY の場合は理由コードとともに拒否します。
guardian_claim	承認された ASK を requestId で取得して実行し、レシートを返します。
guardian_receipt	リクエストの機械可読な証拠レシートを取得します。

Guardian の機能なしでは何も実行されません。モデルの出力は提案であり、アクションではありません。

既存の MCP サーバーをガバナンスする：guardian-mcp proxy（0.3）

WhatsApp、Stripe、Shopify、ファイルシステム、データベースなど、すでに使用している任意の stdio MCP サーバーの前段に Guardian を配置します。クライアントには上流サーバーのツールが変更されずに表示され、すべての呼び出しは最初に判定されます。

{
  "mcpServers": {
    "whatsapp-governed": {
      "command": "guardian-mcp",
      "args": ["proxy", "--", "npx", "-y", "your-whatsapp-mcp-server"],
      "env": {
        "GUARDIAN_BASE_URL": "https://guardian-api.odingard.com",
        "GUARDIAN_AGENT_CREDENTIAL": "gac1.…",
        "GUARDIAN_CONNECTION_ID": "con_…",
        "WHATSAPP_TOKEN": "…"
      }
    }
  }
}

判定	動作
ALLOW	呼び出しを上流サーバーに転送し、その後、機能を引き換えてレシートを記録します。
ASK	何も転送されません。正確な呼び出しは requestId のもとで保留されます。人間が承認すると、guardian_claim がその呼び出しを一度だけ正確に転送します。
DENY	何も転送されません。今後も転送されません。Guardian に接続できない場合も同様です。

• guardian_claim と guardian_receipt がツールリストに追加されます。
• 上流サーバーには GUARDIAN_* 設定が渡されないため、エージェントの認証情報が見えることはありません。
• 判定ゲート付き： 許可された呼び出しは、機能が引き換えられる前に上流で実行されます。引き換え時に拒否された場合は成功ではなく、インシデント（localEffectRan: true）として報告されます。
• 初回セットアップ： Guardian コンソールでツールサーバーを接続し、各上流ツールを「My own code (record-only)」として追加します。その後、エージェントにそれらのツールを許可します。
  • 0.3.1 以降、プロキシはツールを自ら登録しようとしません。
  • GUARDIAN_AUTO_REGISTER=true を設定すると登録が再び有効になりますが、エージェントの許可設定で mcp.install が固定されていない限り拒否されます。
  • Guardian が拒否した場合、結果には修正すべき内容が示されます。
• 保留中の呼び出しはプロキシプロセス内に保持されます。プロキシを再起動すると破棄され、何も転送されません。

guardian-mcp --help で使用方法が表示されます。設定が不足している場合は、スタックトレースではなく、不足している設定名を示す1行のメッセージが表示されます。

これから管理する内容を確認：guardian-mcp tools

サーバーをプロキシの背後に置く前に、ツールとそれぞれに推奨される Guardian モードを一覧表示します。Guardian の認証情報は不要です。

npx -y @odingard/guardian-mcp tools -- npx -y @modelcontextprotocol/server-filesystem ./data

Tool            Suggested     Why
read_file       Allow         server marks it read-only
write_file      Ask me first  "write" may change something
delete_branch   Ask me first  server marks it destructive
createIssue     Ask me first  "create" may change something  ⚠ name not accepted by Guardian

推奨モードの決定方法：

• まず、サーバー独自の MCP アノテーション（readOnlyHint、destructiveHint）を使用します。
• それ以外の場合は、ツールの動詞で決まります。get、list、search は Allow、それ以外は Ask が推奨されます。

あくまで推奨です。実際のモードはコンソールで設定します。Guardian の命名規則に違反するツール名にはフラグが付けられます。そのようなツールへの呼び出しはすべて拒否されるためです。機械可読形式で出力するには、--json を追加してください。

ライセンス

Apache-2.0。正規の開発はOdingard Guardian モノレポで行われています。