sentinel-mcp-data-governance-agent

# Sentinel MCP Data Governance Agent Sentinel is a autonomous data governance agent that audits a PostgreSQL database through the Model Context Protocol (MCP). Instead of giving the LLM direct database access, the project exposes a controlled FastMCP bridge with purpose-built tools for schema inspection, null profiling, and anomaly detection. The demo seeds an intentionally dirty `raw_inventory` table, asks an OpenAI-powered agent to inspect it through MCP tools, and writes a Markdown audit report to `LATEST_AUDIT.md`. ## What It Demonstrates - A Python MCP client that follows a ReAct-style Reason -> Act -> Observe workflow. - A FastMCP server that acts as a governance bridge between the agent and PostgreSQL. - SQLAlchemy-backed tools for safe, structured database inspection. - Data quality checks for missing emails, negative inventory counts, and duplicate SKUs. - A generated Data Health Audit with remediation SQL. ## Architecture ```mermaid 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()` returns table names and column definitions for structural audits. `get_data_health_sample()` returns 100 recent rows from `raw_inventory` for row-level review. `check_null_ratios(table_name="raw_inventory")` returns null counts and percentages for every column. `find_logical_anomalies()` returns rows with negative `stock_count` values and duplicated `sku` groups. ## Project Layout ```text 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 ``` ## Setup Requirements: - Windows 11, macOS, or Linux - Docker Desktop - Python managed with `uv` - An OpenAI API key with available API quota Create your local environment file: ```powershell Copy-Item .env.example .env ``` Edit `.env` and replace placeholder values. Do not commit `.env`. Install dependencies: ```powershell uv sync ``` Start PostgreSQL: ```powershell docker compose up -d ``` Seed the dirty inventory table: ```powershell uv run python seed_data.py ``` Run the MCP server directly: ```powershell uv run python server.py ``` In another terminal, run the autonomous audit agent: ```powershell uv run python agent.py ``` The agent writes its report to: ```text LATEST_AUDIT.md ``` ## Verify the Seeded Data ```powershell 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;" ``` Expected result after seeding: ```text 30 ``` ## Security Notes - `.env` is ignored by Git and must never be committed. - `.env.example` contains placeholders only. - The LLM does not receive raw database credentials directly; it interacts with approved MCP tools. - The MCP server is the policy boundary where database capabilities are explicitly exposed. - Rotate any API key that has appeared in logs, screenshots, terminal output, or chat. ## Why MCP Instead of Direct SQLAlchemy in the Agent? MCP gives the LLM a constrained tool interface rather than unrestricted database access. The FastMCP server defines the allowed actions, making the governance boundary explicit and auditable. The same agent can later interoperate with catalogs, policy engines, warehouses, and observability systems through MCP without rewriting the agent around direct database connections.