agentkit

AgentKit — ガバナンス機能を備えた MCP ツールサーバー

ツールは宣言的に定義され、作用は型付けされ、すべてのアクションがポリシーによって制御され、監査される MCP サーバーです。あらゆる MCP クライアント（Claude Desktop、Cursor、 LangGraph、Claude Agent SDK、CrewAI）で利用できます。

ライブアプリケーション： agentkit.ysiddo-ai-projects.app。

• 研究の背景： RESEARCH.md / オンライン研究ドキュメント
• 実証ベンチマーク： BENCHMARK.md / オンラインベンチマークダッシュボード
• ユーザーガイド： オンラインユーザーガイド
• セルフホスティングガイド： SELF_HOSTING.md

一般的な MCP サーバーとの主な違いは、次の3点です。

• 宣言的なツール。 Python を使ったりフォークしたりせずに、独自の Postgres または HTTP API 上に YAML でツールを定義できます。(docs/REUSE.md)
• 型付けされた作用。 各ツールは作用（read、write、destructive）を宣言し、データを変更するツールは実際にデータを変更します。
• プロンプトに依存しないガードレール。 書き込みはデフォルトで無効です。破壊的なアクションには、モデルには決して見えない、人間が保持する承認トークンが必要です。すべての変更系ツールはドライランに対応し、許可された呼び出しも拒否された呼び出しもすべて監査されます。 (SECURITY.md)

以下に示す同梱のビジネスインテリジェンスツールはリファレンスパックです。仕組みを最初から最後まで示すものであり、サーバーが提供できる機能の限界ではありません。

概要

リファレンス BI パック（組み込み）：

• 6 つのコア MCP ツール：query_kpis、get_company_health、detect_kpi_anomalies、forecast_metric、list_available_metrics、get_executive_summary。これに加えて、宣言型 YAML パック（packs/）から読み込まれるツールもあるため、実行時のツール数は固定の 6 個ではなく、6 個以上です。同梱の annotations パックでは、ガード付きの書き込み／破壊的操作の経路を示す 3 つのツール（list_annotations、annotate_metric、retract_annotation）が追加されます。詳細は以下をご覧ください。
• 10 個の MCP リソース：このプロジェクトで実際にシードされた各ドメイン（Finance、People、Operations、Customer、Engineering、Growth、Logistics、ESG、IT、Security）に対応する kpi://{domain}/latest（src/agentkit_mcp/data/seed.py）。
• 再利用可能なプロンプト 1 個：monthly_executive_briefing

ドメインの一覧、ツールパックのセット、リソース／プロンプトの登録はすべて、このサーバーが提供するのと同じデータ（src/agentkit_mcp/data/seed.py、packs/*.yaml）から導出されており、 ハードコードされていません。そのため、ドメインやツールパックを追加すると、この一覧も自動的に拡張されます。独自の @mcp.resource／@mcp.prompt デコレーターを追加することもできます。詳細は docs/REUSE.mdをご覧ください。

書き込みおよび破壊的操作。 annotations パックを使うと、エージェントはメトリックに永続的な メモを記録でき（annotate_metric、効果 write）、誤って記録したメモをソフト削除できます （retract_annotation、効果 destructive。モデルには決して見えない、人間が保持する AGENTKIT_APPROVAL_TOKEN が必要です）。どちらもデフォルトでは無効です （AGENTKIT_ALLOW_WRITES=false）。SECURITY.md およびポリシーエンジンのモデルについては、RESEARCH.mdのセクション 2 をご覧ください。

プラットフォーム機能：

• 宣言型ツールパック — YAML で独自の Postgres／HTTP にツールを追加（packs/）
• 型付き効果とポリシーエンジン — GET /api/policy で機能の範囲を公開
• 監査証跡 — GET /api/audit。許可／拒否の両方と、拒否理由を記録
• マルチプロバイダー LLM ルーティング（セルフホスト可能なものを含む） — GET /api/llm-routing
• workflow.py の LangGraph 3 エージェントワークフロー（Planner → Analyst → Reporter）
• Claude Agent SDK デモ（demos/claude_agent_sdk_demo.py）
• CrewAI デモ（demos/crewai_demo.py）
• DSPy 調査用スキャフォールド（research/dspy_experiment.py）
• スモークテスト、API、統合、MCP プロトコル、ポリシーガードレール、LangGraph ワークフローにわたる 90 件以上のテスト

PyPI パッケージ

pip install agentkit-mcp
agentkit-mcp               # starts the server (stdio for MCP clients; set PORT for SSE)

MCP クライアントでは、uvx を使うとチェックアウトせずに公開済みパッケージを実行できます。

{ "mcpServers": { "agentkit": { "command": "uvx", "args": ["agentkit-mcp"] } } }

クイックスタート

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt      # server only; demos and research scripts: requirements-demos.txt
cp .env.example .env  # fill in keys + POSTGRES_URL
python mcp_server.py

Claude Desktop のセットアップ

~/.config/Claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "agentkit": {
      "command": "python",
      "args": ["/abs/path/to/agentkit/mcp_server.py"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "POSTGRES_URL": "postgresql://...",
        "LOG_LEVEL": "DEBUG",
        "TELEMETRY_OPT_OUT": "true"
      }
    }
  }
}

ここでは MCP_TRANSPORT=stdio が必須です。これを指定しないと、mcp_server.py は Claude Desktop が起動時に用意するパイプ経由で JSON-RPC をやり取りせず、SSE（ネットワークポート）での配信をデフォルトとして使用するため、ツールが表示されません。ローカルの stdio モードでは MCP_AUTH_TOKEN は不要です（OS のプロセス境界が認証境界になります）。この変数が必要なのは SSE／ネットワーク経由の場合のみです。

マルチプロバイダー LLM ルーティング

3 エージェントの LangGraph ワークフロー（workflow.py）とデモ／研究用スクリプトでは、LiteLLM を介して各役割に独自のモデルを割り当てます。設定にはプレーンな provider/model 文字列を使用するため、プロバイダーの切り替えにコード変更は不要です。

• LLM_REASONING — プランナーエージェントとレポーターエージェント用（デフォルトは anthropic/claude-sonnet-4-6）
• LLM_DEFAULT — ツール呼び出しを行うアナリストエージェント用（デフォルトは groq/openai/gpt-oss-120b）
• LLM_JUDGE — 評価スイートで使用（デフォルトは anthropic/claude-haiku-4-5）
• LLM_LOCAL + INFERENCE_MODE=local — ホスト型プロバイダーの代わりに、ローカル／セルフホスト可能なモデル（例：Ollama）にルーティングします

上記で参照するモデルに対応したプロバイダー API キー（GROQ_API_KEY、ANTHROPIC_API_KEY、OPENAI_API_KEY）を設定してください。.env.example を参照してください。

• 診断：詳細なログを出力するには、LOG_LEVEL を DEBUG に設定してください。
• テレメトリ：MCP コンソールコマンドと REST ファサードの両方で、匿名の起動時 ping（サービス名、バージョン、ランダムなインストール ID。プロンプト、ツール呼び出し、アプリケーションデータは含まれません）がデフォルトで有効です。TELEMETRY_URL で送信先を独自のコレクターに変更できます。TELEMETRY_OPT_OUT=true または DO_NOT_TRACK=1 で無効にできます。上記の Claude Desktop の設定例では TELEMETRY_OPT_OUT を設定しています。

Claude Desktop を再起動してから、次のように質問してください。

• 「現在の会社の健全性はどうですか？」
• 「今後 6 か月の売上を予測してください。」
• 「Finance KPI に異常はありますか？」

LangGraph ワークフロー

from agentkit_mcp.workflow import analyze
result = analyze("What drove gross margin in Q1?")
print(result["report"])

アーキテクチャ

呼び出しの流れ、ポリシーモデル、ツールパック、設計上の決定事項については、ARCHITECTURE.md で説明しています。ダッシュボードではインタラクティブ版を利用できます。REST ファサード（/api/...）は、ダッシュボードや一般の呼び出し元向けに、同じツール、ポリシー、監査、ルーティングのビューを HTTP 経由で提供します。すべての設定変数については .env.example で説明しています。

        Claude Desktop / Cursor / LangGraph
                      │
                      ▼ MCP
              ┌────────────────────────┐
              │     mcp_server.py      │
              │  6 core tools (read)   │
              │  + N pack tools        │
              │    (read/write/        │
              │     destructive)       │
              │ 10 resources, 1 prompt │
              └────────────┬───────────┘
                            │
        ┌───────────────────┼──────────────────┐
        ▼                   ▼                  ▼
   pg_store            insights          forecasting
   (KPIs, real         (health,          (scikit-learn
   domains + write-    anomalies)        LinearRegression
   back annotations)                     + Monte Carlo CI)

設計メモ

• 1 つのサーバー、2 つのトランスポート。 同じツールセットを stdio（ローカルクライアント）と SSE（ネットワーク）経由で提供します。
• ケイパビリティポリシーエンジン。 影響を（読み取り、書き込み、破壊的操作に）分離し、プロンプトとは独立して、モデルの下位層で適用します。
• クライアントの対応状況。 Claude Desktop、Cursor、Devin の設定で動作を確認済みです（以下の統合ガイドを参照）。

正式な定式化、関連文献の背景、引用の詳細については、RESEARCH.md を参照してください。

ベンチマーク再現スイート

再現可能なベンチマーク評価スイートを実行します。

# Test MCP framework overhead
python3 eval/run_benchmarks.py --seed 42

# Full 43-scenario LangGraph suite across all 10 KPI domains
python3 eval/run_dspy_eval.py

# Comprehensive MCP tool execution metrics
python3 eval/run_mcp_tools_benchmark.py

統合ガイド（Claude Desktop、Cursor、Devin）

• Claude Desktop：claude_desktop_config.example.json と docs/INTEGRATION_GUIDE.md を参照してください
• Cursor IDE：cursor_mcp.example.json を参照してください
• Devin AI Agent：devin_mcp.example.json を参照してください

クライアントの自動検証：

python3 tests/test_mcp_client.py

プロジェクトを支援する

AgentKit が役に立った場合は、リポジトリにスターを付けると、ほかのエンジニアが見つけやすくなります。また、@Yacine-ai-tech をフォローすると、新しいリリースの情報を手軽に入手できます。同じ問題を抱える同僚にリンクを共有していただくのも歓迎です。

質問や現場での知見は Discussions へ、再現可能なバグは Issues へお寄せください。

ライセンスとエンタープライズ利用（デュアルライセンス）

このプロジェクトは AGPL-3.0 License のもとでオープンソースとして公開されています。研究者、学生、オープンソースの愛好家は完全に無料で利用できます。 商用ライセンスについては、COMMERCIAL.md を参照してください。