zipnavi — 우리집 공사·인테리어 내비게이터 (MCP 서버)

집 공사·인테리어를 앞둔 사람이 주소 하나로 건물 이력·실거래가·인허가 절차· 시공 체크리스트·업체 검증 방법까지 안내받는 MCP 서버입니다. 공공데이터(건축HUB 건축물대장, 국토부 실거래가)와 주소 검색 API를 결합해 카카오 PlayMCP(AGENTIC PLAYER 10) 환경에서 동작하도록 설계했습니다.

⚠️ 본 서버가 제공하는 정보는 공공데이터 기반 참고용이며 법적 효력이 없습니다. 계약·인허가 전 건축물대장 원부(세움터)와 관할 행정청을 확인하세요.

도구 (5종)

도구	설명	데이터 원천
zipnavi_get_building_info	주소 → 건축물대장 요약(구조·연식·내진·주차·승강기) + 공사 관점 인사이트	건축HUB getBrTitleInfo
zipnavi_get_recent_deals	주소 → 최근 실거래가 (매매/전월세 × 아파트·연립다세대·단독다가구·오피스텔, 1~24개월)	국토부 RTMS 8종
zipnavi_get_permit_guide	공사 유형 → 신고/허가 여부·법적 근거·절차·주의사항 (9유형)	내장 지식
zipnavi_renovation_checklist	단계별 체크리스트 (계약 전/시공 전/시공 중/준공 후)	내장 지식
zipnavi_check_contractor	시공업체 검증 방법·공식 조회처·레드 플래그	내장 지식

모든 도구는 response_format: "markdown"(기본) | "json"을 지원하고, 실패 시에도 오류 대신 행동을 유도하는 한국어 안내문을 돌려줍니다.

환경 변수

변수	필수	설명
ZIPNAVI_MODE	아니오	mock 또는 live. 미지정 시 키 2종이 모두 있으면 live, 아니면 mock
DATA_GO_KR_KEY	live 시	공공데이터포털 서비스 키. 일반 인증키(Decoding) 값을 사용 — Encoding 키를 넣으면 이중 인코딩으로 SERVICE_KEY 오류 발생
KAKAO_REST_KEY	live 시	카카오 로컬 API REST 키 (주소 → 법정동코드 변환)
JUSO_CONFM_KEY	아니오	juso.go.kr 승인키. 있으면 카카오 실패 시 폴백
ZIPNAVI_PORT	아니오	기본 8000

키는 환경 변수로만 주입합니다. 하드코딩·저장소 커밋 금지.

실행

pip install -r requirements.txt

# mock 모드 (키 불필요, 픽스처 데이터로 전 도구 동작)
ZIPNAVI_MODE=mock python -m zipnavi.server

# live 모드
DATA_GO_KR_KEY=... KAKAO_REST_KEY=... python -m zipnavi.server

기동 후:

• MCP 엔드포인트: http://localhost:8000/mcp (streamable-http, stateless)
• 헬스체크: http://localhost:8000/health

테스트

pip install -r requirements-dev.txt
python -m pytest tests -q

• 전 테스트 네트워크 0회 (mock 픽스처 + httpx.MockTransport)
• test_server_roundtrip.py가 PlayMCP 등록 검증(initialize → tools/list → tools/call)을 인메모리로 사전 재현, test_http_roundtrip.py가 실제 HTTP로 재확인

PlayMCP 제약 준수

제약	대응
응답 24KB 초과 시 반려	마크다운은 멀티바이트 안전하게 절단하고, JSON은 유효한 축약 안내 객체로 반환
TextContent만 허용	전 도구 텍스트 반환 + structured_output=False로 structuredContent 자동 복제 차단 (roundtrip 테스트에서 타입 검증)
도구명 ^[A-Za-z0-9_-]{1,128}$, 'kakao' 금지	zipnavi_* 5종 (테스트로 검증)
도구 수 3~10개	5개
Remote HTTPS 전용	streamable-http + 리버스 프록시(TLS 종단)로 배포
평균 100ms / p99 3s	실거래가 다개월 조회 총 데드라인 2.6s(asyncio.wait) + 동시 요청 5개 제한(Semaphore), httpx 타임아웃 2.0s(connect 1.5s), 재시도 1회 제한

데이터·약관 준수

• fixtures/의 mock 데이터는 API 응답 스키마만 모사한 가상 데이터입니다. 카카오 로컬 API 실응답은 약관상 저장하지 않습니다(라이브 콜 즉시 소비).
• 공공데이터 응답 XML은 DTD 선언을 거부하는 파서로만 해석합니다(XXE 방어).