Nile MCP Server工具

这是为 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/预览版本：

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 账户，点击左上角的工作区，选择你的工作区，然后导航到左侧菜单中的安全部分。

与 Claude Desktop 一起使用

设置

1. 如果还没有安装，请安装Claude Desktop
2. 构建项目：

   npm run build
   

3. 打开Claude Desktop
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

使用Cursor

设置

1. 如果还没有安装，请安装Cursor
2. 构建项目：

   npm run build
   

3. 打开Cursor
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 模式

Server-Sent Events (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. 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 (字符串): 要查询的数据库名称
     • query (字符串): 要执行的SQL查询
     • connectionString (字符串, 可选): 用于查询的现有连接字符串
   • 返回: 查询结果以markdown表格格式返回，包括列标题和行数
   • 特性：
     • 自动凭据管理（如果未指定则创建新凭据）
     • 与数据库的安全SSL连接
     • 结果以markdown表格格式呈现
     • 带有提示的详细错误消息
     • 支持使用现有的连接字符串
   • 示例: "在 'my-app' 数据库上执行 SELECT * FROM users LIMIT 5"

资源管理

1. read-resource

   • 读取数据库资源（表、视图等）的模式信息
   • 参数：
     • databaseName (字符串): 数据库名称
     • resourceName (字符串): 资源名称（表/视图）
   • 返回: 详细的模式信息，包括：
     • 列名和类型
     • 主键和索引
     • 外键关系
     • 列描述和约束
   • 示例: "显示 my-app 中 users 表的模式"

2. list-resources

   • 列出数据库中的所有资源（表、视图）
   • 参数：
     • databaseName (字符串): 数据库名称
   • 返回: 所有资源及其类型的列表
   • 示例: "列出 my-app 数据库中的所有表"

租户管理

1. list-tenants

   • 列出数据库中的所有租户
   • 参数：
     • databaseName (字符串): 数据库名称
   • 返回: 包含租户 ID 和元数据的租户列表
   • 示例: "显示 my-app 数据库中的所有租户"

2. create-tenant

   • 在数据库中创建一个新的租户
   • 参数：
     • databaseName (字符串): 数据库名称
     • tenantName (字符串): 新租户的名称
   • 返回: 包含 ID 的新租户详细信息
   • 示例: "在 my-app 中创建名为 'acme-corp' 的租户"

3. delete-tenant

   • 删除数据库中的租户
   • 参数：
     • 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 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