archhub-mcp: Instructions file for Claude Code

archhub-mcp — 프로젝트 메모

⚠️ 배포 — 통합 호스트 (2026-07-02부터)

프로덕션 공식 서빙은 gomdori-mcp 통합 호스트(fly 앱 korean-law-mcp 1대, MCP 5종 동거)다.

• 공식 주소: https://mcp.gomdori.app/archhub (구 앱 archhub-mcp는 통합 완료로 scale 0 처리됨)
• 반영 절차: 이 레포는 PyPI 미배포 — main에 커밋·푸시한 뒤 cd ~/workspace/gomdori-mcp && fly deploy -c fly.production.toml (pip가 GitHub main을 설치) → curl https://mcp.gomdori.app/healthz 확인
• 구 앱은 scale 0이므로 이 레포에서 fly deploy 직접 실행은 무의미 — 통합 반영은 반드시 위 절차로
• 단일 머신 제약(인메모리 캡·세션)은 통합 호스트에서도 유지됨 (fly scale count 1)

국토교통부 건축HUB(공공데이터포털) → MCP 서버. Python + FastMCP 3.x.

구조

archhub/
  __init__.py     # __version__
  __main__.py     # python -m archhub 진입점
  server.py       # FastMCP 인스턴스 + 도구 12개 + /health,/ 라우트 + stdio/http main()
  client.py       # ArchHubClient — 직접 REST 호출 + 법정동코드 캐시 + api_calls 카운터
  errors.py       # [NOT_FOUND]/[ERROR] 포맷 (환각 방지), 키 마스킹
  formatting.py   # DataFrame → 텍스트(종합카드·동단위통계) + 출처 명시

핵심 설계 결정

• 호출은 직접 REST: PublicDataReader의 get_data()는 numOfRows=99999 한 방 + timeout 없음 → MCP에 부적합. 그래서 requests로 timeout/numOfRows/pageNo 직접 제어. 엔드포인트는 https로 승격하고 verify=True(평문 http면 키 노출). fetch_all은 행/페이지/총deadline 3중 상한으로 절단.
• 라이브러리 재활용은 2가지만: meta_dict[type]["url"](엔드포인트 매핑), translate_columns(df)(한글 변환). 단 code_bdong()은 쓰지 않음 — timeout 없고 stdout에 print()(stdio JSON-RPC 오염). 같은 JSON을 timeout 걸어 직접 받아 ~/.cache/archhub-mcp에 캐시(client._load_bdong_json).
• 공용키 방식: ARCHHUB_SERVICE_KEY 하나로 모든 요청 처리 (BYOK 격리 없음). 공개 remote 보호는 opt-in: ARCHHUB_MCP_TOKEN(Bearer 인증·미설정 시 무인증) + ARCHHUB_DAILY_CALL_CAP(일일 호출 캡).
• remote 커넥터: fly.io에 streamable-http로 떠서 URL만 등록하면 연결.

검증

# in-memory MCP Client로 도구 목록 + 실호출
ARCHHUB_SERVICE_KEY=... python -c "import asyncio; from fastmcp import Client; from archhub.server import mcp; ..."

# 단위테스트 (외부 API 비의존, mock)
pytest tests/

자양동 = sigungu 11215, bdong 10500 (표제부 totalCount 6057).