askDB MCP

자연어 데이터 질문을 LLM이 SQL을 작성하는 데 필요한 스키마 컨텍스트로 변환하는 MCP 서버입니다. 데이터베이스에 연결하지 않으며 SQL을 직접 생성하지도 않습니다. Pinecone 인덱스에서 올바른 테이블 정의를 검색하여 질문하는 모델(Claude Code, Claude Desktop, ChatGPT, Cursor)에게 전달합니다.

user question
   │
   ▼
Claude Code / ChatGPT ──calls──► askDB MCP ──semantic search──► Pinecone (ask-db)
   │                                  │
   │      relevant DDL + guardrails ◄─┘
   ▼
generated SQL

도구

모든 응답에는 모델이 반환된 테이블과 열만 사용하도록 하는 지침이 포함되어 있어, 임의의 이름을 만들지 않습니다.

설정

npm install
npm run setup             # creates .env from the template
#                          → then put your PINECONE_API_KEY in .env
npm run doctor            # verify connection, field mapping and retrieval quality

다른 사람과 공유하려고 하나요? SETUP.md를 보내주세요. 로컬 실행과 호스팅 인스턴스 연결 방법을 모두 다룹니다.

npm run doctor가 중요한 단계입니다. 인덱스 구성, 레코드가 실제로 사용하는 메타데이터 필드, 샘플 검색을 출력하므로, 클라이언트에 연결하기 전에 서버가 올바른 필드를 읽고 있는지 확인할 수 있습니다.

npm run doctor       # connectivity + retrieval sanity check
npm run smoke        # drive the stdio server with a real MCP client
npm run smoke:http   # same over Streamable HTTP, with bearer auth

클라이언트 연결

Claude Code

CLI, 데스크톱 앱, IDE 확장 프로그램은 모두 하나의 설정을 공유하므로, 이 설정은 세 가지 모두에 서버를 등록합니다:

# from the repo root — records an absolute path, so it works in any folder
claude mcp add askdb --scope user -- node "$PWD\src\server.js"

claude mcp list(askdb: ... ✓ Connected)로 확인한 후 데스크톱 앱이나 IDE 창을 다시 시작하세요. MCP 서버는 시작 시 로드됩니다.

사용자 범위는 의도적입니다. 다른 저장소에서 작업하는 동안 데이터베이스 질문을 하는 것이 목적이기 때문입니다. 프로젝트 범위의 .mcp.json은 Claude Code가 이 저장소의 루트에서 시작될 때만 적용되며, 두 범위 모두에서 askdb를 정의하면 Claude Code가 중복에 대해 경고합니다.

Claude Desktop / Cursor

claude_desktop_config.json(또는 Cursor의 MCP 설정)에 추가하세요:

{
  "mcpServers": {
    "askdb": {
      "command": "node",
      "args": ["D:\\working-directory\\AI\\askDB-mcp\\src\\server.js"]
    }
  }
}

자격 증명은 서버 옆의 .env에서 가져오므로 클라이언트 구성에 키가 포함되지 않습니다.

ChatGPT

ChatGPT 커넥터는 로컬 프로세스를 생성할 수 없습니다. HTTP를 통한 원격 MCP만 지원합니다. HTTP 전송을 실행하고 노출하세요:

# set MCP_AUTH_TOKEN first: this endpoint serves your whole schema
MCP_AUTH_TOKEN=some-long-random-string npm run start:http

그런 다음 커넥터를 https://<your-host>/mcp로 지정하고 Authorization: Bearer <token> 헤더를 사용하세요. 빠른 테스트를 위해서는 터널링(cloudflared tunnel --url http://localhost:3000)하고, 오래 유지할 용도라면 제대로 호스팅하세요. DEPLOY.md가 Netlify를 처음부터 끝까지 다룹니다. GET /health는 로드 밸런서 확인을 위해 인증이 필요 없습니다. /mcp는 MCP_AUTH_TOKEN이 설정되어 있을 때마다 Bearer 토큰을 요구합니다.

HTTP 전송은 상태 비저장입니다. 요청당 서버 인스턴스 하나이므로 고정 세션 없이 로드 밸런서 뒤에서 확장할 수 있습니다.

호스팅

두 개의 Netlify Functions로 배포됩니다. netlify.toml에 빌드 설정이 포함되어 있으므로 리포지토리를 가져오고 PINECONE_API_KEY + MCP_AUTH_TOKEN을 설정하는 것이 전부입니다. 단계별 가이드: DEPLOY.md.

이 방식은 전송 계층 재작성 없이 작동합니다. MCP SDK의 WebStandardStreamableHTTPServerTransport가 Request를 받아 Response를 반환하는데, 이는 Netlify Functions v2 시그니처이기 때문입니다. 따라서 netlify/functions/mcp.mjs는 src/mcp.js를 변경 없이 가져옵니다. 동일한 파일은 Cloudflare Workers, Deno 또는 Bun에서도 바로 사용할 수 있습니다. src/http.js는 컨테이너와 VM을 다룹니다.

GET /health는 토큰이 필요 없으며 필요한 환경 변수가 설정되었는지 보고합니다(값이 아닌 존재 여부만). 시작 로그를 읽는 서버리스 대안입니다. /mcp는 기본적으로 차단됩니다: MCP_AUTH_TOKEN이 설정되지 않으면 스키마를 인터넷에 제공하는 대신 503을 반환합니다.

서버가 가동되면 팀원은 아무것도 설치할 필요가 없습니다. URL과 토큰만 있으면 됩니다 (SETUP.md, Route A).

구성

API 키를 제외한 모든 항목은 선택 사항입니다. .env.example을 참조하세요.

서버는 레코드가 사용하는 메타데이터 필드와 인덱스에 통합 임베딩이 있는지 자동으로 감지하므로 기본값이 일반적으로 변경 없이 작동합니다.

알아두면 좋은 두 가지

임베딩 모델이 일치해야 합니다. EMBED_MODEL이 스키마를 업서트할 때 사용한 모델이 아니면 모든 점수가 거의 0으로 떨어지고 결과는 노이즈가 됩니다. 벡터가 서로에 대해 사실상 무작위이기 때문입니다. npm run doctor는 관련 없는 테이블이 0.8 대신 0.01 정도의 점수로 반환되는 것으로 이를 보여줍니다. 이 인덱스는 multilingual-e5-large로 구축되었습니다.

인덱스에 여러 환경이 있다면 DEFAULT_DATABASE를 설정하세요. 동일한 스키마가 *_live와 *_test로 존재할 때, 범위를 지정하지 않은 검색은 모든 테이블의 두 복사본을 반환하여 top_k 슬롯의 절반을 중복으로 소모하고 모델이 하나의 쿼리에서 환경을 혼합하게 만듭니다.

파일 구조