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 con init.sql.
  • company_mcp_server: Servidor FastAPI con endpoint SSE en /sse.
• El cliente mcp_chat.py (Python) se conecta al SSE, negocia session_id, y usa un lector en segundo plano para mantener el stream y emparejar respuestas por id.

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 .env automáticamente (via python-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).
• 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 id del 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.

Importante: No publiques tu .env en repositorios públicos.

Cómo ejecutar

1. Levantar servidor y base de datos:
   • docker-compose up -d
2. Ejecutar el cliente de chat:
   • python mcp_chat.py
3. 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_id tras initialize.
• 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 .env cargado y variables correctas (OPENAI_API_KEY u OPENROUTER_API_KEY).
• “Timeout esperando respuesta”: Confirmar que no haya múltiples lectores y que el id del mensaje se use para emparejar la respuesta.
• Pydantic v2: Evitar el uso de model.dict(), usar model_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.