이 프로젝트는 @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 사용하는데, 이는 다이어그램에 표시된 저수준 핸들러에 비해 도구 등록을 간소화합니다).
지엑스피1
Node.js (LTS 버전 권장)
원사 (클래식 또는 베리)
API 키가 있는 BlazeSQL 계정(API를 사용하려면 Team Advanced 구독이 필요함).
BlazeSQL 계정에 하나 이상의 데이터베이스 연결이 구성되어 있습니다.
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 전송 메커니즘을 사용합니다.
서버가 별도로 실행되고 있지 않은지 확인하세요.
검사기를 실행하여 서버를 시작하도록 지시합니다.
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입니다. BlazeSQL 웹 애플리케이션에서 데이터베이스 연결을 관리할 때 이 ID를 찾을 수 있습니다.
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.
