refs #732: add dynamic HMM HTML report MCP tool

docs/design/hmm-html-report-mcp/README.md

@@ -0,0 +1,39 @@
+# HMM HTML 리포트 MCP
+
+## 목적
+
+선사 실적 Federation 조회의 구조화 결과를 HMM 기업 리포트 HTML로 표현한다. 리포트 도구는
+DB를 다시 조회하거나 자연어를 해석하지 않는다.
+
+## 결정사항
+
+- MCP 도구 `render_hmm_carrier_report`는 `reportJson` 문자열 하나를 입력으로 받는다.
+- 입력은 질문·답변 근거·조회 행으로 구성된 허용 JSON 계약이며, Oracle DB 함수는 템플릿에만 매핑한다.
+- 선사 실적 조회 MCP가 VPD를 적용한 데이터 접근 경계이고, 리포트 MCP는 표현 경계다.
+- 승인된 HTML 템플릿은 DB CLOB으로 버전 관리하고, 생성 HTML은 MCP 응답의 `html` 속성으로만 반환한다.
+
+## 전체 흐름
+
+```text
+HMM 포털 → `https://hmm-backoffice.cloud-handson.com/mcp` → 데이터 조회 도구
+→ 포털의 범용 결과 정규화 → 이전 결과 입력형 렌더링 도구 → HTML 미리보기
+```
+
+리포트에 보이는 값은 조회 결과 행에서 계산되므로, 자연어 답변과 별개로 재해석되지 않는다.
+
+## 문서 지도
+
+- [아키텍처와 입력 계약](architecture.md)
+- [적용·검증 절차](cookbook.md)
+- [문제 해결](troubleshooting.md)
+
+## 현재 상태
+
+Oracle DB의 custom Agent Tool과 템플릿 CLOB은 적용됐다. 포털은 리포트·차트·HTML 요청에서
+도구 이름을 고정하지 않고, 발견한 도구의 설명·입력 스키마를 기준으로 데이터 조회 뒤 렌더링을
+순차 호출하도록 운영 배포한다.
+
+2026-08-10 운영 검증에서 `tools/list`, `reportJson` 입력, 64KB 입력 한도, 동적 JSON 매핑과
+Agent 2단계 실행을 확인했다. HTML 템플릿에는 업무 샘플 행을 저장하지 않으며, 호출 시 전달된
+`report`와 `rows`만 표시한다. 선행 조회가 0건을 반환하면 빈 리포트를 생성하는 것이 정상이며,
+조회 결과나 권한 설정은 이 기능의 변경 범위가 아니다.