refs #702: align HMM MCP contract and settings

2026-07-22 15:54:48 +09:00
parent adfd50d1fd
commit 536938895a
20 changed files with 383 additions and 197 deletions
--- a/src/main/resources/templates/mcp-sse.html
+++ b/src/main/resources/templates/mcp-sse.html
@@ -8,7 +8,7 @@
    <h1>MCP 연동</h1>
    <details class="explanation-details">
      <summary>도움말</summary>
-      <p>사용자 Bearer Token을 전달해 GPT-5.4-mini Select AI 자연어 조회를 실행하는 단일 MCP tool을 제공합니다. Select AI는 comment, annotation, constraint 메타데이터를 함께 사용하고, DB에서는 토큰 기준 행 접근 context가 적용됩니다.</p>
+      <p>HMM HR MCP는 표준 용어 변환, HR 데이터 조회, HR 규정 PDF 검색의 세 도구를 제공합니다. 모든 도구는 읽기 전용이며, 휴가·근태 표현이 모호하면 용어 변환을 먼저 사용합니다.</p>
    </details>
  </section>

@@ -21,19 +21,19 @@
    <h2>서비스 구성</h2>
    <div class="mcp-service-grid">
      <div class="mcp-service-item">
-        <span>기본 서비스</span>
-        <strong><code>/mcp/sse</code></strong>
-        <small>기존 MCP client 설정과 호환됩니다.</small>
+        <span>공개 MCP Endpoint</span>
+        <strong><code th:text="${hmmMcpPublicUrl}">https://hmm-mcp.cloud-handson.com/mcp</code></strong>
+        <small>Private Agent Factory와 외부 MCP client가 사용하는 Streamable HTTP Endpoint입니다.</small>
      </div>
      <div class="mcp-service-item">
-        <span>Context 서비스</span>
-        <strong><code>/mcp/{contextPath}/sse</code></strong>
-        <small>업무/환경별 이름으로 같은 ORDS tool set을 분리 노출합니다.</small>
+        <span>인증</span>
+        <strong><code>Authorization: Bearer &lt;HMM MCP Token&gt;</code></strong>
+        <small>고정 MCP 서버 토큰으로 인증합니다. DB 비밀번호와 Wallet은 전달하지 않습니다.</small>
      </div>
      <div class="mcp-service-item">
-        <span>예시</span>
-        <strong><code>/mcp/vpd-live/sse</code></strong>
-        <small>SSE 연결 시 message endpoint가 같은 context로 반환됩니다.</small>
+        <span>도구 수</span>
+        <strong>3개</strong>
+        <small>용어 표준화 → HR 데이터/규정 검색 순서로 사용합니다.</small>
      </div>
    </div>
  </section>
@@ -46,28 +46,20 @@
      <table class="table align-middle">
        <tbody>
        <tr>
-          <th>Default SSE</th>
-          <td><code>/mcp/sse</code></td>
+          <th>HMM MCP</th>
+          <td><code th:text="${hmmMcpPublicUrl}">https://hmm-mcp.cloud-handson.com/mcp</code></td>
        </tr>
        <tr>
-          <th>Default Message</th>
-          <td><code>/mcp/messages?sessionId={sessionId}</code></td>
+          <th>Transport</th>
+          <td>Streamable HTTP</td>
        </tr>
        <tr>
-          <th>Context SSE</th>
-          <td><code>/mcp/{contextPath}/sse</code></td>
-        </tr>
-        <tr>
-          <th>Context Message</th>
-          <td><code>/mcp/{contextPath}/messages?sessionId={sessionId}</code></td>
-        </tr>
-        <tr>
-          <th>Context Path</th>
-          <td>영문/숫자로 시작하고 영문/숫자/<code>_</code>/<code>-</code>만 사용합니다. 예: <code>vpd</code>, <code>ords-prod</code></td>
+          <th>백오피스 호환 Endpoint</th>
+          <td><code>/mcp</code> — 로그인 세션에서 같은 HMM 도구 계약을 확인합니다.</td>
        </tr>
        <tr>
          <th>Auth</th>
-          <td><code>Authorization: Bearer &lt;사용자 Bearer Token&gt;</code> — 이 토큰 하나로 행 접근 컨텍스트를 설정합니다.</td>
+          <td><code>Authorization: Bearer &lt;HMM MCP Token&gt;</code> — 공개 MCP 서버의 고정 인증 토큰입니다.</td>
        </tr>
        <tr>
          <th>Methods</th>
@@ -87,7 +79,7 @@
        <tr>
          <th>Name</th>
          <th>Object</th>
-          <th>ORDS Path</th>
+          <th>Agent Tool</th>
          <th>Instruction / parameter mapping</th>
        </tr>
        </thead>
@@ -95,11 +87,11 @@
        <tr th:each="tool : ${tools}">
          <td><code th:text="${tool.name()}">ords.query.admin.board_posts</code></td>
          <td th:text="${tool.displayName()}">ADMIN.BOARD_POSTS</td>
-          <td><code th:text="${tool.ordsPath()}">cb-ords/cb-object-query/admin/board_posts</code></td>
+          <td><code th:text="${tool.ordsPath()}">HMM_HR_TERM_RESOLVER</code></td>
          <td>
            <div th:text="${tool.description()}">ORDS 행 접근 조회 도구 설명</div>
            <small class="text-muted">
-              HTTP <code>Authorization</code> → 행 접근 컨텍스트 · <code>prompt</code> → GPT-5.4-mini Select AI 자연어 질의 · <code>limit</code> → 최대 반환 행 수
+              <code>resolve_hr_term.term</code> → 표준 용어·코드 · <code>search_hr_data.query</code> → HR 데이터 · <code>search_hr_policy.query</code> → 규정 PDF 검색
            </small>
          </td>
        </tr>
@@ -116,10 +108,9 @@
      <summary>tools/call parameter 예시 보기</summary>
      <h2>tools/call Arguments</h2>
      <pre class="code-block">{
-  "prompt": "KB_CLAIMS의 전체 청구 건수를 조회해 줘.",
-  "limit": 50
+  "term": "연차 이월"
 }</pre>
-      <p class="form-hint">등록 tool은 <code>ords.query.kb_select_ai_vpd</code> 하나입니다. HTTP Authorization의 사용자 Bearer Token으로 컨텍스트를 설정한 뒤 GPT-5.4-mini가 comment, annotation, constraint를 참고해 생성한 검증된 읽기 전용 KB 원장 SQL만 실행합니다.</p>
+      <p class="form-hint">등록 도구는 <code>resolve_hr_term</code>, <code>search_hr_data</code>, <code>search_hr_policy</code>입니다. 표준 용어가 필요한 질문은 <code>resolve_hr_term</code> 결과를 사용해 데이터 또는 규정 검색을 이어갑니다.</p>
    </details>
  </section>

@@ -153,10 +144,9 @@
  "id": 3,
  "method": "tools/call",
  "params": {
-    "name": "ords.query.kb_select_ai_vpd",
+    "name": "search_hr_policy",
    "arguments": {
-      "prompt": "KB_CLAIMS의 전체 청구 건수를 조회해 줘.",
-      "limit": 50
+      "query": "연차 휴가 이월 기준과 제한을 알려줘."
    }
  }
 }</pre>
--- a/src/main/resources/templates/settings.html
+++ b/src/main/resources/templates/settings.html
@@ -8,7 +8,7 @@
    <h1>시스템 설정</h1>
    <details class="explanation-details">
      <summary>도움말</summary>
-      <p>여기서는 ORDS Base URL만 저장합니다. VPD runtime, grant, 지원 테이블 생성처럼 DB에 영향을 주는 작업은 <strong>DB 준비 상태</strong>에서 별도로 확인·실행합니다.</p>
+      <p>HMM HR 질의와 Agent Factory는 HMM MCP를 사용합니다. ORDS는 기존 VPD/ORDS 운영 기능이 필요한 경우에만 별도로 설정합니다.</p>
    </details>
  </div>

@@ -22,18 +22,33 @@
  <section class="content-band">
    <div class="section-heading">
      <div>
-        <span class="architecture-kicker">ORDS 연결</span>
+        <span class="architecture-kicker">HMM MCP · 현재 사용</span>
+        <h2>HMM HR Agent 도구</h2>
+        <p class="section-subtitle">용어 정규화, HR 데이터 조회, HR 정책 문서 검색은 이 MCP의 DBMS_CLOUD_AI_AGENT 도구를 사용합니다.</p>
+      </div>
+    </div>
+    <label class="span-2">
+      Public MCP endpoint
+      <input class="form-control" th:value="${hmmMcpPublicUrl}" readonly aria-readonly="true">
+    </label>
+    <p class="form-help">Agent Factory 등록 주소: <code th:text="${hmmMcpPublicUrl}">https://hmm-mcp.cloud-handson.com/mcp</code></p>
+  </section>
+
+  <section class="content-band">
+    <div class="section-heading">
+      <div>
+        <span class="architecture-kicker">선택형 레거시 연동</span>
        <h2>ORDS Base URL</h2>
-        <p class="section-subtitle">저장 후 접근 검증과 조회 연동이 이 주소를 사용합니다.</p>
+        <p class="section-subtitle">기존 VPD/ORDS 접근 검증과 ORDS Handler 운영에만 사용합니다. 비워 두면 해당 기능은 미설정 상태로 표시되며 HMM HR 질의에는 영향이 없습니다.</p>
      </div>
    </div>
    <form method="post" action="/settings/ords" class="form-grid">
      <input type="hidden" th:name="${_csrf.parameterName}" th:value="${_csrf.token}">
      <label class="span-2">
-        Base URL
-        <input class="form-control" name="ordsBaseUrl" th:value="${ordsBaseUrl}" required inputmode="url" autocomplete="url">
+        Legacy ORDS Base URL
+        <input class="form-control" name="ordsBaseUrl" th:value="${ordsBaseUrl}" inputmode="url" autocomplete="url" placeholder="설정하지 않음">
      </label>
-      <button class="btn rw-btn-primary" type="submit">연결 주소 저장</button>
+      <button class="btn rw-btn-secondary" type="submit">레거시 ORDS 설정 저장</button>
    </form>
  </section>