nile-mcp

Implementación de un servidor de Protocolo de Contexto de Modelo (MCP) para la plataforma de base de datos Nile. Este servidor permite que las aplicaciones LLM interactúen con la plataforma Nile a través de una interfaz estandarizada.

Características

• Gestión de bases de datos : crear, enumerar, obtener detalles y eliminar bases de datos

• Gestión de credenciales : crear y enumerar credenciales de bases de datos

• Gestión de regiones : enumera las regiones disponibles para la creación de bases de datos

• Compatibilidad con consultas SQL : ejecute consultas SQL directamente en las bases de datos de Nile

• Compatibilidad con el protocolo MCP : implementación completa del protocolo de contexto de modelo

• Seguridad de tipos : escrito en TypeScript con verificación de tipos completa

• Manejo de errores : Manejo de errores integral y mensajes de error fáciles de usar

• Cobertura de pruebas : conjunto completo de pruebas con Jest

• Gestión del entorno : Carga automática de variables de entorno desde el archivo .env

• Validación de entrada : Validación de entrada basada en esquemas utilizando Zod

Instalación

Instalar la versión estable:

Para la última versión alfa/previa:

Esto instalará @niledatabase/nile-mcp-server en la carpeta node_modules. Por ejemplo: node_modules/@niledatabase/nile-mcp-server/dist/

Instalación manual

Otros administradores de paquetes mcp

1. npx @michaellatman/mcp-get@última instalación @niledatabase/nile-mcp-server

Iniciando el servidor

Hay varias formas de iniciar el servidor:

1. Ejecución directa de nodos :

   node dist/index.js

2. Modo de desarrollo (con reconstrucción automática):

   npm run dev

El servidor se iniciará y escuchará los mensajes del protocolo MCP. Debería ver los registros de inicio que indican:

• Variables de entorno cargadas

• Instancia de servidor creada

• Herramientas inicializadas

• Conexión de transporte establecida

Para detener el servidor, presione Ctrl+C .

Verificar que el servidor esté en ejecución

Cuando el servidor se inicie correctamente, debería ver registros similares a:

Si ve estos registros, el servidor está listo para aceptar comandos de Claude Desktop.

Configuración

Cree un archivo .env en el directorio raíz con sus credenciales de Nile:

Para crear una clave API de Nile, inicie sesión en su cuenta de Nile , haga clic en Espacios de trabajo en la parte superior izquierda, seleccione su espacio de trabajo y navegue a la sección Seguridad en el menú de la izquierda.

Uso con Claude Desktop

Configuración

1. Instale Claude Desktop si aún no lo ha hecho

2. Construir el proyecto:

   npm run build

3. Abra Claude Desktop

4. Vaya a Configuración > Servidores MCP

5. Haga clic en "Agregar servidor"

6. Agregue la siguiente configuración:

Reemplazar:

• /path/to/your/nile-mcp-server con la ruta absoluta al directorio de su proyecto

• your_api_key_here con su clave API de Nile

• your_workspace_slug con el slug de tu espacio de trabajo de Nile

Uso con cursor

Configuración

1. Instala Cursor si aún no lo has hecho

2. Construir el proyecto:

   npm run build

3. Cursor abierto

4. Vaya a Configuración (⌘,) > Características > Servidores MCP

5. Haga clic en "Agregar nuevo servidor MCP"

6. Configurar el servidor:

   • Nombre: nile-database (o cualquier nombre que prefieras)

   • Dominio:

     env NILE_API_KEY=your_key NILE_WORKSPACE_SLUG=your_workspace node /absolute/path/to/nile-mcp-server/dist/index.js

     Reemplazar:

     • your_key con su clave API de Nile

     • your_workspace con el slug de tu espacio de trabajo de Nile

     • /absolute/path/to con la ruta real a su proyecto

7. Haga clic en "Guardar"

8. Debería ver un indicador verde que muestra que el servidor MCP está conectado

9. Reinicie el cursor para que los cambios surtan efecto

Modos de servidor

El servidor admite dos modos operativos:

Modo STDIO (predeterminado)

El modo predeterminado utiliza entrada/salida estándar para la comunicación, lo que lo hace compatible con las integraciones de Claude Desktop y Cursor.

Modo SSE

El modo de eventos enviados por el servidor (SSE) permite la comunicación en tiempo real basada en eventos a través de HTTP.

Para habilitar el modo SSE:

1. Establezca MCP_SERVER_MODE=sse en su archivo .env

2. El servidor iniciará un servidor HTTP (puerto predeterminado 3000)

3. Conéctese al punto final SSE: http://localhost:3000/sse

4. Enviar comandos a: http://localhost:3000/messages

Ejemplo de uso de SSE con curl:

Ejemplos de indicaciones

Después de configurar el servidor MCP en Cursor, puede usar lenguaje natural para interactuar con las bases de datos de Nile. A continuación, se muestran algunos ejemplos de indicaciones:

Gestión de bases de datos

Creación de tablas

Consulta de datos

Gestión de esquemas

Herramientas disponibles

El servidor proporciona las siguientes herramientas para interactuar con las bases de datos de Nile:

Gestión de bases de datos

1. crear base de datos

   • Crea una nueva base de datos del Nilo

   • Parámetros:

     • name (cadena): Nombre de la base de datos

     • region (cadena): AWS_US_WEST_2 (Oregón) o AWS_EU_CENTRAL_1 (Frankfurt)

   • Devuelve: Detalles de la base de datos que incluyen ID, nombre, región y estado.

   • Ejemplo: "Crear una base de datos llamada 'my-app' en AWS_US_WEST_2"

2. bases de datos de listas

   • Enumera todas las bases de datos en su espacio de trabajo

   • No se requieren parámetros

   • Devuelve: Lista de bases de datos con sus ID, nombres, regiones y estado

   • Ejemplo: "Enumerar todas mis bases de datos"

3. obtener base de datos

   • Obtiene información detallada sobre una base de datos específica

   • Parámetros:

     • name (cadena): Nombre de la base de datos

   • Devoluciones: Información detallada de la base de datos, incluido el host de API y el host de la base de datos

   • Ejemplo: "Obtener detalles de la base de datos 'my-app'"

4. eliminar base de datos

   • Elimina una base de datos

   • Parámetros:

     • name (cadena): Nombre de la base de datos a eliminar

   • Devoluciones: Mensaje de confirmación

   • Ejemplo: "Eliminar la base de datos 'my-app'"

Gestión de credenciales

1. lista de credenciales

   • Enumera todas las credenciales de una base de datos

   • Parámetros:

     • databaseName (cadena): Nombre de la base de datos

   • Devuelve: Lista de credenciales con identificaciones, nombres de usuario y fechas de creación

   • Ejemplo: "Enumerar las credenciales de la base de datos 'my-app'"

2. crear credencial

   • Crea nuevas credenciales para una base de datos

   • Parámetros:

     • databaseName (cadena): Nombre de la base de datos

   • Devoluciones: Nuevos detalles de credenciales que incluyen nombre de usuario y contraseña de un solo uso

   • Ejemplo: "Crear nuevas credenciales para la base de datos 'my-app'"

   • Nota: Guarde la contraseña cuando se muestre, ya que no se volverá a mostrar.

Gestión de regiones

1. lista-regiones

   • Enumera todas las regiones disponibles para crear bases de datos

   • No se requieren parámetros

   • Devoluciones: Lista de regiones de AWS disponibles

   • Ejemplo: "¿Qué regiones están disponibles para crear bases de datos?"

Ejecución de consultas SQL

1. ejecutar-sql

   • Ejecuta consultas SQL en una base de datos Nile

   • Parámetros:

     • databaseName (cadena): Nombre de la base de datos a consultar

     • query (cadena): consulta SQL a ejecutar

     • connectionString (cadena, opcional): cadena de conexión preexistente que se utilizará para la consulta

   • Devoluciones: Resultados de la consulta formateados como una tabla de rebajas con encabezados de columna y recuento de filas

   • Características:

     • Gestión automática de credenciales (crea nuevas si no se especifica)

     • Conexión SSL segura a la base de datos

     • Resultados formateados como tablas de rebajas

     • Mensajes de error detallados con sugerencias

     • Soporte para el uso de cadenas de conexión existentes

   • Ejemplo: "Ejecutar SELECT * FROM users LIMIT 5 en la base de datos 'my-app'"

Gestión de recursos

1. recurso de lectura

   • Lee información de esquema para recursos de base de datos (tablas, vistas, etc.)

   • Parámetros:

     • databaseName (cadena): Nombre de la base de datos

     • resourceName (cadena): Nombre del recurso (tabla/vista)

   • Devuelve: Información detallada del esquema que incluye:

     • Nombres y tipos de columnas

     • Claves primarias e índices

     • Relaciones de clave externa

     • Descripciones y restricciones de columnas

   • Ejemplo: "Muéstrame el esquema de la tabla de usuarios en mi aplicación"

2. lista de recursos

   • Enumera todos los recursos (tablas, vistas) en una base de datos

   • Parámetros:

     • databaseName (cadena): Nombre de la base de datos

   • Devuelve: Lista de todos los recursos con sus tipos

   • Ejemplo: "Enumerar todas las tablas en la base de datos de mi aplicación"

Gestión de inquilinos

1. lista de inquilinos

   • Enumera todos los inquilinos en una base de datos

   • Parámetros:

     • databaseName (cadena): Nombre de la base de datos

   • Devuelve: Lista de inquilinos con sus ID y metadatos

   • Ejemplo: "Mostrar todos los inquilinos en la base de datos de mi aplicación"

2. crear inquilino

   • Crea un nuevo inquilino en una base de datos

   • Parámetros:

     • databaseName (cadena): Nombre de la base de datos

     • tenantName (cadena): nombre del nuevo inquilino

   • Devoluciones: Detalles del nuevo inquilino, incluida la identificación

   • Ejemplo: "Crear un inquilino llamado 'acme-corp' en mi aplicación"

3. eliminar inquilino

   • Elimina inquilinos en la base de datos

   • Parámetros:

     • databaseName (cadena): Nombre de la base de datos

     • tenantName (cadena): nombre del inquilino

   • Devuelve: Éxito si se elimina el inquilino

   • Ejemplo: "Eliminar el inquilino llamado 'acme-corp' en mi aplicación"

Ejemplo de uso

A continuación se muestran algunos comandos de ejemplo que puedes utilizar en Claude Desktop:

Formato de respuesta

Todas las herramientas devuelven respuestas en un formato estandarizado:

• Las respuestas de éxito incluyen datos relevantes y mensajes de confirmación.

• Las respuestas de error incluyen mensajes de error detallados y códigos de estado HTTP

• Los resultados de las consultas SQL se formatean como tablas de rebajas

• Todas las respuestas están formateadas para facilitar su lectura en Claude Desktop.

Manejo de errores

El servidor gestiona varios escenarios de error:

• Credenciales de API no válidas

• Problemas de conectividad de red

• Nombres o regiones de bases de datos no válidos

• Faltan parámetros requeridos

• Fallos en el funcionamiento de la base de datos

• Errores de sintaxis SQL con sugerencias útiles

• Limitación de velocidad y restricciones de API

Solución de problemas

1. Si Claude dice que no puede acceder a las herramientas:

   • Verifique que la ruta del servidor en la configuración sea correcta

   • Asegúrese de que el proyecto esté compilado ( npm run build )

   • Verifique que su clave API y el slug del espacio de trabajo sean correctos

   • Reiniciar Claude Desktop

2. Si falla la creación de la base de datos:

   • Comprueba los permisos de tu clave API

   • Asegúrese de que el nombre de la base de datos sea único en su espacio de trabajo

   • Verifique que la región sea una de las opciones admitidas

3. Si las operaciones de credenciales fallan:

   • Verifique que la base de datos exista y esté en el estado LISTO

   • Comprueba que tu clave API tenga los permisos necesarios

Desarrollo

Estructura del proyecto

Archivos clave

• server.ts : Implementación del servidor principal con registro de herramientas y manejo de transporte

• tools.ts : Implementación de todas las operaciones de base de datos y ejecución de consultas SQL

• types.ts : Interfaces TypeScript para operaciones y respuestas de bases de datos

• logger.ts : registro estructurado con rotación diaria y soporte de depuración

• index.ts : Inicio del servidor y configuración del entorno

• server.test.ts : conjunto de pruebas completo para todas las funciones

Desarrollo

Scripts de desarrollo

Los siguientes scripts npm están disponibles:

• npm run build : Compila TypeScript a JavaScript

• npm start : inicia el servidor en modo de producción

• npm run dev : inicia el servidor en modo de desarrollo con reconstrucción automática

• npm test : ejecuta el conjunto de pruebas

• npm run lint : ejecuta ESLint para verificar la calidad del código

• npm run clean : elimina artefactos de compilación

Pruebas

El proyecto incluye un conjunto de pruebas integral que cubre:

• Registro de herramientas y validación de esquemas

• Operaciones de gestión de bases de datos

• Generación de cadena de conexión

• Ejecución de consultas SQL y manejo de errores

• Formato de respuesta y casos de error

Ejecute las pruebas con:

Explotación florestal

El servidor utiliza un registro estructurado con las siguientes características:

• Archivos de registro rotativos diariamente

• Registros de depuración separados

• Registros con formato JSON y marcas de tiempo

• Salida de consola para desarrollo

• Categorías de registro: información, error, depuración, API, SQL, inicio

Licencia

Licencia MIT: consulte LICENCIA para obtener más detalles.

Enlaces relacionados

• Protocolo de contexto modelo

• Base de datos del Nilo

• Escritorio de Claude

• Cursor