Sentinel MCP Data Governance Agent

Sentinel ist ein kleiner autonomer Data-Governance-Agent, der eine PostgreSQL-Datenbank über das Model Context Protocol (MCP) prüft. Anstatt dem LLM direkten Datenbankzugriff zu gewähren, stellt das Projekt eine kontrollierte FastMCP-Brücke mit zweckgebundenen Tools für Schema-Inspektion, Null-Profilierung und Anomalieerkennung bereit.

Die Demo befüllt eine absichtlich fehlerhafte raw_inventory-Tabelle, weist einen OpenAI-basierten Agenten an, diese über MCP-Tools zu untersuchen, und schreibt einen Markdown-Audit-Bericht in LATEST_AUDIT.md.

Was es demonstriert

Einen Python-MCP-Client, der einem ReAct-artigen Workflow folgt: Reason (Überlegen) -> Act (Handeln) -> Observe (Beobachten).
Einen FastMCP-Server, der als Governance-Brücke zwischen dem Agenten und PostgreSQL fungiert.
SQLAlchemy-basierte Tools für eine sichere, strukturierte Datenbankinspektion.
Datenqualitätsprüfungen auf fehlende E-Mails, negative Lagerbestände und doppelte SKUs.
Einen generierten Datenintegritäts-Audit mit SQL-Korrekturvorschlägen.

Architektur

flowchart LR
    U[User question] --> A[Python Agent<br/>MCP Client]
    A -->|tools/list and tools/call| M[FastMCP Server<br/>Sentinel-Bridge]
    M -->|SQLAlchemy queries| DB[(PostgreSQL 16<br/>raw_inventory)]
    DB -->|schema and quality metrics| M
    M -->|structured MCP tool results| A
    A -->|OpenAI analysis or local fallback| R[LATEST_AUDIT.md]

MCP-Tools

inspect_schema() gibt Tabellennamen und Spaltendefinitionen für strukturelle Audits zurück.

get_data_health_sample() gibt 100 aktuelle Zeilen aus raw_inventory für eine zeilenweise Überprüfung zurück.

check_null_ratios(table_name="raw_inventory") gibt Null-Anzahlen und Prozentsätze für jede Spalte zurück.

find_logical_anomalies() gibt Zeilen mit negativen stock_count-Werten und duplizierten sku-Gruppen zurück.

Projektstruktur

agent.py              # MCP client and ReAct audit workflow
server.py             # FastMCP server exposing database audit tools
seed_data.py          # Faker-based dirty data generator
docker-compose.yml    # PostgreSQL 16 local database
architecture.md       # Mermaid architecture diagram
.env.example          # Safe environment variable template

Einrichtung

Anforderungen:

Windows 11, macOS oder Linux
Docker Desktop
Python verwaltet mit uv
Ein OpenAI-API-Schlüssel mit verfügbarem API-Kontingent

Erstellen Sie Ihre lokale Umgebungsdatei:

Copy-Item .env.example .env

Bearbeiten Sie .env und ersetzen Sie die Platzhalterwerte. Committen Sie .env nicht.

Installieren Sie die Abhängigkeiten:

uv sync

Starten Sie PostgreSQL:

docker compose up -d

Befüllen Sie die fehlerhafte Inventartabelle:

uv run python seed_data.py

Starten Sie den MCP-Server direkt:

uv run python server.py

Führen Sie in einem anderen Terminal den autonomen Audit-Agenten aus:

uv run python agent.py

Der Agent schreibt seinen Bericht nach:

LATEST_AUDIT.md

Überprüfen der befüllten Daten

docker exec -it sentinel_postgres psql -U sentinel_user -d sentinel_db -c "SELECT COUNT(*) AS negative_stock_rows FROM raw_inventory WHERE stock_count < 0;"

Erwartetes Ergebnis nach dem Befüllen:

Sicherheitshinweise

.env wird von Git ignoriert und darf niemals committet werden.
.env.example enthält nur Platzhalter.
Das LLM erhält keine direkten Datenbankzugangsdaten; es interagiert mit genehmigten MCP-Tools.
Der MCP-Server ist die Richtliniengrenze, an der Datenbankfunktionen explizit freigegeben werden.
Rotieren Sie jeden API-Schlüssel, der in Protokollen, Screenshots, Terminalausgaben oder Chats aufgetaucht ist.

Warum MCP anstelle von direktem SQLAlchemy im Agenten?

MCP bietet dem LLM eine eingeschränkte Tool-Schnittstelle anstelle eines uneingeschränkten Datenbankzugriffs. Der FastMCP-Server definiert die erlaubten Aktionen, wodurch die Governance-Grenze explizit und prüfbar wird. Derselbe Agent kann später über MCP mit Katalogen, Richtlinien-Engines, Data Warehouses und Observability-Systemen interagieren, ohne den Agenten für direkte Datenbankverbindungen umschreiben zu müssen.