このプロジェクトは、 @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: MySQL MCP 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/
リポジトリをクローンします。
git clone <repository-url>
cd blaze-sql-mcp-server依存関係をインストールします:
yarn installこれにより、 @modelcontextprotocol/sdk 、 dotenv 、 zodなどの必要な依存関係がすべてインストールされます。
環境変数を設定します。
サンプル環境ファイルをコピーします。
cp .env.sample .env.envファイルを編集します。
# .env
BLAZE_API_KEY=YOUR_BLAZESQL_API_KEY_HEREYOUR_BLAZESQL_API_KEY_HERE 、BlazeSQL アカウント設定から取得した実際の API キーに置き換えます。
サーバーの構築: TypeScript コードを JavaScript にコンパイルします。
yarn build**サーバーの実行:**コンパイルされたコードを実行します。
node build/index.jsサーバーが起動し、 stderrにメッセージが記録されます（「APIキーが正常にロードされました...」などが表示される場合があります）。サーバーは標準入出力（stdio）経由でMCPクライアント接続を待機しています。
このサーバーはstdio トランスポート メカニズムを使用します。
サーバーがすでに個別に実行されていないことを確認してください。
Inspector を実行し、サーバーを起動するように指示します。
npx @modelcontextprotocol/inspector node build/index.jsInspector UI が起動し、自動的にサーバーに接続します。
blazesql_queryツールを操作するには、「ツール」タブに移動します。
ターミナルでサーバーを起動します。
node build/index.jsクライアントを構成する: 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を使用して見つけることができます。
設定を保存します。
これで、クライアントはローカルで実行されているサーバーに接続し、そのツールを一覧表示したり使用したりできるようになります。
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`).Executes a natural language query against a specified BlazeSQL database.
| Name | Required | Description | Default |
|---|---|---|---|
| db_id | Yes | The ID of the BlazeSQL database connection to query. | |
| natural_language_request | Yes | The query expressed in natural language (e.g., 'show me total users per city'). |
| Name | Required | Description |
|---|---|---|
| query | Yes | The SQL query generated and executed by BlazeSQL. |
| data_result | Yes | The structured data returned by the query, as a map of column names to value arrays. |
| agent_response | Yes | Natural language explanation of the results from BlazeSQL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool executes queries but doesn't describe traits like error handling, performance implications, authentication needs, or rate limits. For a query execution tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and appropriately sized, making it easy to understand quickly. Every part of the sentence contributes to clarifying the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return values), 100% schema coverage, and no annotations, the description is minimally complete. It covers the basic purpose but lacks behavioral context and usage guidelines. For a query tool with no annotations, it should do more to compensate, but the output schema mitigates some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents both parameters (db_id and natural_language_request) with clear descriptions. The description adds no additional meaning beyond what the schema provides, such as examples or constraints. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('executes') and resource ('natural language query against a specified BlazeSQL database'). It distinguishes what it does (execute natural language queries) from potential alternatives (like SQL queries), though without sibling tools, differentiation isn't needed. However, it could be more specific about the type of queries or results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, prerequisites, or exclusions. It mentions the tool's function but lacks context on appropriate scenarios, such as when natural language queries are supported or if there are limitations. With no sibling tools, this gap is less critical but still present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0blazesql_queryScored across 1 tool
With only one tool, there is no possibility of ambiguity or overlap between tools. The single tool has a clearly defined purpose that cannot be confused with any other tool in the set.
A single tool inherently has perfect naming consistency as there are no other tools to compare it against. The tool name follows a clear verb_noun pattern (blazesql_query) which would be consistent if more tools existed.
A single tool is generally too few for a database query server, as it lacks basic operations like listing databases, describing schemas, or managing connections. This minimal set limits functionality and forces all interactions through one interface.
The tool surface is severely incomplete for a SQL database server. While the query tool covers execution, there are obvious gaps such as no tools for schema exploration, database listing, transaction management, or data manipulation beyond queries, which will cause agent failures in many workflows.
A Model Context Protocol server for Wix AI tools
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
