Pod role	Gradle module	Container service	Internal endpoint	Local Docker endpoint
Customer/common integration	`dap-was-cus`	`was-cus`	`http://was-cus:8084/mcp`	`http://localhost:8284/mcp`
Sales/notification integration	`dap-was-sal`	`was-sal`	`http://was-sal:8082/mcp`	`http://localhost:8282/mcp`
Process integration (new)	`dap-was-pro`	`was-pro`	`http://was-pro:8085/mcp`	`http://localhost:8085/mcp`
System integration (new)	`dap-was-sys`	`was-sys`	`http://was-sys:8086/mcp`	`http://localhost:8086/mcp`

The former dap-was-oth module is now dap-was-cus; the former dap-was-sms module is now dap-was-sal.
This is a deployment Pod rename only. Existing tool category and function names such as oth_* and sms_* remain valid so already registered MCP clients are not broken.
dap-was-pro and dap-was-sys are empty, independently deployable Tool Pods ready for new business tools.

Run the Tool Pods locally

.\gradlew.bat :dap-was-cus:bootRun
.\gradlew.bat :dap-was-sal:bootRun
.\gradlew.bat :dap-was-pro:bootRun
.\gradlew.bat :dap-was-sys:bootRun

AX HUB에서 AI Agent가 업무 Tool을 검색하고 호출할 수 있도록 Gateway와 독립 Tool Pod를 제공하는 멀티 모듈 Spring Boot 프로젝트입니다.

1. 현재 구성

MCP Client / AI Agent
        |
        v
Gateway (dap-gateway, 8081)
  - MCP 연결, Tool Registry, 인증·인가, 라우팅, 공통 화면
        |
        +-------------------------+
        |                         |
        v                         v
SMS Tool Pod (dap-was-sms, 8082)  OTH Tool Pod (dap-was-oth, 8084)
  - SMS 업무 Tool                  - 공통/업무/MCI 연계 Tool
  - Tool Manifest                  - Tool Manifest
  - Pod Test Console               - Pod Test Console
        |
        v
MCI / EAI / EIMS 등 레거시 연계 대상

Gateway는 외부 MCP 진입점과 Tool 등록·라우팅을 담당하고, 실제 업무 로직과 레거시 호출은 각 Tool Pod가 담당합니다. Tool Pod는 업무/조직 단위로 독립 배포할 수 있습니다.

2. 모듈

모듈	역할	기본 포트
`dap-gateway`	MCP Gateway, Registry, 라우팅, Chat·Catalog·Tester·Scaffold 화면	8081
`dap-was-lib`	Tool 공통 라이브러리: 어노테이션, Schema, Manifest, MCI/EAI 어댑터, 공통 Web·보안 기능	-
`dap-was-sms`	SMS/알림 업무 Tool Pod	8082
`dap-was-oth`	공통/샘플/MCI 연계 업무 Tool Pod	8084

기존 dap-tool-core, dap-tool-sms, dap-tool-oth 명칭은 현재 각각 dap-was-lib, dap-was-sms, dap-was-oth로 변경되었습니다.

3. 개발 환경

항목	기준
Java	21
Spring Boot	3.5.11
Gradle	8.14.3 (Wrapper)
Spring AI BOM	1.1.8
기본 프로필	`local`

로컬 환경에서는 민감한 값은 환경 변수로만 주입합니다.

$env:SPRING_PROFILES_ACTIVE = 'local'
$env:OPENROUTER_API_KEY = '<발급받은-키>'

4. 실행

4.1 Gradle 로컬 실행

각 애플리케이션은 별도 터미널에서 실행합니다.

.\gradlew.bat :dap-gateway:bootRun
.\gradlew.bat :dap-was-sal:bootRun
.\gradlew.bat :dap-was-cus:bootRun
.\gradlew.bat :dap-was-pro:bootRun
.\gradlew.bat :dap-was-sys:bootRun

4.2 Docker Compose 실행

docker compose up -d --build

서비스	호스트 URL	컨테이너 포트
Gateway	http://localhost:8281	8081
SMS Tool Pod	http://localhost:8282	8082
OTH Tool Pod	http://localhost:8284	8084
MCI Mock	http://localhost:8089	8080
Dozzle 로그 화면	http://localhost:8288	8080

5. 화면과 운영 도구

Gateway 화면

화면	로컬 URL	용도
메인	http://localhost:8081/index.html	플랫폼 진입 화면
Catalog	http://localhost:8081/catalog.html	등록 Tool 탐색
Playground	http://localhost:8081/playground.html	단건 Tool 호출 확인
Chat	http://localhost:8081/chat.html	Agent 기반 대화형 호출
Auto Tester	http://localhost:8081/tester.html	Gateway 기준 다중 Tool 스모크/회귀 테스트
Scaffold	http://localhost:8081/admin/scaffold.html	Pod·Tool 소스 생성 지원

Docker Compose로 실행한 경우 Gateway 화면은 포트 8281을 사용합니다.

Tool Pod Test Console

공통 정적 화면인 tool-test-console.html은 Tool Pod의 /tool-manifest를 읽어, 해당 Pod에 등록된 Tool과 inputSchema를 기준으로 요청 JSON을 만들어 직접 실행합니다.

대상 Pod	로컬 URL	Docker Compose URL
OTH	http://localhost:8084/tool-test-console.html	http://localhost:8284/tool-test-console.html
SMS	http://localhost:8082/tool-test-console.html	http://localhost:8282/tool-test-console.html

사용 방법은 다음과 같습니다.

대상 Tool Pod의 Console에 접속합니다.
Tool을 선택하고 Schema 샘플 채우기로 요청 JSON을 생성합니다.
업무에 맞는 값으로 보정한 뒤 실행합니다.
재사용할 요청은 현재 요청 저장으로 브라우저 localStorage에 저장합니다.

Gateway Auto Tester

tester.html은 Gateway에 등록된 Tool을 대상으로 다음 기능을 제공합니다.

Tool 목록 자동 조회 및 Tool별 실행
JSON Schema 기반 더미 요청 생성, 사용자 요청 JSON 저장
필터된 Tool 일괄 실행 및 실패 Tool 재실행
결과 차트, 실시간 실행 로그, CSV 내보내기, 호출 예제 복사
Tool별 자동 Ping(3초 간격) 및 Stress Test(현재 50건 동시 요청)

Auto Tester의 더미 요청 성공은 통신·등록·기본 스키마 확인용 스모크 테스트입니다. 실제 MCI/EAI 업무 규칙, 권한, 데이터 정합성은 보장하지 않습니다. Stress Test와 Auto Ping은 실제 Tool·레거시 호출을 유발할 수 있으므로 개발/테스트 환경 및 승인된 테스트 데이터에서만 사용합니다.

UI에서 사용하는 Tailwind CSS와 Chart.js는 dap-gateway/src/main/resources/static/lib에 포함되어 있어, 화면 라이브러리 로딩을 위해 외부 CDN 연결이 필요하지 않습니다.

6. 주요 HTTP API

Gateway API

기능	Method	경로
등록 Tool 목록	GET	`/mcp/api/v1/tools/list`
Gateway를 통한 Tool 호출	POST	`/mcp/api/v1/tools/call`
Tool 문서 Markdown	GET	`/mcp/api/v1/tools/docs/markdown`
Tool 등록	POST	`/mcp/api/v1/registry/register`
Tool 해제	POST	`/mcp/api/v1/registry/deregister`
Heartbeat	POST	`/mcp/api/v1/registry/heartbeat`

호출 본문은 JSON-RPC 형식을 사용합니다.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "cmm_claim_search",
    "arguments": {
      "claimNo": "CLM2026070100120"
    }
  },
  "id": 1
}

Tool Pod API

기능	Method	경로
현재 Pod의 Tool Manifest	GET	`/tool-manifest`
현재 Pod의 로컬 Tool 목록	GET	`/mcp/api/v1/tools/local`
현재 Pod에 직접 Tool 호출	POST	`/mcp/{toolName}`

Agent나 외부 클라이언트의 표준 MCP 진입은 Gateway를 사용합니다. Pod 직접 호출은 개발·단위 테스트·Pod Console 용도로 사용합니다.

7. Tool 개발 규칙

이름

Tool 함수명은 아래 4단계 규칙을 사용합니다.

pod_domain_service_action
예: cmm_claim_search

pod: Tool Pod 식별자 (oth, sms 등)
domain: 업무 도메인 또는 categoryKey (cmm, smp 등)
service: 업무 서비스명
action: 동작 (search, issue, send 등)

기본 구현 계층

Request DTO
  -> UseCase Interface
  -> UseCaseImpl
  -> Converter (AI DTO <-> MCI/EAI Interface IO)
  -> Client / Adapter
  -> Legacy System

Request DTO에는 @McpValidation으로 단순 입력 검증을 선언합니다.
복잡하거나 조건부 규칙이 필요한 입력은 tool-schemas/{categoryKey}/...-input-schema.json 리소스를 사용합니다.
응답은 @McpOutputSchema로 간단한 설명을 제공하고, 복잡한 응답은 Output Schema 리소스로 명시합니다.
null의 업무 의미, 조건부 필드, 배열 정렬 기준, hasMore 여부, 민감 정보 제외 원칙을 Schema 설명에 명확히 씁니다.

Schema 우선순위

inputSchemaResource 또는 outputSchemaResource가 지정된 경우: 해당 JSON Schema를 사용합니다.
리소스가 없으면: DTO 어노테이션(@McpValidation, @McpOutputSchema)과 공통 Generator로 생성합니다.

8. Manifest와 Registry

각 Tool Pod는 기동 시 @McpTool, @McpFunction 정보를 읽어 /tool-manifest를 제공합니다. Manifest에는 Tool 이름, 설명, endpoint, revision, Input/Output Schema가 포함됩니다.

Gateway는 Registry 등록 및 Heartbeat 정보를 이용해 Tool을 라우팅합니다. Tool Pod가 추가되어도 동일한 Manifest/Registry 규약을 준수하면 Gateway에서 탐색·호출할 수 있습니다.

9. MCI/EAI 연계

공통 MCI/EAI 연계 기능과 Glow 기본 설정은 dap-was-lib에서 제공합니다. Tool Pod별 애플리케이션 프로필은 각 Pod의 application*.yml에서 관리합니다.

dap-was-lib/src/main/resources/glow/application-glow*.yml
dap-was-sms/src/main/resources/application*.yml
dap-was-oth/src/main/resources/application*.yml

MCI 호출 주소는 일반적으로 host + uri로 구성합니다. 예를 들어 host=https://dev-ichmci.shinhanlife.co.kr, uri=/ntl_mci/clc_rcv이면 호출 대상은 다음과 같습니다.

https://dev-ichmci.shinhanlife.co.kr/ntl_mci/clc_rcv

receive-uri는 Tool이 호출할 주소가 아니라, MCI가 비동기/콜백 방식으로 응답을 전달하도록 별도 계약된 경우 수신에 사용하는 경로입니다.

10. 품질 검증

.\gradlew.bat :dap-was-lib:test
.\gradlew.bat :dap-was-cus:compileJava
.\gradlew.bat :dap-was-sal:compileJava
.\gradlew.bat :dap-was-pro:compileJava
.\gradlew.bat :dap-was-sys:compileJava
.\gradlew.bat validateMcpToolNames

배포 전에는 다음을 확인합니다.

Tool 이름의 전역 중복 여부와 pod_domain_service_action 규칙(아래 확인 사항 반영 후)
Request/Response Schema 및 실제 예제 JSON
Tool Pod 단위 테스트와 Gateway 경유 호출
MCI/EAI 오류 코드의 사용자용 응답 매핑
민감정보가 요청·응답·로그에 포함되지 않는지
승인된 개발/테스트 계정과 데이터만 사용했는지

11. 보안과 운영 원칙

API Key, Runner 등록 토큰, 계정·비밀번호 등 비밀값은 Git에 넣지 않고 환경 변수 또는 Secret Manager로 주입합니다.
TESTER-DEV 같은 테스트 권한은 개발 환경에서만 허용하고, 운영에서는 Tool 단위 최소 권한으로 제한합니다.
Tool 요청·응답 로그는 마스킹/제외 정책을 거친 값만 남깁니다.
Trace ID는 요청 흐름 전체를 추적하고, Request ID는 HTTP 호출 단위로 새로 부여합니다.
Tool Pod는 업무 소유권과 장애 격리 단위에 맞춰 독립 이미지·배포·운영 책임으로 분리합니다.

12. 참고 소스 위치

기능	위치
Tool 공통 Controller	`dap-was-lib/src/main/java/io/shinhanlife/dap/mcc/presentation`
Tool 어노테이션	`dap-was-lib/src/main/java/io/shinhanlife/dap/lib/annotation`
JSON Schema/검증	`dap-was-lib/src/main/java/io/shinhanlife/dap/lib/schema`, `.../validation`
Manifest	`dap-was-lib/src/main/java/io/shinhanlife/dap/lib/manifest`
Tool Scaffold	`dap-was-lib/src/main/java/io/shinhanlife/dap/lib/util/ToolScaffolder.java`
Gateway 라우터	`dap-gateway/src/main/java/io/shinhanlife/dap/mcg/presentation/McpRouterController.java`
OTH Tool	`dap-was-oth/src/main/java`
SMS Tool	`dap-was-sms/src/main/java`

13. 모듈명 전환 검증

Tool 관련 공통 기능은 dap-was-* 모듈명만 기준으로 동작합니다.

validateMcpToolNames는 dap-was-* Tool Pod를 탐색하여 이름 규칙과 전역 중복을 검사합니다.
Tool Scaffold는 Pod 이름을 Tool 함수명에 포함하지 않습니다. 함수명은 도메인_비즈니스_행위 형식입니다. 예: cmm_notification_send
Pod Scaffold와 Gateway Scaffold 화면/API의 모듈 목록도 dap-was-* 명칭으로 통일되어 있습니다.
Tool Source Update 기능은 dap-was-* 아래의 *UseCase.java를 검색합니다.

14. BC-DAB-STD-003 Tool Schema V17 적용

각 Tool의 표준 명세는 Tool Pod별 다음 경로에서 관리합니다.

dap-was-{pod}/src/main/resources/tool-definitions/{categoryKey}/{toolName}.yml

Tool 이름은 Pod 정보를 포함하지 않는 도메인_서비스_행위 형태의 영문 소문자 snake_case를 사용하며, 정규식 ^[a-z][a-z0-9_]{2,63}$을 만족해야 합니다. 예: cmm_claim_search.

필수 항목은 name, display_name, version, category_key, 설명 4개 요소(function, when_to_use, when_not_to_use, io_limits), display_description, 예시 질의 3~10건, 동작 힌트 3개(read_only, destructive, idempotent), parameters_schema입니다. 입력 Schema는 루트 type: object, 각 property의 description, additionalProperties: false를 갖춰야 합니다. 선택 운영 항목은 tags, legacy_interface_id, required_env_keys, owner_org입니다.

기동 시 tool-definitions/**/*.yml을 한 번 읽어 이름 기준으로 캐시하고, @McpTool 실행 정보와 결합한 동일한 ToolMetadata를 /tool-manifest, Tool Pod MCP, Gateway MCP에 사용합니다.

입력 Schema 우선순위는 inputSchemaResource → V17 parameters_schema → DTO 자동 생성이고, 출력은 outputSchemaResource → 명시 Output Schema → @McpOutputSchema 기반 생성입니다. Output Schema를 명시한 Tool만 최종 응답 검증을 수행합니다.

Scaffold 화면의 Tool Schema V17 Metadata 영역에서는 기능 설명, 사용/비사용 조건, 입출력 제한, 표시 설명, 예시 질의, 태그와 소유 조직을 입력합니다. Java 소스와 함께 V17 YAML이 생성되며, 기본값은 배포 전에 업무 담당자가 실제 의미에 맞게 검토해야 합니다.

.\gradlew.bat validateMcpToolNames validateToolSchemaV17

bootJar는 두 검증에 의존하므로 이름 중복, 필수 항목 누락, Java Tool과 YAML 명세 불일치가 있으면 Docker 이미지 생성 전에 빌드가 실패합니다.