Agent- und MCP-Workflow-Plattform

Ein genehmigungspflichtiger Incident-Workflow, der Beweise über schreibgeschützte MCP-Tools sammelt, eine exakte idempotente Aktion ausführt, das Ergebnis verifiziert und ein dauerhaftes Prüfprotokoll aufbewahrt.

Übersicht

Agentische Workflows bergen Risiken, die über gewöhnliche Request/Response-APIs hinausgehen: Externe Tool-Ausgaben können feindselig sein, Wiederholungen können Seiteneffekte duplizieren, Genehmigungen können veralten, und eine erfolgreiche Tool-Antwort spiegelt möglicherweise nicht den dauerhaft gespeicherten Zustand wider.

Dieses Projekt implementiert einen bewusst eingeschränkten Incident-Response-Workflow für diese Fehlermodi. Ein deterministischer Planer entdeckt und ruft genehmigte Lese-Tools über das Model Context Protocol (MCP) auf, schlägt ein Ticket vor, pausiert für eine menschliche Genehmigung, bindet diese Genehmigung an einen SHA-256-Aktions-Digest, führt einen idempotenten Datenbank-Schreibvorgang durch und verifiziert das gespeicherte Ergebnis. Es verwendet kein LLM; der Fokus liegt auf zuverlässiger Orchestrierung und Kontrollgrenzen.

Related MCP server: mcp-policy-gateway

Hauptmerkmale

• MCP-Tool-Erkennung und -Aufrufe über JSON-RPC stdio

• Separater schreibgeschützter MCP-Server mit Service-Status- und Runbook-Suche-Tools

• Anwendungsweite Zulassungsliste unabhängig von der MCP-Tool-Erkennung

• Explizite Workflow-Zustandsmaschine mit Schrittbudget-Durchsetzung

• Menschliche Genehmigung oder Ablehnung vor dem folgenreichen Schreibvorgang

• SHA-256-Digest, der die Genehmigung an die vollständige vorgeschlagene Aktion bindet

• Stabile Idempotenzschlüssel, die doppelte Ticket-Erstellung bei Wiederholungen verhindern

• Unabhängige Überprüfung nach dem Schreibvorgang gegen SQLite

• Dauerhafte Ausführungen, Genehmigungen, Tickets und geordnete Audit-Ereignisse

• Bearer-authentifizierte FastAPI-Endpunkte, CLI-Workflows, CI und deterministische Tests

Architektur

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

Der MCP-Peer kann Beobachtungen liefern, hat aber keine Schreibberechtigung. Die Ticket-Erstellung bleibt innerhalb der Anwendung und kann erst erfolgen, wenn der eingereichte Genehmigungs-Hash mit dem aktuellen Vorschlag übereinstimmt.

Workflow-Zustandsmaschine

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

API

Alle /v1-Endpunkte erfordern Authorization: Bearer <AGENT_API_TOKEN>.

Technologie-Stack

So funktioniert es

1. Ein Client erstellt eine Ausführung für einen Dienst und ein gemeldetes Symptom.

2. Der Workflow erkennt MCP-Tools, schneidet sie mit seiner eigenen Lese-Zulassungsliste und sammelt begrenzte Beobachtungen.

3. Tool-Ausgaben werden als nicht vertrauenswürdige Beweise gespeichert und niemals als Workflow-Anweisungen interpretiert.

4. Die Anwendung erstellt eine vorgeschlagene Ticket-Aktion, einen stabilen Idempotenzschlüssel und einen kanonischen SHA-256-Aktions-Hash.

5. Der Workflow persistiert awaiting_approval und kehrt zurück, ohne einen Schreibvorgang durchzuführen.

6. Ein Mensch reicht eine Genehmigung oder Ablehnung für den exakten Hash ein. Geänderte oder veraltete Vorschläge werden mit HTTP 409 abgelehnt.

7. Eine genehmigte Aktion erstellt das Ticket idempotent, liest es aus SQLite zurück und markiert die Ausführung erst nach der Überprüfung als abgeschlossen.

8. Wenn die Ausführung nach der Genehmigung fehlschlägt, kann /resume sicher wiederholt werden, da der Idempotenzschlüssel stabil bleibt.

Technische Entscheidungen

• Erkennung gewährt keine Autorität. Der Workflow schneidet MCP-Ergebnisse mit einer hartcodierten Lese-Zulassungsliste, sodass ein Peer keine Berechtigung durch das Ankündigen eines anderen Tools erlangen kann.

• Externe Beobachtungen bleiben Daten. Tool-Ausgaben sind längenbegrenzt, im Audit-Ereignis als nicht vertrauenswürdig markiert und werden nur als Ticket-Beweise verwendet.

• Genehmigung ist inhaltsadressiert. Kanonisches JSON und SHA-256 binden die Genehmigung an jedes Feld der vorgeschlagenen Aktion und verhindern Nutzlastsubstitution.

• Schreibvorgänge sind idempotent und verifiziert. Ein eindeutiger Idempotenzschlüssel behandelt Mehrdeutigkeiten bei Wiederholungen, während ein separater Lesevorgang den dauerhaften Datensatz bestätigt.

• Zustand überquert Seiteneffektgrenzen dauerhaft. Status und Audit-Ereignisse werden vor und nach Genehmigung, Ausführung, Überprüfung, Fehlschlag und Abschluss geschrieben.

• Der Planer ist absichtlich deterministisch. Dies hält das Sicherheitsmodell überprüfbar, während eine austauschbare Planer-Grenze für zukünftige evaluierte Modellnutzung erhalten bleibt.

Projektstruktur

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

Erste Schritte

Voraussetzung: 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

Die API läuft unter http://127.0.0.1:8000; interaktive Dokumentation ist unter /docs verfügbar.

Beispielverwendung

Eine Ausführung erstellen:

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"}'

Die Antwort enthält die Ausführungs-ID, die vollständige vorgeschlagene Aktion und action_hash. Nach der Überprüfung diese exakte Aktion genehmigen:

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"}'

Den wiederholbaren Ereignisverlauf einsehen:

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

Tests

pytest
ruff check .
mypy

Die Suite überprüft Authentifizierung, MCP-Erkennung und -Aufrufe, Ablehnung von Genehmigungsabweichungen, Ablehnungsverhalten, Behandlung nicht vertrauenswürdiger Ausgaben, Ausgabe- und Schrittlimits, Verhinderung doppelter Ausführung, idempotente Ticket-Erstellung, Fehlerbehebung, unabhängige Überprüfung und geordnete Audit-Historie.

Was dieses Projekt demonstriert

• Dauerhaftes Agent-Workflow- und Zustandsmaschinen-Design

• MCP-Integration und JSON-RPC-Prozessgrenzen

• Human-in-the-Loop-Genehmigungskontrollen für folgenreiche Aktionen

• Idempotenz, Fehlerbehebung und Nachbedingungsüberprüfung

• Sicherheitsorientierte Handhabung nicht vertrauenswürdiger Tool-Ausgaben

• Typisierte API- und SQLite-Persistenz-Design

• Automatisierte Tests und CI-basierte Qualitätssicherung

Fahrplan

• Ersetzen des Entwicklungs-Bearer-Tokens durch OIDC-Authentifizierung und rollenbasierte Autorisierung

• Verbinden der Schreibgrenze mit einem echten Ticketing-Anbieter über einen idempotenten Adapter

• Verschieben der Ausführung auf dauerhafte Hintergrundarbeiter mit Parallelitätskontrolle

• Hinzufügen von Metriken, Tracing, strukturierten Betriebsprotokollen und Alarmierung

• Evaluieren eines LLM-Planers gegenüber der deterministischen Baseline, bevor ihm begrenzte Planungsverantwortung übertragen wird

Siehe Architektur, API-Referenz und Sicherheitsrichtlinie für weitere Details.