BlazeSQL MCP Server

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を選択します。
   • コマンド:サーバーの実行に使用するコマンドを正確に指定します。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`).