AX-HUB/dap-was-dapms
10
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs를 저장소로 되돌리고 계약 예제를 복원한다

Browse Source 
5cfb8a1이 .gitignore에 docs/를 넣고 68개 파일을 지웠다. 그런데
AgentBuilderContractExampleTest, ToolBundleContractExampleTest,
ArchitectureDocumentContractTest는 docs/ 아래 계약 예제와 architecture
문서를 입력으로 직접 읽는다. 그 결과 clean clone에서 테스트 10건이
입력을 찾지 못해 실패했다.

제외 범위를 원래 의도대로 좁힌다. 에이전트 산출물(AGENTS.md, .agents/,
.codex/, docs/superpowers/)은 계속 제외하고 저장소 문서는 추적한다.

문서는 삭제 직전 상태(3de052a)를 기준으로 복원하고, 그 위에 main 코드와
대조해 어긋난 부분을 고쳤다.

- ADR-0007을 Superseded로 바꾸고 ADR-0013을 새로 쓴다. route당 Tool
  Service N개가 최종안이며, PortalToolRegistryClient가 이미 route별로
  N개를 유지하고 있는데 ADR-0007은 "bundles는 항상 한 항목"을 Accepted
  상태로 주장하고 있었다. ADR-0009 결정 4도 부분 대체한다.
- ADR-0008 파일 헤더가 Accepted였으나 ADR-0009가 이미 대체한 상태였다.
- 6078852의 endpoint 소유권 반전이 반영되지 않은 서술을 계약 v0.2,
  bundle 설정 예제, Tool 적재 안내에서 고친다.
- Portal registry 계약 v0.1과 route key 규약을 새로 문서화한다. 둘 다
  구현은 있는데 계약 문서가 없었다.
- MCP SDK 2.0.0 SBOM을 추가한다.

번호 주석: ADR-0011과 0012는 feature/mcp-integration이 Tool inputSchema
정책에 쓰고 있어 비워 둔다.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
koseokmin
2026-08-22 23:27:56 +09:00
parent 5a523ab317
commit cb29b192b4
76 changed files with 4626 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
docs/contracts/tool-service-mcp/README.md Normal file
View File

@@ -0,0 +1,39 @@
# Tool Service-MCP 계약 문서
이 디렉터리는 Tool Service와 MCP Server 사이의 metadata 조회·실행 계약을 관리한다.
```text
Agent Builder ──[agent-builder-mcp 계약]──▶ MCP Server ──[tool-service-mcp 계약]──▶ Tool Service
```
| 문서 | 상태 | 용도 |
|---|---|---|
| [protocol-v0.2-bundle-discovery.md](protocol-v0.2-bundle-discovery.md) | Implemented | Tool Service Bundle의 매니페스트 조회·실행 계약. 구현은 N개 Bundle을 지원하지만 운영 배포는 1개로 고정 |
| [tool-list-loading-guide.md](tool-list-loading-guide.md) | Guide | Tool 개발 파트가 현재 최초 적재·memory snapshot·`tools/list` 변환 흐름을 이해하기 위한 안내. 규범 내용은 담지 않고 v0.2를 가리킨다 |
push 등록 방식(v0.1)은 채택하지 않았다. 그 이유는
[v0.2 §2](protocol-v0.2-bundle-discovery.md#2-왜-조회-방식인가-왜-기동-시-1회가-아닌가)에 있다.
## 현재 원칙
- 운영 Tool metadata의 유일한 원천은 각 Tool Service의 매니페스트다.
- `local` profile은 Tool Service 매니페스트를 먼저 조회하고, 최초 실패 시 `config/local-core-tools-manifest-sample-v1.json` fallback을 사용한다.
- 표준 MCP `name`이 `tools/list`와 `tools/call`의 실행 식별자다. Agent Builder UID는 이 계약에 포함하지 않는다.
- Tool Service는 표준 MCP `name`을 선언한다. MCP는 자기 Bundle 안에서 형식·접두사·중복을 검증하며, 서로 다른 MCP 배포 간 전역 유일성은 Tool Service·플랫폼의 변경 절차로 보장한다.
- MCP는 요청 경로에서 in-memory snapshot만 읽는다. Redis는 선택적인 공유 last-good cache다.
- 조회 실패는 Tool 삭제가 아니다. 성공한 매니페스트가 Tool을 제외했을 때만 삭제를 반영한다.
- 불완전한 aggregate, 중복 name, 총량 상한 초과는 현재 snapshot을 교체하지 않는다.
## 예제와 검증
[examples/bundle-v0.2](examples/bundle-v0.2/)의 매니페스트, MCP 설정, Actuator 상태 응답을 계약 테스트가 직접 읽는다.
예제와 구현은 같은 변경에서 함께 수정한다.
운영 적용 전에 Tool 개발 파트와 다음 항목을 확정한다.
1. MCP → Tool 방향 NetworkPolicy와 매니페스트 인증 방식
2. Tool name 변경·폐기 시 rolling 호환 기간
3. `namePrefix`, Tool 수, 매니페스트 크기 상한
4. Tool Service별 timeout과 권한 scope
상세 필드와 장애 처리는 [v0.2 계약](protocol-v0.2-bundle-discovery.md)을 따른다.

54
docs/contracts/tool-service-mcp/examples/bundle-v0.2/bundle-status-response.json Normal file
View File

@@ -0,0 +1,54 @@
{
"bundles": [
{
"bundleId": "insurance-processing",
"enabled": true,
"status": "healthy",
"revision": "sha256:9f2c4a17b83e5d06c1f9a2e7b45d8c30ff1a6b92e4c7d5083a1b6e9f2c4d7a850",
"toolCount": 2,
"consecutiveFailures": 0,
"lastSuccessAt": "2026-07-29T02:29:45Z",
"lastFailureReason": null
},
{
"bundleId": "insurance-corebanking",
"enabled": true,
"status": "degraded",
"revision": "sha256:1d70e6b4c2a89f35e0b7d4816c3a92f5088b1e7d6a4c93520fb8e1d7a6c40395",
"toolCount": 5,
"consecutiveFailures": 1,
"lastSuccessAt": "2026-07-29T02:29:15Z",
"lastFailureReason": "ResourceAccessException"
},
{
"bundleId": "insurance-payment",
"enabled": true,
"status": "degraded",
"revision": "sha256:7e4c81b0f90f4a2c31e7d1086aa9cd31b2f14403e1f0c6633ca2b424e6d4a812",
"toolCount": 3,
"consecutiveFailures": 4,
"lastSuccessAt": "2026-07-29T02:10:00Z",
"lastFailureReason": "ResourceAccessException"
},
{
"bundleId": "insurance-claim",
"enabled": true,
"status": "unreachable",
"revision": null,
"toolCount": 0,
"consecutiveFailures": 2,
"lastSuccessAt": null,
"lastFailureReason": "IllegalStateException"
},
{
"bundleId": "insurance-channel",
"enabled": false,
"status": "disabled",
"revision": null,
"toolCount": 0,
"consecutiveFailures": 0,
"lastSuccessAt": null,
"lastFailureReason": null
}
]
}

97
docs/contracts/tool-service-mcp/examples/bundle-v0.2/manifest-response.json Normal file
View File

@@ -0,0 +1,97 @@
{
"bundleId": "insurance-processing",
"revision": "sha256:9f2c4a17b83e5d06c1f9a2e7b45d8c30ff1a6b92e4c7d5083a1b6e9f2c4d7a850",
"tools": [
{
"name": "processing.contract.inquiry",
"title": "계약 조회",
"description": "계약번호로 계약의 기본 정보를 조회합니다. 사용자가 특정 계약의 상태, 보험료, 계약일을 물어볼 때 사용합니다. 테스트 전용이며 실제 고객 계약 데이터는 처리하지 않습니다.",
"inputSchema": {
"type": "object",
"properties": {
"contractNo": {
"type": "string",
"description": "조회할 계약번호입니다.",
"minLength": 1
}
},
"required": ["contractNo"],
"additionalProperties": false
},
"annotations": {
"title": "계약 조회",
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
},
"_meta": {
"version": "1.2.0",
"endpoint": "/mcp/processing.contract.inquiry",
"timeoutMillis": 3000,
"enabled": true
}
},
{
"name": "processing.payment.history",
"title": "수납 이력 조회",
"description": "계약번호로 수납 이력을 조회합니다. 사용자가 납입 내역이나 미납 여부를 물어볼 때 사용합니다.",
"inputSchema": {
"type": "object",
"properties": {
"contractNo": {
"type": "string",
"description": "조회할 계약번호입니다.",
"minLength": 1
},
"months": {
"type": "integer",
"description": "조회할 최근 개월 수입니다.",
"minimum": 1,
"maximum": 36
}
},
"required": ["contractNo"],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
},
"_meta": {
"version": "1.0.1",
"endpoint": "/mcp/processing.payment.history",
"timeoutMillis": 5000,
"enabled": true
}
},
{
"name": "processing.notice.send",
"title": "안내 발송",
"description": "계약자에게 안내 메시지를 발송합니다. 사용자가 명시적으로 발송을 요청한 경우에만 사용합니다.",
"inputSchema": {
"type": "object",
"properties": {
"contractNo": { "type": "string", "minLength": 1 },
"template": { "type": "string", "enum": ["PAYMENT_DUE", "CONTRACT_EXPIRY"] }
},
"required": ["contractNo", "template"],
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": false
},
"_meta": {
"version": "0.9.0",
"endpoint": "/mcp/processing.notice.send",
"timeoutMillis": 10000,
"enabled": false
}
}
]
}

51
docs/contracts/tool-service-mcp/examples/bundle-v0.2/mcp-bundle-config.yaml Normal file
View File

@@ -0,0 +1,51 @@
# MCP Server의 bundle 조회 설정 예시 (protocol-v0.2-bundle-discovery.md 3절)
#
# 이 파일은 계약 예시이며 실제 적용 설정이 아니다.
# 운영에서는 ConfigMap으로 주입하고 MCP Server마다 다른 bundle 목록을 갖는다.
#
# 키 이름은 구현된 McpProperties와 1:1로 맞춰 두었다. Spring relaxed binding이
# camelCase와 kebab-case를 모두 받으므로 이 문서는 읽기 쉬운 camelCase를 쓴다.
mcp:
# 이 MCP Server의 식별자. Redis key namespace에 사용한다.
identity: mcp-insurance-core
registry:
# 조회 주기와 첫 scheduled refresh 쏠림을 줄이는 지연 jitter. 기동 preload는 즉시 실행한다.
refreshIntervalSeconds: 30
refreshJitterSeconds: 5
discovery:
# 운영 profile에서는 true이고 아래 Tool Service 매니페스트만 원천으로 사용한다.
# false는 local profile의 테스트 JSON에만 사용한다.
enabled: true
connectTimeoutMillis: 1000
readTimeoutMillis: 3000
# 상한. 초과 시 처리는 계약 7절을 따른다.
maxToolsPerBundle: 100
maxToolsTotal: 200
maxManifestBytes: 1048576
# 매니페스트가 선언한 Tool timeout의 상한. 초과분은 절삭한다.
# Tool이 과도한 timeout을 선언해 MCP 스레드를 점유하는 것을 막는다.
maxToolTimeoutMillis: 30000
# 스키마는 N개를 허용하지만 운영 배포에서는 항상 한 항목이다.
# MCP 배포 하나가 Tool Service 하나만 보기 때문이다(ADR-0007).
# 대상을 늘리려면 이 목록이 아니라 MCP 배포를 하나 더 만든다.
bundles:
- id: insurance-processing
# 매니페스트 조회 주소 (MCP -> Tool)
manifestUrl: http://tool-processing.ax-hub.svc.cluster.local:8080/tool-manifest
# 매니페스트의 상대 endpoint를 절대 URL로 바꿀 때 쓰는 기준 주소.
# Pod IP가 아니라 Service URL을 사용한다.
# Tool 실행 주소 자체는 매니페스트의 endpoint 또는 _meta.endpoint가 정한다(ADR-0010).
# 매니페스트가 절대 URL을 쓰면 해석에는 쓰이지 않지만, 그때도 절대 HTTP(S)여야 한다.
baseEndpoint: http://tool-processing.ax-hub.svc.cluster.local:8080/mcp
# Tool Service가 선언한 표준 MCP name이 따라야 할 접두사.
# 업무 단위이며 중요도 등급을 넣지 않는다. 등급이 이름에 들어가면
# Tool 재분류가 Tool name 변경이 되어 Agent Builder 재등록을 부른다.
namePrefix: "processing."
enabled: true

355
docs/contracts/tool-service-mcp/protocol-v0.2-bundle-discovery.md Normal file
View File

@@ -0,0 +1,355 @@
# Tool Service-MCP Bundle 조회 계약 v0.2
- 상태: **Implemented** (MCP 서버 측 구현 완료, Tool Service 측 합의 대기)
- 기준일: 2026-07-30
- 대체 대상: push 등록 방식(v0.1). 채택하지 않은 이유는 §2
- 조회 endpoint: `GET {manifestUrl}` — Tool Service가 제공
- 실행 endpoint: Tool Service manifest의 top-level `endpoint` 또는 `_meta.endpoint` — 현재 구현
## 1. 계약 범위와 원칙
Tool Service는 여러 Tool을 함께 배포하는 하나의 프로젝트이며, 이 계약에서 **bundle**이라 부른다.
MCP Server는 자기 설정에 선언된 bundle의 매니페스트를 **주기적으로 조회**해 Tool 목록을 구성한다.
| 원칙 | 내용 |
|---|---|
| MCP가 가져온다 | Tool Service는 매니페스트를 제공만 한다. MCP에 등록 요청을 보내지 않는다 |
| 조회 대상은 설정이 정한다 | 어떤 bundle이 이 MCP에 속하는지는 배포 시점 YAML로 확정된다 |
| **Tool Server domain은 포털이, Tool endpoint는 Tool Service가 소유한다** | 포털은 Tool Server의 `serviceDomain`과 `manifestPath`만 제공하고, 개별 Tool 실행 endpoint는 Tool Service manifest의 top-level `endpoint` 또는 `_meta.endpoint`에서 온다 |
| 매니페스트는 전체 상태 | 응답은 그 bundle의 Tool 전체 목록이다. 증분 없음 |
| 조회 성공이 생존 신호 | 별도 heartbeat·TTL 장치가 없다 |
| bundle 단위 조회 격리 | 한 bundle의 조회 실패가 다른 bundle의 조회를 중단시키지 않는다 |
| aggregate는 전부 아니면 전무 | 단, 직전 성공본조차 없는 bundle이 하나라도 있으면 카탈로그 전체를 교체하지 않는다 |
세 번째 원칙이 이 계약의 신뢰 경계다. 매니페스트는 **무엇을 노출하는가**와 **어디로 호출할 것인가**를
함께 말한다. MCP는 endpoint의 scheme(HTTP(S))과 host 존재만 형식 검사하고 도메인 허용목록을 두지
않으므로, 매니페스트 원천의 신뢰성이 그대로 outbound 대상의 신뢰성이 된다. 따라서 §4의 "매니페스트
endpoint를 MCP Server namespace에서만 접근 가능하게 한다"는 요구는 선택적 강화가 아니라 이 계약의
전제 조건이다([ADR-0010](../../decisions/ADR-0010-tool-service-manifest-owns-execution-endpoint.md)).
마지막 두 원칙은 층이 다르다. **조회**는 bundle마다 독립이고 실패해도 직전 성공본이 남으므로
평소에는 한 bundle의 장애가 다른 bundle을 건드리지 않는다. 그러나 **카탈로그 교체**는 전부 아니면
전무다. 한 번도 성공한 적 없는 bundle이 남아 있으면 그 상태로 목록을 확정하지 않는다.
일부만 담긴 목록은 "필요한 Tool이 조용히 사라진 상태"를 만들기 때문이다(§7, §11 W11).
> **운영 배포에서 bundle은 항상 하나다.** MCP 배포 하나가 Tool Service 하나만 보기로 했기 때문이다
> ([ADR-0007](../../decisions/ADR-0007-one-mcp-per-tool-service.md)). 따라서 여러 bundle을 전제로 한
> 규칙(§7의 4·6번, `maxToolsTotal`)은 운영에서 발동하지 않는다. 계약과 구현은 N개를 계속 지원하지만
> 배포 정의가 1개로 잠그며, 그 사실은 `HelmDeploymentContractTest`가 검사한다.
## 2. 왜 조회 방식인가, 왜 기동 시 1회가 아닌가
### push를 채택하지 않은 이유
Tool Service가 MCP로 등록을 보내는 방식은 **MCP Server가 재기동되면 카탈로그를 복구할 방법이 없다.**
Tool Service는 이미 등록을 마쳤으므로 다시 보내지 않고, MCP는 빈 상태로 서비스한다.
재기동 빈도는 오히려 MCP 쪽이 높다(배포·스케일·노드 이동).
조회 방식은 MCP가 스스로 물어보므로 이 문제가 성립하지 않는다.
또한 MCP에 쓰기 endpoint를 열지 않아도 된다.
### 기동 시 1회로 끝내지 않는 이유
조회 방식이라도 기동 시 1회만 하면 아래를 따라가지 못한다.
| 상황 | 기동 시 1회만 | 주기적 조회 |
|---|---|---|
| MCP 재기동 | ✅ 다시 조회하므로 복구 | ✅ |
| Tool이 Tool 목록·schema 변경 | ❌ MCP 재기동 전까지 모름 | ✅ 다음 주기 반영 |
| Tool Service 장애 | ❌ 계속 노출 | ✅ 직전 성공본 유지, 정상 응답에서 삭제 확인 시 제거 |
| MCP 기동 시점에 Tool이 배포 중이라 응답 실패 | ❌ **영구 누락** | ✅ 다음 주기 복구 |
마지막 항목이 가장 위험하다. 조회는 반드시 주기적이어야 한다.
## 3. MCP 설정 (YAML)
조회 대상과 라우팅 주소를 선언한다. 예시는
[mcp-bundle-config.yaml](examples/bundle-v0.2/mcp-bundle-config.yaml)에 있다.
```yaml
mcp:
identity: mcp-insurance-core
registry:
refreshIntervalSeconds: 30
discovery:
enabled: true
connectTimeoutMillis: 1000
readTimeoutMillis: 3000
maxToolsPerBundle: 100
maxToolsTotal: 200
maxManifestBytes: 1048576
maxToolTimeoutMillis: 30000
bundles:
# 운영 배포에서 이 목록은 항상 한 항목이다(ADR-0007). 스키마는 N개를 허용한다.
- id: insurance-processing
manifestUrl: http://tool-processing.ax-hub.svc.cluster.local:8080/tool-manifest
baseEndpoint: http://tool-processing.ax-hub.svc.cluster.local:8080/mcp
namePrefix: "processing."
# local 검증에서만 사용. 최초 원격 조회 실패 때만 읽으며 운영 Helm에는 넣지 않는다.
fallbackManifestFile: file:./config/local-process-tools-manifest-sample-v1.json
enabled: true
```
| 항목 | 설명 |
|---|---|
| `discovery.enabled` | 운영에서는 `true`이며 bundle 매니페스트를 원천으로 사용한다. `false`는 legacy local JSON fixture에만 사용한다 |
| `manifestUrl` | 매니페스트 조회 주소 |
| `baseEndpoint` | 매니페스트의 **상대** endpoint를 절대 URL로 바꿀 때 쓰는 기준 주소. Pod IP가 아니라 Service URL을 사용한다. Tool 실행 주소 자체는 매니페스트가 정한다 |
| `namePrefix` | 이 bundle이 사용할 수 있는 Tool 이름 접두사 |
| `fallbackManifestFile` | 선택. 최초 원격 조회 실패 때만 읽을 local manifest 파일. 운영 Helm에는 설정하지 않는다 |
| `enabled` | `false`면 조회하지 않는다. Actuator 상태에는 `status: "disabled"`로 나타난다 |
`manifestUrl`과 `baseEndpoint`를 나눈 이유는 매니페스트 제공 경로와 실행 경로가 다를 수 있기 때문이다.
같아도 무방하다. 매니페스트가 절대 URL을 선언하면 `baseEndpoint`는 해석에 쓰이지 않지만, 그때도
`baseEndpoint`는 절대 HTTP(S)여야 한다. MCP가 endpoint 종류와 무관하게 먼저 검사하므로 값이 잘못되면
그 bundle 전체가 거부된다.
원격 매니페스트와 legacy local JSON fixture는 **배타적**이다. `ToolRegistryClient` 구현은
`discovery.enabled`로 선택된다. 다만 local profile에서 원격 조회를 켠 경우에는 bundle별
`fallbackManifestFile`을 둘 수 있다. 이는 **최초 원격 조회가 실패했을 때만** 읽는 같은 매니페스트 형식의
cold-start fallback이며, 원격 정상 목록이나 직전 성공본을 덮어쓰지 않는다.
| profile | `discovery.enabled` | 등록되는 원천 | 결과 |
|---|:---:|---|---|
| `local` | `false` | `LocalFileToolRegistryClient` | legacy JSON fixture만 사용 |
| `local` | `true` | `ToolBundleRegistryClient` | 원격 우선, 설정 시 local manifest fallback |
| `local` 아님(`ocp` 등) | `true` | `ToolBundleRegistryClient` | 정상. 운영 |
| `local` 아님 | `false` | 없음 | **기동 실패** |
원천이 하나도 없으면 `ToolRegistryService`가 주입받을 bean이 없어 기동 단계에서 멈춘다.
빈 Tool 목록으로 조용히 뜨는 것보다 낫지만, 오류 메시지가 Spring의 bean 해석 실패이므로
원인을 바로 알기 어렵다. 두 profile YAML이 이미 올바른 값을 고정하고 있으므로
(`application-local.yml`과 `application-ocp.yml`은 `true`; legacy local fixture만 쓸 때에만 `false`)
새 profile을 추가할 때만 주의하면 된다.
### 조회 주기와 jitter
주기는 기존 `mcp.registry.refreshIntervalSeconds`를 사용한다. replica가 동시에 기동할 때
조회 쏠림을 줄이기 위해 첫 **scheduled refresh**에만 `refreshJitterSeconds` 범위의 bounded jitter를 더한다.
ApplicationReady 직후 warm start와 원천 preload는 빈 목록 구간을 줄이기 위해 jitter 없이 즉시 실행한다.
### 기동 시 검증
아래를 위반하면 **기동에 실패한다.** 잘못된 설정이 운영 중 엉뚱한 라우팅으로 나타나는 것보다 낫다.
| 규칙 | 이유 |
|---|---|
| `discovery.enabled=true`이면 `bundles`가 비어 있을 수 없다 | 이 상태로 뜨면 `tools/list`가 영구히 빈다 |
| `id`는 중복될 수 없다 | 상태 추적 단위가 겹친다 |
| `namePrefix`는 중복될 수 없고 다른 prefix의 접두사도 될 수 없다 | `a.`와 `a.b.`가 함께 있으면 `a.b.search`의 소속이 확정되지 않는다 |
## 4. Tool Service가 제공할 endpoint
```text
GET {manifestUrl}
Accept: application/json
If-None-Match: "<직전 revision>" # 선택
```
매니페스트 조회는 사용자 요청이 아니라 **배경 갱신**이다. 특정 호출자의 요청 context가 없으므로
correlation·사원 식별자 header를 붙이지 않는다.
응답:
```text
200 OK
Content-Type: application/json
ETag: "sha256:9f2c..." # 선택. revision과 같은 값
```
응답 예시는 [manifest-response.json](examples/bundle-v0.2/manifest-response.json)을 따른다.
`If-None-Match`가 현재 `revision`과 같으면 `304 Not Modified`를 본문 없이 반환해도 된다.
MCP는 이 경우 직전 매니페스트를 그대로 유지한다. **선택 기능이며 구현하지 않아도 계약을 만족한다.**
이 endpoint는 인증을 요구하지 않아도 되지만, **NetworkPolicy로 MCP Server에서만 접근 가능하도록
제한한다.** Tool 이름·설명·schema는 내부 시스템 구조를 드러내므로 클러스터 전체에 공개하지 않는다.
## 5. 매니페스트 스키마
### 최상위 필드
| 필드 | 필수 | 설명 |
|---|:---:|---|
| `bundleId` | 예 | MCP 설정의 `id`와 일치해야 한다. 다르면 그 응답을 버린다 |
| `revision` | 아니오 | 매니페스트 버전. 변경 감지·로그·ETag에만 쓰인다 |
| `tools` | 예 | 이 bundle이 노출하는 Tool 전체. 빈 배열은 "노출할 Tool 없음"이다 |
Tool 실행 endpoint는 각 Tool의 top-level `endpoint` 또는 `_meta.endpoint`에 넣는다. 상대 경로를 쓰면 포털 registry의 `serviceDomain` 뒤에 붙고, 절대 URL을 쓰면 Tool Service manifest가 제공한 실행 주소 원천으로 그대로 사용한다. HTTP(S)가 아닌 scheme은 거부한다.
### `tools[]` 필드
| 필드 | 필수 | 설명 |
|---|:---:|---|
| `name` | 예 | MCP 표준에 맞춘 `[A-Za-z0-9_./-]{1,64}`이며 bundle의 `namePrefix`로 시작해야 한다 |
| `title` | 아니오 | 표시용 이름 |
| `description` | 예 | 에이전트가 Tool 선택에 사용한다. 언제 쓰는 도구인지 명확히 쓴다 |
| `inputSchema` | 예 | JSON Schema 2020-12 |
| `endpoint` 또는 `_meta.endpoint` | 예 | Tool 실행 주소. top-level `endpoint`를 먼저 읽고 없으면 `_meta.endpoint`를 쓴다. 둘 다 없으면 Bundle 전체를 거부한다 |
| `outputSchema` | 아니오 | `structuredContent` 응답 구조. 현재 MCP는 구조화 출력을 만들지 않으므로 운영에서는 사용하지 않는다 |
| `annotations` | 아니오 | `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` |
| `_meta.version` | 예 | Tool 버전 |
| `_meta.timeoutMillis` | 아니오 | MCP 설정의 `maxToolTimeoutMillis`로 상한을 건다 |
| `_meta.enabled` | 아니오 | 기본 `true`. `false`면 `tools/list`에 노출하지 않는다 |
`name`, `title`, `description`, `inputSchema`, `outputSchema`, `annotations`는 MCP가 `tools/list`로
그대로 공개한다. `_meta`와 `endpoint`는 내부 실행 정보이므로 공개본에서 제거한다.
현재 MCP의 `tools/call`은 `content[0].text`만 반환하고 `structuredContent` 생성·응답 schema 검증은 하지 않는다.
MCP 2025-11-25에서 `outputSchema`를 선언한 서버는 이에 맞는 구조화 결과를 제공해야 하므로, Tool Service는
구조화 출력 지원이 별도 계약으로 반영되기 전까지 운영 매니페스트에서 `outputSchema`를 생략한다.
## 6. MCP의 조회 동작
| 항목 | 권장값 | 근거 |
|---|---|---|
| 주기 | `30초` | 변경 반영 지연의 상한 |
| 첫 scheduled refresh jitter | `0~5초` | 반복 조회 주기가 replica마다 같은 시점에 고정되는 것을 방지 |
| 연결 timeout | `1초` | |
| 읽기 timeout | `3초` | |
| 기동 시 | **즉시 1회 조회하되 기동을 막지 않는다** | Tool 장애가 MCP 기동 실패로 번지지 않게 |
| readiness | **첫 조회 시도 완료 + usable snapshot이면 ready** | 원천 또는 Redis last-good이 있어 실제 요청을 처리할 수 있을 때만 트래픽을 받는다 |
usable snapshot은 원천 조회 성공본, 최초 원격 조회 실패 때 채택한 local fallback, 또는 Redis에서 채택한 last-good이다. 정상 매니페스트가 반환한 빈 Tool
목록도 유효한 전체 상태다. 반대로 첫 조회가 끝났더라도 memory와 Redis에 성공본이 하나도 없으면 readiness는
DOWN을 유지하고 다음 주기 조회를 기다린다.
### 동시 조회
bundle N개를 **동시에** 조회한다. 순차 조회하면 소요 시간이 합산되어 기동과 갱신이 지연된다.
개별 조회 실패는 **예외가 아니라 결과값**으로 다룬다. 하나의 실패가 전체 조회를 중단시키면
나머지 성공분까지 버려진다.
### 실패 판정과 유예
| 조회 결과 | 처리 |
|---|---|
| 성공 + 검증 통과 | 새 매니페스트 채택 |
| 성공 + 검증 실패 | 직전 성공본 유지. 실패 횟수 증가 |
| timeout / 연결 실패 / 5xx | 직전 성공본 유지. 실패 횟수 증가 |
| `304 Not Modified` | 직전 성공본 유지. 실패 횟수 **초기화** |
`304`는 **아직 구현하지 않았다.** §4에서 선택 기능으로 둔 항목이므로 `If-None-Match`를 보내지 않고,
Tool Service가 `304`를 반환할 일도 없다. 매번 전체 매니페스트를 받아 채택한다.
구현상 실패는 **예외가 아니라 결과값**이다. 조회 작업이 예외를 그대로 올리면 `Future` 하나가 깨지면서
나머지 bundle의 성공분까지 함께 버려지기 때문이다. bundle별 작업이 자기 예외를 잡아 실패 결과로 바꾸고,
그 바깥에 예상 밖의 오류까지 흡수하는 2차 방어선을 둔다.
## 7. 병합 규칙
1. **이름 검증** — `namePrefix`로 시작하지 않는 Tool은 그 bundle 전체를 거부한다
2. **`enabled: false` 제외** — 등록은 하되 `tools/list`에 노출하지 않는다
3. **상한 검사** — `maxToolsPerBundle` 초과 시 그 bundle 거부, `maxToolsTotal` 초과 시 전체 aggregate 거부
4. **정렬** — `(bundleId, name)` 오름차순으로 정렬한다
5. **`timeoutMillis` 상한** — `maxToolTimeoutMillis`를 넘는 값은 상한으로 절삭한다
6. **bundle 간 이름 충돌** — 어느 Tool도 임의 선택하지 않고 전체 aggregate를 거부한다
1번은 Tool 하나가 규칙을 어겨도 **bundle 전체를 거부**한다는 뜻이다. 필수 필드 누락, `bundleId` 불일치,
매니페스트 내부 이름 중복도 같다. 일부만 반영된 카탈로그는 "필요한 Tool이 조용히 사라진 상태"를 만들어,
직전 성공본을 유지하는 것보다 나쁘다.
6번을 정렬 **뒤에** 두는 이유는 1번과 같다. 정렬 전에 처리하면 어느 쪽이 살아남는지가
동시 조회의 응답 순서에 좌우되어 replica마다 달라진다.
정렬이 없으면 동시 조회 응답 순서에 따라 `tools/list` 순서가 매번 달라진다.
Agent Builder 쪽 프롬프트가 매 호출 달라져 캐시 적중률이 떨어지므로 반드시 정렬한다.
`maxToolsTotal`은 [ADR-0002](../../decisions/ADR-0002-tool-exposure-and-single-call.md)의
Tool 노출 상한과 함께 검토한다. 운영 배포는 bundle이 하나이므로(ADR-0007) 이 상한은
`maxToolsPerBundle`과 같은 층에서 동작하며, 50개 노출 상한은 한 Agent가 **여러 MCP에서 가져온
Tool의 합계**에 적용된다. MCP를 나눈다고 상한이 늘지 않는다.
## 8. Tool을 찾지 못했을 때의 재확인
`tools/call` 요청의 Tool이 현재 스냅샷에 없으면, **해당 bundle을 즉시 1회 재조회한 뒤**
그래도 없으면 `-32001 Tool not found`로 응답한다.
MCP replica마다 조회 시점이 달라 스냅샷이 일시적으로 어긋날 수 있기 때문이다(§11 W2).
구현은 해당 bundle 하나가 아니라 **전체를 한 번 재조회**한다. 재조회 대상은 병렬이고 timeout이 짧아
비용 차이가 작은 반면, "어느 bundle에 속한 Tool인가"를 이름만으로 되짚는 경로를 따로 두지 않아도 된다.
계약이 요구하는 것(한 번 더 확인한 뒤 판정)은 그대로 만족한다.
## 9. 운영 상태 조회
```text
GET /actuator/toolBundles
```
management port(운영 기본 9090)에서 MCP가 알고 있는 bundle의 조회 상태를 반환한다. 외부 ingress에는
노출하지 않는다. 응답 예시는
[bundle-status-response.json](examples/bundle-v0.2/bundle-status-response.json)에 있다.
설정에 선언되어 있으나 한 번도 조회에 성공하지 못한 bundle도 반환한다.
**설정에 기대값이 있으므로 누락 감지가 가능하다.**
| `status` | 의미 |
|---|---|
| `healthy` | 마지막 조회 성공 |
| `fallback` | 최초 원격 조회에 실패해 local manifest sample을 사용 중 |
| `degraded` | 최근 조회는 실패했지만 직전 성공본을 계속 노출 중 |
| `unreachable` | 켜져 있으나 한 번도 성공한 적 없음 |
| `disabled` | 설정에서 `enabled: false` |
응답에 **`manifestUrl`과 `namePrefix`는 넣지 않는다.** 진단에 꼭 필요하지 않은데 내부 주소 체계를 더 드러낸다.
`lastFailureReason`도 메시지가 아니라 **예외 타입 이름만** 담는다. 메시지에는 URL이나 응답 조각이 섞일 수 있다.
읽기 전용이며 상태를 바꾸지 않는다. 그러나 내부 구조를 노출하므로 외부에 공개하지 않는다.
이 endpoint는 Spring Boot Actuator가 제공하므로 `/mcp`의 JSON-RPC 예외 처리 경계를 통과하지 않는다.
## 10. 실행 경로 (MCP → Tool, 현재 구현)
이미 구현되어 있는 계약이다. Tool Service는 아래를 받을 수 있어야 한다.
```text
POST {endpoint}
Content-Type: application/json
guid, x-request-id, mcp-session-id, employee-no, virtual-employee-no
Authorization: <설정에 따라 전달>
<tools/call의 arguments 객체 원본>
```
- 호출자 header 다섯 개는 **이름과 값을 바꾸지 않고 그대로 bypass**한다. 값이 없는 header는 보내지 않는다.
- `employee-no`·`virtual-employee-no`는 호출자가 암호화한 값이다. **복호화는 Tool Service 몫이며
사내 KMS에서 발급받은 키를 사용한다.** MCP는 키를 갖지 않으므로 값을 읽지도, 로그에 남기지도 못한다.
MCP가 인증을 하지 않으므로([ADR-0006](../../decisions/ADR-0006-no-authentication-in-mcp.md))
이 값의 신뢰 여부는 Tool Service가 판단한다. 두 header가 모두 없을 수 있다는 점도 함께 고려한다.
- 발송·등록·변경 Tool의 중복 실행 방지는 Tool Service 책임이다. retry가 같은 `guid`를 재사용할지와
이를 멱등성 키로 사용할지는 아직 합의되지 않았으므로 현재 wire 계약으로 가정하지 않는다.
합의 대상은 [extension-points.md](../../extension-points.md)에 한 번만 관리한다.
- 요청 body는 에이전트가 보낸 `arguments` 객체 **그대로**다. MCP는 이름·값을 바꾸지 않는다.
- 응답이 JSON object/array면 MCP가 compact JSON 문자열로 `result.content[0].text`에 담는다.
- Tool이 반환한 HTTP 4xx/5xx와 timeout은 `result.isError: true`로 변환한다.
- 호출 소요 시간은 `result.content[0]._meta.searchTime`(ms)로 반환한다.
향후 Tool Service를 MCP 서버로 만들면 매니페스트 조회를 표준 `tools/list`로, 실행을 표준
`tools/call`로 대체할 수 있다. 이 경우 §4·§5는 MCP 표준으로 흡수된다. 전환 여부는 합의 항목이다.
## 11. 트레이드오프와 확장 경계
현재 선택은 **Tool Service 원천 + 주기 pull + in-memory last-good + 선택 Redis 공유 cache**다.
Redis의 key 형식, TTL, 공유 범위와 운영 정책은 이 Tool Service wire 계약의 범위가 아니며
[extension-points.md](../../extension-points.md#운영-적용-전-필수-보완)에서 합의한다.
| 트레이드오프 | 현재 선택 |
|---|---|
| replica snapshot 차이 | 일시 허용. 성공본만 교체하고 Tool miss 시 원천을 한 번 재확인 |
| 변경 반영 지연 | 기본 한 주기 허용. 즉시 알림·ETag는 아직 도입하지 않음 |
| 조회 부하 | replica별 조회 허용. 규모가 커질 때만 leader election 검토 |
| 기동 중 원천 장애 | Redis warm start 후 즉시 preload. local profile에 fallback 파일이 있으면 최초 실패 때만 채택하고, 없으면 다음 조회까지 Registry unavailable |
| stale Tool | 조회 실패만으로 삭제하지 않음. 성공한 매니페스트에서 빠진 경우에만 삭제 |
| Redis 장애 | cache miss로 격리. 요청 경로는 in-memory만 조회 |
NetworkPolicy·egress, 관측 지표, retry/idempotency, outputSchema 등 아직 합의하거나 보완할 내용은
[extension-points.md](../../extension-points.md)에서만 관리한다. 구현 목록은 코드와 테스트가 정본이며 이 계약에 다시 나열하지 않는다.
## 12. 의도적으로 넣지 않은 기능
- `If-None-Match` / `304`: 매니페스트가 작아 현재 효용이 없음
- 즉시 refresh 알림 endpoint: 주기 반영으로 부족하다는 운영 근거가 생길 때 검토
- leader election: replica 조회 부하가 실제 병목이 될 때 검토
- 상태 응답의 `manifestUrl`·`namePrefix`: 불필요한 내부 주소 노출 방지

187
docs/contracts/tool-service-mcp/tool-list-loading-guide.md Normal file
View File

@@ -0,0 +1,187 @@
# 안내: Tool 목록 최초 적재와 `tools/list` 노출 흐름
> 상태: **안내 문서** · 기준: 현재 MCP 서버 구현 · 대상: Tool Service 개발 파트
>
> 이 문서는 현재 동작을 이해하기 위한 안내다. 외부 wire 계약의 정본은
> [Tool Service-MCP Bundle 조회 계약 v0.2](protocol-v0.2-bundle-discovery.md)다.
> 규범 내용은 여기에 복제하지 않고 계약을 가리킨다. 복제본은 조용히 낡기 때문이다.
## 먼저 구분할 것
Tool Service가 MCP 표준 `tools/list`를 직접 구현하는 구조가 아니다. Tool Service는 아래의 내부
**매니페스트 endpoint**를 제공하고, MCP Server가 이를 읽어 Agent Builder용 표준 `tools/list` 응답으로
변환한다.
```text
Tool Service -- GET /tool-manifest --> MCP Server -- JSON-RPC tools/list --> Agent Builder
```
현재 운영 배포는 MCP 하나가 Tool Service Bundle 하나를 본다. 구현은 호환 목적으로 여러 Bundle의
병합도 지원하지만, Tool 개발 파트는 자기 Bundle 하나의 매니페스트만 제공하면 된다.
## 1. 최초 적재는 구현되어 있는가?
**구현되어 있다.** Spring 애플리케이션이 준비되면 `ToolRegistryRefreshScheduler.preload()`가 실행된다.
```text
ApplicationReadyEvent
-> 선택 Redis snapshot warm start (있으면 memory에 임시 적재)
-> Tool Service manifest 즉시 조회
-> 검증 성공한 전체 Tool 목록으로 memory snapshot 교체
-> 선택 Redis cache 저장
-> readiness 판단 가능
```
Redis는 선택 cache일 뿐이다. Redis가 없거나 실패해도 Tool Service 매니페스트 조회가 성공하면 정상
기동한다. 반대로 최초 조회와 선택 cache 모두 실패하면 애플리케이션 프로세스는 살아 있어도 usable
Tool 목록이 없으므로 readiness는 DOWN이다. 다음 주기 조회에서 자동 재시도한다.
`tools/list` 요청이 기동 preload보다 먼저 들어와 memory snapshot이 비어 있으면, 요청 경로도 원천을
한 번 직접 조회해 cold start 공백을 메운다.
## 2. Tool Service에서 memory까지의 처리 순서
```text
ToolBundleRegistryClient.fetchTools()
-> ToolBundleDiscovery.discoverAll()
-> GET {manifestUrl}
-> bundleId / tools[] / Tool 필수 필드 검증
-> ToolMetadata 생성 (endpoint는 Tool Service manifest의 top-level endpoint 또는 _meta.endpoint 사용)
-> enabled=false Tool 제외
-> immutable List<ToolMetadata>를 AtomicReference snapshot에 저장
```
실제 memory 저장소는 `ToolRegistryService`의 `AtomicReference<List<ToolMetadata>>`다.
- 매니페스트 조회·검증에 **성공했을 때만** 새 immutable 목록으로 통째로 교체한다.
- HTTP 오류, timeout, JSON 오류, 필수 필드 누락, 이름 규칙 위반은 기존 snapshot을 비우지 않는다.
- Tool 하나만 걸러서 부분 반영하지 않는다. 매니페스트 하나가 잘못되면 해당 Bundle 전체를 거부한다.
- 현재 운영은 Bundle 하나지만, 구현상 여러 Bundle이면 모두 사용 가능한 성공본이 있을 때만 하나의 snapshot을 교체한다.
- 주기 refresh가 겹치면 single-flight로 하나의 원천 조회를 공유한다.
## 3. Agent Builder의 `tools/list` 요청은 어떻게 처리되는가?
Agent Builder는 공개 `POST https://{mcpHost}{publicPath}`로 JSON-RPC 요청을 보낸다. OpenShift Route는
해당 path의 MCP Service만 선택하고, 컨테이너가 같은 `POST {publicPath}`를 직접 처리한다.
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}
```
처리 경로는 다음과 같다.
```text
McpController
-> McpMethodHandlerRegistry
-> ToolsListHandler
-> ToolRegistryService.listTools()
-> in-memory snapshot 읽기
-> MCP SDK ListToolsResult 변환
-> JSON-RPC result.tools 반환
```
memory snapshot이 이미 있으면 `tools/list`는 Tool Service나 Redis를 호출하지 않는다. 따라서 Tool
Service가 잠시 느리거나 Redis가 장애여도 이미 적재한 목록은 바로 반환한다.
`ToolsListHandler`는 매니페스트 Tool 정의의 공개 필드만 MCP Tool로 만든다. `_meta` 안의
`version`, `timeoutMillis`, `enabled`와 MCP 내부의 `endpoint`는 절대 Agent Builder에 노출하지 않는다.
```json
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"tools": [
{
"name": "processing.contract.inquiry",
"title": "계약 조회",
"description": "계약번호로 계약의 기본 정보를 조회합니다.",
"inputSchema": {
"type": "object",
"properties": {
"contractNo": { "type": "string" }
},
"required": ["contractNo"]
},
"annotations": {
"readOnlyHint": true
}
}
]
}
}
```
정확한 Agent Builder 응답 fixture는
[tools-list-response.json](../agent-builder-mcp/examples/agentbuilder-v0.3/tools-list-response.json)을 따른다.
## 4. Tool Service가 구현할 매니페스트 endpoint
Tool Service는 MCP 배포 설정에 등록된 `manifestUrl`에 대해 다음을 반환한다.
```text
GET /tool-manifest
Accept: application/json
200 OK
Content-Type: application/json
```
이 요청은 사용자 Tool 실행이 아니라 MCP의 배경 metadata 갱신이다. 따라서 `guid`, 사원 식별자,
`Mcp-Session-Id` 같은 요청 상관·사용자 header를 기대하면 안 된다.
현재 구현은 conditional GET을 보내지 않으므로 Tool Service는 우선 항상 `200 OK`와 전체 JSON을
반환하면 된다. `304 Not Modified`와 ETag는 계약상 선택 사항이지만 현재 MCP 구현 범위가 아니다.
### 응답 규칙
필드별 규칙과 검증 결과는 [계약 v0.2 §5](protocol-v0.2-bundle-discovery.md#5-매니페스트-스키마)가
정본이다. 이 문서에 같은 표를 두지 않는다. 예전에 표와 예제를 복제했다가 `endpoint` 필수화를 놓쳐,
MCP가 거부할 매니페스트를 안내하고 있었다.
실제 응답 예제는 [examples/bundle-v0.2/manifest-response.json](examples/bundle-v0.2/manifest-response.json)을
본다. 이 파일은 `ToolBundleContractExampleTest`가 직접 읽어 구현과 대조하므로, 문서 가운데 유일하게
조용히 어긋날 수 없는 사본이다.
Tool Service가 특히 놓치기 쉬운 세 가지만 짚는다.
- **`endpoint`는 필수다.** top-level `endpoint` 또는 `_meta.endpoint`가 없으면 그 Tool 하나가 아니라
Bundle 전체가 거부된다. 상대 경로는 Portal registry의 `serviceDomain` 뒤에 붙고, 절대 URL은
HTTP(S) scheme과 host를 갖춰야 한다.
- **`tools`는 전체 상태다.** 부분 목록이나 증분 변경을 보내면 안 된다.
- **credential·개인정보·업무 payload는 매니페스트에 넣지 않는다.**
## 5. Tool Service가 알아야 할 실패 동작
조회 결과별 처리는 [계약 v0.2 §6](protocol-v0.2-bundle-discovery.md#6-mcp의-조회-동작)과
[§7 병합 규칙](protocol-v0.2-bundle-discovery.md#7-병합-규칙)이 정본이다.
Tool Service 입장에서 결론은 하나다. **한 번의 `200` 응답은 그 시점에 노출할 Tool의 완전한 목록이어야
한다.** 조회가 실패하면 MCP는 직전 성공 목록을 유지하므로 실패가 Tool 삭제로 해석되지는 않는다.
그러나 성공한 응답에서 Tool이 빠지면 그것은 삭제로 반영된다. 부분 목록을 한 번 보내는 순간 그대로
카탈로그가 된다.
## Tool Service 구현 체크리스트
1. `GET /tool-manifest`를 MCP Server namespace에서만 접근 가능하게 제공한다.
2. `bundleId`가 배포 설정의 Bundle id와 정확히 일치하는지 배포 전에 함께 확인한다.
3. 모든 Tool에 고유한 표준 `name`, 비어 있지 않은 `description`, object 형태의 `inputSchema`, `_meta.version`을 넣는다.
4. Tool을 숨기려면 `_meta.enabled: false`를 쓰거나 정상 전체 목록에서 제거한다. 둘의 변경 반영 시점은 다음 refresh다.
5. credential·개인정보·업무 payload를 매니페스트에 넣지 않는다. 실행 주소는 6번을 따른다.
6. Tool 자체 실행 endpoint는 manifest의 top-level `endpoint` 또는 `_meta.endpoint`에 선언한다. 상대 경로는 Portal registry의 `serviceDomain` 뒤에 붙고, 절대 HTTP(S) URL은 Tool Service가 제공한 실행 주소 원천으로 그대로 사용한다.
## 확인한 구현·테스트
- 최초 preload·주기 refresh: `ToolRegistryRefreshScheduler`
- in-memory snapshot·실패 fallback: `ToolRegistryService`
- HTTP 매니페스트 조회·필드 검증: `ToolBundleDiscovery`
- `tools/list` 공개 필드 변환·`_meta` 제거: `ToolsListHandler`
- 회귀 테스트: `ToolRegistryServiceTest`, `ToolBundleDiscoveryTest`, `ToolsListHandlerTest`
자세한 field 정의와 실행 계약은 [v0.2 계약](protocol-v0.2-bundle-discovery.md), 실제 manifest 전체 예시는
[manifest-response.json](examples/bundle-v0.2/manifest-response.json)을 참고한다.