Initial commit

2026-08-14 18:16:14 +09:00
commit 22f4fab58d
656 changed files with 22614 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,268 @@
+# DAP WAS Tool Pods
+
+신한라이프 업무 시스템과 MCP(Model Context Protocol) 클라이언트를 연결하는 독립형 Tool WAS 프로젝트입니다. 이 저장소에는 Gateway가 포함되어 있지 않습니다. 각 Tool Pod가 직접 MCP Streamable HTTP와 REST 실행 API를 제공하고, 업무 요청은 `UseCase → Converter → MCI/EAI 연동`으로 처리합니다.
+
+> 이 문서는 현재 `main`의 구현과 설정을 기준으로 합니다. 과거 `dap-gateway`, Chat API, SSE, 외부 Tool Registry/Heartbeat 관련 문서는 현재 저장소의 동작 범위가 아니므로 포함하지 않습니다.
+
+## 구성
+
+```text
+MCP Client
+  ├─ Streamable HTTP: /mcp
+  └─ REST: POST /mcp/{tool-name}
+          │
+          ▼
+Tool Pod (dap-was-oth 또는 dap-was-sms)
+  │
+  ├─ LocalToolScanner: @McpTool / @McpFunction 메타데이터 생성
+  ├─ BusinessToolController: 입력 검증·DTO 변환·동적 실행
+  ├─ ToolManifestController: /tool-manifest 제공
+  └─ UseCase → Converter → MCI/EAI Client → 대상 시스템
+```
+
+## Gradle 모듈
+
+| 모듈 | 역할 | 기본 포트 |
+|---|---|---:|
+| `dap-was-lib` | MCP 어노테이션, 스캐너, 실행 Controller, Manifest, Schema, MCI/EAI/로깅/보안 공통 기능 | - |
+| `dap-was-oth` | 공통·기타·샘플·SOL 업무 Tool Pod | 8084 |
+| `dap-was-sms` | SMS/알림 업무 Pod | 8082 |
+
+기술 기준은 Java 21, Spring Boot 4.0.5, Gradle Wrapper 8.14.3, Spring AI MCP Server WebMVC, Redis, MapStruct, MyBatis, Resilience4j입니다.
+
+## 현재 제공 API
+
+아래 API는 각 Tool Pod가 직접 제공합니다. OTH Pod의 로컬 주소는 `http://localhost:8084`, SMS Pod는 `http://localhost:8082`입니다.
+
+| 목적 | 메서드 | 경로 | 구현 |
+|---|---|---|---|
+| MCP Streamable HTTP 전송 | MCP 프로토콜 | `/mcp` | `ToolMcpServerConfiguration` |
+| Pod에서 스캔한 Tool 메타데이터 조회 | `GET` | `/mcp/api/v1/tools/local` | `BusinessToolController` |
+| 이름으로 Tool 직접 실행 | `POST` | `/mcp/{name}` | `BusinessToolController` |
+| Pod 소유 Manifest 조회 | `GET` | `/tool-manifest` | `ToolManifestController` |
+
+`GET /tool-manifest`는 `If-None-Match` 요청 헤더를 지원하며, 내용이 바뀌지 않으면 `304 Not Modified`를 반환합니다. 응답에는 bundle ID, revision, Tool 목록, 입력 Schema, 실행 endpoint, annotation/meta 정보가 포함됩니다. Manifest는 `LocalToolScanner`의 전체 스캔 목록을 사용하므로 `visible = false` 또는 `register = false`인 항목도 포함될 수 있습니다.
+
+`GET /mcp/api/v1/tools/local`은 Manifest 검증이나 MCP 세션을 열지 않고, 현재 Pod에서 스캔한 `ToolMetadata` 목록을 반환합니다.
+
+### REST 실행 예시
+
+Tool 이름은 `@McpFunction.name` 값입니다. 예를 들어 OTH Pod의 `oth.smp.weather.inquiry`는 다음처럼 호출합니다.
+
+```powershell
+$headers = @{
+  'trace-id' = 'trace-local-001'
+  'request-id' = 'request-local-001'
+}
+
+Invoke-RestMethod `
+  -Method Post `
+  -Uri 'http://localhost:8084/mcp/oth.smp.weather.inquiry' `
+  -Headers $headers `
+  -ContentType 'application/json' `
+  -Body '{"city":"Seoul"}'
+```
+
+Controller는 이름을 찾은 뒤 요청 JSON을 첫 번째 DTO 매개변수로 변환합니다. 입력 Schema 검증 실패는 `422 INVALID_PARAM`, 존재하지 않는 Tool은 `404 TOOL_NOT_FOUND`, 실행 예외는 `502 TOOL_ERROR` 응답입니다. `trace-id`와 `request-id`는 성공 응답 헤더로 다시 전달됩니다.
+
+## Tool 검색과 MCP 노출 규칙
+
+애플리케이션 기동 시 `LocalToolScanner`는 Spring Bean에서 `@McpTool`과 `@McpFunction` 메타데이터를 읽어 로컬 Tool 목록을 만듭니다. 기동 완료 후 `ToolPodMcpToolSynchronizer`는 이 목록 중 `visible = true`인 Tool만 MCP SDK 서버에 추가합니다.
+
+| 속성 | 현재 구현에서의 의미 |
+|---|---|
+| `visible` | `false`이면 MCP SDK의 Tool 등록에서 제외됩니다. |
+| `register` | 스캐너 메타데이터의 `isRegistered` 값과 내부 `registeredTools` 목록에만 반영됩니다. 현재 저장소에는 외부 Registry 전송 구현이 없습니다. |
+| `namespace` | 비어 있지 않으면 Tool 이름 앞에 `{namespace}_`가 붙습니다. 기본 설정은 빈 문자열입니다. |
+| `enabled` | Manifest의 `_meta.enabled` 값으로 노출됩니다. 현재 synchronizer는 이 값으로 별도 필터링하지 않습니다. |
+| `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` | MCP Tool annotation과 Manifest annotation에 반영됩니다. |
+
+`POST /mcp/{name}`의 동적 실행은 `visible` 및 `register` 값으로 차단하지 않습니다. 따라서 직접 호출을 막아야 하는 Tool은 네트워크 경계와 별도 인증·인가 정책으로 보호해야 합니다.
+
+### 현재 Tool 선언 현황
+
+`dap-was-oth`에는 실제 `@McpFunction` 선언이 17개 있습니다. 도메인은 다음과 같습니다.
+
+| 도메인 | 예시 Tool 이름 | 내용 |
+|---|---|---|
+| `cmm` | `oth.cmm.claim.search`, `oth.cmm.customer.detail`, `oth.cmm.meta.table` | 공통·고객·계약·청구·메타 기능 |
+| `smp` | `oth.smp.weather.inquiry`, `oth.smp.exchange-rate.inquiry` | 샘플·조회 기능 |
+| `sol` | `oth.sol.request.list`, `oth.sol.request.detail` | SOL 요청 조회 |
+
+`dap-was-oth`에는 `categoryKey = "oth"`인 `Onnba3011UseCase`도 있으나, 현재 `@McpFunction` 선언은 없습니다. `dap-was-sms`도 `@McpTool(routingType = "EAI", categoryKey = "notification")`은 선언되어 있지만, `SmsToolUseCase`/구현체에 `@McpFunction`이 없습니다. 따라서 현 상태에서 두 영역은 스캐너, `/tool-manifest`, MCP SDK에 노출되는 호출 가능 Tool을 만들지 않습니다. MCP Tool로 제공하려면 각 계약 메서드에 `@McpFunction`을 선언해야 합니다.
+
+## Tool 개발 방식
+
+Tool 그룹은 인터페이스에 `@McpTool`, Agent가 호출하는 메서드는 `@McpFunction`을 선언합니다. `@McpTool`은 Spring `@Component` 별칭이므로 Tool 인터페이스와 구현체는 Spring Bean으로 구성되어야 합니다.
+
+```java
+@McpTool(routingType = "MCI", categoryKey = "claim")
+public interface ClaimInquiryUseCase {
+
+    @McpFunction(
+        name = "oth.claim.inquiry.detail",
+        displayName = "청구 상세 조회",
+        description = "청구 번호로 청구 상세를 조회합니다.",
+        mappingId = "CLM00000001",
+        readOnlyHint = true
+    )
+    ClaimInquiryResponse inquire(ClaimInquiryRequest request);
+}
+```
+
+구현체에는 업무 흐름만 두고, Tool DTO와 레거시 인터페이스 DTO의 변환은 Converter에 둡니다.
+
+```java
+@Service
+@RequiredArgsConstructor
+class ClaimInquiryUseCaseImpl implements ClaimInquiryUseCase {
+    private final ClaimInquiryConverter converter;
+    private final MciClaimClient client;
+
+    @Override
+    public ClaimInquiryResponse inquire(ClaimInquiryRequest request) {
+        ClaimMciRequest legacyRequest = converter.toMciRequest(request);
+        ClaimMciResponse legacyResponse = client.call(legacyRequest);
+        return converter.toResponse(legacyResponse);
+    }
+}
+```
+
+`@McpFunction.name`은 소문자 점 표기 형식으로 작성합니다. 현재 선언은 `oth.cmm.claim.search`, `oth.smp.weather.inquiry`처럼 `{pod}.{domain}.{service}.{action}` 패턴을 사용합니다. `validateMcpToolNames` Gradle 작업은 모든 Tool 모듈을 대상으로 이름 형식과 중복을 검사하며, 패키징 빌드 전에 실행됩니다.
+
+## Input/Output Schema
+
+입력 Schema는 다음 우선순위로 결정됩니다.
+
+1. `inputSchemaResource`에 지정한 classpath JSON Schema
+2. `inputSchema`에 인라인으로 지정한 JSON Schema
+3. 요청 DTO의 `@McpValidation`을 이용한 자동 생성 Schema
+
+출력 검증은 선택 사항입니다. 다음 중 하나가 있을 때만 반환값을 검증합니다.
+
+1. `outputSchemaResource`
+2. `outputSchema`
+3. 반환 DTO의 `@McpOutputSchema`와 `@McpValidation`
+
+복잡한 Schema 리소스는 Tool 모듈에 둡니다. 현재 OTH의 청구 검색 예제는 다음 리소스를 사용합니다.
+
+```text
+dap-was-oth/src/main/resources/tool-schemas/cmm/
+├─ claim-search-resource-input-schema.json
+└─ claim-search-resource-output-schema.json
+```
+
+입력 검증에는 JSON Schema Draft 7이 사용됩니다. 출력 Schema 검증에 실패하면 `500 INVALID_TOOL_RESPONSE`을 반환합니다.
+
+## 로컬 실행
+
+### 사전 조건
+
+- JDK 21
+- Docker (Redis 또는 MCI mock을 사용할 경우)
+- Gradle Wrapper 사용 권장
+
+로컬 프로필은 기본값이며, 두 Pod 모두 H2 메모리 DB와 P6Spy를 설정합니다. Pod URL은 `AXHUB_TOOL_URL` 환경 변수로 설정하며, 지정하지 않으면 해당 `server.port`의 localhost 주소를 사용합니다.
+
+```powershell
+# 필수: Redis 기동 (캐시 및 세션 처리용)
+$env:ACTIVE_PROFILE = 'local'
+docker compose up -d redis
+
+# OTH Tool Pod 실행
+$env:SPRING_PROFILES_ACTIVE = 'local'
+$env:AXHUB_TOOL_URL = 'http://localhost:8084'
+.\gradlew.bat :dap-was-oth:bootRun
+
+# SMS Tool Pod 실행 (별도 PowerShell)
+$env:SPRING_PROFILES_ACTIVE = 'local'
+$env:AXHUB_TOOL_URL = 'http://localhost:8082'
+.\gradlew.bat :dap-was-sms:bootRun
+```
+
+실행 후 OTH Pod에서 다음 URL로 현재 스캔된 메타데이터와 Manifest를 확인할 수 있습니다.
+
+```text
+http://localhost:8084/mcp/api/v1/tools/local
+http://localhost:8084/tool-manifest
+http://localhost:8084/tool-test-console.html
+```
+
+`tool-test-console.html`은 공통 라이브러리의 정적 리소스입니다. `/tool-manifest`에서 Tool과 입력 Schema를 읽어 요청 JSON을 만들고, 현재 Pod의 `/mcp/{toolName}`으로 호출합니다. 저장한 테스트 케이스는 브라우저 `localStorage`에 보관됩니다.
+
+## 테스트와 빌드
+
+```powershell
+# 전체 테스트
+.\gradlew.bat test
+
+# 공통 라이브러리 테스트
+.\gradlew.bat :dap-was-lib:test
+
+# OTH Tool 테스트
+.\gradlew.bat :dap-was-oth:test
+
+# Tool 이름 규칙 및 중복 검증
+.\gradlew.bat validateMcpToolNames
+
+# 패키징 전 전체 빌드
+.\gradlew.bat clean build
+```
+
+테스트는 공통 MCP Schema/Manifest/Header 처리, Glow MCI 파서, Tool 이름 검증과 OTH의 청구·SOL·MCI 변환을 다룹니다. SMS 모듈에는 현재 별도 테스트 소스가 없습니다.
+
+## Docker Compose
+
+현재 Compose 서비스와 호스트 포트는 다음과 같습니다.
+
+| 서비스 | 컨테이너 포트 | 호스트 포트 |
+|---|---:|---:|
+| `redis` | 6379 | 6379 |
+| `was-sms` | 8082 | 8282 |
+| `was-oth` | 8084 | 8284 |
+
+Compose의 Pod URL은 컨테이너 DNS 이름을 사용합니다.
+
+```text
+was-sms: http://was-sms:8082
+was-oth: http://was-oth:8084
+```
+
+### Docker 컨테이너 기동
+
+별도의 CI/CD 러너나 외부 의존성(MCI Mock 등) 없이 독립적으로 실행 가능하도록 구성되어 있습니다. `docker-compose.yml`을 통해 Redis 및 각 Pod 컨테이너를 구동할 수 있습니다.
+
+
+## 설정
+
+| 설정 | 위치/환경 변수 | 설명 |
+|---|---|---|
+| Pod 포트 | `server.port` 또는 `PORT` | SMS 8082, OTH 8084 |
+| Pod 외부 URL | `AXHUB_TOOL_URL` | 스캐너가 Tool endpoint를 만들 때 사용 |
+| MCP namespace | `mcp.namespace` | Tool 이름 앞에 `{namespace}_`를 붙임 |
+| Manifest bundle | `mcp.manifest.bundle-id` | SMS는 `tool-sms`, OTH는 `tool-oth` |
+| Manifest 이름 접두사 | `mcp.manifest.name-prefix` | 지정 시 모든 Manifest Tool 이름이 이 접두사로 시작해야 함 |
+| 활성 프로필 | `SPRING_PROFILES_ACTIVE` | 기본값 `local`, 선택값 `dev` |
+
+`mcp.security.tenant-domains` 설정은 각 Pod의 YAML에 존재하지만, 현재 `McpProperties`와 `BusinessToolController`에는 이를 이용해 호출을 차단하는 로직이 없습니다. 문서상 권한 기능으로 간주하지 말고, 운영 노출 시 별도 인증·인가 계층을 적용해야 합니다.
+
+## 보안과 운영 주의사항
+
+- `BusinessToolController`는 요청 파라미터와 결과를 로그로 남깁니다. Tool 입력·응답에는 주민번호, 계좌번호, 전화번호, 인증값 등 민감정보를 포함하지 않도록 설계하고 공통 마스킹 적용 여부를 검토해야 합니다.
+- `employee-id` 헤더는 Controller가 수신하지만 현재 실행 로직에서 사용하지 않습니다. 이 헤더만으로 인증·인가가 수행된다고 가정하면 안 됩니다.
+- `mcp.security.tenant-domains`, `requiresApproval`, `register`는 현재 독립 WAS에서 실행 차단 정책을 구현하지 않습니다.
+- 외부 MCI/EAI 대상은 local/dev 설정과 실제 네트워크 정책을 별도로 점검해야 합니다.
+
+## 참고 소스
+
+| 주제 | 위치 |
+|---|---|
+| REST 실행 및 로컬 목록 | `dap-was-lib/src/main/java/io/shinhanlife/dap/lib/presentation/BusinessToolController.java` |
+| Manifest API | `dap-was-lib/src/main/java/io/shinhanlife/dap/lib/presentation/ToolManifestController.java` |
+| MCP Streamable HTTP | `dap-was-lib/src/main/java/io/shinhanlife/dap/lib/mcp/ToolMcpServerConfiguration.java` |
+| MCP Tool 동기화 | `dap-was-lib/src/main/java/io/shinhanlife/dap/lib/mcp/ToolPodMcpToolSynchronizer.java` |
+| Tool 스캔 | `dap-was-lib/src/main/java/io/shinhanlife/dap/lib/usecase/LocalToolScanner.java` |
+| Tool 어노테이션 | `dap-was-lib/src/main/java/io/shinhanlife/dap/lib/annotation/McpTool.java`, `McpFunction.java` |
+| OTH 업무 Tool | `dap-was-oth/src/main/java/io/shinhanlife/dap/mcc/biz/` |
+| SMS Tool | `dap-was-sms/src/main/java/io/shinhanlife/dap/mcc/biz/sms/` |
+| 컨테이너 구성 | `docker-compose.yml`, `dap-was-oth/Dockerfile`, `dap-was-sms/Dockerfile` |