nile-mcp

官方

<p align="center">
 <a href="https://thenile.dev" target="_blank"><img width="96px" src="https://www.thenile.dev/about-logo.png" /></a>
 <h2 align="center">Nile MCP 服务器
  <br/>
  <img src="https://img.shields.io/npm/v/@niledatabase/server"/>
 </h2>
 <p align="center">
  <a href="https://thenile.dev/docs/ai-embeddings/nile-mcp-server"><strong>了解更多 ↗️</strong></a>
  <br />
  <br />
  <a href="https://discord.gg/akRKRPKA">Discord</a>
  🔵
  <a href="https://thenile.dev">网站</a>
  🔵 
  <a href="https://github.com/orgs/niledatabase/discussions">问题</a>
 </p>
</p>

[![smithery badge](https://smithery.ai/badge/@niledatabase/nile-mcp-server)](https://smithery.ai/server/@niledatabase/nile-mcp-server)

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

## 功能

- **数据库管理**：创建、列出、获取详细信息和删除数据库
- **凭证管理**：创建和列出数据库凭证
- **区域管理**：列出可用于创建数据库的可用区域
- **SQL 查询支持**：直接在 Nile 数据库上执行 SQL 查询
- **MCP 协议支持**：模型上下文协议的完整实现
- **类型安全**：使用 TypeScript 编写，具有完整的类型检查
- **错误处理**：全面的错误处理和用户友好的错误消息
- **测试覆盖率**：使用 Jest 的全面测试套件
- **环境管理**：从 .env 文件自动加载环境变量
- **输入验证**：使用 Zod 的基于模式的输入验证

## 安装

安装稳定版本：
```bash
npm install @niledatabase/nile-mcp-server

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

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

这将在您的 node_modules 文件夹中安装 @niledatabase/nile-mcp-server。例如：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 包管理器

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] 正在启动 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 帐户，单击左上角的“工作区”，选择您的工作区，然后导航到左侧菜单中的“安全”部分。

与 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 模式

服务器发送事件 (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 用法示例：

# 在终端 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 的产品

模式管理

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

在 my_app 数据库中向 users 表添加一个新列“status”

在 my_app 数据库中在 users 表的 email 列上创建一个索引

可用工具

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

数据库管理

1. create-database

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

2. list-databases

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

3. get-database

   • 获取有关特定数据库的详细信息
   • 参数：
     • name (string)：数据库的名称
   • 返回：详细的数据库信息，包括 API 主机和 DB 主机
   • 示例：“获取数据库 'my-app' 的详细信息”

4. delete-database

   • 删除数据库
   • 参数：
     • name (string)：要删除的数据库的名称
   • 返回：确认消息
   • 示例：“删除数据库 'my-app'”

凭证管理

1. list-credentials

   • 列出数据库的所有凭据
   • 参数：
     • databaseName (string)：数据库的名称
   • 返回：凭据列表，其中包含 ID、用户名和创建日期
   • 示例：“列出数据库 'my-app' 的凭据”

2. create-credential

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

区域管理

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

SQL 查询执行

1. execute-sql
   • 在 Nile 数据库上执行 SQL 查询
   • 参数：
     • databaseName (string)：要查询的数据库的名称
     • query (string)：要执行的 SQL 查询
     • connectionString (string, optional)：用于查询的预先存在的连接字符串
   • 返回：查询结果，格式化为带有列标题和行数的 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 中使用的示例命令：

# 数据库管理
请在 AWS_US_WEST_2 区域中创建一个名为“my-app”的新数据库。
你能列出我的所有数据库吗？
获取数据库“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 限制

故障排除

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

   • 检查配置中的服务器路径是否正确
   • 确保项目已构建 (npm run build)
   • 验证您的 API 密钥和工作区 slug 是否正确
   • 重新启动 Claude Desktop

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

   • 检查您的 API 密钥权限
   • 确保数据库名称在您的工作区中是唯一的
   • 验证该区域是否为受支持的选项之一

3. 如果凭据操作失败：

   • 验证数据库是否存在并且处于 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。

相关链接

• 模型上下文协议
• Nile 数据库
• Claude Desktop
• Cursor