FastMCP server: enrich places/addresses with 5-digit Korean postcode using Juso API
Server has 5 tools with complete input schemas and descriptions. Naming follows verb_noun pattern (normalize_, get_, resolve_, enrich_). Descriptions are domain-specific and contextual (avg ~150 chars), exceeding the 10-char minimum. However, parameter descriptions lack actionable constraints (ranges, formats, enums). Output schemas are partially documented via Pydantic models but not explicitly declared in tool registration. Error handling is minimal, no recovery guidance or categorization. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite all tools being read-only. Missing per-parameter validation rules and dependency documentation.
카카오맵 키워드 검색 결과(단일 place)에서 road_address_name을 넣어 호출하는 용도. PlayMCP에서 'SearchPlaceByKeywordOpen' 결과를 LLM이 받았을 때 이어붙이기 좋음.
표준 도로명 주소를 기반으로 영문 주소를 조회합니다. 해외 배송지, 여권 정보, 글로벌 서비스용 주소 데이터 정리에 사용할 수 있습니다.
표준 주소(도로명 또는 지번)를 바탕으로 5자리 우편번호를 조회합니다. 이미 정규화된 주소에서 우편번호만 추출할 때 사용합니다.
텍스트로 입력한 주소를 행안부 주소 데이터 기준의 표준 주소 후보로 정규화합니다. 배송지/회원가입 폼의 주소 문자열을 정제하거나, 데이터 파이프라인에서 주소를 표준화할 때 사용합니다.
카카오 place JSON 1개에서 주소를 추출해 표준 주소/우편번호/영문주소로 정제·보강합니다. 카카오 검색 결과를 그대로 쓰지 않고, 배송지/회원가입/데이터 정제용 주소 데이터로 가공하는 보조 도구입니다.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite all tools being read-only. Agents cannot infer safety properties.
Parameter descriptions lack actionable constraints. 'max_candidates' has min/max in schema but description says only 'maximum 20 items', no guidance on typical values or performance implications.
Output schemas not explicitly documented in tool registration. Pydantic models exist (NormalizeResult, etc.) but are not referenced in @mcp.tool() decorators. LLMs cannot see expected response structure.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 60 | <=2025-11-25 | v2 |
Minimal error handling. get_postcode returns a dict with 'message' field on missing params, but no guidance on recovery. get_english_address returns 'NO_ENGLISH_PROVIDER' error without suggesting fallback tools.
Parameter dependencies undocumented. resolve_from_kakao_place accepts both kakao_place and kakao_places; unclear which takes precedence or if both can be passed. No mutual-exclusivity guidance.