Nile Postgres

Gestionar y consultar bases de datos, inquilinos, usuarios, autenticación usando LLMs

Documentación

Servidor MCP de Nile

Aprende más ↗️

Discord 🔵 Sitio web 🔵 Problemas

Una implementación del servidor del Model Context Protocol (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, listar, obtener detalles y eliminar bases de datos
Gestión de credenciales: Crear y listar credenciales de bases de datos
Gestión de regiones: Listar regiones disponibles para la creación de bases de datos
Soporte de consultas SQL: Ejecutar consultas SQL directamente en bases de datos Nile
Soporte del protocolo MCP: Implementación completa del Model Context Protocol
Seguridad de tipos: Escrito en TypeScript con verificación completa de tipos
Manejo de errores: Manejo integral de errores y mensajes de error fáciles de usar
Cobertura de pruebas: Suite de pruebas integral usando Jest
Gestión de entorno: Carga automática de variables de entorno desde el archivo .env
Validación de entrada: Validación de entrada basada en esquemas usando Zod

Instalación

Instala la versión estable:

npm install @niledatabase/nile-mcp-server

Para la última versión alfa/vista previa:

npm install @niledatabase/nile-mcp-server@alpha

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

Instalación manual

# Clone the repository
git clone https://github.com/yourusername/nile-mcp-server.git
cd nile-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Otros gestores de paquetes mcp

npx @michaellatman/mcp-get@latest install @niledatabase/nile-mcp-server

Iniciando el Servidor

Hay varias formas de iniciar el servidor:

Ejecución directa con Node:
```
node dist/index.js
```
Modo de desarrollo (con reconstrucción automática):
```
npm run dev
```

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

Variables de entorno cargadas
Instancia del servidor creada
Herramientas inicializadas
Conexión de transporte establecida

Para detener el servidor, presiona Ctrl+C.

Verificando que el Servidor está Ejecutándose

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

[info] Starting Nile MCP Server...
[info] Loading environment variables...
[info] Environment variables loaded successfully
[info] Creating server instance...
[info] Tools initialized successfully
[info] Setting up stdio transport...
[info] Server started successfully

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

Configuración

Crea un archivo .env en el directorio raíz con tus credenciales de Nile:

NILE_API_KEY=your_api_key_here
NILE_WORKSPACE_SLUG=your_workspace_slug

Para crear una clave API de Nile, inicia sesión en tu cuenta de Nile, haz clic en Workspaces en la parte superior izquierda, selecciona tu espacio de trabajo y navega a la sección Security en el menú izquierdo.

Uso con Claude Desktop

Configuración

Instala Claude Desktop si aún no lo has hecho
Compila el proyecto:
```
npm run build
```
Abre Claude Desktop
Ve a Settings > MCP Servers
Haz clic en "Add Server"
Agrega la siguiente configuración:

{
  "mcpServers": {
    "nile-database": {
      "command": "node",
      "args": [
        "/path/to/your/nile-mcp-server/dist/index.js"
      ],
      "env": {
        "NILE_API_KEY": "your_api_key_here",
        "NILE_WORKSPACE_SLUG": "your_workspace_slug"
      }
    }
  }
}

Reemplaza:

/path/to/your/nile-mcp-server con la ruta absoluta a tu directorio del proyecto
your_api_key_here con tu clave API de Nile
your_workspace_slug con tu slug de espacio de trabajo de Nile

Uso con Cursor

Configuración

Instala Cursor si aún no lo has hecho
Compila el proyecto:
```
npm run build
```
Abre Cursor
Ve a Settings (⌘,) > Features > MCP Servers
Haz clic en "Add New MCP Server"
Configura el servidor:
- Nombre: nile-database (o cualquier nombre que prefieras)
- Comando:
```
env NILE_API_KEY=your_key NILE_WORKSPACE_SLUG=your_workspace node /absolute/path/to/nile-mcp-server/dist/index.js
```
  Reemplaza:
  - your_key con tu clave API de Nile
  - your_workspace con tu slug de espacio de trabajo de Nile
  - /absolute/path/to con la ruta real a tu proyecto
Haz clic en "Save"
Deberías ver un indicador verde que muestra que el servidor MCP está conectado
Reinicia Cursor para que los cambios surtan efecto

Modos del Servidor

El servidor admite dos modos operativos:

Modo STDIO (Predeterminado)

El modo predeterminado usa 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 Server-Sent Events (SSE) permite comunicación en tiempo real y basada en eventos a través de HTTP.

Para habilitar el modo SSE:

Establece MCP_SERVER_MODE=sse en tu archivo .env
El servidor iniciará un servidor HTTP (puerto predeterminado 3000)
Conéctate al endpoint SSE: http://localhost:3000/sse
Envía comandos a: http://localhost:3000/messages

Ejemplo de uso de SSE con curl:

# In terminal 1 - Listen for events
curl -N http://localhost:3000/sse

# In terminal 2 - Send commands
curl -X POST http://localhost:3000/messages \
  -H "Content-Type: application/json" \
  -d '{
    "type": "function",
    "name": "list-databases",
    "parameters": {}
  }'

Ejemplos de Prompts

Después de configurar el servidor MCP en Cursor, puedes usar lenguaje natural para interactuar con las bases de datos de Nile. Aquí hay algunos ejemplos de prompts:

Gestión de Bases de Datos

Create a new database named "my_app" in AWS_US_WEST_2 region

List all my databases

Get details for database "my_app"

Delete database "test_db"

Creación de Tablas

Create a users table in my_app database with columns:
- tenant_id (UUID, references tenants)
- id (INTEGER)
- email (VARCHAR, unique per tenant)
- name (VARCHAR)
- created_at (TIMESTAMP)

Create a products table in my_app database with columns:
- tenant_id (UUID, references tenants)
- id (INTEGER)
- name (VARCHAR)
- price (DECIMAL)
- description (TEXT)
- created_at (TIMESTAMP)

Consulta de Datos

Execute this query on my_app database:
SELECT * FROM users WHERE tenant_id = 'your-tenant-id' LIMIT 5

Run this query on my_app:
INSERT INTO users (tenant_id, id, email, name) 
VALUES ('tenant-id', 1, 'user@example.com', 'John Doe')

Show me all products in my_app database with price > 100

Gestión de Esquemas

Show me the schema for the users table in my_app database

Add a new column 'status' to the users table in my_app database

Create an index on the email column of the users table in my_app

Herramientas Disponibles

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

Gestión de Bases de Datos

create-database
- Crea una nueva base de datos de Nile
- Parámetros:
  - name (cadena): Nombre de la base de datos
  - region (cadena): Ya sea AWS_US_WEST_2 (Oregón) o AWS_EU_CENTRAL_1 (Fráncfort)
- Devuelve: Detalles de la base de datos incluyendo ID, nombre, región y estado
- Ejemplo: "Crea una base de datos llamada 'my-app' en AWS_US_WEST_2"
list-databases
- Lista todas las bases de datos en tu espacio de trabajo
- No requiere parámetros
- Devuelve: Lista de bases de datos con sus IDs, nombres, regiones y estados
- Ejemplo: "Lista todas mis bases de datos"
get-database
- Obtiene información detallada sobre una base de datos específica
- Parámetros:
  - name (cadena): Nombre de la base de datos
- Devuelve: Información detallada de la base de datos incluyendo host de API y host de DB
- Ejemplo: "Obtén detalles de la base de datos 'my-app'"
delete-database
- Elimina una base de datos
- Parámetros:
  - name (cadena): Nombre de la base de datos a eliminar
- Devuelve: Mensaje de confirmación
- Ejemplo: "Elimina la base de datos 'my-app'"

Gestión de Credenciales

list-credentials
- Lista todas las credenciales de una base de datos
- Parámetros:
  - databaseName (cadena): Nombre de la base de datos
- Devuelve: Lista de credenciales con IDs, nombres de usuario y fechas de creación
- Ejemplo: "Lista las credenciales de la base de datos 'my-app'"
create-credential
- Crea nuevas credenciales para una base de datos
- Parámetros:
  - databaseName (cadena): Nombre de la base de datos
- Devuelve: Detalles de las nuevas credenciales incluyendo nombre de usuario y contraseña de un solo uso
- Ejemplo: "Crea nuevas credenciales para la base de datos 'my-app'"
- Nota: Guarda la contraseña cuando se muestre, ya que no se volverá a mostrar

Gestión de Regiones

list-regions
- Lista todas las regiones disponibles para crear bases de datos
- No requiere parámetros
- Devuelve: Lista de regiones AWS disponibles
- Ejemplo: "¿Qué regiones están disponibles para crear bases de datos?"

Ejecución de Consultas SQL

execute-sql
- Ejecuta consultas SQL en una base de datos de 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 para usar en la consulta
- Devuelve: Resultados de la consulta formateados como tabla markdown con encabezados de columna y recuento de filas
- Características:
  - Gestión automática de credenciales (crea nuevas si no se especifican)
  - Conexión SSL segura a la base de datos
  - Resultados formateados como tablas markdown
  - Mensajes de error detallados con sugerencias
  - Soporte para usar cadenas de conexión existentes
- Ejemplo: "Ejecuta SELECT * FROM users LIMIT 5 en la base de datos 'my-app'"

Gestión de Recursos

read-resource
- 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 incluyendo:
  - Nombres y tipos de columnas
  - Claves primarias e índices
  - Relaciones de claves foráneas
  - Descripciones y restricciones de columnas
- Ejemplo: "Muéstrame el esquema de la tabla users en my-app"
list-resources
- Lista 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: "Lista todas las tablas en la base de datos my-app"

Gestión de Inquilinos

list-tenants
- Lista todos los inquilinos en una base de datos
- Parámetros:
  - databaseName (cadena): Nombre de la base de datos
- Devuelve: Lista de inquilinos con sus IDs y metadatos
- Ejemplo: "Muestra todos los inquilinos en la base de datos my-app"
create-tenant
- Crea un nuevo inquilino en una base de datos
- Parámetros:
  - databaseName (cadena): Nombre de la base de datos
  - tenantName (cadena): Nombre para el nuevo inquilino
- Devuelve: Detalles del nuevo inquilino incluyendo ID
- Ejemplo: "Crea un inquilino llamado 'acme-corp' en my-app"
delete-tenant
- 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 el inquilino se elimina
- Ejemplo: "Elimina el inquilino llamado 'acme-corp' en my-app"

Ejemplo de Uso

Aquí hay algunos comandos de ejemplo que puedes usar en Claude Desktop:

# Database Management
Please create a new database named "my-app" in the AWS_US_WEST_2 region.
Can you list all my databases?
Get the details for database "my-app".
Delete the database named "test-db".

# Connection String Management
Get a connection string for database "my-app".
# Connection string format: postgres://<user>:<password>@<region>.db.thenile.dev:5432/<database>
# Example: postgres://cred-123:password@us-west-2.db.thenile.dev:5432/my-app

# SQL Queries
Execute SELECT * FROM users LIMIT 5 on database "my-app"
Run this query on my-app database: SELECT COUNT(*) FROM orders WHERE status = 'completed'
Using connection string "postgres://user:pass@host:5432/db", execute this query on my-app: SELECT * FROM products WHERE price > 100

Formato de Respuesta

Todas las herramientas devuelven respuestas en un formato estandarizado:

Las respuestas exitosas 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 consultas SQL se formatean como tablas markdown
Todas las respuestas están formateadas para facilitar su lectura en Claude Desktop

Manejo de Errores

El servidor maneja varios escenarios de error:

Credenciales de API inválidas
Problemas de conectividad de red
Nombres de bases de datos o regiones inválidos
Parámetros requeridos faltantes
Fallos en operaciones de base de datos
Errores de sintaxis SQL con sugerencias útiles
Limitación de velocidad y restricciones de API

Solución de Problemas

Si Claude dice que no puede acceder a las herramientas:
- Verifica que la ruta del servidor en la configuración sea correcta
- Asegúrate de que el proyecto esté compilado (npm run build)
- Verifica que tu clave API y slug de espacio de trabajo sean correctos
- Reinicia Claude Desktop
Si la creación de la base de datos falla:
- Verifica los permisos de tu clave API
- Asegúrate de que el nombre de la base de datos sea único en tu espacio de trabajo
- Verifica que la región sea una de las opciones admitidas
Si las operaciones de credenciales fallan:
- Verifica que la base de datos exista y esté en estado READY
- Comprueba que tu clave API tenga los permisos necesarios

Desarrollo

Estructura del Proyecto

nile-mcp-server/
├── src/
│   ├── server.ts      # MCP server implementation
│   ├── tools.ts       # Tool implementations
│   ├── types.ts       # Type definitions
│   ├── logger.ts      # Logging utilities
│   ├── index.ts       # Entry point
│   └── __tests__/     # Test files
│       └── server.test.ts
├── dist/             # Compiled JavaScript
├── logs/            # Log files directory
├── .env             # Environment configuration
├── .gitignore       # Git ignore file
├── package.json     # Project dependencies
└── tsconfig.json    # TypeScript configuration

Archivos Clave

server.ts: Implementación principal del servidor 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 base 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: Suite de pruebas integral para toda la funcionalidad

Desarrollo

# Install dependencies
npm install

# Build the project
npm run build

# Start the server in production mode
node dist/index.js

# Start the server using npm script
npm start

# Start in development mode with auto-rebuild
npm run dev

# Run tests
npm test

Scripts de Desarrollo

Los siguientes scripts npm están disponibles:

npm run build: Compila TypeScript a JavaScript
npm start: Inicia el servidor en modo producción
npm run dev: Inicia el servidor en modo desarrollo con reconstrucción automática
npm test: Ejecuta la suite de pruebas
npm run lint: Ejecuta ESLint para verificación de calidad de código
npm run clean: Elimina artefactos de compilación

Pruebas

El proyecto incluye una suite de pruebas integral que cubre:

Registro de herramientas y validación de esquemas
Operaciones de gestión de bases de datos
Generación de cadenas de conexión
Ejecución de consultas SQL y manejo de errores
Formato de respuestas y casos de error

Ejecuta las pruebas con:

npm test

Registro

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

Archivos de registro rotativos diarios
Registros de depuración separados
Registros formateados en JSON con marcas de tiempo
Salida en consola para desarrollo
Categorías de registro: info, error, debug, api, sql, startup

Licencia

Licencia MIT - Consulte LICENSE para obtener detalles.

Nile Postgres

Documentación

Servidor MCP de Nile

Características

Instalación

Instalación manual

Otros gestores de paquetes mcp

Iniciando el Servidor

Verificando que el Servidor está Ejecutándose

Configuración

Uso con Claude Desktop

Configuración

Uso con Cursor

Configuración

Modos del Servidor

Modo STDIO (Predeterminado)

Modo SSE

Ejemplos de Prompts

Gestión de Bases de Datos

Creación de Tablas

Consulta de Datos

Gestión de Esquemas

Herramientas Disponibles

Gestión de Bases de Datos

Gestión de Credenciales

Gestión de Regiones

Ejecución de Consultas SQL

Gestión de Recursos

Gestión de Inquilinos

Ejemplo de Uso

Formato de Respuesta

Manejo de Errores

Solución de Problemas

Desarrollo

Estructura del Proyecto

Archivos Clave

Desarrollo

Scripts de Desarrollo

Pruebas

Registro

Licencia

Enlaces Relacionados