MCP Test DB Server

# 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.