v0.5.1: MCP tool 출력 강타입화 (PATCH)

[DanMeon]

Summary

v0.5.0 GA 한 rhwp-mcp 의 7 도구 중 약타입 (dict[str, Any] / list[dict[str, Any]]) 으로 반환하던 3 도구 (get_ir / iter_blocks / chunks) 의 출력을 Pydantic V2 모델 (HwpDocument / list[Block] / list[ChunkRecord]) 로 강타입화. fastmcp v3 의 자동 outputSchema 가 약타입 (additionalProperties: true 만) → 강타입 (필드별 type / Discriminator + Tag 11 변형 / required 명시) 으로 강화 — LLM 응답 정확도 향상. wire format byte-equal — 외부 클라이언트 (Claude Desktop / Cline 등) 영향 0.

변경 요약

영역	변경
python/rhwp/mcp/tools.py	3 함수 시그니처 강화 + ChunkRecord 신규 BaseModel
python/rhwp/ir/nodes.py	UnknownBlock.kind JSON Schema not.enum constraint — fastmcp strict oneOf 호환. 런타임 동작 0 변경, schema export 만 strict 화
python/rhwp/ir/schema/hwp_ir_v1.json	packaged JSON Schema 자동 재생성
tests/test_mcp_server.py	5 신규 테스트 클래스 (AC-1~AC-7) — typed signatures / outputSchema 강화 / wire format byte-equal / typed result.data / Pydantic round-trip
Cargo.toml + CHANGELOG.md	0.5.0 → 0.5.1 release marker + [0.5.1] 섹션
spec / ADR / migration	모두 Frozen + GA 인덱스 갱신
README.md	MCP 도구 표 출력 컬럼 + v0.5.1 마이그 노트

작업 중 표면화된 fastmcp v3 한계 (spec 본문 정확화)

1. result.structured_content wrap 분기 — BaseModel = inline (no wrap) / list[T] = {"result": [...]} envelope. spec § wire format byte-equal 의 wrap 분기 표 추가.
2. callable Discriminator + Tag 유니온의 client-side deserialization 한계 — fastmcp Client 의 자동 reconstruct 가 oneOf 11 변형을 dynamic 모델로 변환 못 해 list element dict 폴백. server side 의 typed 출력은 AC-2 가 cover, wire format byte-equal 은 AC-5 가 cover. v0.5.0 dict access 패턴 그대로 backwards-compat.
3. strict oneOf validation 충돌 — ParagraphBlock + UnknownBlock 양쪽 valid 인스턴스에서 RuntimeError: Invalid structured content. 결정 8 (UnknownBlock.kind not.enum) 추가로 해결.

Why

v0.5.0 S3 의 code-reviewer 가 LOW-2 로 권고: "iter_blocks / get_ir / chunks 가 같은 패턴 (list[dict[str, Any]]) 이라 일괄 후속 polish 처리". v0.5.0 GA (2026-05-06) 직후 후속 polish 시점이 v0.5.1 PATCH. outputSchema 본문이 48 bytes (additionalProperties: true only) → 약 28-32 KB (Discriminator + Tag 11 변형, $defs 약 20 종) 로 확장 — LLM 의 응답 해석 / 후속 도구 호출 정확도에 측정 가능한 개선.

Related Issues

없음 — code-reviewer LOW-2 후속 polish.

---

검증

• uv run pytest tests/ -m "not slow" — 585 passed, 2 skipped (pre-existing aift fixture), 6 deselected
• uv run pyright python/rhwp/ tests/test_mcp_server.py — 0 errors (변경 파일) + 4 intentional tests/type_check_errors.py 보존
• uv run ruff check (변경 파일) — clean
• uv run python scripts/lint_docs.py — exit 0
• uv run python scripts/generate_spec_trace.py --check — up to date (16 v0.5.1 mappings)
• code-reviewer fresh-context (sub-agent) — PASS, HIGH 0 / MEDIUM 4 / LOW 2. MEDIUM-1 (측정값 stale) + MEDIUM-3 (lib name in new comments) 처리 완료. MEDIUM-2 (Cargo / CHANGELOG) 는 본 PR 의 release marker commit 으로 처리. MEDIUM-4 / LOW-1 / LOW-2 는 pre-existing 또는 spec design intent.

Spec / ADR / Migration

• docs/roadmap/v0.5.1/mcp-typed-output.md (Frozen) — 8 결정 + AC-1~AC-10
• docs/design/v0.5.1/mcp-typed-output-research.md (Frozen) — 5 결정 매트릭스
• docs/implementation/v0.5.1/migration.md (Frozen) — 산출물 / AC↔테스트 매핑 / fastmcp v3 한계 / GA 절차 인계

Commit history

d3a39f5 docs: v0.5.1 GA — Frozen 전환 + roadmap 인덱스 갱신
0272e0b chore: v0.5.1 release marker
d9f61a1 docs(v0.5.1): mcp-typed-output spec / ADR / migration
747d6b2 test(mcp): v0.5.1 typed-output AC-1~AC-7 회귀 가드
28774a2 refactor(mcp): get_ir / iter_blocks / chunks 출력 강타입화
03a399d fix(ir): UnknownBlock.kind not.enum for fastmcp strict oneOf 호환

머지 후 GitHub Release v0.5.1 published 로 publish.yml 트리거 (Trusted Publisher OIDC → PyPI 자동 배포).