vpd-permission-poc/docs/design/hmm-html-report-mcp/cookbook.md

적용·검증 절차

1. 준비

• vpd-backoffice 배포본에 HTML 템플릿과 HMM CI 리소스가 포함되어야 한다.
• 조회 도구 search_carrier_performance가 구조화된 items 배열을 반환해야 한다.
• 배포 환경의 BACKOFFICE_MCP_TOOLS에 AGENT_TOOL 도구 계약을 추가한다.

먼저 database/adb/83_hmm_carrier_html_report_tool.sql을 실행한 뒤 다음 명령으로 현재 승인 템플릿을 CLOB에 적재한다. 스크립트는 템플릿을 UTF-8 Base64로 복원한다.

./scripts/load-hmm-carrier-report-template.sh

2. 확인

1. 동일 Bearer token으로 tools/list를 호출한다.
2. render_hmm_carrier_report와 입력 속성 reportJson이 보이는지 확인한다.
3. 먼저 search_carrier_performance를 호출해 items를 얻는다.
4. 질문·답변 근거·items를 reportJson으로 구성해 리포트 도구를 호출한다.
5. 응답 response.html을 새 탭 또는 sandboxed iframe에서 연다.

성공 판정은 제목, 담당자별 막대 차트, 위험 분포, 상세 표가 rows와 일치하는 것이다. 템플릿 내부에 __REPORT_DATA__가 남지 않고, 검증 payload의 담당자·선사 식별자가 반환 HTML에 포함되는지도 확인한다.

3. 포털 순차 실행 확인

1. 포털 MCP 설정의 endpoint를 https://hmm-backoffice.cloud-handson.com/mcp로 설정하고, 허용 목록에 조회 도구와 리포트 렌더링 도구를 모두 넣는다.
2. 포털에서 예를 들어 E1001 팀의 선사 최신 실적을 HMM 리포트로 만들어줘라고 요청한다.
3. 실행 상세에서 첫 단계가 데이터 조회이고 두 번째 단계가 HTML 렌더링인지 확인한다.
4. 결과 영역에 생성된 리포트 iframe이 표시되고, 막대·상세 표가 첫 단계 items와 일치하는지 확인한다.

첫 단계가 0건이면 두 번째 단계의 reportJson.rows도 빈 배열이어야 한다. 이 경우 순차 실행과 HTML 생성은 성공한 것이며, 데이터 조회 문제는 리포트 Tool과 분리해 확인한다.

실패 시 문제 해결의 텍스트만 답하고 리포트가 생성되지 않음을 따른다.

4. 롤백

BACKOFFICE_MCP_TOOLS에서 리포트 도구 항목을 제거하고 서비스를 재기동하면 기존 조회 MCP에는 영향 없이 리포트 후속 호출만 중단된다. 템플릿은 DB나 사용자 데이터에 변경을 만들지 않는다.