尼罗河-MCP服务器

Name: 尼罗河-MCP服务器
Author: niledatabase

作者：niledatabase16 星标更新：2025-03-11

项目介绍

<p align="center"> <a href="https://thenile.dev" target="_blank"><img width="96px" src="https://gips0.baidu.com/it/u=1980770404,4265842161&fm=3081&app=3081&f=PNG?w=1536&h=1537" /></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>

这是一个用于 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/

手动安装

# 克隆仓库
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 账户，点击左上角的工作区，选择你的工作区，并导航到左侧菜单的安全部分。

使用 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 工作区 slug
  - /absolute/path/to 为实际的项目路径
点击“保存”
你应该看到绿色指示器显示 MCP 服务器已连接
重启 Cursor 以使更改生效

服务器模式

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

STDIO 模式（默认）

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

SSE 模式

Server-Sent Events (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 的所有产品

架构管理

显示 my_app 数据库中 users 表的架构

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

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

可用工具

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

数据库管理

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

凭证管理

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

区域管理

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

SQL 查询执行

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

资源管理

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

租户管理

list-tenants
- 列出数据库中的所有租户
- 参数：
  - databaseName (字符串)：数据库名称
- 返回：包含 ID 和元数据的所有租户列表
- 示例："显示 my-app 数据库中的所有租户"
create-tenant
- 在数据库中创建新的租户
- 参数：
  - databaseName (字符串)：数据库名称
  - tenantName (字符串)：新租户的名称
- 返回：新租户详情，包括 ID
- 示例："在 my-app 中创建一个名为 'acme-corp' 的租户"
delete-tenant
- 删除数据库中的租户
- 参数：
  - databaseName (字符串)：数据库名称
  - tenantName (字符串)：租户名称
- 返回：如果租户被删除则成功
- 示例："删除 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 限制

故障排除

如果 Claude 说无法访问工具：
- 检查配置中的服务器路径是否正确
- 确保项目已构建 (npm run build)
- 核实你的 API 密钥和工作区 slug 是否正确
- 重新启动 Claude Desktop
如果数据库创建失败：
- 检查你的 API 密钥权限
- 确保数据库名称在你的工作区中是唯一的
- 核实区域是支持的选项之一
如果凭证操作失败：
- 核实数据库存在且处于就绪状态
- 检查你的 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：移除构建产物

测试

该项目包含一个全面