mcp-agent-template

mcp-agent-template — ガード機能を備えたエンタープライズ向け MCP エージェント

英語での概要。 IT 部門が LLM エージェントに使わせることのできる MCP サーバーのテンプレートです。すべてのツール呼び出しには、許可リストポリシー（policy.yaml）、呼び出し元のロール（MCP ツールのアノテーションから判定される lecteur ／ operateur ／ admin）、パラメーターごとの許可値、破壊的な操作に対する人間の確認（MCP エリシテーション。2025-11-25 と 2026-07-28 の両プロトコルに対応）、および JSONL 監査ログ（モード 0600、呼び出しごとに相関 ID を 1 つ）が適用されます。mcp-agent-template パッケージには、実行可能なサンプルが 2 つ含まれています。エンタープライズ向け（チケット、読み取り専用の LDAP 風ディレクトリ、読み取り専用の SQL インベントリ。すべて架空のローカルデータを使用）と、汎用運用向け（systemd と docker のステータス、確認を伴う再起動）です。ローカル優先、セルフホスト可能、オンプレミスで、クラウドもテレメトリーもありません。AGPL-3.0 または、規模を問わず企業向けの商用ライセンスでデュアルライセンスされています。

---

企業で AI エージェントにツールを提供すると、いつも同じ疑問が生じます。誰が、何を実行する権限を持つのか、危険な操作を誰が承認したのか、そして記録はどこにあるのか。このリポジトリは、公式 MCP SDK を中心に、これらの疑問に一度で答えるテンプレート（「Use this template」ボタン）です。

ガード機能

ツール呼び出しには、次の順序で処理が適用されます。

1. 許可リスト（policy.yaml）：リストにないツールは拒否されます。

2. 呼び出し元のロール：最低限必要なロールはツールの種類によって決まり、ポリシーで引き上げることだけができます。

   ツールの種類	公開される MCP アノテーション	最低限必要なロール
   読み取り	readOnlyHint	lecteur
   非破壊的な書き込み	—	operateur
   破壊的操作	destructiveHint	admin + 人間による確認

3. 許可される値：たとえば、再起動できる systemd ユニットを特定のものだけに限定できます。

4. 破壊的なツールに対する人間の確認：クライアントが人間に質問を表示します（MCP エリシテーション）。チェック 1～3 はその前に実行されます。ロールで許可されていない操作の承認を人間に求めることはありません。明示的な「はい」以外はすべて拒否として扱われます。質問を表示できないクライアントの場合も同様です。

5. JSONL 監査ログ。ファイルは 0600 で、呼び出しごとに 1 つの相関 ID が付与され、判定、確認、結果を関連付けます。秘密情報に見えるパラメーター（password、token、api_key など）はマスクされます。

拒否された場合は、エージェントにわかりやすいエラーが返され、偽の成功が返ることはありません。

試す

uvx mcp-agent-template --help
uvx mcp-agent-template serve --example enterprise   # tickets, annuaire, inventaire (donnees fictives)
uvx mcp-agent-template serve --example ops          # systemd et docker
uvx mcp-agent-template check-policy policy.yaml     # valide une politique et resume ses regles

MCP クライアント（Claude Code、Claude Desktop など）で：

{
  "mcpServers": {
    "entreprise": {
      "command": "uvx",
      "args": ["mcp-agent-template", "serve", "--example", "enterprise"],
      "env": { "MCP_AGENT_TEMPLATE_ROLE": "operateur" }
    }
  }
}

変数	役割	デフォルト
MCP_AGENT_TEMPLATE_ROLE	呼び出し元のロール：lecteur、operateur、admin	lecteur
MCP_AGENT_TEMPLATE_CONFIRM	elicit：人間がクライアント経由で確認します。client：クライアントがすでに確認します（destructiveHint を読み取ります）	elicit
MCP_AGENT_TEMPLATE_AUDIT_DIR	監査ログのディレクトリ	~/.local/state/mcp-agent-template
MCP_AGENT_TEMPLATE_DATA_DIR	サンプル用 SQLite データベース	~/.local/state/mcp-agent-template-demo

現時点では、ロールはクライアントの設定から取得します。各端末または各プロファイルに、それぞれのロールが割り当てられます。ロールの取得元は小さなインターフェース（RoleSource）であり、ツールに手を加えることなく、トークン認証を接続できます。

例

企業（--example enterprise）：外部サービスを一切使わず、ローカルで作成した架空の企業「Exemple SA」のデータを使用します。

• サポート：list_tickets、get_ticket、create_ticket（「critical」の優先度はポリシーにより人間に限定）、close_ticket、delete_ticket（管理者権限＋確認）；
• LDAP 形式の読み取り専用ディレクトリ：search_directory、get_user、group_members；
• SQL による読み取り専用インベントリ：list_tables、query_inventory。2 つの保護策があります。データベースは mode=ro で開かれ、SQLite の認可機能により、WITH 内に隠されている場合も含め、あらゆる書き込み、PRAGMA、ATTACH が拒否されます。

Ops（--example ops）：読み取り用の service_status と list_containers、ポリシーで指定されたユニットに限定し、確認後に実行する restart_service。

独自のサーバーを作成する

from mcp.server.mcpserver import MCPServer
from mcp_agent_template import Guard, Policy, ToolKind

server = MCPServer("mon-agent")
guard = Guard(server, Policy.load("policy.yaml"))

@guard.tool(ToolKind.READ, title="Lister les commandes")
def list_orders(status: str = "ouverte") -> list[dict]:
    """Commandes du jour."""
    ...

@guard.tool(ToolKind.DESTRUCTIVE, title="Annuler une commande")
def cancel_order(order_id: int) -> dict:
    """Annule une commande (admin + confirmation humaine)."""
    ...

server.run()

# policy.yaml
version: 1
default: deny
tools:
  list_orders: {}
  cancel_order:
    allowed_values:
      order_id: ["1042", "1043"]

実際のチケット管理ツール、LDAP ディレクトリ、またはデータベースに接続するには、src/mcp_agent_template/examples/stores.py のクラスを置き換えます。MCP ツールとガードは変更する必要はありません。

開発

uv sync
uv run pytest        # garde, politique, audit, exemples, protocoles 2025-11-25 et 2026-07-28, stdio
uv run ruff check src tests

devcontainer が用意されています（.devcontainer/）。

ライセンス

デュアルライセンスです。

• AGPL-3.0（LICENSE）：個人、団体、教育・研究機関は無料で利用できます。
• 商用ライセンス：規模を問わず企業向けです。COMMERCIAL-LICENSE.md をご覧ください。

コントリビューションは、CLA.md の契約に基づいて受け付けています。

Lyra エコシステムの一部

fedora-agents（相関 ID 付きの監査ログ、MCP アノテーション）およびLyraと同じアプローチです。Lyra はフランス語を優先する音声アシスタントで、機密性の高いアクションの前に毎回、人間の確認を求めます。