BlazeSQL MCP Server

BlazeSQL MCP 服务器

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

特征

• 使用 MCP SDK 中的现代McpServer帮助类构建。
• 将 BlazeSQL 自然语言查询 API 作为名为blazesql_query的 MCP 工具公开。
• 使用zod对工具输入参数进行稳健验证。
• 通过环境变量安全地处理 API 密钥认证。
• 使用标准 MCP stdio 传输与客户端通信。

工作流程图

该图显示了客户端使用blazesql_query工具时的交互顺序（注意：内部服务器逻辑现在使用McpServer ，与图中所示的低级处理程序相比，它简化了工具注册）：

先决条件

• 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
   这将安装所有必要的依赖项，包括@modelcontextprotocol/sdk 、 dotenv和zod 。
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 （字符串，必需）：您要执行的查询，以简单的英语编写（例如，“显示用户总数”）。 （使用zod验证输入）
• 示例调用（使用mcp test语法进行说明）：
  call-tool blazesql_query --db_id "db_your_actual_db_id" --natural_language_request "What were the total sales last month?"
• **输出：**如果成功，该工具将返回包含以下内容的单个text内容块：
  • BlazeSQL 代理的自然语言响应。
  • Markdown 代码围栏内生成的 SQL 查询 ( sql ... )。
  • 数据结果在 Markdown 代码围栏 ( json ... ) 内格式化为 JSON。

  text块内的示例结构：

  **Agent Response:** The total sales last month were $12345.67. **Generated SQL:** ```sql SELECT sum(sales_amount) FROM sales WHERE sale_date >= date('now', '-1 month');

  数据结果（JSON）：

  [ { "sum(sales_amount)": 12345.67 } ]
  If unsuccessful, it returns a `text` content block containing the error message from the BlazeSQL API and marks the response as an error (`isError: true`).