저장소 문서를 다시 추적하고 계약 예제를 복원한다

계약 테스트는 docs/contracts 아래 예제를 golden example로 읽는다. docs/와 README.md가 ignore되어 있어 예제 파일이 사라졌고 9건이 실패하고 있었다. 문서가 온전했던 마지막 상태(3de052a)에서 복원하고 .gitignore에서 두 항목을 제거한다. 에이전트 산출물인 docs/superpowers/ 제외는 유지한다. initialize 응답의 capabilities.tools.listChanged를 문서는 true로 적고 있었으나 InitializeHandler는 false를 낸다. 현재 HTTP 단발 응답 transport가 notification을 push할 수 없으므로 false가 맞다. 예제와 architecture.md를 코드에 맞추고, ToolListChangedEvent가 발행되지만 아직 소비되지 않는다는 점과 SSE 도입 시 true로 바꾼다는 조건을 남긴다. 169개 테스트 전부 통과. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-15 17:16:13 +09:00
parent 2d730ea9c1
commit 58d3014a0f
70 changed files with 3689 additions and 2 deletions
--- a/docs/contracts/tool-service-mcp/README.md
+++ b/docs/contracts/tool-service-mcp/README.md
@@ -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개로 고정 |
+| [TEMP-tool-list-loading-guide.md](TEMP-tool-list-loading-guide.md) | Temporary | Tool 개발 파트가 현재 최초 적재·memory snapshot·`tools/list` 변환 흐름을 이해하기 위한 안내 |
+
+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)을 따른다.
--- a/docs/contracts/tool-service-mcp/TEMP-tool-list-loading-guide.md
+++ b/docs/contracts/tool-service-mcp/TEMP-tool-list-loading-guide.md
@@ -0,0 +1,227 @@
+# 임시 안내: 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 구현 범위가 아니다.
+
+### 응답 규칙
+
+```json
+{
+  "bundleId": "insurance-processing",
+  "revision": "2026-08-03T01",
+  "tools": [
+    {
+      "name": "processing.contract.inquiry",
+      "title": "계약 조회",
+      "description": "계약번호로 계약의 기본 정보를 조회합니다.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "contractNo": {
+            "type": "string",
+            "description": "조회할 계약번호입니다.",
+            "minLength": 1
+          }
+        },
+        "required": ["contractNo"],
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false
+      },
+      "_meta": {
+        "version": "1.0.0",
+        "timeoutMillis": 3000,
+        "enabled": true
+      }
+    }
+  ]
+}
+```
+
+| 항목 | Tool Service 규칙 | MCP 처리 |
+|---|---|---|
+| `bundleId` | 필수. MCP 배포 설정의 Bundle id와 정확히 일치 | 다르면 Bundle 전체 거부 |
+| `revision` | 선택. 변경 식별·운영 진단용 | 현재 호출 대상이나 공개 응답에는 사용하지 않음 |
+| `tools` | 필수. 이 Bundle의 **전체 상태**를 배열로 반환 | 정상 빈 배열은 “노출 Tool 없음”으로 채택 |
+| `name` | 필수. `[A-Za-z0-9_./-]{1,64}` 및 설정 `namePrefix`로 시작 | 위반 시 Bundle 전체 거부 |
+| `description` | 필수. Agent Builder가 Tool 선택에 사용할 설명 | 그대로 `tools/list`에 공개 |
+| `inputSchema` | 필수 JSON Schema object | 그대로 공개하고 `tools/call` 전에 검증 |
+| `title`, `annotations` | 선택 공개 정보 | 있으면 `tools/list`에 공개 |
+| `_meta.version` | 필수 | 내부 metadata로만 사용, 공개하지 않음 |
+| `_meta.timeoutMillis` | 선택 | 설정 상한 이하로 제한, 공개하지 않음 |
+| `_meta.enabled` | 선택, 기본 `true` | `false`면 memory snapshot과 `tools/list`에서 제외 |
+| `outputSchema` | 현재 운영에서는 생략 | `structuredContent` 미지원 상태라 선언하지 않음 |
+
+`baseEndpoint`, Tool 실행 URL, credential은 매니페스트에 넣지 않는다. MCP가 실제 호출할 주소는
+배포 설정의 `baseEndpoint`에서만 결정한다. 매니페스트 안의 `endpoint` 성격 필드는 있어도 읽지 않는다.
+
+## 5. Tool Service가 알아야 할 실패 동작
+
+| Tool Service 매니페스트 결과 | MCP 동작 |
+|---|---|
+| `200` + 전체 검증 통과 | 새 목록을 memory에 교체하고 다음 `tools/list`부터 노출 |
+| `200` + JSON/필수 필드/이름 오류 | 직전 성공 목록 유지. 첫 기동이면 목록을 만들지 못함 |
+| timeout, 연결 실패, 4xx/5xx | 직전 성공 목록 유지. 첫 기동이면 readiness DOWN |
+| 정상 `tools: []` | 빈 목록을 정상 전체 상태로 채택 |
+| Tool 하나만 제거한 정상 전체 manifest | 다음 갱신에 그 Tool도 목록에서 제거 |
+
+따라서 Tool Service는 manifest 응답을 부분 목록이나 증분 변경으로 보내면 안 된다. 한 번의 `200` 응답은
+그 시점에 노출할 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. 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)을 참고한다.
--- a/docs/contracts/tool-service-mcp/examples/bundle-v0.2/bundle-status-response.json
+++ b/docs/contracts/tool-service-mcp/examples/bundle-v0.2/bundle-status-response.json
@@ -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
+    }
+  ]
+}
--- a/docs/contracts/tool-service-mcp/examples/bundle-v0.2/manifest-response.json
+++ b/docs/contracts/tool-service-mcp/examples/bundle-v0.2/manifest-response.json
@@ -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
+      }
+    }
+  ]
+}
--- a/docs/contracts/tool-service-mcp/examples/bundle-v0.2/mcp-bundle-config.yaml
+++ b/docs/contracts/tool-service-mcp/examples/bundle-v0.2/mcp-bundle-config.yaml
@@ -0,0 +1,49 @@
+# 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
+      # Tool 실행 주소. Pod IP가 아니라 Service URL을 사용한다.
+      # 매니페스트가 이 값을 바꿀 수 없다. 이것이 조회 방식의 보안 기반이다.
+      baseEndpoint: http://tool-processing.ax-hub.svc.cluster.local:8080/mcp
+      # Tool Service가 선언한 표준 MCP name이 따라야 할 접두사.
+      # 업무 단위이며 중요도 등급을 넣지 않는다. 등급이 이름에 들어가면
+      # Tool 재분류가 Tool name 변경이 되어 Agent Builder 재등록을 부른다.
+      namePrefix: "processing."
+      enabled: true
--- a/docs/contracts/tool-service-mcp/protocol-v0.2-bundle-discovery.md
+++ b/docs/contracts/tool-service-mcp/protocol-v0.2-bundle-discovery.md
@@ -0,0 +1,349 @@
+# 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이 하나라도 있으면 카탈로그 전체를 교체하지 않는다 |
+
+세 번째 원칙이 이 계약의 보안 기반이다. 매니페스트는 **무엇을 노출하는가**만 말하고
+**어디로 호출할 것인가**는 말하지 않는다. Tool Service가 임의의 주소를 MCP에 주입할 수 없다.
+
+마지막 두 원칙은 층이 다르다. **조회**는 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` | **Tool 실행 주소.** Pod IP가 아니라 Service URL을 사용한다 |
+| `namePrefix` | 이 bundle이 사용할 수 있는 Tool 이름 접두사 |
+| `fallbackManifestFile` | 선택. 최초 원격 조회 실패 때만 읽을 local manifest 파일. 운영 Helm에는 설정하지 않는다 |
+| `enabled` | `false`면 조회하지 않는다. Actuator 상태에는 `status: "disabled"`로 나타난다 |
+
+`manifestUrl`과 `baseEndpoint`를 나눈 이유는 매니페스트 제공 경로와 실행 경로가 다를 수 있기 때문이다.
+같아도 무방하다.
+
+원격 매니페스트와 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 |
+| `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`는 공개하지 않는다.
+
+현재 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`: 불필요한 내부 주소 노출 방지