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:

1. Complejidad de la base de datos abstracta : ocultar el esquema subyacente y los detalles de SQL

2. Proporcionar operaciones específicas del dominio : ofrecer funciones que se alineen con los conceptos comerciales

3. Optimizar para consultas comunes : Implementar patrones de consulta eficientes para preguntas frecuentes

4. Aplicar reglas de negocio : incorporar lógica y restricciones específicas del dominio

5. 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:

Nuestro enfoque de servidor MCP personalizado:

Estructura del proyecto

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

1. Rendimiento mejorado : consultas optimizadas y estrategias de almacenamiento en caché

2. Mejor experiencia de usuario : respuestas más precisas y rápidas

3. Uso reducido de tokens : LLM no necesita procesar información compleja de SQL o esquemas

4. Seguridad mejorada : la falta de acceso directo a SQL significa un menor riesgo de ataques de inyección

5. Mantenibilidad : Los cambios en el esquema de la base de datos no requieren volver a entrenar el LLM.

6. Escalabilidad : Puede manejar bases de datos más grandes y complejas

Empezando

Instalación

1. Clonar este repositorio

2. Instalar dependencias: npm install

3. Copie .env.example a .env y configure su cadena de conexión PostgreSQL y las claves API de LLM

4. Ejecute el script de prueba del servidor MCP: npm run test

5. Ejecute el script de prueba de integración de LLM: npm run test:llm

6. Iniciar el servidor: npm start

Herramientas disponibles

El servidor MCP proporciona las siguientes herramientas:

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

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

3. 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:

1. Procesa las consultas del usuario para comprender la intención.

2. Determina qué herramientas utilizar en función de la consulta.

3. Ejecuta automáticamente las herramientas adecuadas

4. Sintetiza los resultados en una respuesta coherente

5. 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:

1. Se conecta al servidor MCP mediante StdioClientTransport

2. Carga todas las herramientas MCP disponibles utilizando los adaptadores MCP de LangChain

3. Crea un agente LangChain con la API OpenAI

4. Procesa una consulta en lenguaje natural sobre monstruos.

5. Muestra cómo el LLM realiza llamadas a herramientas para recuperar información

6. 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:

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

1. Instalar la CLI de Clever Cloud:

   npm install -g clever-tools

2. Inicie sesión en su cuenta de Clever Cloud:

   clever login

3. Crear una nueva aplicación:

   clever create --type node <APP_NAME>

4. Añade tu dominio (opcional pero recomendado):

   clever domain add <YOUR_DOMAIN_NAME>

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

   Esto establecerá automáticamente la variable de entorno POSTGRESQL_ADDON_URI en su aplicación.

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

7. Implemente su aplicación:

   clever deploy

8. Abra su aplicación:

   clever open

Uso de la consola Clever Cloud

También puedes implementar directamente desde la consola Clever Cloud :

1. Crear una nueva aplicación en la consola

2. Seleccione Node.js como entorno de ejecución

3. Cree un complemento de PostgreSQL y vincúlelo a su aplicación

4. Establezca las variables de entorno necesarias en la consola:

   • LLM_API_KEY : Su clave API de OpenAI

   • LLM_API_MODEL : (opcional) El modelo a utilizar, el valor predeterminado es gpt-4o-mini

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

• RAGmonsters para el conjunto de datos de muestra

• Protocolo de contexto de modelo para la especificación MCP

• FastMCP para la implementación de MCP de alto rendimiento

• Clever Cloud para capacidades de alojamiento