Data Platform MCP

Data Platform MCP es un servicio independiente del proveedor de LLM para explorar fuentes de datos desde clientes compatibles con Model Context Protocol (MCP), incluido Open WebUI. El proyecto se construye por sprints y actualmente implementa el Sprint 9: un segundo motor SQL, MariaDB (mismas tools que PostgreSQL, dialecto mysql de SQLGlot resuelto internamente), y el primer motor documental, MongoDB (list_mongo_collections, validate_mongo_query, execute_mongo_find, execute_mongo_aggregate, con una interfaz DocumentDatabaseAdapter separada que nunca implementa ni expone un método de escritura — ver docs/document-security.md). SQL Server e Informix quedan bloqueados por falta de soporte ARM64 confirmado. Además implementa el Sprint 8 (integración con Open WebUI como cliente MCP nativo, Streamable HTTP, sin proxy ni bridge intermedio — ver docs/openwebui-integration.md), el Sprint 7 (RAG documental desacoplado sobre Qdrant, ver docs/rag.md), el Sprint 6 (lectura cacheada de procedimientos/funciones y triggers PostgreSQL, y su explicación en lenguaje natural vía LLM separando hechos verificables de inferencias) y el Sprint 5 (generación de SQL asistida por LLM sobre el catálogo cacheado, ejecución orquestada bajo revalidación completa, aclaraciones ante ambigüedad y reportes XLSX/PDF/CSV/JSON desde lenguaje natural), todo opcional y deshabilitado por defecto, además de la exploración MCP completa y las capacidades seguras de conexión, catálogo y SQL de los sprints anteriores.

No existe todavía ejecución de escritura en ningún motor. Ningún procedimiento ni trigger se ejecuta jamás: solo se leen sus definiciones desde catálogos internos de PostgreSQL/MariaDB. El catálogo nunca almacena filas de negocio, el RAG nunca almacena contenido de documentos ni preguntas de búsqueda en texto plano, MongoDB nunca expone un método de escritura, y la auditoría guarda metadatos de seguridad — nunca el SQL, los filtros/pipelines de MongoDB, la pregunta en lenguaje natural, los parámetros, los valores devueltos, las definiciones de objetos, el contenido de documentos ni los archivos de reporte generados.

Arquitectura actual

El mismo servidor FastMCP se expone por Streamable HTTP dentro del proceso ASGI y por STDIO para clientes locales. La superficie pública contiene 18 herramientas:

• GET /health: liveness administrativo de FastAPI.

• /mcp: transporte MCP Streamable HTTP de FastMCP.

• health_check: liveness MCP con versión del servidor y del contrato.

• hello_world: herramienta de verificación básica.

• list_connections: declaraciones y capacidades sin host, usuario ni secretos.

• get_connection_capabilities: capacidades seguras de una conexión identificada.

• test_connection: prueba acotada de conectividad con latencia y error normalizado.

• refresh_schema_cache: actualiza la metadata de una conexión o de todas las habilitadas.

• get_schema_cache_status: informa estado, fecha, error y obsolescencia de cada snapshot.

• search_catalog: busca tablas, columnas y descripciones, e incluye relaciones FK relevantes.

• list_schemas: lista schemas del snapshot de una conexión.

• list_tables: lista tablas cacheadas, con filtro opcional por schema.

• describe_table: devuelve columnas, comentarios, PK, índices únicos y FK.

• list_relationships: devuelve origen, destino, columnas y cardinalidad inferida de cada FK.

• validate_sql: parsea, clasifica y explica por qué una sentencia puede o no ejecutarse.

• execute_read_query: ejecuta un único SELECT validado con límites de tiempo, filas y bytes.

• explain_query: devuelve el plan JSON de un SELECT sin utilizar ANALYZE.

• generate_sql: genera SQL desde una pregunta en lenguaje natural sobre el catálogo cacheado, sin ejecutarlo.

• generate_and_execute_query: genera SQL y lo ejecuta solo si la revalidación completa lo permite.

• generate_report: genera SQL, lo ejecuta y entrega el resultado como XLSX/PDF/CSV/JSON en línea.

La configuración pasa por Pydantic, el servicio resuelve secretos desde el entorno y una fábrica por registro crea el adaptador. CatalogService coordina snapshots atómicos guardados en SQLite; QueryValidationService aplica una política AST por dialecto y QueryExecutionService es la única entrada a consultas de usuario. Consulta la arquitectura, los contratos MCP, la seguridad SQL y la operación del catálogo.

Related MCP server: MCP Docker Demo

Requisitos

• Docker Engine 24 o posterior.

• Docker Compose v2.20 o posterior.

• Red Docker externa ai-platform creada previamente.

• Para desarrollo sin Docker: Python 3.12 y un entorno virtual.

Las imágenes python:3.12.13-slim-bookworm y postgres:17.10-bookworm disponen de variantes Linux ARM64. El proyecto no usa rutas absolutas del anfitrión y es desplegable en Oracle Cloud Free Tier ARM64, sujeto al dimensionamiento y monitoreo propios del entorno.

Inicio rápido con Docker

cp .env.example .env
# Cambia las contraseñas de laboratorio (PostgreSQL, MariaDB, MongoDB) dentro de .env.
docker network inspect ai-platform >/dev/null 2>&1 || docker network create ai-platform
docker compose up -d --build
docker compose ps
curl --fail http://127.0.0.1:8000/health

Respuesta esperada:

{
  "status": "ok",
  "service": "data-platform-mcp",
  "version": "0.9.0"
}

El puerto MCP se publica en 127.0.0.1:8000 por defecto, PostgreSQL en 127.0.0.1:5432, MariaDB en 127.0.0.1:3306 y MongoDB en 127.0.0.1:27017. Los contenedores de ai-platform usan estas URLs internas:

MCP:        http://data-platform-mcp:8000/mcp
PostgreSQL: postgres-lab:5432
MariaDB:    mariadb-lab:3306
MongoDB:    mongo-lab:27017
Qdrant:     qdrant:6333

Open WebUI puede permanecer en otro proyecto Compose: solo necesita compartir ai-platform. Ver docs/openwebui-integration.md para la guía completa, incluido un compose de ejemplo aislado en examples/openwebui/.

Para un cliente MCP local, el entry point instalado inicia exactamente el mismo catálogo de tools por STDIO:

data-platform-mcp-stdio

Para eliminar también los datos desechables del laboratorio:

docker compose down --volumes

Configuración de conexiones

connections.yaml contiene declaraciones sin contraseña. Cada password_env indica qué variable de entorno debe proporcionar el secreto al proceso:

connections:
  - id: postgres-demo
    name: PostgreSQL Demo
    type: postgres
    host: postgres-lab
    port: 5432
    database: demo
    username: mcp_readonly
    password_env: POSTGRES_DEMO_PASSWORD
    readonly: true
    enabled: true
    connect_timeout_seconds: 10
    query_timeout_seconds: 30
    max_rows: 500
    options:
      application_name: data-platform-mcp
      sslmode: disable

El archivo se monta como solo lectura, por lo que puede cambiarse sin reconstruir la imagen. El proceso debe reiniciarse para cargar la nueva configuración. IDs duplicados, valores fuera de rango, opciones reservadas, conexiones habilitadas sin modo readonly, motores sin adaptador o secretos ausentes detienen el arranque con un error claro. La referencia completa está en conexiones.

La sección raíz catalog controla si el caché está activo, el refresh al arrancar, el intervalo, la edad para marcarlo obsoleto y los filtros de schemas/tablas. El ejemplo usa 60 minutos entre actualizaciones y marca el snapshot como stale a partir de 120 minutos. SQLite se persiste en el volumen nombrado catalog-data; docker compose down --volumes también lo elimina.

Las secciones query y audit controlan los límites globales y la bitácora de seguridad:

query:
  global_max_rows: 1000
  max_serialized_bytes: 1000000
  max_concurrent_queries: 4

audit:
  enabled: true

La ejecución utiliza el menor límite entre la solicitud, la conexión y la política global. Los placeholders deben ser nombrados, por ejemplo %(cliente_id)s, y el diccionario de parámetros debe coincidir exactamente. La auditoría se persiste en /app/data/audit.db dentro del mismo volumen.

Variables Compose incluidas en .env.example:

Los valores de .env.example son marcadores para desarrollo local, no credenciales aptas para producción.

Desarrollo y validación

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'

Validaciones reproducibles mediante Docker:

docker build --target test -t data-platform-mcp:test .
docker run --rm data-platform-mcp:test pytest
docker run --rm data-platform-mcp:test ruff check app tests scripts
docker run --rm data-platform-mcp:test ruff format --check app tests scripts
docker run --rm data-platform-mcp:test mypy app tests
docker compose --env-file .env.example config --quiet
docker compose --env-file .env.example build data-platform-mcp

Con el stack activo, el smoke test de red refresca el catálogo y llama las herramientas de exploración reales:

docker run --rm --network ai-platform \
  data-platform-mcp:test \
  python scripts/smoke_mcp.py --url http://data-platform-mcp:8000/mcp

Las pruebas de integración requieren el laboratorio y se habilitan explícitamente; consulta desarrollo.

Seguridad

• El MCP utiliza mcp_readonly, nunca el superusuario del laboratorio.

• El rol tiene SELECT y default_transaction_read_only=on; no recibe escritura ni DDL.

• El adaptador fuerza además sesiones de solo lectura.

• SQLGlot parsea PostgreSQL y solo permite una raíz de lectura; bloquea DML, DDL, escritura en CTE, sentencias múltiples, bloqueos, comandos administrativos y funciones peligrosas conocidas.

• La ejecución revalida siempre, usa parámetros nombrados y aplica límites de timeout, filas, bytes serializados y concurrencia.

• EXPLAIN fija ANALYZE FALSE; una solicitud no puede inyectar sus propias opciones de plan.

• La auditoría guarda hash SHA-256, decisión, razones, duración y conteo, nunca SQL o resultados.

• El caché persiste únicamente schemas, tablas, columnas, comentarios, PK, índices únicos y FK.

• Contraseñas y cadenas completas no aparecen en herramientas ni errores normalizados.

• El runtime usa UID/GID 10001, raíz de solo lectura, sin capabilities y sin privilegios nuevos.

• Los puertos se publican solo en loopback por defecto.

Esta defensa en profundidad no sustituye autenticación MCP ni segmentación de red. No expongas el servicio directamente a Internet. Consulta seguridad.

Estado de motores

Roadmap

El plan se mantiene en TASKS.md. Sprint 5 (generación de SQL mediante lenguaje natural sobre metadata real, aclaraciones ante ambigüedad y reportes XLSX/PDF/CSV/JSON), Sprint 6 (lectura de procedimientos/triggers y explicaciones asistidas por LLM), Sprint 7 (RAG documental sobre Qdrant), Sprint 8 (integración con Open WebUI como cliente MCP nativo) y Sprint 9 (MariaDB y MongoDB; SQL Server e Informix bloqueados por soporte ARM64) ya están implementados; la generación LLM y el RAG siguen deshabilitados por defecto. HU-802 y HU-803 de Sprint 8 quedan IN_PROGRESS en TASKS.md hasta que se confirme su ejecución con un proveedor LLM real dentro de Open WebUI (ver docs/openwebui-integration.md). El siguiente hito, que no se iniciará sin aprobación, es Sprint 10: hardening y operación.