Servidor MCP PostgreSQL personalizado para RAGmonsters
Descripción general
Este repositorio demuestra un enfoque más avanzado para la integración de Modelos de Lenguaje Grandes (LLM) con bases de datos mediante el Protocolo de Contexto de Modelo (MCP). Si bien los servidores PostgreSQL MCP genéricos permiten a los LLM explorar bases de datos mediante consultas SQL sin procesar, este proyecto adopta un enfoque diferente al crear un servidor MCP personalizado que proporciona una API específica del dominio, adaptada a las necesidades de la aplicación.
Esta implementación utiliza FastMCP , una implementación de alto rendimiento del Protocolo de contexto de modelo, que proporciona mayor eficiencia y confiabilidad para las interacciones basadas en herramientas con LLM.
Este proyecto se basa en el conjunto de datos RAGmonsters . RAGmonsters es un proyecto de código abierto que proporciona un rico conjunto de datos ficticios de monstruos con diversos atributos, habilidades y relaciones, diseñado específicamente para demostrar y probar sistemas de Generación Aumentada por Recuperación (RAG).
El problema con el acceso genérico a bases de datos MCP
Los servidores PostgreSQL MCP genéricos proporcionan a los LLM una herramienta query que les permite:
- Explorar esquemas de bases de datos
- Formular consultas SQL basadas en preguntas en lenguaje natural
- Ejecutar esas consultas contra la base de datos
Si bien este enfoque funciona, tiene varias limitaciones para las aplicaciones del mundo real:
- Carga cognitiva : El LLM debe comprender todo el esquema de la base de datos
- Ineficiencia : a menudo se necesitan múltiples consultas SQL para responder una sola pregunta
- Preocupaciones de seguridad : el acceso a SQL sin procesar requiere una ingeniería rápida y cuidadosa para evitar ataques de inyección
- Rendimiento : Las consultas complejas pueden resultar ineficientes si el LLM no comprende la estrategia de indexación de la base de datos.
- Brecha de conocimiento del dominio : el LLM carece de comprensión de las reglas comerciales y las limitaciones específicas del dominio
Acerca del conjunto de datos RAGmonsters
RAGmonsters es un conjunto de datos abierto diseñado específicamente para probar y demostrar sistemas de Recuperación-Generación Aumentada (RAG). Contiene información sobre monstruos ficticios con atributos, habilidades y relaciones complejos, lo que lo hace ideal para demostraciones de consultas en lenguaje natural.
La versión PostgreSQL de RAGmonsters proporciona una base de datos relacional bien estructurada con múltiples tablas y relaciones, que incluyen:
- Monstruos con varios atributos (poder de ataque, defensa, salud, etc.)
- Habilidades que pueden poseer los monstruos
- Elementos (fuego, agua, tierra, etc.) con relaciones complejas
- Hábitats donde se pueden encontrar monstruos
- Cadenas evolutivas y relaciones entre monstruos
Este rico conjunto de datos interconectados es ideal para demostrar el poder de las API específicas del dominio frente al acceso SQL genérico.
Nuestra solución: API MCP específica del dominio
Este proyecto demuestra cómo crear un servidor MCP personalizado que proporciona una API de alto nivel y específica del dominio para el conjunto de datos RAGmonsters. En lugar de exponer capacidades SQL sin procesar, nuestro servidor MCP ofrece funciones específicas que:
- Complejidad de la base de datos abstracta : ocultar el esquema subyacente y los detalles de SQL
- Proporcionar operaciones específicas del dominio : ofrecer funciones que se alineen con los conceptos comerciales
- Optimizar para consultas comunes : Implementar patrones de consulta eficientes para preguntas frecuentes
- Aplicar reglas de negocio : incorporar lógica y restricciones específicas del dominio
- Mejore la seguridad : limite la superficie de ataque eliminando el acceso directo a SQL
Interfaz web
El proyecto incluye dos interfaces principales para interactuar con el conjunto de datos RAGmonsters:
Interfaz del explorador
Una interfaz centrada en datos para explorar y filtrar el conjunto de datos de RAGmonsters a través de la API de MCP:
- Explora todos los monstruos filtrando por categoría, hábitat y rareza.
- Ver información detallada sobre cada monstruo
- Interfaz de usuario interactiva creada con Bootstrap
Interfaz de chat
Una interfaz de lenguaje natural para interactuar con el conjunto de datos RAGmonsters:
- Haz preguntas sobre monstruos en lenguaje natural.
- Obtenga respuestas con formato Markdown y formato enriquecido
- Desarrollado con el patrón de agente ReAct de LangGraph
- Integración perfecta con las herramientas MCP
Esta interfaz permite a los usuarios:
- Explorar todos los monstruos en el conjunto de datos
- Filtrar monstruos por hábitat, categoría y rareza.
- Ver información detallada sobre cada monstruo, incluidos poderes, habilidades, fortalezas y debilidades.
Ejemplo: API específica de dominio vs. SQL genérico
Enfoque genérico MCP PostgreSQL:
User: "What are the top 3 monsters with the highest attack power that are vulnerable to fire?"
LLM: (Must understand schema, joins, and SQL syntax)
1. First query to understand the schema
2. Second query to find monsters with attack power
3. Third query to find vulnerabilities
4. Final query to join and filter results
Nuestro enfoque de servidor MCP personalizado:
User: "What are the top 3 monsters with the highest attack power that are vulnerable to fire?"
LLM: (Uses our domain-specific API)
1. Single call: getMonsters({ vulnerableTo: "fire", sortBy: "attackPower", limit: 3 })
Estructura del proyecto
├── .env.example # Example environment variables
├── package.json # Node.js project configuration
├── README.md # This documentation
├── img/ # Images for documentation
├── scripts/
│ ├── testMcpServer.js # Test script for the MCP server
│ └── testLogger.js # Logger for test script
├── src/
│ ├── index.js # Main application server
│ ├── mcp-server/ # Custom MCP server implementation with FastMCP
│ │ ├── index.js # Server entry point
│ │ ├── tools/ # Domain-specific tools
│ │ │ ├── index.js # Tool registration
│ │ │ └── monsters.js # Monster-related operations
│ │ └── utils/ # Helper utilities
│ │ └── logger.js # Logging functionality
│ ├── llm.js # LangChain integration for LLM
│ └── public/ # Web interface files
│ ├── index.html # Monster explorer interface
│ └── chat.html # Chat interface for LLM interactions
Características
- Servidor MCP personalizado con FastMCP : API específica de dominio de alto rendimiento para datos de RAGmonsters
- Consultas optimizadas : operaciones de base de datos eficientes y predefinidas
- Capa de lógica empresarial : reglas y restricciones de dominio integradas en la API
- Formato de respuesta estructurada : respuestas JSON consistentes para el consumo de LLM
- Registro completo : registro detallado para depuración y supervisión
- Conjunto de pruebas : scripts para verificar la funcionalidad del servidor y la integración de LLM
- Integración LLM :
- Integración de LangChain.js con OpenAI y otros proveedores de LLM compatibles
- Patrón de agente ReAct de LangGraph para un uso eficiente de las herramientas
- Manejo automático de llamadas y respuestas de herramientas
- Interfaces web :
- Interfaz de explorador para navegar y filtrar monstruos
- Interfaz de chat con renderizado Markdown para interacción en lenguaje natural
Características
- Integración con LangChain.js : interacciones LLM totalmente integradas con herramientas MCP
- Interfaz web : Interfaces de explorador y chat para interactuar con el conjunto de datos RAGmonsters
- Listo para implementación : configurado para una fácil implementación en plataformas como Clever Cloud
Beneficios de este enfoque
- Rendimiento mejorado : consultas optimizadas y estrategias de almacenamiento en caché
- Mejor experiencia de usuario : respuestas más precisas y rápidas
- Uso reducido de tokens : LLM no necesita procesar información compleja de SQL o esquemas
- Seguridad mejorada : la falta de acceso directo a SQL significa un menor riesgo de ataques de inyección
- Mantenibilidad : Los cambios en el esquema de la base de datos no requieren volver a entrenar el LLM.
- Escalabilidad : Puede manejar bases de datos más grandes y complejas
Empezando
Instalación
- Clonar este repositorio
- Instalar dependencias:
npm install - Copie
.env.example a .env y configure su cadena de conexión PostgreSQL y las claves API de LLM - Ejecute el script de prueba del servidor MCP:
npm run test - Ejecute el script de prueba de integración de LLM:
npm run test:llm - Iniciar el servidor:
npm start
Herramientas disponibles
El servidor MCP proporciona las siguientes herramientas:
- getMonsters : obtenga una lista de monstruos con filtrado, clasificación y paginación opcionales
- Parámetros: filtros (categoría, hábitat, rareza), ordenación (campo, dirección), límite, desplazamiento
- Devuelve: Matriz de objetos monstruosos con información básica
- getMonsterById - Obtenga información detallada sobre un monstruo específico por ID
- Parámetros: monsterId
- Devoluciones: Objeto monstruo detallado con todos los atributos, poderes, habilidades, fortalezas y debilidades.
- add - Utilidad sencilla para sumar dos números (para probar)
- Parámetros: a, b
- Devuelve: Suma de los dos números
Arquitectura de integración LLM
Este proyecto utiliza un enfoque moderno para la integración de LLM con herramientas específicas del dominio:
Patrón de agente ReAct de LangGraph
La aplicación utiliza el patrón de agente ReAct (Razonamiento y Acción) de LangGraph, que:
- Procesa las consultas del usuario para comprender la intención.
- Determina qué herramientas utilizar en función de la consulta.
- Ejecuta automáticamente las herramientas adecuadas
- Sintetiza los resultados en una respuesta coherente
- Maneja el razonamiento de varios pasos cuando es necesario
Prueba de la integración de LLM
El proyecto incluye un script de prueba que demuestra cómo usar LangChain.js para integrar un LLM con el servidor MCP:
Este guión:
- Se conecta al servidor MCP mediante StdioClientTransport
- Carga todas las herramientas MCP disponibles utilizando los adaptadores MCP de LangChain
- Crea un agente LangChain con la API OpenAI
- Procesa una consulta en lenguaje natural sobre monstruos.
- Muestra cómo el LLM realiza llamadas a herramientas para recuperar información
- Registra información detallada sobre la interacción
Puede modificar las consultas de prueba en el script para explorar las diferentes capacidades del sistema. El script se encuentra en scripts/testLlmWithMcpServer.js .
Prerrequisitos
- Node.js 23 o posterior
- Base de datos PostgreSQL con datos de RAGmonsters
- Acceso a una API LLM (por ejemplo, OpenAI)
- Paquete FastMCP (incluido en las dependencias)
Variables de entorno
Crea un archivo .env con las siguientes variables:
# PostgreSQL connection string
POSTGRESQL_ADDON_URI=postgres://username:password@host:port/database
# LLM API configuration
LLM_API_KEY=your_openai_api_key
LLM_API_MODEL=gpt-4o-mini
LLM_API_URL=https://api.openai.com/v1
Configuración de LLM
- LLM_API_KEY : Su clave de API de OpenAI o clave de proveedor compatible
- LLM_API_MODEL : El modelo a utilizar (predeterminado: gpt-4o-mini)
- LLM_API_URL : El punto final de la API (predeterminado: el punto final de OpenAI)
La aplicación admite cualquier API compatible con OpenAI, incluidos modelos autohospedados y proveedores alternativos.
Implementación en Clever Cloud
Uso de la CLI de Clever Cloud
- Instalar la CLI de Clever Cloud:
npm install -g clever-tools
- Inicie sesión en su cuenta de Clever Cloud:
- Crear una nueva aplicación:
clever create --type node <APP_NAME>
- Añade tu dominio (opcional pero recomendado):
clever domain add <YOUR_DOMAIN_NAME>
- Cree un complemento de PostgreSQL y vincúlelo a su aplicación:
clever addon create <APP_NAME>-pg --plan dev
clever service link-addon <APP_NAME>-pg
POSTGRESQL_ADDON_URI en su aplicación. - Establezca las variables de entorno necesarias:
clever env set LLM_API_KEY "your-openai-api-key"
clever env set LLM_API_MODEL "gpt-4o-mini" # Optional, defaults to gpt-4o-mini
clever env set LLM_API_URL "https://api.your-llm-provider.com" # Optional, for alternative OpenAI-compatible providers
- Implemente su aplicación:
- Abra su aplicación:
Uso de la consola Clever Cloud
También puedes implementar directamente desde la consola Clever Cloud :
- Crear una nueva aplicación en la consola
- Seleccione Node.js como entorno de ejecución
- Cree un complemento de PostgreSQL y vincúlelo a su aplicación
- Establezca las variables de entorno necesarias en la consola:
LLM_API_KEY : Su clave API de OpenAILLM_API_MODEL : (opcional) El modelo a utilizar, el valor predeterminado es gpt-4o-mini
- Implemente su aplicación usando Git o la integración de GitHub
Notas importantes
- Clever Cloud establece automáticamente la variable de entorno
POSTGRESQL_ADDON_URI cuando vincula un complemento de PostgreSQL a su aplicación - La aplicación requiere Node.js 20 o posterior, que está disponible en Clever Cloud
- La aplicación se ejecutará automáticamente en el puerto 8080, que es el puerto predeterminado para las aplicaciones Node.js en Clever Cloud.
Licencia
Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.
Expresiones de gratitud