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 トランスポートを使用してクライアントと通信します。

ワークフロー図

この図は、クライアントがblazesql_queryツールを使用する場合の相互作用のシーケンスを示しています (注: 内部サーバー ロジックではMcpServerが使用されるようになり、図に示されている低レベルのハンドラーに比べてツールの登録が簡素化されています)。

前提条件

• 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を選択します。

   • コマンド:と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 （文字列、必須）: 実行したいクエリを平易な英語で記述します（例：「ユーザーの合計数を表示してください」）。 （入力は

• 呼び出し例 (説明のために

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