Data Platform MCP

Data Platform MCP

Data Platform MCP es un servicio independiente del proveedor de LLM para explorar fuentes de datosdesde clientes compatibles con Model Context Protocol (MCP), incluido Open WebUI. El proyecto seconstruye por sprints y actualmente implementa el Sprint 1: configuración de conexiones porYAML, herramientas de descubrimiento/conectividad y un adaptador PostgreSQL de metadatos.

No existe todavía ejecución de SQL de usuario, catálogo persistente, generación de consultas, RAGni auditoría. El adaptador solo ejecuta consultas constantes o de catálogos internos controladas porla aplicación.

Arquitectura actual

Un proceso ASGI ejecutado por Uvicorn expone:

• GET /health: liveness administrativo de FastAPI.
• /mcp: transporte MCP Streamable HTTP de FastMCP.
• hello_world: herramienta de verificación básica.
• list_connections: declaraciones y capacidades sin host, usuario ni secretos.
• test_connection: prueba acotada de conectividad con latencia y error normalizado.

La configuración pasa por Pydantic, el servicio resuelve secretos desde el entorno y una fábrica porregistro crea el adaptador. PostgresAdapter puede probar conectividad y obtener schemas, tablas,columnas, claves primarias y foráneas; esas operaciones de metadata todavía no se exponen como tools.Consulta la arquitectura para los límites de las capas.

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 variantesLinux ARM64. El proyecto no usa rutas absolutas del anfitrión y es desplegable en Oracle Cloud FreeTier ARM64, sujeto al dimensionamiento y monitoreo propios del entorno.

Inicio rápido con Docker

cp .env.example .env
# Cambia ambas contraseñas de laboratorio 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.2.0"
}

El puerto MCP se publica en 127.0.0.1:8000 por defecto y PostgreSQL en127.0.0.1:5432. Los contenedores de ai-platform usan estas URLs internas:

MCP:        http://data-platform-mcp:8000/mcp
PostgreSQL: postgres-lab:5432

Open WebUI puede permanecer en otro proyecto Compose: solo necesita compartir ai-platform.

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é variablede 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. Elproceso 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 secretosausentes detienen el arranque con un error claro. La referencia completa está enconexiones.

Variables Compose incluidas en .env.example:

Los valores de .env.example son marcadores para desarrollo local, no credenciales aptas paraproducció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
docker run --rm data-platform-mcp:test ruff format --check app tests
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

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

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.
• Las consultas de metadata están definidas por la aplicación y sus filtros usan parámetros.
• 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 elservicio directamente a Internet. Consulta seguridad.

Estado de motores

Roadmap

El plan se mantiene en TASKS.md. El siguiente hito, pendiente de aprobación del Sprint1, es Sprint 2: catálogo y caché de schemas. Después siguen validación/ejecución SQL segura,contratos MCP de metadata, generación, objetos, RAG, Open WebUI, motores adicionales y hardening.