Ask-My-Data MCP

하나의 자연어 질문을 의미 검색(RAG) 과 데이터 집계(Text2SQL) 경로로 자동 라우팅해 답하는 MCP 서버. LangGraph 기반 Multi-Agent 파이프라인을 완전 합성 검색 평가 데이터로 검증하는 포트폴리오 프로젝트입니다.

실행 증거

아래 이미지는 2026-07-15에 클린 가상환경에서 MCP stdio 연결 후 tools/list와 search_documents를 실제 호출한 결과입니다.

검증	결과
pip install -e ".[dev]"	통과 (Python 3.14.5)
python -m pytest -q	6 passed
MCP initialize · tools/list	통과 — 3 tools
search_documents 호출	통과 — API 키 없이 BM25 검색

ask와 query_stats는 라우팅·SQL 생성·답변 합성에 Claude를 사용하므로 ANTHROPIC_API_KEY가 필요합니다. 위 smoke test는 키나 외부 API 없이 검증 가능한 검색 경로입니다.

동일한 검증은 python scripts/smoke_test.py로 재현할 수 있습니다.

무엇을 보여주나

• MCP 서버 — 범용 LLM 클라이언트(Claude Desktop 등)에서 도구로 호출
• Multi-Agent 라우팅 — 질문 유형(semantic/structured/both)을 판단해 경로 분기
• RAG — BM25 키워드 + (옵션)다국어 임베딩 Hybrid Search
• Text2SQL — 자연어 → 검증된 SELECT → 검색 실험 결과 집계
• Synthesize — 문서 근거와 정형 결과를 결합한 답변 생성

아키텍처

          ┌──────────┐
질문 ────▶ │  Router  │  semantic / structured / both 분류
          └────┬─────┘
       ┌───────┼────────┐
       ▼                ▼
  ┌─────────┐     ┌───────────┐
  │  RAG    │     │ Text2SQL  │
  │ (문서)   │     │ (SQLite)  │
  └────┬────┘     └─────┬─────┘
       └────────┬───────┘         (both: RAG → Text2SQL 순으로 이어붙임)
                ▼
         ┌────────────┐
         │ Synthesize │  근거 종합 → 자연어 답변
         └────────────┘

검색 실험용 합성 데이터

data/는 특정 회사·고객·서비스와 무관하게 이 프로젝트를 위해 새로 만든 데이터입니다.

구성	내용	실험 질문 예시
문서 코퍼스	검색 지표·방법론 + 실시간 협업 편집 OT/CRDT 기술 문서	“MRR과 nDCG의 차이는?”, “OT와 CRDT는 언제 선택해?”
datasets	언어·질의 수·문서 수가 다른 가상 데이터셋 3개	“다국어 데이터셋은 무엇인가?”
experiments	BM25·Dense·Hybrid-RRF 가상 실험 9개	“MRR이 가장 높은 실험은?”
experiment_results	데이터셋과 실험을 결합한 조회용 View	“한국어 데이터셋의 품질·지연 시간 비교”

모든 이름, 설명, 지표와 지연 시간은 검색/RAG 실험을 위해 임의로 구성한 합성 값입니다. 실시간 협업 편집 문서는 사용자가 제공한 일반 기술 리서치 문서로, 합성 실험 수치와 분리되어 있습니다.

빠른 시작

# 1) 설치
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"          # 기본 + 테스트
pip install -e ".[embeddings]"   # 옵션: 다국어 임베딩 Hybrid Search

# 2) 환경변수
cp .env.example .env              # ANTHROPIC_API_KEY 채우기
export $(cat .env | xargs)        # 또는 direnv/python-dotenv

# 3) 합성 검색 실험 DB 생성
python data/build_sample_db.py

# 4) MCP 없이 바로 테스트 (CLI)
python -m src.cli "MRR이 뭐야?"
python -m src.cli "Mosaic 데이터셋에서 MRR이 가장 높은 실험은?"
python -m src.cli "nDCG@10이 가장 높은 실험은 무엇이고, nDCG는 어떻게 계산해?"

# 단위 테스트
python -m pytest -q

MCP 클라이언트에 연결 (Claude Desktop 예시)

claude_desktop_config.json:

{
  "mcpServers": {
    "ask-my-data": {
      "command": "python",
      "args": ["/absolute/path/to/ask-my-data-mcp/server.py"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

노출 도구: ask (자동 라우팅) · search_documents (RAG) · query_stats (Text2SQL)

예시 질문과 라우팅

질문	라우팅	경로
"MRR이 뭐야?"	semantic	RAG
"Mosaic 데이터셋에서 MRR이 가장 높은 실험은?"	structured	Text2SQL
"nDCG@10이 가장 높은 실험은 무엇이고, nDCG는 어떻게 계산해?"	both	RAG + Text2SQL

기술 스택

Python · MCP · LangGraph · Anthropic Claude · rank-bm25 · sentence-transformers(옵션) · SQLite

관련 글

• 하나의 프롬프트로는 안 됐다 — LangGraph Multi-Agent 라우팅
• 70%짜리 검색으로 90%짜리 경험을 만드는 법

라이선스

MIT