pubdata-mcp

한국 공공데이터를 수집·정규화해 DuckDB 데이터마트에 적재하고, 이를 MCP 서버로 노출한 뒤 Ollama 로컬 LLM 에이전트가 자연어 질문에 답하는 end-to-end 파이프라인입니다.

데이터 엔지니어링(수집·정규화·안전한 쿼리 서빙)과 AI 오케스트레이션(MCP + LLM 툴콜)을 하나의 프로젝트로 보여주는 백엔드 포트폴리오입니다.

아키텍처

data.go.kr ──ingest──> DuckDB 데이터마트 ──> MCP Server ──stdio──> Ollama Agent Host
 (실거래가/기상/대기질)   (정규화 테이블)      (툴/리소스)          (자연어 → 툴콜 → 답변)

• ingest: 커넥터 인터페이스 + 3개 커넥터 (아파트 실거래가, 일별 기상, 일별 대기질). API 키 없으면 mock 폴백

• store: DuckDB 적재 및 read-only 쿼리 (지역 partition 기반 idempotent 적재)

• server: MCP 서버 (list_datasets, describe_schema, query_sql, price_stats, correlate + pubdata://catalog 리소스)

• host: MCP 서버를 subprocess로 띄우고 Ollama 툴콜 루프로 질의에 답하는 에이전트

데이터셋

• apt_trade — 아파트 매매 실거래가 (지역/월)

• weather — 일별 기온·강수·풍속 (지역/일)

• air_quality — 일별 PM10·PM2.5·오존 (지역/일)

weather와 air_quality는 (obs_date, region_code)를 공유해 correlate 툴로 크로스 도메인 상관분석이 가능합니다 (예: 풍속 vs 미세먼지 → corr ≈ -0.95, 바람이 강한 날 미세먼지가 낮음).

핵심 백엔드 포인트는 server/safe_sql.py의 read-only SQL 가드(단일문 강제, DDL/DML 차단, LIMIT 강제)와 DuckDB read-only 커넥션 이중 방어입니다.

Related MCP server: pykrx-mcp

빠른 시작

# 1. 의존성 설치 (uv)
uv sync

# 2. 데이터 적재 (키 없으면 mock 데이터로 동작)
for r in 11680 11650 11440; do
  uv run pubdata-ingest apt_trade   --region $r --ym 202406
  uv run pubdata-ingest weather     --region $r --ym 202406
  uv run pubdata-ingest air_quality --region $r --ym 202406
done

# 3. MCP 서버 단독 실행 (Claude Desktop / MCP Inspector에 연결 가능)
uv run pubdata-server

# 4. 에이전트로 자연어 질의 (CLI)
uv run pubdata-agent "강남구와 서초구 아파트 평균 거래가를 비교해줘"

# 5. 웹 UI (질문 + 답변 + 툴 호출 트레이스 표시) — http://localhost:8000
uv run pubdata-web

웹 UI / API

pubdata-web은 FastAPI 앱을 띄웁니다.

• GET / — 질문 입력 → 답변과 함께 에이전트가 호출한 MCP 툴 트레이스(인자·결과·소요시간)를 표시

• POST /api/ask {"question": "..."} → {answer, model, steps, elapsed_ms, trace[]}

• GET /api/health — 상태 및 설정된 모델

Docker

Ollama는 호스트에서 실행 중이라고 가정합니다. compose는 host networking으로 호스트의 localhost:11434 Ollama에 바로 접근합니다 (Linux 기준).

docker compose up --build
# http://localhost:8000

첫 기동 시 마트가 비어 있으면 mock 데이터로 3개 지역을 자동 적재합니다. 호스트에 tool-calling 모델(ollama pull qwen2.5:7b)이 있어야 합니다. Docker Desktop(mac/Windows)에서는 docker-compose.yml 주석의 대안 설정을 참고하세요.

실제 API 사용

.env.example를 .env로 복사하고 PUBDATA_DATA_GO_KR_KEY에 data.go.kr 서비스 키를 넣으면 mock 대신 실데이터를 수집합니다.

Claude Desktop 연결 예시

{
  "mcpServers": {
    "pubdata": {
      "command": "uv",
      "args": ["run", "pubdata-server"],
      "cwd": "/home/jcyeom/dlwlr/pubdata-mcp"
    }
  }
}

관측성 (Observability)

모든 에이전트 실행은 data/traces.jsonl에 append됩니다 (질문·모델·툴 궤적·소요시간·에러·답변).

• GET /api/traces?limit=20 — 최근 실행 조회 (최신순)

• best-effort 로깅이라 실패해도 요청에 영향 없음

평가 (Eval)

골든 케이스로 에이전트 품질을 회귀 검증합니다.

uv run pubdata-eval

각 케이스는 3가지를 채점합니다:

• answer-correctness: 답변에 기대값(실데이터 숫자)이 포함되는가 (콤마 무시 비교)

• tool-trajectory: 기대한 MCP 툴이 호출됐는가

• error-free: 툴 에러가 없었는가

결과는 표로 출력되고 data/eval_report.json에 저장됩니다. 하나라도 실패하면 exit code 1 (CI 연동 가능). 로컬 LLM 재현성을 위해 에이전트는 temperature=0으로 호출합니다.

테스트

uv run pytest   # 23 tests: SQL 가드, 파이프라인, 관측성, eval 스코어링

로드맵

• end-to-end 파이프라인 (ingest → DuckDB → MCP → Ollama 에이전트)

• read-only SQL 가드 + idempotent 적재

• Docker 배포 + 웹 UI (툴 트레이스 표시)

• 툴콜 정확도 eval 셋 + 요청 트레이싱/관측성

• 기상/대기질 커넥터 추가 → 크로스 도메인 상관분석 (correlate 툴)

• 기상/대기질 실 API 연동 (현재 mock, apt_trade는 실 API 지원)

• 수집 스케줄러(APScheduler) + 증분 적재