BlazeSQL MCP Server

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.

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

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

Предпосылки

• 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`).