BlazeSQL MCP Server

BlazeSQL MCP 服务器

该项目实现了一个模型上下文协议 (MCP) 服务器，作为 BlazeSQL 自然语言查询 API 的代理。它允许兼容 MCP 的客户端（例如 Cursor、附带工具的 Claude 3、MCP Inspector 等）使用自然语言与 BlazeSQL 进行交互。

特征

• 将 BlazeSQL 自然语言查询 API 作为名为blazesql_query的 MCP 工具公开。
• 通过环境变量安全地处理 API 密钥认证。
• 使用标准 MCP stdio 传输与客户端通信。

工作流程图

这张图展示了客户端使用blazesql_query工具时的交互顺序：

先决条件

• Node.js （推荐 LTS 版本）
• 纱线（经典或浆果）
• 具有 API 密钥的 BlazeSQL 帐户（API 需要 Team Advanced 订阅）。
• 您的 BlazeSQL 帐户中至少配置了一个数据库连接。
• BlazeSQL 自然语言查询 API 文档： https://help.blazesql.com/en/article/natural-language-query-api-1fgx4au/

设置

1. 克隆存储库：
   git clone <repository-url> cd blaze-sql-mcp-server
2. 安装依赖项：
   yarn install
3. 配置环境变量：
   • 复制示例环境文件：
     cp .env.sample .env
   • 编辑.env文件：
     # .env BLAZE_API_KEY=YOUR_BLAZESQL_API_KEY_HERE
     将YOUR_BLAZESQL_API_KEY_HERE替换为从 BlazeSQL 帐户设置中获取的实际 API 密钥。

运行服务器

1. **构建服务器：**将 TypeScript 代码编译为 JavaScript：
   yarn build
2. **运行服务器：**执行编译后的代码：
   node build/index.js
   服务器将启动并将消息记录到stderr （您可能会看到“API 密钥已成功加载……”等信息）。现在，服务器正在通过标准输入/输出 (stdio) 监听 MCP 客户端连接。

连接 MCP 客户端

该服务器使用stdio传输机制。

使用 MCP 检查器（推荐用于测试）

1. 确保服务器尚未单独运行。
2. 运行检查器，告诉它启动你的服务器：
   npx @modelcontextprotocol/inspector node build/index.js
3. Inspector UI 将启动并自动连接到您的服务器。
4. 导航到“工具”选项卡以与blazesql_query工具进行交互。

使用集成客户端（Cursor、Claude 3 等）

1. 在终端中启动服务器：
   node build/index.js
2. **配置客户端：**在您的 MCP 客户端设置中，您需要添加自定义服务器配置。
   • **传输：**选择stdio 。
   • 命令：指定用于运行服务器的具体命令。您需要提供 node 的绝对路径以及build/index.js文件的绝对路径。
     • 示例（macOS/Linux - 根据需要调整路径）： /usr/local/bin/node /Users/your_username/path/to/blaze-sql-mcp-server/build/index.js
     • 您可以使用终端中的which node找到节点的路径。
     • 您可以在项目目录中使用pwd找到项目的路径。
   • 保存配置。
3. 客户端现在应该能够连接到您本地运行的服务器并列出/使用其工具。

使用blazesql_query工具

一旦连接，客户端就可以调用blazesql_query工具。

• 工具名称： blazesql_query
• 参数：
  • db_id （字符串，必需）：BlazeSQL 帐户中目标数据库连接的 ID。您可以在 BlazeSQL Web 应用程序管理数据库连接时找到此 ID。
  • natural_language_request （字符串，必需）：您想要执行的查询，用简单的英语编写（例如，“显示用户总数”）。
• 示例调用（使用mcp test语法进行说明）：
  call-tool blazesql_query --db_id "db_your_actual_db_id" --natural_language_request "What were the total sales last month?"
• **输出：**如果成功，该工具将返回：
  • 包含来自 BlazeSQL 代理的自然语言响应的text块。
  • 包含由 BlazeSQL 生成和执行的 SQL 查询的code块（语言sql ）。
  • 包含查询实际数据的json块。如果查询失败，则返回 MCP 错误消息。