niledatabase/nile-mcp-server

Nile MCP Server

Nile 数据库平台的模型上下文协议（MCP）服务器实现。该服务器允许大型语言模型（LLM）应用程序通过标准接口与 Nile 平台进行交互。

功能

数据库管理：创建、列出、获取详情和删除数据库
凭证管理：创建和列出数据库凭证
区域管理：列出可用于创建数据库的区域
SQL 查询支持：直接在 Nile 数据库上执行 SQL 查询
MCP 协议支持：模型上下文协议的完整实现
类型安全：使用 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/

手动安装

# 克隆仓库
git clone https://github.com/yourusername/nile-mcp-server.git
cd nile-mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

其他 mcp 包管理器

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

启动服务器

启动服务器有几种方法：

直接 Node 执行：
```
node dist/index.js
```
开发模式（带自动重建）：
```
npm run dev
```

服务器将启动并监听 MCP 协议消息。您应该看到启动日志指示：

环境变量加载
服务器实例创建
工具初始化
传输连接建立

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

验证服务器是否正在运行

服务器成功启动后，您应该看到类似以下日志：

[info] 正在启动 Nile MCP 服务器...
[info] 正在加载环境变量...
[info] 环境变量加载成功
[info] 正在创建服务器实例...
[info] 工具初始化成功
[info] 正在设置 stdio 传输...
[info] 服务器启动成功

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

配置

在根目录创建一个 .env 文件，包含您的 Nile 凭证：

NILE_API_KEY=your_api_key_here
NILE_WORKSPACE_SLUG=your_workspace_slug

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

与 Claude Desktop 一起使用

设置

如果尚未安装，请安装 Claude Desktop
构建项目：
```
npm run build
```
打开 Claude Desktop
转到设置 > MCP 服务器
点击“添加服务器”
添加以下配置：

{
  "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 一起使用

设置

如果尚未安装，请安装 Cursor
构建项目：
```
npm run build
```
打开 Cursor
转到设置 (⌘,) > 功能 > MCP 服务器
点击“添加新的 MCP 服务器”
配置服务器：
- 名称：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 工位
  - /absolute/path/to 为您的项目实际路径
点击“保存”
您应该看到绿色指示器显示 MCP 服务器已连接
重新启动 Cursor 以使更改生效

服务器模式

服务器支持两种操作模式：

STDIO 模式（默认）

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

SSE 模式

服务器端事件（SSE）模式启用实时、事件驱动的 HTTP 通信。

要启用 SSE 模式：

在您的 .env 文件中设置 MCP_SERVER_MODE=sse
服务器将启动一个 HTTP 服务器（默认端口 3000）
连接到 SSE 端点：http://localhost:3000/sse
向 http://localhost:3000/messages 发送命令

使用 curl 的 SSE 用法示例：

# 在终端 1 - 监听事件
curl -N http://localhost:3000/sse

# 在终端 2 - 发送命令
curl -X POST http://localhost:3000/messages \
  -H "Content-Type: application/json" \
  -d '{
    "type": "function",
    "name": "list-databases",
    "parameters": {}
  }'

示例提示

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

数据库管理

在 AWS_US_WEST_2 区域创建一个名为 "my_app" 的新数据库

列出我的所有数据库

获取数据库 "my_app" 的详情

删除数据库 "test_db"

创建表

在 my_app 数据库中创建一个 users 表，包含以下列：
- tenant_id (UUID, 引用 tenants)
- id (INTEGER)
- email (VARCHAR, 每个租户唯一)
- name (VARCHAR)
- created_at (TIMESTAMP)

在 my_app 数据库中创建一个 products 表，包含以下列：
- tenant_id (UUID, 引用 tenants)
- id (INTEGER)
- name (VARCHAR)
- price (DECIMAL)
- description (TEXT)
- created_at (TIMESTAMP)

查询数据

在 my_app 数据库上执行此查询：SELECT * FROM users WHERE tenant_id = 'your-tenant-id' LIMIT 5

在 my_app 上运行此查询：INSERT INTO users (tenant_id, id, email, name) 
VALUES ('tenant-id', 1, 'user@example.com', 'John Doe')

显示 my_app 数据库中价格 > 100 的所有 products

模式管理

显示 my_app 数据库中 users 表的模式

向 my_app 数据库中的 users 表添加一个名为 'status' 的新列

在 my_app 数据库中为 users 表的 email 列创建索引

可用工具

服务器提供以下工具用于与 Nile 数据库进行交互：

数据库管理

create-database
- 创建新的 Nile 数据库
- 参数：
  - name (string)：数据库名称
  - region (string)：AWS_US_WEST_2（俄勒冈）或 AWS_EU_CENTRAL_1（法兰克福）
- 返回：数据库详情，包括 ID、名称、区域和状态
- 示例："创建一个名为 'my-app' 的数据库，区域为 AWS_US_WEST_2"
list-databases
- 列出您工作区中的所有数据库
- 无需参数
- 返回：数据库列表及其 ID、名称、区域和状态
- 示例："列出我的所有数据库"
get-database
- 获取特定数据库的详细信息
- 参数：
  - name (string)：数据库名称
- 返回：详细的数据库信息，包括 API 主机和 DB 主机
- 示例："获取数据库 'my-app' 的详情"
delete-database
- 删除数据库
- 参数：
  - name (string)：要删除的数据库名称
- 返回：确认消息
- 示例："删除数据库 'my-app'"

凭证管理

list-credentials
- 列出数据库的所有凭证
- 参数：
  - databaseName (string)：数据库名称
- 返回：凭证列表，包括 ID、用户名和创建日期
- 示例："列出数据库 'my-app' 的凭证"
create-credential
- 为数据库创建新凭证
- 参数：
  - databaseName (string)：数据库名称
- 返回：新凭证详情，包括用户名和一次性密码
- 示例："为数据库 'my-app' 创建新凭证"
- 注意：当密码显示时请保存，因为它将不再显示

区域管理

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

SQL 查询执行

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

资源管理

read-resource
- 读取数据库资源（表、视图等）的模式信息
- 参数：
  - databaseName (string)：数据库名称
  - resourceName (string)：资源名称（表/视图）
- 返回：详细模式信息，包括：
  - 列名和类型
  - 主键和索引
  - 外键关系
  - 列描述和约束
- 示例："显示 my-app 中 users 表的模式"
list-resources
- 列出数据库中的所有资源（表、视图）
- 参数：
  - databaseName (string)：数据库名称
- 返回：所有资源列表及其类型
- 示例："列出 my-app 数据库中的所有表"

租户管理

list-tenants
- 列出数据库中的所有租户
- 参数：
  - databaseName (string)：数据库名称
- 返回：租户列表及其 ID 和元数据
- 示例："显示 my-app 数据库中的所有租户"
create-tenant
- 在数据库中创建新租户
- 参数：
  - databaseName (string)：数据库名称
  - tenantName (string)：新租户的名称
- 返回：新租户详情，包括 ID
- 示例："在 my-app 中创建一个名为 'acme-corp' 的租户"
delete-tenant
- 删除数据库中的租户
- 参数：
  - databaseName (string)：数据库名称
  - tenantName (string)：租户名称
- 返回：如果租户被删除则显示成功
- 示例："删除 my-app 中名为 'acme-corp' 的租户"

示例用法

以下是在 Claude Desktop 中可以使用的示例命令：

# 数据库管理
请创建一个名为 "my-app" 的新数据库，区域为 AWS_US_WEST_2。
你能列出我的所有数据库吗？
获取数据库 "my-app" 的详情。
删除名为 "test-db" 的数据库。

# 连接字符串管理
获取数据库 "my-app" 的连接字符串。
# 连接字符串格式：postgres://<user>:<password>@<region>.db.thenile.dev:5432/<database>
# 示例：postgres://cred-123:password@us-west-2.db.thenile.dev:5432/my-app

# SQL 查询
在数据库 "my-app" 上执行 SELECT * FROM users LIMIT 5
在 my-app 数据库上运行此查询：SELECT COUNT(*) FROM orders WHERE status = 'completed'
使用连接字符串 "postgres://user:pass@host:5432/db"，在 my-app 上执行此查询：SELECT * FROM products WHERE price > 100

响应格式

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

成功响应包含相关数据和确认消息
错误响应包含详细错误消息和 HTTP 状态码
SQL 查询结果格式化为 Markdown 表格
所有响应都格式化为易于在 Claude Desktop 中阅读的格式

错误处理

服务器处理各种错误场景：

无效的 API 凭证
网络连接问题
无效的数据库名称或区域
缺少必需参数
数据库操作失败
SQL 语法错误（带提示）
速率限制和 API 限制

故障排除

如果 Claude 表示无法访问工具：
- 检查配置中的服务器路径是否正确
- 确保项目已构建 (npm run build)
- 验证您的 API 密钥和工位 slug 是否正确
- 重新启动 Claude Desktop
如果数据库创建失败：
- 检查您的 API 密钥权限
- 确保数据库名称在工作区中唯一
- 验证区域是否为支持选项之一
如果凭证操作失败：
- 验证数据库是否存在且状态为 READY
- 检查您的 API 密钥是否具有必要的权限

开发

项目结构

nile-mcp-server/
├── src/
│   ├── server.ts      # MCP 服务器实现
│   ├── tools.ts       # 工具实现
│   ├── types.ts       # 类型定义
│   ├── logger.ts      # 日志工具
│   ├── index.ts       # 入口点
│   └── __tests__/     # 测试文件
│       └── server.test.ts
├── dist/             # 编译后的 JavaScript
├── logs/            # 日志文件目录
├── .env             # 环境配置
├── .gitignore       # Git 忽略文件
├── package.json     # 项目依赖
└── tsconfig.json    # TypeScript 配置

关键文件

server.ts：主服务器实现，包含工具注册和传输处理
tools.ts：数据库操作和 SQL 查询执行的实现
types.ts：数据库操作和响应的 TypeScript 接口
logger.ts：结构化日志记录，支持每日轮换和调试
index.ts：服务器启动和环境配置
server.test.ts：所有功能的全面测试套件

开发

# 安装依赖
npm install

# 构建项目
npm run build

# 以生产模式启动服务器
node dist/index.js

# 使用 npm 脚本启动服务器
npm start

# 以开发模式启动服务器（带自动重建）
npm run dev

# 运行测试
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 格式日志
开发环境的控制台输出
日志类别：info、error、debug、api、sql、startup

许可证

MIT 许可证 - 详细内容请参阅 LICENSE

niledatabase/nile-mcp-server

星标增长

证据时间轴

Nile MCP Server

功能

安装

手动安装

其他 mcp 包管理器

启动服务器

验证服务器是否正在运行

配置

与 Claude Desktop 一起使用

设置

与 Cursor 一起使用

设置

服务器模式

STDIO 模式（默认）

SSE 模式

示例提示

数据库管理

创建表

查询数据

模式管理

可用工具

数据库管理

凭证管理

区域管理

SQL 查询执行

资源管理

租户管理

示例用法

响应格式

错误处理

故障排除

开发

项目结构

关键文件

开发

开发脚本

测试

日志记录

许可证

相关链接