BlazeSQL MCP サーバー

このプロジェクトは、 @modelcontextprotocol/sdkを使用して、BlazeSQL 自然言語クエリ API のプロキシとして機能するモデルコンテキストプロトコル (MCP) サーバーを実装します。これにより、MCP 対応クライアント (Cursor、ツール使用機能を備えた Claude 3、MCP Inspector など) が自然言語を使用して BlazeSQL と対話できるようになります。

特徴

• MCP SDK の最新のMcpServerヘルパー クラスを使用して構築されました。

• BlazeSQL 自然言語クエリ API をblazesql_queryという名前の MCP ツールとして公開します。

• ツール入力パラメータの堅牢な検証に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 バージョンを推奨)

• 糸（クラシックまたはベリー）

• API キーを持つ BlazeSQL アカウント (API には Team Advanced サブスクリプションが必要です)。

• BlazeSQL アカウントに少なくとも 1 つのデータベース接続が構成されています。

• 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 Inspector の使用 (テストに推奨)

1. サーバーがすでに個別に実行されていないことを確認してください。

2. Inspector を実行し、サーバーを起動するように指示します。

   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。このIDは、データベース接続を管理する際にBlazeSQL Webアプリケーションで確認できます。

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