Nile Postgres

Gerencie e consulte bancos de dados, tenants, usuários e autenticação usando LLMs.

Documentação

Nile MCP Server

Saiba mais ↗️

Discord 🔵 Website 🔵 Issues

Uma implementação de servidor Model Context Protocol (MCP) para a plataforma de banco de dados Nile. Este servidor permite que aplicações LLM interajam com a plataforma Nile através de uma interface padronizada.

Recursos

Gerenciamento de Banco de Dados: Criar, listar, obter detalhes e excluir bancos de dados
Gerenciamento de Credenciais: Criar e listar credenciais de banco de dados
Gerenciamento de Regiões: Listar regiões disponíveis para criação de bancos de dados
Suporte a Consultas SQL: Executar consultas SQL diretamente nos bancos de dados Nile
Suporte ao Protocolo MCP: Implementação completa do Model Context Protocol
Segurança de Tipos: Escrito em TypeScript com verificação completa de tipos
Tratamento de Erros: Tratamento abrangente de erros e mensagens de erro amigáveis
Cobertura de Testes: Suíte de testes abrangente usando Jest
Gerenciamento de Ambiente: Carregamento automático de variáveis de ambiente do arquivo .env
Validação de Entrada: Validação de entrada baseada em esquema usando Zod

Instalação

Instale a versão estável:

npm install @niledatabase/nile-mcp-server

Para a versão alpha/preview mais recente:

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

Isso instalará @niledatabase/nile-mcp-server na sua pasta node_modules. Por exemplo: node_modules/@niledatabase/nile-mcp-server/dist/

Instalação 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

Outros gerenciadores de pacotes mcp

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

Iniciando o Servidor

Existem várias maneiras de iniciar o servidor:

Execução Direta com Node:
```
node dist/index.js
```
Modo de Desenvolvimento (com recompilação automática):
```
npm run dev
```

O servidor iniciará e ficará ouvindo mensagens do protocolo MCP. Você deve ver logs de inicialização indicando:

Variáveis de ambiente carregadas
Instância do servidor criada
Ferramentas inicializadas
Conexão de transporte estabelecida

Para parar o servidor, pressione Ctrl+C.

Verificando se o Servidor Está em Execução

Quando o servidor iniciar com sucesso, você deve ver logs semelhantes 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

Se você vir esses logs, o servidor está pronto para aceitar comandos do Claude Desktop.

Configuração

Crie um arquivo .env no diretório raiz com suas credenciais Nile:

NILE_API_KEY=your_api_key_here
NILE_WORKSPACE_SLUG=your_workspace_slug

Para criar uma chave de API Nile, faça login na sua conta Nile, clique em Workspaces no canto superior esquerdo, selecione seu workspace e navegue até a seção Security no menu esquerdo.

Usando com Claude Desktop

Configuração

Instale o Claude Desktop se ainda não tiver
Compile o projeto:
```
npm run build
```
Abra o Claude Desktop
Vá para Configurações > Servidores MCP
Clique em "Adicionar Servidor"
Adicione a seguinte configuração:

{
  "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"
      }
    }
  }
}

Substitua:

/path/to/your/nile-mcp-server pelo caminho absoluto para o diretório do seu projeto
your_api_key_here pela sua chave de API Nile
your_workspace_slug pelo slug do seu workspace Nile

Usando com Cursor

Configuração

Instale o Cursor se ainda não tiver
Compile o projeto:
```
npm run build
```
Abra o Cursor
Vá para Configurações (⌘,) > Recursos > Servidores MCP
Clique em "Adicionar Novo Servidor MCP"
Configure o servidor:
- Nome: nile-database (ou qualquer nome que preferir)
- Comando:
```
env NILE_API_KEY=your_key NILE_WORKSPACE_SLUG=your_workspace node /absolute/path/to/nile-mcp-server/dist/index.js
```
  Substitua:
  - your_key pela sua chave de API Nile
  - your_workspace pelo slug do seu workspace Nile
  - /absolute/path/to pelo caminho real para o seu projeto
Clique em "Salvar"
Você deve ver um indicador verde mostrando que o servidor MCP está conectado
Reinicie o Cursor para que as alterações tenham efeito

Modos do Servidor

O servidor suporta dois modos operacionais:

Modo STDIO (Padrão)

O modo padrão usa entrada/saída padrão para comunicação, tornando-o compatível com integrações do Claude Desktop e Cursor.

Modo SSE

O modo Server-Sent Events (SSE) permite comunicação em tempo real orientada a eventos via HTTP.

Para habilitar o modo SSE:

Defina MCP_SERVER_MODE=sse no seu arquivo .env
O servidor iniciará um servidor HTTP (porta padrão 3000)
Conecte-se ao endpoint SSE: http://localhost:3000/sse
Envie comandos para: http://localhost:3000/messages

Exemplo de uso SSE com 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": {}
  }'

Exemplos de Prompts

Após configurar o servidor MCP no Cursor, você pode usar linguagem natural para interagir com bancos de dados Nile. Aqui estão alguns exemplos de prompts:

Gerenciamento de Banco de Dados

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"

Criando Tabelas

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)

Consultando Dados

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

Gerenciamento de Esquema

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

Ferramentas Disponíveis

O servidor fornece as seguintes ferramentas para interagir com bancos de dados Nile:

Gerenciamento de Banco de Dados

create-database
- Cria um novo banco de dados Nile
- Parâmetros:
  - name (string): Nome do banco de dados
  - region (string): Ou AWS_US_WEST_2 (Oregon) ou AWS_EU_CENTRAL_1 (Frankfurt)
- Retorna: Detalhes do banco de dados incluindo ID, nome, região e status
- Exemplo: "Crie um banco de dados chamado 'my-app' em AWS_US_WEST_2"
list-databases
- Lista todos os bancos de dados no seu workspace
- Nenhum parâmetro necessário
- Retorna: Lista de bancos de dados com seus IDs, nomes, regiões e status
- Exemplo: "Liste todos os meus bancos de dados"
get-database
- Obtém informações detalhadas sobre um banco de dados específico
- Parâmetros:
  - name (string): Nome do banco de dados
- Retorna: Informações detalhadas do banco de dados incluindo host da API e host do banco
- Exemplo: "Obtenha detalhes para o banco de dados 'my-app'"
delete-database
- Exclui um banco de dados
- Parâmetros:
  - name (string): Nome do banco de dados a ser excluído
- Retorna: Mensagem de confirmação
- Exemplo: "Exclua o banco de dados 'my-app'"

Gerenciamento de Credenciais

list-credentials
- Lista todas as credenciais para um banco de dados
- Parâmetros:
  - databaseName (string): Nome do banco de dados
- Retorna: Lista de credenciais com IDs, nomes de usuário e datas de criação
- Exemplo: "Liste credenciais para o banco de dados 'my-app'"
create-credential
- Cria novas credenciais para um banco de dados
- Parâmetros:
  - databaseName (string): Nome do banco de dados
- Retorna: Detalhes das novas credenciais incluindo nome de usuário e senha de uso único
- Exemplo: "Crie novas credenciais para o banco de dados 'my-app'"
- Nota: Salve a senha quando ela for exibida, pois não será mostrada novamente

Gerenciamento de Regiões

list-regions
- Lista todas as regiões disponíveis para criar bancos de dados
- Nenhum parâmetro necessário
- Retorna: Lista de regiões AWS disponíveis
- Exemplo: "Quais regiões estão disponíveis para criar bancos de dados?"

Execução de Consultas SQL

execute-sql
- Executa consultas SQL em um banco de dados Nile
- Parâmetros:
  - databaseName (string): Nome do banco de dados para consultar
  - query (string): Consulta SQL a ser executada
  - connectionString (string, opcional): String de conexão pré-existente para usar na consulta
- Retorna: Resultados da consulta formatados como tabela markdown com cabeçalhos de coluna e contagem de linhas
- Recursos:
  - Gerenciamento automático de credenciais (cria novas se não especificadas)
  - Conexão SSL segura ao banco de dados
  - Resultados formatados como tabelas markdown
  - Mensagens de erro detalhadas com dicas
  - Suporte para uso de strings de conexão existentes
- Exemplo: "Execute SELECT * FROM users LIMIT 5 no banco de dados 'my-app'"

Gerenciamento de Recursos

read-resource
- Lê informações de esquema para recursos do banco de dados (tabelas, views, etc.)
- Parâmetros:
  - databaseName (string): Nome do banco de dados
  - resourceName (string): Nome do recurso (tabela/view)
- Retorna: Informações detalhadas do esquema incluindo:
  - Nomes e tipos de colunas
  - Chaves primárias e índices
  - Relacionamentos de chaves estrangeiras
  - Descrições e restrições de colunas
- Exemplo: "Mostre-me o esquema da tabela users em my-app"
list-resources
- Lista todos os recursos (tabelas, views) em um banco de dados
- Parâmetros:
  - databaseName (string): Nome do banco de dados
- Retorna: Lista de todos os recursos com seus tipos
- Exemplo: "Liste todas as tabelas no banco de dados my-app"

Gerenciamento de Tenants

list-tenants
- Lista todos os tenants em um banco de dados
- Parâmetros:
  - databaseName (string): Nome do banco de dados
- Retorna: Lista de tenants com seus IDs e metadados
- Exemplo: "Mostre todos os tenants no banco de dados my-app"
create-tenant
- Cria um novo tenant em um banco de dados
- Parâmetros:
  - databaseName (string): Nome do banco de dados
  - tenantName (string): Nome para o novo tenant
- Retorna: Detalhes do novo tenant incluindo ID
- Exemplo: "Crie um tenant chamado 'acme-corp' em my-app"
delete-tenant
- Exclui tenants no banco de dados
- Parâmetros:
  - databaseName (string): Nome do banco de dados
  - tenantName (string): Nome do tenant
- Retorna: Sucesso se o tenant for excluído
- Exemplo: "Exclua o tenant chamado 'acme-corp' em my-app"

Exemplo de Uso

Aqui estão alguns exemplos de comandos que você pode usar no 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 Resposta

Todas as ferramentas retornam respostas em um formato padronizado:

Respostas de sucesso incluem dados relevantes e mensagens de confirmação
Respostas de erro incluem mensagens de erro detalhadas e códigos de status HTTP
Resultados de consultas SQL são formatados como tabelas markdown
Todas as respostas são formatadas para fácil leitura no Claude Desktop

Tratamento de Erros

O servidor lida com vários cenários de erro:

Credenciais de API inválidas
Problemas de conectividade de rede
Nomes de banco de dados ou regiões inválidos
Parâmetros obrigatórios ausentes
Falhas em operações de banco de dados
Erros de sintaxe SQL com dicas úteis
Limitação de taxa e restrições de API

Solução de Problemas

Se o Claude disser que não pode acessar as ferramentas:
- Verifique se o caminho do servidor na configuração está correto
- Certifique-se de que o projeto foi compilado (npm run build)
- Verifique se sua chave de API e slug do workspace estão corretos
- Reinicie o Claude Desktop
Se a criação do banco de dados falhar:
- Verifique as permissões da sua chave de API
- Certifique-se de que o nome do banco de dados é único no seu workspace
- Verifique se a região é uma das opções suportadas
Se as operações de credenciais falharem:
- Verifique se o banco de dados existe e está no estado READY
- Verifique se sua chave de API tem as permissões necessárias

Desenvolvimento

Estrutura do Projeto

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

Arquivos Principais

server.ts: Implementação principal do servidor com registro de ferramentas e tratamento de transporte
tools.ts: Implementação de todas as operações de banco de dados e execução de consultas SQL
types.ts: Interfaces TypeScript para operações e respostas de banco de dados
logger.ts: Logging estruturado com rotação diária e suporte a debug
index.ts: Inicialização do servidor e configuração de ambiente
server.test.ts: Suíte de testes abrangente para todas as funcionalidades

Desenvolvimento

# 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 Desenvolvimento

Os seguintes scripts npm estão disponíveis:

npm run build: Compila TypeScript para JavaScript
npm start: Inicia o servidor em modo de produção
npm run dev: Inicia o servidor em modo de desenvolvimento com recompilação automática
npm test: Executa a suíte de testes
npm run lint: Executa ESLint para verificação de qualidade de código
npm run clean: Remove artefatos de compilação

Testes

O projeto inclui uma suíte de testes abrangente que cobre:

Registro de ferramentas e validação de esquema
Operações de gerenciamento de banco de dados
Geração de strings de conexão
Execução de consultas SQL e tratamento de erros
Formatação de respostas e casos de erro

Execute os testes com:

npm test

Logging

O servidor usa registro estruturado com os seguintes recursos:

Arquivos de log com rotação diária
Logs de depuração separados
Logs formatados em JSON com carimbos de data/hora
Saída de console para desenvolvimento
Categorias de log: info, error, debug, api, sql, startup

Licença

Licença MIT - Veja Licença para detalhes.

Nile Postgres

Documentação

Nile MCP Server

Recursos

Instalação

Instalação Manual

Outros gerenciadores de pacotes mcp

Iniciando o Servidor

Verificando se o Servidor Está em Execução

Configuração

Usando com Claude Desktop

Configuração

Usando com Cursor

Configuração

Modos do Servidor

Modo STDIO (Padrão)

Modo SSE

Exemplos de Prompts

Gerenciamento de Banco de Dados

Criando Tabelas

Consultando Dados

Gerenciamento de Esquema

Ferramentas Disponíveis

Gerenciamento de Banco de Dados

Gerenciamento de Credenciais

Gerenciamento de Regiões

Execução de Consultas SQL

Gerenciamento de Recursos

Gerenciamento de Tenants

Exemplo de Uso

Formato de Resposta

Tratamento de Erros

Solução de Problemas

Desenvolvimento

Estrutura do Projeto

Arquivos Principais

Desenvolvimento

Scripts de Desenvolvimento

Testes

Logging

Licença

Links Relacionados