| name | ipzitalk-complex-overview |
| description | 단지명·주소·K-apt 코드 중 하나를 입력받아 K-apt 단지 개요를 한 장 요약으로 정리한다. 세대수, 사용승인연차, 시공사, 주차, 지하철/버스 도보분, 위치 식별자를 빠르게 보여준다. "단지 개요", "아파트 요약", "이 단지 어떤 곳", "간단히 정리", 그리고 범위를 밝히지 않은 "OO아파트 어때" 요청에 사용한다. 실거래·입지·인근 단지까지 필요하면 이 아파트 한눈에 보기(ipzitalk-complex-overview-all)를 권한다.
|
| version | 1.0.1 |
| license | proprietary |
단지 개요 요약
tier: L2
단지 스펙 카드의 압축형. 사용자가 빠르게 단지 성격을 파악하도록 1페이지 요약을 만든다.
입력
| 파라미터 | 필수 | 기본값 | 설명 |
|---|
target | ✅ | - | 단지명, 주소, kapt_code 중 하나 |
detail | ✕ | true | 주차·도보분을 위해 기본 true |
output_format | ✕ | html | `markdown |
필수 도구
| 도구 | 용도 |
|---|
resolve-site 규약 | 단지명/주소/코드를 표준 번들로 해소 |
get_complex_info(detail=true) | 단지 기본·상세정보 조회 |
get_map_embed_url | 위치 지도 생성 |
워크플로우
- 입력 해소 — 단지명/주소/코드 →
kapt_code, 주소, 좌표, 법정동코드 확보.
- 단지정보 조회 —
get_complex_info(..., detail=true).
- 요약 문장 생성 — 세대수·연식·시공사·주차·교통 도보분만 사용해 1~2문장. 정성 우열 단정 금지.
- 위치 번들 표기 — 법정동코드, 시군구코드, 좌표, 해소 정밀도.
- 주의 표시 — K-apt 편의/교육시설 텍스트가 빈 괄호일 수 있으므로 POI 검증 전 단정 금지.
- 지도/출처 첨부.
데모에서 확인한 파라미터
- 입력:
방배롯데캐슬아르떼
- 결과: 744세대, 2013년 사용승인, 롯데건설, 주차 1.57대/세대, 버스 5분 이내, K-apt 지하철 15~20분 이내
- 레이아웃 기준:
templates/result.html
출력 포맷
- 한 줄 요약 + 핵심 4지표 + 위치 번들 + 주의/해석 메모 + 지도.
- 상세 스펙 전체가 필요하면
ipzitalk-complex-spec-card로 안내.
- 화면 표기는 사용자용 용어만: 출처는
공동주택관리정보시스템(K-apt) · 카카오맵 · 네이버 지도.
엣지 · 실패 처리
| 상황 | 처리 |
|---|
| 후보 다수 | 후보 제시 후 선택 요청 |
| 법정동코드만 입력 | 단일 단지 개요 생성 불가. 단지명/kapt_code 요청 |
| 상세정보 일부 결측 | 결측 필드는 숨기거나 자료없음 표기 |
필수 단서
- 개요 요약은 K-apt 등록정보 기반.
- 교통/교육/생활 정성 판단은 별도 POI 스킬 검증 후 수행.
- 출처 표기에는 공식 명칭
공동주택관리정보시스템(K-apt)과 링크 https://www.k-apt.go.kr/web/main/index.do를 함께 표시한다.
섹션마다 출처를 작게 단다
데이터 블록 하단에 .src 한 줄. 도구·API 이름은 쓰지 않는다. 사용자가 아는 기관명만.
| 블록 | 출처 표기 |
|---|
| 단지 개요·세대수·준공·주차·연차 | 공동주택관리정보시스템(K-apt) |
| 매매·전세·평당가·거래량 | 국토교통부 실거래가 |
| 학교·교통·생활·상권 등 장소 | 카카오맵 |
| 분양공고·분양가·주택형·입주월 | 청약홈 |
| 지도 (장소 마커) | 네이버 지도 · 카카오맵 |
| 지도 (분양공고 마커) | 네이버 지도 · 청약홈 |
- 🚨 출처 문자열은
ipzi-data JSON으로 받지 않고 템플릿 마크업에 직접 박는다.
어느 블록이 어디서 왔는지는 실행마다 달라지지 않는다. 데이터로 받으면 채우는 걸 잊거나 틀리게 쓸 여지만 생긴다.
- 🚨 한 블록에 두 출처가 섞이면 병기한다. 예:
세대수·주차 — 공동주택관리정보시스템(K-apt) · 위치 — 카카오맵.
하나로 뭉뚱그리면 어느 숫자가 어디서 왔는지 사용자가 알 수 없다.
- 🚨 쓰지 않은 기관을 출처로 적지 않는다. 우리가 부르는 곳은 위 다섯 곳뿐이다.
- 히어로·유의사항·푸터에는 달지 않는다. 데이터 블록에만.
디자인 정본
스킬 폴더 밖 문서에 의존하지 않도록 규칙을 여기 인라인으로 둔다.
- CDN·외부 폰트·이모지 금지. 아이콘은
<symbol> 인라인 + <use> 참조로 self-contained.
- 라이트/다크 양쪽.
prefers-color-scheme + :root[data-theme] 모두 대응.
- 토큰만 사용:
--g/--y/--o/--r/--x/--brand/--up/--down/--zebra (+ -s 배경 변형).
- 예외 상태:
null은 "정보없음"(0 아님) · 표본 부족은 판정 유보 · 45건 캡 도달은 "목록 불완전" 표기.
★·☆는 활자 기호이며 이모지가 아니다. 등급 표기에 사용 가능.- 지도 카드 CSS:
.map{overflow-x:auto; overflow-y:hidden} + .map iframe{display:block; min-width:720px}.
overflow:hidden만 주면 iframe이 카드 폭에 짓눌려 지도가 최소 줌(한반도)으로 떨어진다.
- 🚨 지도 링크는 발급 후 7일 만료. 산출물 지도 캡션에 유효기간·재발급 필요를 반드시 적는다.
만료 시 iframe이 빈 화면이 되는데, 원인 표기가 없으면 리포트가 고장난 것처럼 보인다.
- 🚨 반경 눈금 마커를 넣지 않는다. 예전엔
fitBounds가 반경 원을 무시해 원이 잘리는 걸 막으려고
정북·남·동·서에 회색 더미 마커 4개를 심었다. 사용자에게는 정체를 알 수 없는 점으로 보여 혼란만 준다.
원이 잘리더라도 마커는 실제 장소만 찍는다. (근본 해결은 render.ts가 원을 bounds에 포함하도록 고치는 것 — 발견사항 6번)
🚨 K-apt 도보시간은 자기보고값이다 (실측 2026-07-09)
관리주체 신고값이고 검증 절차가 없다. 위례 송파푸르지오 실측:
K-apt 신고 "10~15분이내"
카카오 POI 최근접역 장지역 8호선 1,313m (도보 20분 안팎)
- 화면에 쓰려면 출처를 밝히고 참고값임을 표기한다. 내부 필드명은 쓰지 않는다.
- hero/요약 지표로 올리지 않는다. 사용자가 확정값으로 읽는다.
- 접근성을 말해야 하면 카카오 POI 직선거리를 병기한다.
MCP 도구 네임스페이스와 출처
ipzitalk MCP 도구의 네임스페이스는 실행 환경(Codex, Claude Code, Hermes, claude.ai 커넥터 등)에 따라 다르다.
이 문서에 적힌 도구 이름(search_announcement_info, get_geocode, get_map_embed_url 등)은 접두사 없는 기본 도구명(base tool name) 이다.
- 먼저 연결된 도구 목록에서 같은 기본 도구명을 찾는다.
- 그중
ipzitalk-remote 플러그인의 ipzitalk 서버 provenance가 확인되는 도구만 우선 사용한다. Codex에서는 실제 도구 호출 이벤트의 server: ipzitalk과 기본 도구명을 기준으로 확인한다.
presale-mcp 또는 다른 로컬 MCP provenance의 동명 도구는 Remote Skill의 대체 수단으로 사용하지 않는다.- provenance를 확인할 수 없거나 같은 기본 도구명이 여러 서버에 있어 모호하면 임의 선택하지 말고 중단하여 필요한 Remote 도구명을 안내한다.
클라이언트가 연결 도구 목록에 plugin/server provenance를 구조적으로 제공하지 않을 때만 다음 명시적 fallback을 사용한다.
mcp__plugin_ipzitalk-remote_ipzitalk__<도구명>mcp__ipzitalk_mcp__<도구명>mcp__ipzitalk__<도구명>mcp__claude_ai_ipzitalk__<도구명>
fallback으로도 Remote 출처를 유일하게 확인할 수 없으면 값을 추정하지 말고, 사용자에게 ipzitalk Remote MCP 연결 상태를 확인하도록 안내한 뒤 중단한다.
