MCP-сервер BlazeSQL

Этот проект реализует сервер Model Context Protocol (MCP) с использованием @modelcontextprotocol/sdk , который действует как прокси для API BlazeSQL Natural Language Query. Он позволяет MCP-совместимым клиентам (например, Cursor, Claude 3 с использованием инструмента, MCP Inspector и т. д.) взаимодействовать с BlazeSQL с использованием естественного языка.

Функции

• Создан с использованием современного вспомогательного класса McpServer из MCP SDK.

• Предоставляет API запросов на естественном языке BlazeSQL как инструмент MCP с именем blazesql_query .

• Использует zod для надежной проверки входных параметров инструмента.

• Обеспечивает безопасную аутентификацию API-ключа с помощью переменных среды.

• Взаимодействует с клиентами, используя стандартный транспорт MCP stdio.

Related MCP server: MCP MySQL Server

Диаграмма рабочего процесса

На этой диаграмме показана последовательность взаимодействий, когда клиент использует инструмент blazesql_query (Примечание: внутренняя логика сервера теперь использует McpServer , что упрощает регистрацию инструмента по сравнению с низкоуровневыми обработчиками, показанными на диаграмме):

sequenceDiagram
    participant Client as MCP Client (e.g., Cursor)
    participant Server as BlazeSQL MCP Server (index.ts)
    participant Env as Environment (.env)
    participant BlazeAPI as BlazeSQL API

    Client->>Server: ListTools Request (via stdio)
    Server-->>Client: ListTools Response (tools: [blazesql_query]) (via stdio)

    Client->>Server: CallTool Request (blazesql_query, db_id, nl_request) (via stdio)
    Server->>Env: Read BLAZE_API_KEY
    Env-->>Server: BLAZE_API_KEY
    Server->>BlazeAPI: POST /natural_language_query_api (apiKey, db_id, nl_request)
    BlazeAPI->>BlazeAPI: Process Query (NL->SQL, Execute)
    BlazeAPI-->>Server: HTTPS Response (JSON: agent_response, query, data_result OR error)
    Server->>Server: Format Response (Agent response, SQL, and data into single text block)
    Server-->>Client: CallTool Response (content: [{type: text, text: formattedMarkdown}]) (via stdio)

Предпосылки

• Node.js (рекомендуется версия LTS)

• Пряжа (классическая или ягодная)

• Учетная запись BlazeSQL с ключом API (для API требуется подписка Team Advanced).

• В вашей учетной записи BlazeSQL настроено как минимум одно подключение к базе данных.

• Документация API запросов на естественном языке BlazeSQL: 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 на ваш фактический ключ API, полученный из настроек вашей учетной записи BlazeSQL.

Запуск сервера

1. Сборка сервера: Скомпилируйте код TypeScript в JavaScript:

   yarn build

2. Запустите сервер: Выполните скомпилированный код:

   node build/index.js

   Сервер запустится и запишет сообщения в stderr (вы можете увидеть «API Key загружен успешно...» и т. д.). Теперь он прослушивает клиентское соединение MCP через стандартный ввод/вывод (stdio).

Подключение MCP-клиента

Этот сервер использует механизм транспорта stdio .

Использование MCP Inspector (рекомендуется для тестирования)

1. Убедитесь, что сервер еще не запущен отдельно.

2. Запустите Inspector и дайте ему команду запустить ваш сервер:

   npx @modelcontextprotocol/inspector node build/index.js

3. Запустится пользовательский интерфейс Inspector, который автоматически подключится к вашему серверу.

4. Перейдите на вкладку «Инструменты», чтобы взаимодействовать с инструментом blazesql_query .

Использование интегрированных клиентов (Cursor, Claude 3 и т. д.)

1. Запустите сервер в терминале:

   node build/index.js

2. Настройте клиент: в настройках вашего клиента MCP вам необходимо добавить пользовательскую конфигурацию сервера.

   • Транспорт: Выберите stdio .

   • Команда: Укажите точную команду, используемую для запуска сервера. Вам необходимо указать абсолютный путь к узлу и абсолютный путь к файлу 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 (string, required): Идентификатор целевого подключения к базе данных в вашей учетной записи BlazeSQL. Вы можете найти этот идентификатор в веб-приложении BlazeSQL при управлении подключениями к базе данных.

  • natural_language_request (string, required): Запрос, который вы хотите выполнить, написанный на простом английском языке (например, «покажите мне общее количество пользователей»). (Входные данные проверяются с помощью 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.

  • Сгенерированный SQL-запрос внутри кода Markdown ( sql ... ).

  • Результаты данных форматируются как JSON в коде Markdown ( 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`).