MCP Test DB — Servidor MCP (FastAPI + SSE) y Cliente Chat LLM
Este proyecto demuestra un flujo completo donde:
- Un servidor MCP (basado en FastAPI) expone herramientas para acceder a una base de datos PostgreSQL.
- La comunicación cliente-servidor se realiza vía SSE (Server‑Sent Events) usando JSON‑RPC.
- Un cliente de chat LLM (
mcp_chat.py) interactúa con el servidor, descubre herramientas y las invoca (p. ej., listar y agregar empleados) para responder en conversación.
Arquitectura
- Docker Compose levanta:
company_postgres: Base de datos PostgreSQL inicializada coninit.sql.company_mcp_server: Servidor FastAPI con endpoint SSE en/sse.
- El cliente
mcp_chat.py(Python) se conecta al SSE, negociasession_id, y usa un lector en segundo plano para mantener el stream y emparejar respuestas porid.
Herramientas disponibles (MCP)
list_employees(GET): Lista empleados. Parámetros típicos:limit(opcional, int): número máximo de empleados a devolver.
add_employee(POST): Agrega un empleado. Parámetros típicos:name(str),position(str),department(str),salary(number).
La base de datos se inicializa con datos de ejemplo (ver init.sql).
Cliente de Chat LLM (mcp_chat.py)
- Carga
.envautomáticamente (viapython-dotenv). - Soporta múltiples proveedores de modelos:
- OpenAI:
MODEL_PROVIDER=openai,MODEL_NAME=gpt-4o-mini(ejemplo). - OpenRouter:
MODEL_PROVIDER=openrouter,MODEL_NAME=meta-llama/llama-3.1-8b-instruct(ejemplo).
- OpenAI:
- Convierte los esquemas de herramientas MCP a formato de “function calling” del proveedor y realiza la llamada real al servidor vía SSE.
- Patrón SSE robusto:
- Un solo lector en segundo plano mantiene el stream.
- Extrae y guarda
session_id. - Respuestas se almacenan por
iddel mensaje JSON‑RPC.
Requisitos
- Docker y Docker Compose.
- Python 3.11+ en tu sistema para ejecutar
mcp_chat.py. - Variables de entorno (en
.env):- OpenAI:
OPENAI_API_KEY. - OpenRouter:
OPENROUTER_API_KEY. - Selección de modelo:
MODEL_PROVIDER,MODEL_NAME.
- OpenAI:
Importante: No publiques tu
.enven repositorios públicos.
Cómo ejecutar
- Levantar servidor y base de datos:
docker-compose up -d
- Ejecutar el cliente de chat:
python mcp_chat.py
- Escribe consultas naturales. Ejemplos:
- "Lista los primeros 5 empleados"
- "Agrega un empleado llamado Pedro con salario 62000 en Analytics"
El agente decidirá si debe invocar una herramienta (p. ej., list_employees o add_employee). Los resultados reales del servidor se integran a la conversación para producir una respuesta final.
Contenido del repositorio
- main.py — Servidor MCP (FastAPI) con endpoint SSE (/sse) y herramientas de base de datos (listar y agregar empleados).
- mcp_chat.py — Cliente de chat (LLM + SSE) que descubre y llama herramientas del servidor.
- docker-compose.yml — Orquestación de Postgres y servidor MCP.
- init.sql — Inicialización de la base de datos.
- .env / .env.example — Variables de entorno.
- Dockerfile — Imagen del servidor MCP.
- pyproject.toml — Dependencias y configuración de Python.
- uv.lock — Archivo de lock para uv.
Guía incremental (docs/)
Para compartir con el equipo, consulta los módulos paso a paso:
- docs/01-introduccion-mcp.md — Qué es MCP y arquitectura del repo
- docs/02-entorno-y-dotenv.md — Preparación de entorno y configuración segura con .env
- docs/03-docker-compose-db-server.md — Cómo levantar Postgres y el servidor MCP con Docker Compose
Buenas prácticas SSE
- Mantener un único lector SSE para toda la sesión.
- Guardar
session_idtrasinitialize. - Emparejar cada respuesta JSON‑RPC por
id. - No cerrar el stream hasta terminar la sesión.
Solución a problemas comunes
- “Falla la conexión SSE”: Verificar que el servidor esté corriendo (
docker-compose ps), firewall y puerto. - “Falta la API key”: Asegurar
.envcargado y variables correctas (OPENAI_API_KEYuOPENROUTER_API_KEY). - “Timeout esperando respuesta”: Confirmar que no haya múltiples lectores y que el
iddel mensaje se use para emparejar la respuesta. - Pydantic v2: Evitar el uso de
model.dict(), usarmodel_dump().
Estado del repositorio
Se eliminaron scripts de prueba antiguos para simplificar el proyecto. La interacción recomendada es a través de mcp_chat.py usando las herramientas del servidor. Documentos de referencia sobre SSE se conservan para apoyo.