Agente de Gobernanza de Datos Sentinel MCP

Sentinel es un pequeño agente autónomo de gobernanza de datos que audita una base de datos PostgreSQL a través del Protocolo de Contexto de Modelo (MCP). En lugar de dar al LLM acceso directo a la base de datos, el proyecto expone un puente FastMCP controlado con herramientas diseñadas específicamente para la inspección de esquemas, perfilado de nulos y detección de anomalías.

La demostración inicializa una tabla raw_inventory intencionalmente sucia, solicita a un agente impulsado por OpenAI que la inspeccione a través de herramientas MCP y escribe un informe de auditoría en Markdown en LATEST_AUDIT.md.

Qué demuestra

Un cliente MCP en Python que sigue un flujo de trabajo de estilo ReAct: Razonar -> Actuar -> Observar.
Un servidor FastMCP que actúa como puente de gobernanza entre el agente y PostgreSQL.
Herramientas respaldadas por SQLAlchemy para una inspección de base de datos segura y estructurada.
Comprobaciones de calidad de datos para correos electrónicos faltantes, recuentos de inventario negativos y SKU duplicados.
Una Auditoría de Salud de Datos generada con SQL de remediación.

Arquitectura

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]

Herramientas MCP

inspect_schema() devuelve nombres de tablas y definiciones de columnas para auditorías estructurales.

get_data_health_sample() devuelve 100 filas recientes de raw_inventory para una revisión a nivel de fila.

check_null_ratios(table_name="raw_inventory") devuelve recuentos y porcentajes de nulos para cada columna.

find_logical_anomalies() devuelve filas con valores negativos en stock_count y grupos de sku duplicados.

Diseño del proyecto

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

Configuración

Requisitos:

Windows 11, macOS o Linux
Docker Desktop
Python gestionado con uv
Una clave de API de OpenAI con cuota de API disponible

Cree su archivo de entorno local:

Copy-Item .env.example .env

Edite .env y reemplace los valores de marcador de posición. No confirme .env en el control de versiones.

Instale las dependencias:

uv sync

Inicie PostgreSQL:

docker compose up -d

Inicialice la tabla de inventario sucia:

uv run python seed_data.py

Ejecute el servidor MCP directamente:

uv run python server.py

En otra terminal, ejecute el agente de auditoría autónomo:

uv run python agent.py

El agente escribe su informe en:

LATEST_AUDIT.md

Verifique los datos inicializados

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;"

Resultado esperado después de la inicialización:

Notas de seguridad

.env es ignorado por Git y nunca debe ser confirmado.
.env.example contiene solo marcadores de posición.
El LLM no recibe credenciales de base de datos sin procesar directamente; interactúa con herramientas MCP aprobadas.
El servidor MCP es el límite de política donde las capacidades de la base de datos se exponen explícitamente.
Rote cualquier clave de API que haya aparecido en registros, capturas de pantalla, salida de terminal o chat.

¿Por qué MCP en lugar de SQLAlchemy directo en el agente?

MCP proporciona al LLM una interfaz de herramientas restringida en lugar de un acceso ilimitado a la base de datos. El servidor FastMCP define las acciones permitidas, haciendo que el límite de gobernanza sea explícito y auditable. El mismo agente puede interoperar más tarde con catálogos, motores de políticas, almacenes y sistemas de observabilidad a través de MCP sin tener que reescribir el agente en torno a conexiones directas a la base de datos.