Nile Mcp Server

Nile MCP Server

了解更多 ↗️

Discord 🔵 网站 🔵 问题

Nile 数据库平台的 Model Context Protocol（MCP）服务实现。此服务允许 LLM 应用通过标准化接口与 Nile 平台交互。

功能

• 数据库管理：创建、列出、获取数据库详情和删除数据库
• 凭据管理：创建和列出数据库凭据
• 区域管理：列出可用于创建数据库的区域
• SQL 查询支持：直接在 Nile 数据库上执行 SQL 查询
• MCP 协议支持：完整实现 Model Context Protocol
• 类型安全：使用 TypeScript 编写，并进行完整的类型检查
• 错误处理：全面的错误处理和易于理解的错误消息
• 测试覆盖：使用 Jest 的全面测试套件
• 环境管理：自动从 .env 文件加载环境变量
• 输入验证：使用 Zod 进行基于架构的输入验证

安装

安装稳定版本：

npm install @niledatabase/nile-mcp-server

安装最新的 alpha/preview 版本：

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 install @niledatabase/nile-mcp-server

启动服务

有多种方式可以启动服务：

1. 直接使用 Node 执行：

   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 的命令。

配置

在根目录中创建 .env 文件，并填入你的 Nile 凭据：

NILE_API_KEY=your_api_key_here
NILE_WORKSPACE_SLUG=your_workspace_slug

要创建 Nile API 密钥，请登录你的 Nile 账户，点击左上角的 Workspaces，选择你的工作区，然后在左侧菜单中前往 Security 部分。

与 Claude Desktop 搭配使用

设置

1. 如果尚未安装，请安装 Claude Desktop
2. 构建项目：

   npm run build
   

3. 打开 Claude Desktop
4. 前往 Settings > MCP Servers
5. 点击“Add Server”
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

与 Cursor 搭配使用

设置

1. 如果尚未安装，请安装 Cursor
2. 构建项目：

   npm run build
   

3. 打开 Cursor
4. 前往 Settings（⌘,）> Features > MCP Servers
5. 点击“Add New MCP Server”
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. 点击“Save”
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, '[email protected]', '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. create-database

   • 创建新的 Nile 数据库
   • 参数：
     • name（字符串）：数据库名称
     • region（字符串）：AWS_US_WEST_2（俄勒冈）或 AWS_EU_CENTRAL_1（法兰克福）
   • 返回：数据库详细信息，包括 ID、名称、区域和状态
   • 示例：“在 AWS_US_WEST_2 中创建一个名为 'my-app' 的数据库”

2. list-databases

   • 列出工作区中的所有数据库
   • 无需参数
   • 返回：数据库列表，包括其 ID、名称、区域和状态
   • 示例：“列出我的所有数据库”

3. get-database

   • 获取特定数据库的详细信息
   • 参数：
     • name（字符串）：数据库名称
   • 返回：数据库详细信息，包括 API 主机和 DB 主机
   • 示例：“获取数据库 'my-app' 的详细信息”

4. delete-database

   • 删除数据库
   • 参数：
     • name（字符串）：要删除的数据库名称
   • 返回：确认消息
   • 示例：“删除数据库 'my-app'”

凭据管理

1. list-credentials

   • 列出数据库的所有凭据
   • 参数：
     • databaseName（字符串）：数据库名称
   • 返回：凭据列表，包括 ID、用户名和创建日期
   • 示例：“列出数据库 'my-app' 的凭据”

2. create-credential

   • 为数据库创建新凭据
   • 参数：
     • databaseName（字符串）：数据库名称
   • 返回：新凭据的详细信息，包括用户名和一次性密码
   • 示例：“为数据库 'my-app' 创建新凭据”
   • 注意：密码显示时请保存，因为之后不会再次显示

区域管理

1. list-regions
   • 列出可用于创建数据库的所有区域
   • 无需参数
   • 返回：可用的 AWS 区域列表
   • 示例：“创建数据库时有哪些可用区域？”

SQL 查询执行

1. execute-sql
   • 在 Nile 数据库上执行 SQL 查询
   • 参数：
     • databaseName（string）：要查询的数据库名称
     • query（string）：要执行的 SQL 查询
     • connectionString（string，可选）：用于查询的现有连接字符串
   • 返回：格式化为 Markdown 表格的查询结果，包含列标题和行数
   • 功能：
     • 自动管理凭据（未指定时会创建新凭据）
     • 使用安全的 SSL 连接到数据库
     • 将结果格式化为 Markdown 表格
     • 提供带提示的详细错误消息
     • 支持使用现有连接字符串
   • 示例："在数据库 'my-app' 上执行 SELECT * FROM users LIMIT 5"

资源管理

1. read-resource

   • 读取数据库资源（表、视图等）的架构信息
   • 参数：
     • databaseName（string）：数据库名称
     • resourceName（string）：资源名称（表/视图）
   • 返回：详细的架构信息，包括：
     • 列名称和类型
     • 主键和索引
     • 外键关系
     • 列说明和约束
   • 示例："向我展示 my-app 中 users 表的架构"

2. list-resources

   • 列出数据库中的所有资源（表、视图）
   • 参数：
     • databaseName（string）：数据库名称
   • 返回：包含类型的所有资源列表
   • 示例："列出 my-app 数据库中的所有表"

租户管理

1. list-tenants

   • 列出数据库中的所有租户
   • 参数：
     • databaseName（string）：数据库名称
   • 返回：包含 ID 和元数据的租户列表
   • 示例："显示 my-app 数据库中的所有租户"

2. create-tenant

   • 在数据库中创建新租户
   • 参数：
     • databaseName（string）：数据库名称
     • tenantName（string）：新租户的名称
   • 返回：包含 ID 的新租户详情
   • 示例："在 my-app 中创建名为 'acme-corp' 的租户"

3. delete-tenant

   • 删除数据库中的租户
   • 参数：
     • databaseName（string）：数据库名称
     • tenantName（string）：租户名称
   • 返回：租户删除成功时返回成功信息
   • 示例："在 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:[email protected]: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 Desktop

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 许可证 - 详情请参阅 LICENSE。

相关链接

• 模型上下文协议
• Nile 数据库
• Claude 桌面版
• Cursor