272 lines
11 KiB
Markdown
272 lines
11 KiB
Markdown
# AX HUB MCP Tool Platform
|
|
|
|
AX HUB에서 AI Agent가 업무 Tool을 검색하고 호출할 수 있도록 Gateway와 독립 Tool Pod를 제공하는 멀티 모듈 Spring Boot 프로젝트입니다.
|
|
|
|
## 1. 현재 구성
|
|
|
|
```text
|
|
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` |
|
|
|
|
로컬 환경에서는 민감한 값은 환경 변수로만 주입합니다.
|
|
|
|
```powershell
|
|
$env:SPRING_PROFILES_ACTIVE = 'local'
|
|
$env:OPENROUTER_API_KEY = '<발급받은-키>'
|
|
```
|
|
|
|
## 4. 실행
|
|
|
|
### 4.1 Gradle 로컬 실행
|
|
|
|
각 애플리케이션은 별도 터미널에서 실행합니다.
|
|
|
|
```powershell
|
|
.\gradlew.bat :dap-gateway:bootRun
|
|
.\gradlew.bat :dap-was-sms:bootRun
|
|
.\gradlew.bat :dap-was-oth:bootRun
|
|
```
|
|
|
|
### 4.2 Docker Compose 실행
|
|
|
|
```powershell
|
|
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 |
|
|
|
|
사용 방법은 다음과 같습니다.
|
|
|
|
1. 대상 Tool Pod의 Console에 접속합니다.
|
|
2. Tool을 선택하고 `Schema 샘플 채우기`로 요청 JSON을 생성합니다.
|
|
3. 업무에 맞는 값으로 보정한 뒤 실행합니다.
|
|
4. 재사용할 요청은 `현재 요청 저장`으로 브라우저 `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 형식을 사용합니다.
|
|
|
|
```json
|
|
{
|
|
"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단계 규칙을 사용합니다.
|
|
|
|
```text
|
|
pod_domain_service_action
|
|
예: cmm_claim_search
|
|
```
|
|
|
|
- `pod`: Tool Pod 식별자 (`oth`, `sms` 등)
|
|
- `domain`: 업무 도메인 또는 `categoryKey` (`cmm`, `smp` 등)
|
|
- `service`: 업무 서비스명
|
|
- `action`: 동작 (`search`, `issue`, `send` 등)
|
|
|
|
### 기본 구현 계층
|
|
|
|
```text
|
|
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 우선순위
|
|
|
|
1. `inputSchemaResource` 또는 `outputSchemaResource`가 지정된 경우: 해당 JSON Schema를 사용합니다.
|
|
2. 리소스가 없으면: 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`에서 관리합니다.
|
|
|
|
```text
|
|
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`이면 호출 대상은 다음과 같습니다.
|
|
|
|
```text
|
|
https://dev-ichmci.shinhanlife.co.kr/ntl_mci/clc_rcv
|
|
```
|
|
|
|
`receive-uri`는 Tool이 호출할 주소가 아니라, MCI가 비동기/콜백 방식으로 응답을 전달하도록 별도 계약된 경우 수신에 사용하는 경로입니다.
|
|
## 10. 품질 검증
|
|
|
|
```powershell
|
|
.\gradlew.bat :dap-was-lib:test
|
|
.\gradlew.bat :dap-was-oth:compileJava
|
|
.\gradlew.bat :dap-was-sms: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`를 검색합니다.
|