From a5ac2f99eb2533a112e33f12c54ae7e18102dbc4 Mon Sep 17 00:00:00 2001 From: jade Date: Mon, 31 Aug 2026 17:06:06 +0900 Subject: [PATCH] docs: update DATMT README for tool metadata --- README.md | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 30dcc2404..b2dd64c05 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ Tool Pod │ └─ Spring Bean의 @McpTool 메서드 탐색 및 실행 메서드 캐시 ├─ ToolRegistryHeartbeatSender │ ├─ Tool 메타데이터 생성 - │ └─ tool-definitions YAML 병합 + │ └─ 선택적 tool-definitions YAML 병합 ├─ ToolManifestService │ └─ DATMS가 pull할 bundle 단위 Manifest 생성 ├─ McpToolExecutionService @@ -171,11 +171,15 @@ DATMS가 DATMT Tool Service를 호출할 때 사용하는 헤더는 다음과 @GrowToolHint( categoryKey = "iam", mappingId = "DIRECT_IAM_STATUS", - requiresApproval = false + requiresApproval = false, + timeoutMillis = 5000L, + retryMaxAttempts = 3 ) SystemStatusResponse getSystemStatus(SystemStatusRequest request); ``` +`@GrowToolHint`의 실행 제어 기본값은 `timeoutMillis = 5000L`, `retryMaxAttempts = 3`입니다. 어노테이션에서 값을 지정하면 해당 Tool의 메타데이터에 반영됩니다. `retryEnabled`는 지원하지 않으며, 재시도 여부는 `retryMaxAttempts` 값으로 판단합니다. + `@McpTool.name`은 다음 형식을 사용합니다. ```text @@ -206,6 +210,30 @@ dat-was-*/src/main/resources/tool-definitions/{category}/{tool-name}.yml 입력·출력 Schema는 `ToolSchemaResolver`가 어노테이션의 Schema 리소스와 인라인 Schema, DTO에서 생성한 Schema를 해석합니다. YAML 정의가 있으면 `ToolRegistryHeartbeatSender`가 `parameters_schema`와 `output_schema`를 병합하여 최종 메타데이터를 만듭니다. +### Tool 실행 제어 메타데이터 + +다음 메타데이터는 Tool 목록과 Manifest에 함께 제공됩니다. + +| 필드 | 기본값 | 설명 | +|---|---:|---| +| `timeoutMillis` | `5000` | Gateway가 Tool 응답을 기다리는 최대 시간(밀리초) | +| `retryMaxAttempts` | `3` | 최초 호출을 포함한 최대 시도 횟수 | + +`retryEnabled` 필드는 외부 메타데이터와 `ToolMetadata`에서 제거되었습니다. 따라서 클라이언트와 Gateway는 `retryMaxAttempts`만 사용해야 하며, 값이 없거나 1보다 작으면 기본값 3이 적용됩니다. Scaffold로 생성되는 Tool에도 위 두 값이 자동으로 삽입됩니다. + +표준 MCP `tools/list` 응답에서는 두 필드가 Tool의 `_meta`에 camelCase로 내려갑니다. + +```json +{ + "_meta": { + "timeoutMillis": 5000, + "retryMaxAttempts": 3 + } +} +``` + +`GET /tool-manifest` 응답의 각 Tool `_meta`에도 동일한 두 필드가 포함됩니다. `GET /mcp/api/v1/tools/local` 응답은 내부 `ToolMetadata` 표현을 사용하므로 동일한 실행 제어 값을 확인할 수 있습니다. + 실행 시 Schema 검증은 MCP Java SDK의 `DefaultJsonSchemaValidator`를 사용하며 JSON Schema 2020-12 기준으로 처리합니다. 입력 불일치는 `422 INVALID_PARAM`, 출력 불일치는 `500 INVALID_TOOL_RESPONSE`로 반환됩니다. 단, Schema 해석 또는 검증기 자체에서 예외가 발생하면 현재 구현은 오류를 로그에 기록하고 해당 검증을 건너뜁니다. ## 로컬 실행 @@ -458,6 +486,7 @@ oc get deployment,pod,svc -n axhub-datmt-dev | MCP SDK 서버 | `dat-was-lib/src/main/java/io/shinhanlife/dat/lib/mcp/ToolMcpServerConfiguration.java` | | MCP Tool 동기화 | `dat-was-lib/src/main/java/io/shinhanlife/dat/lib/mcp/ToolPodMcpToolSynchronizer.java` | | Tool 스캔 및 메타데이터 생성 | `dat-was-lib/src/main/java/io/shinhanlife/dat/lib/mcp/ToolRegistryHeartbeatSender.java` | +| MCP `tools/list` 메타데이터 변환 | `dat-was-lib/src/main/java/io/shinhanlife/dat/lib/mcp/ToolMetadataMcpMapper.java` | | YAML Tool 정의 로딩 | `dat-was-lib/src/main/java/io/shinhanlife/dat/lib/metadata/ToolDefinitionRepository.java` | | V17 정의 검증 | `dat-was-lib/src/main/java/io/shinhanlife/dat/lib/metadata/ToolDefinitionValidator.java` | | Manifest 생성 | `dat-was-lib/src/main/java/io/shinhanlife/dat/lib/manifest/ToolManifestService.java` |