nile-mcp

针对 Nile 数据库平台的模型上下文协议 (MCP) 服务器实现。该服务器允许 LLM 应用程序通过标准化接口与 Nile 平台交互。

特征

• 数据库管理：创建、列出、获取详细信息和删除数据库

• 凭证管理：创建并列出数据库凭证

• 区域管理：列出可用于创建数据库的区域

• SQL 查询支持：直接在 Nile 数据库上执行 SQL 查询

• MCP 协议支持：全面实现模型上下文协议

• 类型安全：用 TypeScript 编写，并进行全面类型检查

• 错误处理：全面的错误处理和用户友好的错误消息

• 测试覆盖率：使用 Jest 的综合测试套件

• 环境管理：从.env文件自动加载环境变量

• 输入验证：使用 Zod 进行基于模式的输入验证

Related MCP server: mcp-db-server

安装

安装稳定版本：

npm install @niledatabase/nile-mcp-server

对于最新的 alpha/预览版本：

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

这会将 @niledatabase/nile-mcp-server 安装到你的 node_modules 文件夹中。例如：node_modules/@niledatabase/nile-mcp-server/dist/

手动安装

# 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

其他 mcp 包管理器

1. npx @michaellatman/mcp-get@latest 安装 @niledatabase/nile-mcp-server

启动服务器

有几种方法可以启动服务器：

1. 直接节点执行：

   node dist/index.js

2. 开发模式（自动重建）：

   npm run dev

服务器将启动并监听 MCP 协议消息。您应该看到启动日志，其中显示以下内容：

• 已加载环境变量

• 服务器实例已创建

• 工具已初始化

• 已建立传输连接

要停止服务器，请按Ctrl+C 。

验证服务器正在运行

当服务器成功启动时，您应该会看到类似以下内容的日志：

[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

如果您看到这些日志，则表示服务器已准备好接受来自 Claude Desktop 的命令。

配置

使用您的 Nile 凭证在根目录中创建一个.env文件：

NILE_API_KEY=your_api_key_here
NILE_WORKSPACE_SLUG=your_workspace_slug

要创建 Nile API 密钥，请登录您的Nile 帐户，单击左上角的工作区，选择您的工作区，然后导航到左侧菜单中的安全部分。

与 Claude Desktop 一起使用

设置

1. 如果你还没有安装Claude Desktop

2. 构建项目：

   npm run build

3. 打开 Claude 桌面

4. 前往“设置”>“MCP 服务器”

5. 点击“添加服务器”

6. 添加以下配置：

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

代替：

• /path/to/your/nile-mcp-server为您的项目目录的绝对路径

• your_api_key_here是您的 Nile API 密钥

• your_workspace_slug与您的 Nile 工作区 slug

与游标一起使用

设置

1. 如果尚未安装Cursor ，请安装

2. 构建项目：

   npm run build

3. 打开游标

4. 前往“设置”（⌘,）>“功能”>“MCP 服务器”

5. 点击“添加新的 MCP 服务器”

6. 配置服务器：

   • 名称： nile-database （或您喜欢的任何名称）

   • 命令：

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

     代替：

     • your_key是您的 Nile API 密钥

     • your_workspace与您的 Nile 工作区 slug

     • /absolute/path/to为项目的实际路径

7. 点击“保存”

8. 您应该会看到一个绿色指示灯，表明 MCP 服务器已连接

9. 重新启动 Cursor 以使更改生效

服务器模式

该服务器支持两种运行模式：

STDIO模式（默认）

默认模式使用标准输入/输出进行通信，使其与 Claude Desktop 和 Cursor 集成兼容。

SSE模式

服务器发送事件 (SSE) 模式支持通过 HTTP 进行实时事件驱动的通信。

要启用 SSE 模式：

1. 在.env文件中设置MCP_SERVER_MODE=sse

2. 服务器将启动一个HTTP服务器（默认端口3000）

3. 连接到 SSE 端点： http://localhost:3000/sse

4. 发送命令至： http://localhost:3000/messages

使用 curl 的 SSE 示例：

# 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": {}
  }'

示例提示

在 Cursor 中设置好 MCP 服务器后，您就可以使用自然语言与 Nile 数据库进行交互。以下是一些示例提示：

数据库管理

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"

创建表

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)

查询数据

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

模式管理

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

可用工具

该服务器提供了以下与 Nile 数据库交互的工具：

数据库管理

1. 创建数据库

   • 创建一个新的尼罗河数据库

   • 参数：

     • name （字符串）：数据库的名称

     • region （字符串）： AWS_US_WEST_2 （俄勒冈州）或AWS_EU_CENTRAL_1 （法兰克福）

   • 返回：数据库详细信息，包括 ID、名称、区域和状态

   • 示例：“在 AWS_US_WEST_2 中创建名为‘my-app’的数据库”

2. 列表数据库

   • 列出工作区中的所有数据库

   • 无需参数

   • 返回：数据库列表及其 ID、名称、区域和状态

   • 例如：“列出我的所有数据库”

3. 获取数据库

   • 获取特定数据库的详细信息

   • 参数：

     • name （字符串）：数据库的名称

   • 返回：详细的数据库信息，包括 API 主机和 DB 主机

   • 示例：“获取数据库‘my-app’的详细信息”

4. 删除数据库

   • 删除数据库

   • 参数：

     • name （字符串）：要删除的数据库的名称

   • 返回：确认消息

   • 例如：“删除数据库‘my-app’”

凭证管理

1. 列出凭证

   • 列出数据库的所有凭据

   • 参数：

     • databaseName （字符串）：数据库的名称

   • 返回：包含 ID、用户名和创建日期的凭证列表

   • 示例：“列出数据库‘my-app’的凭据”

2. 创建凭证

   • 为数据库创建新的凭证

   • 参数：

     • databaseName （字符串）：数据库的名称

   • 返回：新的凭证详细信息，包括用户名和一次性密码

   • 示例：“为数据库‘my-app’创建新的凭据”

   • 注意：显示密码时请保存，因为不会再次显示

区域管理

1. 列出区域

   • 列出所有可用于创建数据库的区域

   • 无需参数

   • 返回：可用 AWS 区域列表

   • 例如：“哪些区域可用于创建数据库？”

SQL查询执行

1. 执行sql

   • 在 Nile 数据库上执行 SQL 查询

   • 参数：

     • databaseName （字符串）：要查询的数据库的名称

     • query （字符串）：要执行的 SQL 查询

     • connectionString （字符串，可选）：用于查询的预先存在的连接字符串

   • 返回：查询结果格式化为带有列标题和行数的 markdown 表

   • 特征：

     • 自动凭证管理（如果未指定则创建新的）

     • 安全的 SSL 数据库连接

     • 结果格式化为 Markdown 表

     • 带有提示的详细错误消息

     • 支持使用现有的连接字符串

   • 示例：“在数据库‘my-app’上执行 SELECT * FROM users LIMIT 5”

资源管理

1. 读取资源

   • 读取数据库资源（表、视图等）的架构信息

   • 参数：

     • databaseName （字符串）：数据库的名称

     • resourceName （字符串）：资源的名称（表/视图）

   • 返回：详细的架构信息，包括：

     • 列名和类型

     • 主键和索引

     • 外键关系

     • 列描述和约束

   • 例如：“显示我的应用程序中用户表的架构”

2. 列表资源

   • 列出数据库中的所有资源（表、视图）

   • 参数：

     • databaseName （字符串）：数据库的名称

   • 返回：所有资源及其类型的列表

   • 例如：“列出 my-app 数据库中的所有表”

租户管理

1. 列出租户

   • 列出数据库中的所有租户

   • 参数：

     • databaseName （字符串）：数据库的名称

   • 返回：租户列表及其 ID 和元数据

   • 示例：“显示 my-app 数据库中的所有租户”

2. 创建租户

   • 在数据库中创建新租户

   • 参数：

     • databaseName （字符串）：数据库的名称

     • tenantName （字符串）：新租户的名称

   • 返回：新租户详细信息（包括身份证）

   • 示例：“在 my-app 中创建名为‘acme-corp’的租户”

3. 删除租户

   • 删除数据库中的租户

   • 参数：

     • databaseName （字符串）：数据库的名称

     • tenantName （字符串）：租户名称

   • 返回：如果租户被删除则成功

   • 示例：“删除 my-app 中名为‘acme-corp’的租户”

示例用法

以下是您可以在 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

响应格式

所有工具都以标准化格式返回响应：

• 成功响应包括相关数据和确认消息

• 错误响应包括详细的错误消息和 HTTP 状态代码

• SQL 查询结果被格式化为 markdown 表

• 所有回复均已格式化，方便在 Claude Desktop 中阅读

错误处理

服务器处理各种错误情况：

• API 凭证无效

• 网络连接问题

• 无效的数据库名称或区域

• 缺少必需参数

• 数据库操作失败

• SQL 语法错误及有用提示

• 速率限制和 API 限制

故障排除

1. 如果 Claude 说无法访问工具：

   • 检查配置中的服务器路径是否正确

   • 确保项目已构建（ npm run build ）

   • 验证您的 API 密钥和工作区 slug 是否正确

   • 重启Claude桌面

2. 如果数据库创建失败：

   • 检查您的 API 密钥权限

   • 确保数据库名称在您的工作区中是唯一的

   • 验证区域是否是受支持的选项之一

3. 如果凭证操作失败：

   • 验证数据库是否存在并且处于 READY 状态

   • 检查您的 API 密钥是否具有必要的权限

发展

项目结构

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

关键文件

• server.ts ：具有工具注册和传输处理的主服务器实现

• tools.ts ：实现所有数据库操作和 SQL 查询的执行

• types.ts ：用于数据库操作和响应的 TypeScript 接口

• logger.ts ：具有每日轮换和调试支持的结构化日志记录

• index.ts ：服务器启动和环境配置

• server.test.ts ：所有功能的综合测试套件

发展

# 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

开发脚本

以下 npm 脚本可用：

• npm run build ：将 TypeScript 编译为 JavaScript

• npm start ：以生产模式启动服务器

• npm run dev ：以自动重建的方式启动开发模式的服务器

• npm test ：运行测试套件

• npm run lint ：运行 ESLint 进行代码质量检查

• npm run clean ：删除构建工件

测试

该项目包括一个全面的测试套件，涵盖：

• 工具注册和模式验证

• 数据库管理操作

• 连接字符串生成

• SQL查询执行和错误处理

• 响应格式和错误情况

使用以下命令运行测试：

npm test

日志记录

服务器使用具有以下特点的结构化日志记录：

• 每日轮换日志文件

• 单独的调试日志

• 带有时间戳的 JSON 格式日志

• 用于开发的控制台输出

• 日志类别：信息、错误、调试、api、sql、启动

执照

MIT 许可证 - 详情请参阅许可证。

相关链接

• 模型上下文协议

• 尼罗河数据库

• 克劳德桌面

• 光标