AX-HUB/dap-was-dapmt
10
0
Fork 0
forked from kimhyungsik/ax_hub_mcp_tool
Code Pull Requests Actions Activity

fix: safely rename dasmt to datmt without breaking encoding
All checks were successful
Deploy Tools / deploy (push) Successful in 2m46s
Details

Browse Source
This commit is contained in:
jade
2026-08-31 15:55:43 +09:00
parent cd991bd623
commit 42a04c03fd
11 changed files with 63 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
README.md
View File

@@ -1,8 +1,8 @@
# DASMT MCP Tool Pods
# DATMT MCP Tool Pods
신한라이프 업무 기능을 MCP(Model Context Protocol) Tool로 제공하는 Java 멀티 모듈 프로젝트입니다. 각 업무 모듈은 독립 실행 가능한 Spring Boot 애플리케이션이며, MCP Streamable HTTP와 REST 실행 API를 함께 제공합니다.
이 저장소에는 DATMS(Gateway) 애플리케이션이 포함되어 있지 않습니다. DASMT는 Gateway로 Tool을 push 등록하지 않으며, 각 Pod가 `GET /tool-manifest`를 제공하면 DATMS가 이 Manifest를 pull하여 Tool 목록을 구성합니다. Tool 조회와 직접 실행은 각 Pod에서도 자체적으로 처리합니다.
이 저장소에는 DATMS(Gateway) 애플리케이션이 포함되어 있지 않습니다. DATMT는 Gateway로 Tool을 push 등록하지 않으며, 각 Pod가 `GET /tool-manifest`를 제공하면 DATMS가 이 Manifest를 pull하여 Tool 목록을 구성합니다. Tool 조회와 직접 실행은 각 Pod에서도 자체적으로 처리합니다.
## 기술 기준
@@ -60,20 +60,20 @@ Tool Pod
4. `ToolPodMcpToolSynchronizer`가 Tool을 MCP SDK 서버에 등록합니다.
5. REST와 MCP 요청은 공통 `McpToolExecutionService`를 통해 실행됩니다.
DASMT 내부에는 `/registry/register`, `/registry/deregister` 호출이나 주기적인 Gateway heartbeat 전송이 없습니다. `ToolRegistryHeartbeatSender`라는 클래스명은 호환성을 위해 남아 있지만 현재 역할은 로컬 Tool 스캔과 메타데이터 생성뿐입니다.
DATMT 내부에는 `/registry/register`, `/registry/deregister` 호출이나 주기적인 Gateway heartbeat 전송이 없습니다. `ToolRegistryHeartbeatSender`라는 클래스명은 호환성을 위해 남아 있지만 현재 역할은 로컬 Tool 스캔과 메타데이터 생성뿐입니다.
### DATMS 연동 방식
```text
DATMS
└─ GET {DASMT Pod URL}/tool-manifest
└─ GET {DATMT Pod URL}/tool-manifest
└─ bundleId + revision + tools[]
└─ 각 Tool endpoint: {Pod URL}/mcp/{toolName}
```
- `mcp.manifest.bundle-id`는 Manifest를 제공하는 Pod의 고유 식별자이며 필수입니다.
- 현재 값은 `was-sal`, `was-cus`, `was-pro`, `was-sys`입니다.
- DATMS에 설정한 bundle ID와 DASMT가 반환하는 `bundleId`가 일치해야 같은 Tool bundle로 관리됩니다.
- DATMS에 설정한 bundle ID와 DATMT가 반환하는 `bundleId`가 일치해야 같은 Tool bundle로 관리됩니다.
- `mcp.manifest.name-prefix`가 비어 있지 않으면 모든 Tool 이름이 해당 prefix로 시작해야 합니다.
- Manifest 내용이 바뀌면 `revision`이 증가하며, `If-None-Match`가 일치하면 `304 Not Modified`를 반환합니다.
@@ -104,7 +104,7 @@ $headers = @{
'X-Request-Id' = 'request-local-001'
'X-Request-Time' = '2026-08-25T12:34:56+09:00'
'X-Vrtl-Praf-No' = 'V100001'
'X-App-Code' = 'DASMT'
'X-App-Code' = 'DATMT'
'X-Project-Code' = 'AXHUB'
'X-User-Ip' = '10.0.0.10'
'X-Caller-Ip' = '10.0.0.20'
@@ -124,11 +124,11 @@ Invoke-RestMethod `
### 요청 헤더 계약
DATMS가 DASMT Tool Service를 호출할 때 사용하는 헤더는 다음과 같습니다. HTTP 헤더 이름은 대소문자를 구분하지 않지만, 문서와 구현에서는 아래 표기를 기준으로 사용합니다.
DATMS가 DATMT Tool Service를 호출할 때 사용하는 헤더는 다음과 같습니다. HTTP 헤더 이름은 대소문자를 구분하지 않지만, 문서와 구현에서는 아래 표기를 기준으로 사용합니다.
| 헤더 | 필수 여부 | 용도 | 전달 동작 |
|---|---|---|---|
| `X-Tool-Server-API-Key` | 인증 설정 시 필수 | DATMS와 DASMT 사이의 Tool Server 인증 | `mcp.security.api-key` 또는 `api-keys`와 비교 |
| `X-Tool-Server-API-Key` | 인증 설정 시 필수 | DATMS와 DATMT 사이의 Tool Server 인증 | `mcp.security.api-key` 또는 `api-keys`와 비교 |
| `X-Guid` | 선택 | 업무 호출 상관관계 식별자 | 실행 로그, 성공 응답, 하위 HTTP 호출로 전달 |
| `X-Praf-No` | 선택 | 실제 사용자 사번 | 세션 조회와 하위 HTTP 호출로 전달 |
| `X-Request-Id` | 선택 | 요청 추적 식별자 | 실행 로그, 성공 응답, 하위 HTTP 호출로 전달 |
@@ -261,7 +261,7 @@ http://localhost:8086/swagger-ui/index.html
| `PORT` | Pod 수신 포트 | 모듈별 기본 포트 |
| `TOOL_SERVER_API_KEY` | DATMS가 `X-Tool-Server-API-Key`로 전달할 공통 인증 Key | `tool-server-key` |
| `AXHUB_TOOL_URL` | Manifest의 Tool endpoint 생성에 사용할 Pod 외부 URL | `http://localhost:${server.port}` |
| `AXHUB_GATEWAY_URL` | 프로필 및 Compose 호환용 Gateway URL. 현재 DASMT의 push 등록에는 사용하지 않음 | `http://localhost:8081` |
| `AXHUB_GATEWAY_URL` | 프로필 및 Compose 호환용 Gateway URL. 현재 DATMT의 push 등록에는 사용하지 않음 | `http://localhost:8081` |
| `SPRING_DATA_REDIS_HOST` | Redis 호스트 | `localhost` |
| `SPRING_DATA_REDIS_PORT` | Redis 포트 | `6379` |
| `GLOW_COMMUNICATION_MCI_HOST` | MCI 대상 호스트 | 프로필별 설정 |
@@ -338,7 +338,7 @@ mcp:
## Docker Compose
`docker-compose.yml`은 DASMT의 네 업무 Pod만 정의합니다.
`docker-compose.yml`은 DATMT의 네 업무 Pod만 정의합니다.
| 서비스 | 컨테이너 포트 | 호스트 포트 |
|---|---:|---:|
@@ -358,14 +358,14 @@ Compose 파일의 용도와 현재 주의점은 다음과 같습니다.
| 파일 | 용도 | 현재 소스 기준 주의점 |
|---|---|---|
| `docker-compose.yml` | DASMT 네 Pod 단독 실행 | `gateway` 서비스가 없지만 push 등록이 제거되어 DASMT 시작에는 필요하지 않음 |
| `docker-compose.local.yml` | DATMS와 DASMT의 로컬 통합 구성 | 두 저장소가 같은 상위 디렉터리에 있는 구조를 가정 |
| `docker-compose.prod.yml` | DATMS와 DASMT의 개발 프로필 기반 OCI 구성 | 저장소의 runner 등록 토큰을 운영 Secret으로 분리해야 함 |
| `docker-compose.yml` | DATMT 네 Pod 단독 실행 | `gateway` 서비스가 없지만 push 등록이 제거되어 DATMT 시작에는 필요하지 않음 |
| `docker-compose.local.yml` | DATMS와 DATMT의 로컬 통합 구성 | 두 저장소가 같은 상위 디렉터리에 있는 구조를 가정 |
| `docker-compose.prod.yml` | DATMS와 DATMT의 개발 프로필 기반 OCI 구성 | 저장소의 runner 등록 토큰을 운영 Secret으로 분리해야 함 |
`docker-compose.local.yml`과 `docker-compose.prod.yml`의 build context는 각각 `./dat-was-DATMS`, `./dat-was-dasmt`입니다. 현재 파일 위치에서 사용할 때는 context 기준을 두 저장소의 상위 디렉터리로 맞춰야 합니다.
`docker-compose.local.yml`과 `docker-compose.prod.yml`의 build context는 각각 `./dat-was-DATMS`, `./dat-was-datmt`입니다. 현재 파일 위치에서 사용할 때는 context 기준을 두 저장소의 상위 디렉터리로 맞춰야 합니다.
```powershell
# DASMT 저장소 디렉터리에서 실행
# DATMT 저장소 디렉터리에서 실행
docker compose --project-directory .. -f docker-compose.local.yml up --build
```
@@ -373,7 +373,7 @@ docker compose --project-directory .. -f docker-compose.local.yml up --build
## OpenShift (Kubernetes) 배포
OpenShift 개발 환경용 Kustomize 매니페스트는 [`k8s/`](k8s/)에 있습니다. 대상은 DASMT의 네 Tool Pod뿐이며 DATMS(Gateway)의 Deployment·Service·Route는 이 저장소에서 만들지 않습니다.
OpenShift 개발 환경용 Kustomize 매니페스트는 [`k8s/`](k8s/)에 있습니다. 대상은 DATMT의 네 Tool Pod뿐이며 DATMS(Gateway)의 Deployment·Service·Route는 이 저장소에서 만들지 않습니다.
```text
k8s/
@@ -392,7 +392,7 @@ k8s/
| `was-pro` | 8085 | `http://was-pro:8085` |
| `was-sys` | 8086 | `http://was-sys:8086` |
Gateway가 다른 namespace에 있으면 `was-sal.axhub-dasmt-dev.svc`와 같은 FQDN을 사용하고, NetworkPolicy에서 Gateway namespace의 ingress를 별도로 허용해야 합니다.
Gateway가 다른 namespace에 있으면 `was-sal.axhub-datmt-dev.svc`와 같은 FQDN을 사용하고, NetworkPolicy에서 Gateway namespace의 ingress를 별도로 허용해야 합니다.
### 반영 전 설정
@@ -402,11 +402,11 @@ Gateway가 다른 namespace에 있으면 `was-sal.axhub-dasmt-dev.svc`와 같은
2. [`k8s/base/configmap.yaml`](k8s/base/configmap.yaml)의 `CHANGE_ME` MCI·EXTMCI·EAI 호스트
3. 실제 Secret 값
`dasmt-runtime-secrets` Secret은 Git에 저장하지 않고 OpenShift namespace에서 별도로 생성합니다. 최소한 `TOOL_SERVER_API_KEY`는 DATMS가 전달하는 `X-Tool-Server-API-Key`와 같은 값이어야 합니다. DB 계정·비밀번호, API Key, 인증서 비밀번호 등도 이 Secret으로 관리합니다.
`datmt-runtime-secrets` Secret은 Git에 저장하지 않고 OpenShift namespace에서 별도로 생성합니다. 최소한 `TOOL_SERVER_API_KEY`는 DATMS가 전달하는 `X-Tool-Server-API-Key`와 같은 값이어야 합니다. DB 계정·비밀번호, API Key, 인증서 비밀번호 등도 이 Secret으로 관리합니다.
```powershell
# runtime-secrets.env는 저장소 밖에 보관합니다.
oc -n axhub-dasmt-dev create secret generic dasmt-runtime-secrets `
oc -n axhub-datmt-dev create secret generic datmt-runtime-secrets `
--from-env-file=runtime-secrets.env
```
@@ -422,7 +422,7 @@ Secret이 없으면 각 Deployment의 `envFrom.secretRef`를 해석할 수 없
# OpenShift 로그인 및 project 선택 후
oc kustomize k8s/overlays/dev
oc apply -k k8s/overlays/dev
oc get deployment,pod,svc -n axhub-dasmt-dev
oc get deployment,pod,svc -n axhub-datmt-dev
```
적용 전에는 `oc kustomize k8s/overlays/dev | oc apply --dry-run=client -f -`로 서버 측 스키마 검증을 수행합니다. 현재 매니페스트의 readiness/liveness probe는 TCP 포트 확인 방식입니다. Actuator health endpoint를 추가한 뒤에는 HTTP readiness/liveness probe로 변경하는 것을 권장합니다.
@@ -471,5 +471,5 @@ oc get deployment,pod,svc -n axhub-dasmt-dev
3. `validateMcpToolNames`와 모듈·전체 테스트를 실행합니다. Tool YAML 정의를 추가한 경우에는 V17 항목을 별도 검증합니다.
4. 모듈 테스트와 전체 테스트를 실행합니다.
5. 로컬 Pod에서 `/mcp/api/v1/tools/local`과 `/tool-manifest`를 확인합니다.
6. DATMS의 bundle ID, Pod Manifest URL, Tool Server API Key가 DASMT 설정과 일치하는지 확인합니다.
6. DATMS의 bundle ID, Pod Manifest URL, Tool Server API Key가 DATMT 설정과 일치하는지 확인합니다.
7. REST와 MCP 양쪽에서 동일한 Tool 결과·요청 헤더 전달·오류 계약을 확인합니다.