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 사용하는데, 이는 다이어그램에 표시된 저수준 핸들러에 비해 도구 등록을 간소화합니다).

지엑스피1

필수 조건

• Node.js (LTS 버전 권장)
• 원사 (클래식 또는 베리)
• API 키가 있는 BlazeSQL 계정(API를 사용하려면 Team Advanced 구독이 필요함).
• BlazeSQL 계정에 하나 이상의 데이터베이스 연결이 구성되어 있습니다.
• 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. 검사기를 실행하여 서버를 시작하도록 지시합니다.
   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입니다. 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`).