Protocolo de contexto de modelo del servidor PostgreSQL

Este proyecto implementa un servidor de Protocolo de Contexto de Modelo (MCP) que se conecta a una base de datos PostgreSQL. Permite que los modelos de IA interactúen con la base de datos mediante un protocolo estandarizado.

Características

• Se conecta a una base de datos PostgreSQL mediante agrupación de conexiones
• Implementa el Protocolo de Contexto de Modelo para la interacción del modelo de IA
• Proporciona información del esquema de base de datos como recursos
• Permite ejecutar consultas SQL con lógica de reintento
• Maneja errores de conexión con elegancia

Prerrequisitos

• Node.js 20 o superior
• Base de datos PostgreSQL
• Credenciales de acceso a la base de datos

Instalación

1. Clonar este repositorio
2. Instalar dependencias:

Configuración

El servidor lee las credenciales de la base de datos desde un archivo .env en el directorio raíz del proyecto. Debe agregar las credenciales de la base de datos como una cadena JSON en la variable de entorno DB_CREDENTIALS :

1. Cree un archivo .env en la raíz del proyecto:

2. Agregue la siguiente línea con sus credenciales de base de datos reales:

Regresar a los archivos de configuración del shell

Si el archivo .env no está presente o no se encuentra la variable de credenciales, el servidor buscará automáticamente las credenciales en los archivos de configuración de shell en el siguiente orden:

1. ~/.zshrc
2. ~/.bashrc
3. ~/.bash_profile
4. ~/.profile

Esto es especialmente útil en entornos donde los archivos de configuración de shell no se obtienen automáticamente, como el entorno Cursor MCP.

Para configurar credenciales en cualquiera de los archivos de configuración de shell:

1. Abra el archivo de configuración de shell que prefiera, por ejemplo:

2. Agregue la siguiente línea con sus credenciales de base de datos reales:

El servidor detectará y utilizará automáticamente estas credenciales cuando el archivo .env no esté disponible.

Variable de credenciales personalizadas

También puede utilizar un nombre de variable de entorno personalizado en lugar de DB_CREDENTIALS utilizando el indicador --credentials-var al iniciar el servidor:

En este caso, deberá definir MY_CUSTOM_DB_CREDS en su archivo .env .

Combinando opciones

Puede combinar diferentes opciones de línea de comandos según sea necesario:

Uso

Inicie el servidor MCP:

Opciones de registro

De forma predeterminada, el servidor se ejecuta en modo silencioso y solo muestra mensajes de error. Si desea ver todos los mensajes de registro, puede usar la opción verbose:

También puedes utilizar la bandera corta -v :

El servidor hará lo siguiente:

1. Probar la conexión a la base de datos
2. Inicie el servidor MCP usando el transporte stdio
3. Gestionar solicitudes de modelos de IA

Integración con Cursor

Este servidor admite el Protocolo de contexto de modelo (MCP) y se integra con Cursor AI.

Configuración automática

Este proyecto incluye un archivo .cursor/mcp.json preconfigurado para la configuración automática dentro de Cursor.

Configuración manual

Para agregar manualmente este servidor a Cursor:

1. Vaya a Configuración del cursor → Funciones → MCP
2. Haga clic en "+ Agregar nuevo servidor MCP"
3. Introduzca los siguientes datos:
   • Nombre : Postgres MCP
   • Tipo : stdio
   • Comando : node /full/path/to/server.js

Para obtener más información sobre la integración de MCP con Cursor, consulte la documentación oficial .

Herramientas disponibles

El servidor proporciona las siguientes herramientas a los modelos de IA:

• query : Ejecutar consultas SQL con lógica de reintento

Recursos

El servidor expone las tablas de la base de datos como recursos, lo que permite que los modelos de IA:

• Listar todas las tablas en la base de datos
• Ver información del esquema para cada tabla

Manejo de errores

El servidor incluye:

• Lógica de reintento de conexión
• Registro detallado de errores
• Manejo elegante del apagado

Solución de problemas

Problemas de conexión

1. Error en la conexión a la base de datos
   • Compruebe si PostgreSQL se está ejecutando: pg_isready -h localhost -p 5433
   • Verifique que sus credenciales en el archivo .env sean correctas
   • Asegúrese de que su dirección IP tenga acceso a la base de datos (verifique pg_hba.conf)
   • Intente conectarse con otra herramienta como psql para verificar las credenciales
2. Problemas de variables ambientales
   • Asegúrese de que su archivo .env esté en el directorio raíz del proyecto
   • Compruebe que la estructura JSON en DB_CREDENTIALS sea válida
   • Verifique que no haya espacios adicionales ni saltos de línea en la cadena JSON
   • Prueba con: node -e "console.log(JSON.parse(process.env.DB_CREDENTIALS))" < .env
3. Problemas de versión de Node.js
   • Comprueba tu versión de Node.js: node -v
   • Este servidor requiere Node.js 20+
   • Si usa una versión anterior, instale Node.js 20: nvm install 20 && nvm use 20

Integración del cursor

1. El servidor no se muestra en el cursor
   • Asegúrese de que el archivo .cursor/mcp.json exista y tenga el formato correcto
   • Intente reiniciar Cursor para detectar la configuración específica del proyecto
   • Verifique los registros del cursor para ver si hay mensajes de error
2. Error "No se pudo crear el cliente"
   • Esto generalmente indica que el servidor falló durante el inicio.
   • Ejecute el servidor manualmente con registro detallado para ver el error: node server.js -v
   • Compruebe si las credenciales de la base de datos son accesibles en el entorno del Cursor
3. No hay herramientas disponibles en el cursor
   • Asegúrese de que el servidor esté funcionando correctamente (verifique los registros)
   • Intente hacer clic en el botón Actualizar en el panel de herramientas de MCP
   • Reinicie el cursor e inténtelo nuevamente

Problemas específicos de PostgreSQL

1. Errores de permiso denegado
   • Asegúrese de que el usuario de la base de datos tenga los permisos adecuados para las tablas
   • Intente otorgar los permisos necesarios: GRANT SELECT ON ALL TABLES IN SCHEMA public TO username;
2. Errores "La relación no existe"
   • Verifique que la tabla exista: \dt tablename en psql
   • Comprueba si te estás conectando a la base de datos correcta
   • Asegúrese de que el usuario tenga acceso al esquema donde se encuentra la tabla
3. Problemas de rendimiento
   • Los resultados de consultas grandes pueden causar retrasos, considere agregar cláusulas LIMIT
   • Comprueba si tu base de datos necesita optimización (índices, limpieza)

Para obtener ayuda adicional, puede ejecutar el servidor con registro detallado (indicador -v ) para ver mensajes de error detallados y registros de operaciones.

Licencia

Instituto Tecnológico de Massachusetts (MIT)