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 사용하는데, 이는 다이어그램에 표시된 저수준 핸들러에 비해 도구 등록을 간소화합니다).
지엑스피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_HEREBlazeSQL 계정 설정에서 얻은 실제 API 키로 바꾸세요.
서버 실행
서버 빌드: TypeScript 코드를 JavaScript로 컴파일합니다.
yarn build서버 실행: 컴파일된 코드를 실행합니다.
node build/index.js서버가 시작되고
stderr에 메시지가 기록됩니다("API 키가 성공적으로 로드되었습니다..." 등의 메시지가 표시될 수 있음). 이제 표준 입출력(stdio)을 통해 MCP 클라이언트 연결을 수신합니다.
MCP 클라이언트 연결
이 서버는 stdio 전송 메커니즘을 사용합니다.
MCP Inspector 사용(테스트 권장)
서버가 별도로 실행되고 있지 않은지 확인하세요.
검사기를 실행하여 서버를 시작하도록 지시합니다.
npx @modelcontextprotocol/inspector node build/index.jsInspector UI가 실행되고 자동으로 서버에 연결됩니다.
"도구" 탭으로 이동하여
blazesql_query도구와 상호 작용하세요.
통합 클라이언트(Cursor, Claude 3 등) 사용
터미널에서 서버를 시작합니다 .
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(문자열, 필수): 실행하려는 쿼리를 일반 영어로 작성합니다(예: "사용자 총 수를 보여주세요"). (입력은
예제 호출(설명을 위해
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`).