Agent と MCP ワークフロープラットフォーム

承認ゲート付きインシデントワークフローで、読み取り専用の MCP ツールを通じて証拠を収集し、1 つの正確な冪等アクションを実行し、結果を検証し、耐久性のある監査証跡を保持します。

概要

エージェンティックワークフローは、通常のリクエスト/レスポンス API を超えるリスクをもたらします。外部ツールの出力が悪意を持つ可能性があり、リトライによって副作用が重複する可能性があり、承認が古くなる可能性があり、ツールの応答が成功しても永続化された状態を反映していない可能性があります。

このプロジェクトは、これらの障害モードに対処するために、意図的に範囲を限定したインシデント対応ワークフローを実装します。決定論的プランナーが、Model Context Protocol (MCP) を通じて承認された読み取りツールを発見して呼び出し、チケットを提案し、人間の承認のために一時停止し、その承認を SHA-256 アクションダイジェストにバインドし、冪等なデータベース書き込みを実行し、保存された結果を検証します。LLM は使用しません。焦点は信頼性の高いオーケストレーションと制御境界にあります。

Related MCP server: mcp-policy-gateway

主な機能

• JSON-RPC stdio を介した MCP ツールの発見と呼び出し

• サービスステータスとランブック検索ツールを備えた独立した読み取り専用 MCP サーバー

• MCP ツール発見とは独立したアプリケーションレベルの許可リスト

• ステップ予算の適用を伴う明示的なワークフローステートマシン

• 結果を伴う書き込みの前に行われる人間による承認または拒否

• 完全な提案アクションに承認をバインドする SHA-256 ダイジェスト

• リトライ中のチケット重複作成を防ぐ安定した冪等性キー

• SQLite に対する独立した書き込み後検証

• 耐久性のある実行、承認、チケット、および順序付けられた監査イベント

• Bearer 認証された FastAPI エンドポイント、CLI ワークフロー、CI、および決定論的テスト

アーキテクチャ

flowchart LR
    C[API Client] --> A[FastAPI]
    A --> W[Workflow Service]
    W --> P[Deterministic Planner]
    W --> M[MCP Stdio Client]
    M --> S[Read-Only MCP Server]
    W --> D[(SQLite Store)]
    H[Human Approver] --> A
    A --> W
    W --> T[Idempotent Ticket Write]
    T --> D
    D --> V[Verification]
    V --> W

MCP ピアは観測結果を提供できますが、書き込み権限はありません。チケット作成はアプリケーション内に留まり、送信された承認ハッシュが現在の提案と一致するまで発生しません。

ワークフローステートマシン

created -> gathering -> awaiting_approval -> executing -> verifying -> completed
                |              |               |            |
                v              v               v            v
              failed        cancelled        failed       failed
                                                 |
                                                 `-- resume with matching approval

API

すべての /v1 エンドポイントには Authorization: Bearer <AGENT_API_TOKEN> が必要です。

技術スタック

仕組み

1. クライアントが、サービスと報告された症状に対して実行を作成します。

2. ワークフローが MCP ツールを発見し、それらを自身の読み取り許可リストと比較し、範囲を限定した観測結果を収集します。

3. ツール出力は信頼できない証拠として保存され、ワークフロー命令として解釈されることはありません。

4. アプリケーションが、1 つの提案されたチケットアクション、安定した冪等性キー、および正規の SHA-256 アクションハッシュを作成します。

5. ワークフローは awaiting_approval を永続化し、書き込みを行わずに返します。

6. 人間が正確なハッシュに対する承認または拒否を送信します。変更された、または古い提案は HTTP 409 で拒否されます。

7. 承認されたアクションは、冪等にチケットを作成し、SQLite からそれを読み戻し、検証後にのみ実行を完了としてマークします。

8. 承認後に実行が失敗した場合、冪等性キーが安定しているため、/resume で安全にリトライできます。

設計上の決定

• 発見は権限を付与しない。 ワークフローは MCP の結果をハードコードされた読み取り許可リストと比較するため、ピアは別のツールを宣伝することで権限を得ることはできません。

• 外部からの観測結果はデータのまま。 ツール出力は長さ制限され、監査イベントで信頼できないとマークされ、チケットの証拠としてのみ使用されます。

• 承認はコンテンツアドレス指定される。 正規の JSON と SHA-256 は、提案されたアクションのすべてのフィールドに承認をバインドし、ペイロードのすり替えを防ぎます。

• 書き込みは冪等で検証される。 一意の冪等性キーがリトライのあいまいさを処理し、独立した読み取りが永続化されたレコードを確認します。

• 状態は副作用の境界を越えて耐久性を持って渡される。 ステータスと監査イベントは、承認、実行、検証、失敗、および完了の前後に書き込まれます。

• プランナーは意図的に決定論的である。 これにより、安全性モデルを検査可能に保ちながら、将来の評価済みモデル使用のために交換可能なプランナー境界を維持します。

プロジェクト構造

agent-mcp-workflow-platform/
|-- src/agent_platform/
|   |-- workflow.py          # State machine, planner, approval, execution, verification
|   |-- tools.py             # MCP stdio client and deterministic test client
|   |-- mcp_server.py        # Local read-only MCP server
|   |-- database.py          # SQLite schema and durable workflow store
|   |-- models.py            # Typed run, action, approval, event, and tool contracts
|   |-- api.py               # Authenticated FastAPI endpoints
|   |-- settings.py          # Environment-based configuration
|   `-- cli.py               # Database, MCP discovery, demo, and server commands
|-- tests/                   # Workflow safety, retry, MCP, and API tests
|-- docs/                    # Architecture and API reference
|-- .github/workflows/ci.yml
|-- SECURITY.md
|-- CONTRIBUTING.md
`-- pyproject.toml

はじめに

前提条件: Python 3.12+

cd agent-mcp-workflow-platform
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
Copy-Item .env.example .env
agent-workflow init-db
agent-workflow mcp-tools
agent-workflow serve

API は http://127.0.0.1:8000 で実行されます。インタラクティブなドキュメントは /docs で利用できます。

使用例

実行を作成する:

curl -X POST http://127.0.0.1:8000/v1/runs \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{"service":"payments-api","symptom":"Elevated 5xx responses"}'

応答には、実行 ID、完全な提案アクション、および action_hash が含まれます。それらを確認した後、その正確なアクションを承認します:

curl -X POST http://127.0.0.1:8000/v1/runs/RUN_ID/approval \
  -H "Authorization: Bearer change-me" \
  -H "Content-Type: application/json" \
  -d '{"approved":true,"action_hash":"HASH_FROM_PROPOSAL"}'

再生可能なイベント履歴を検査する:

curl http://127.0.0.1:8000/v1/runs/RUN_ID/events \
  -H "Authorization: Bearer change-me"

テスト

pytest
ruff check .
mypy

スイートは、認証、MCP の発見と呼び出し、承認不一致の拒否、拒否動作、信頼できない出力の処理、出力とステップの制限、重複実行の防止、冪等なチケット作成、障害回復、独立した検証、および順序付けられた監査履歴を検証します。

このプロジェクトが示すもの

• 耐久性のあるエージェントワークフローとステートマシンの設計

• MCP 統合と JSON-RPC プロセス境界

• 結果を伴うアクションに対するヒューマンインザループ承認制御

• 冪等性、障害回復、および事後条件検証

• 信頼できないツール出力のセキュリティを考慮した処理

• 型付けされた API と SQLite 永続化の設計

• 自動テストと CI ベースの品質保証

ロードマップ

• 開発用 Bearer トークンを OIDC 認証とロールベースの認可に置き換える

• 書き込み境界を冪等アダプターを介して実際のチケットプロバイダーに接続する

• 実行を同時実行制御付きの耐久性のあるバックグラウンドワーカーに移行する

• メトリクス、トレーシング、構造化運用ログ、およびアラートを追加する

• 制限された計画責任を付与する前に、決定論的ベースラインに対して LLM プランナーを評価する

詳細については、アーキテクチャ、API リファレンス、およびセキュリティポリシーを参照してください。