diff --git a/.gitignore b/.gitignore index 56417b1..7513856 100644 --- a/.gitignore +++ b/.gitignore @@ -16,8 +16,6 @@ tmp/ .claude/ .idea/codeStyles/ AGENTS.md -README.md -docs/ # 에이전트 작업 계획·산출물. 저장소 문서가 아니므로 반입 대상에 넣지 않는다. # 결정은 docs/decisions/의 ADR에, 규칙은 계약 테스트에 남긴다(AGENTS.md 4절). diff --git a/README.md b/README.md new file mode 100644 index 0000000..a044291 --- /dev/null +++ b/README.md @@ -0,0 +1,170 @@ +# AX HUB MCP Server + +Agent Builder와 Tool Service 사이의 stateless MCP 실행 계층이다. Agent Builder가 `tools/call`에 명시한 단일 Tool을 JSON-RPC 2.0과 `inputSchema`로 검증하고, 서버가 관리하는 metadata에 따라 Tool Service를 호출한다. + +이 서버는 Tool을 추천하거나 사용자 의도를 판단하지 않는다. 업무 규칙은 Tool Service가, Tool 선택과 사용자·Agent별 노출 정책은 Agent Builder가 소유한다. + +## 기술 기준 + +- Java 21, Spring Boot 3.5.11, Spring MVC +- MCP Java SDK 2.0.0의 `mcp-json-jackson2`: protocol 상수·표준 result 모델·JSON Schema 검증에만 사용 +- Spring Data Redis: 선택적 공유 cache +- Spring AI MCP Starter/transport: 사용하지 않음 + +SDK 적용 경계는 [MCP Java SDK 선택적 도입 설계](docs/mcp-java-sdk-adoption.md)를 따른다. + +## 빠른 시작 + +필수 조건은 JDK 21이다. 기본 profile은 `local`이며 Redis 없이 Tool Service 매니페스트를 먼저 조회하고, 최초 조회 실패 시 `config/local-core-tools-manifest-sample-v1.json`을 fallback으로 사용한다. + +```powershell +.\gradlew.bat check +.\gradlew.bat bootRun +``` + +**빌드는 외부 저장소에서 코드 스타일 도구를 내려받지 않는다.** 폐쇄망에서 검사 하나 때문에 빌드 전체가 시작되지 못하는 상황을 만들지 않기 위해서다. 서식 검사는 저장소 안의 테스트가 소유한다. + +Java 포맷은 `.idea/codeStyles/Project.xml`의 IntelliJ IDEA 코드 스타일로 고정한다. 이 파일은 저장소에 포함되어 있어 IDE에서 자동으로 적용된다. Java 소스의 줄바꿈은 운영체제와 무관하게 LF이며 `.gitattributes`가 commit 시점에 이를 강제한다. + +두 가지가 보장하는 범위가 다르다. + +| 무엇이 | 보장하는 것 | 조건 | +|---|---|---| +| `CodeStyleContractTest` | LF 줄바꿈, 탭 없음, 후행 공백 없음, 파일 끝 개행, 미사용 import 없음 | 항상 (`test`에 포함) | +| IntelliJ formatter | 4칸 들여쓰기, 줄바꿈 스타일, 단순 lambda·다중 표현식 분리 | `IDEA_FORMATTER` 설정 시에만 | + +**`IDEA_FORMATTER`가 없으면 IntelliJ formatter 단계는 경고를 남기고 건너뛴다.** IntelliJ가 없는 CI나 폐쇄망 빌드에서 빌드가 깨지지 않게 하기 위한 것이며, 그 환경에서는 들여쓰기와 줄바꿈이 검증되지 않는다는 뜻이다. **도구 없이 판정할 수 있는 규칙은 그때도 계속 검사된다.** + +포맷터로 코드를 실제로 정리하려면 경로를 지정하고 `ideaFormat`을 실행한다. `CodeStyleContractTest`는 검사만 하고 고쳐 주지 않는다. + +```powershell +$env:IDEA_FORMATTER='C:/Program Files/JetBrains/IntelliJ IDEA 2026.1.4/bin/format.bat' +.\gradlew.bat ideaFormat +``` + +줄 폭 160자는 코드 스타일의 권장값이며 기존 코드에 소급 적용되지 않는다. 강제 대상이 아니다. + +local Tool 파일을 바꾸려면 다음 환경변수에 Spring resource 경로를 지정한다. + +```powershell +$env:MCP_LOCAL_TOOL_REGISTRY_FILE='file:C:/path/local-tools.json' +``` + +## 공개 계약 + +- 공개 endpoint: `POST https://{global.mcpHost}{deployments..publicPath}` +- 예: `https://mcp-dev.apps.example.internal/mcp/processing-critical` +- OpenShift Route는 공개 path로 MCP Service만 선택하고, 컨테이너가 같은 path를 직접 처리 +- Method: `initialize`, `notifications/initialized`, `tools/list`, `tools/call` +- Response: 항상 단일 `application/json` JSON-RPC response +- `Accept: application/json, text/event-stream`: 호환 목적으로 수용하지만 SSE 경로는 제공하지 않음 +- 공개 endpoint의 `GET`: `405 Method Not Allowed` +- `MCP-Protocol-Version`: `initialize` 이후 필수, 현재 `2025-11-25` +- `Mcp-Session-Id`: initialize lifecycle 추적용 correlation 값이며 서버 세션이 아님 + +정확한 요청·응답과 오류 의미는 [Agent Builder-MCP 현재 계약 v0.3](docs/contracts/agent-builder-mcp/protocol-v0.3-streaming-policy.md)이 정본이다. +Agent Builder는 공개 URL마다 별도 MCP로 등록하고 initialize한다. URL 사이에 lifecycle correlation이나 Tool 목록을 공유하지 않는다. + +## Tool metadata와 실행 + +| 환경 | Tool 원천 | Redis | +|---|---|---| +| `local` | local JSON fixture | 사용 안 함 | +| 운영(`prod`) | 이 배포가 보는 Tool Service 매니페스트를 주기적으로 pull | 성공 snapshot 공유와 warm start에만 사용 | + +요청 경로의 `tools/list`와 `tools/call`은 in-memory snapshot만 읽는다. 운영 refresh는 bundle별 last-good을 유지하고, 모든 bundle에 사용 가능한 성공본이 있을 때만 aggregate를 교체한다. 조회 실패만으로 Tool을 제거하지 않으며 정상 매니페스트에서 삭제가 확인될 때만 반영한다. 코드는 bundle N개 병합을 지원하지만 **운영 배포의 bundle은 항상 하나다**([ADR-0007](docs/decisions/ADR-0007-one-mcp-per-tool-service.md)). + +Tool 실행 주소는 local `_meta.endpoint` 또는 운영 `baseEndpoint` 설정에서만 정한다. Agent Builder의 `arguments`와 Tool Service 매니페스트는 호출 대상을 바꿀 수 없다. + +운영 매니페스트와 장애 처리의 wire 계약은 [Tool Service-MCP bundle 조회 계약 v0.2](docs/contracts/tool-service-mcp/protocol-v0.2-bundle-discovery.md)를 따른다. + +## Correlation과 로그 + +Agent Builder가 보낼 수 있는 표준 헤더는 12개다. MCP는 권한 판정이나 헤더 업무 검증을 하지 않고, 표준 헤더를 필수로 요구하지 않는다. 값이 없으면 없는 상태로 두며, 이 표준 헤더 때문에 요청을 차단하지 않는다. + +| 헤더 | 기대 형식 | MCP 동작 | +|---|---|---| +| `X-Guid` | UUID V4 | 있으면 end-to-end 상관 값으로 응답과 Tool Service 호출에 이어서 사용하고, 없으면 생략 | +| `X-Praf-No` | 숫자 8자리 | 있으면 Tool Service로 전달. 권한 판단은 하지 않음 | +| `X-Request-Id` | UUID V4 | 있으면 Agent→MCP 요청 식별자로 사용. Tool Service 호출 시에는 새 UUID V4로 재채번 | +| `X-Request-Time` | ISO-8601 offset date-time | 있으면 수신 context에 보관. Tool Service 호출 시에는 재채번 시각으로 교체 | +| `X-Vrtl-Praf-No` | 숫자 8자리 | 있으면 Tool Service로 전달 | +| `X-App-Code` | 대문자 3자리 | 있으면 Tool Service로 전달 | +| `X-Project-Code` | 대문자 5자리 | 있으면 Tool Service로 전달 | +| `X-User-Ip` | 사용자 단말 IP | 있으면 Tool Service로 전달 | +| `X-Caller-IP` | 호출 서버 IP | 있으면 수신 context에 보관. Tool Service 호출 시 MCP 서버 IP로 교체 | +| `X-Caller-Host` | 호출 서버 host name | 있으면 수신 context에 보관. Tool Service 호출 시 MCP 서버 host로 교체 | +| `X-Channel` | 채널 코드 | 있으면 수신 context에 보관. Tool Service 호출 시 `MCP`로 교체 | +| `X-Agent-Id` | Agent 식별자 | 있으면 Tool Service로 전달 | + +MCP는 사번·가상사번·사용자 IP를 로그에 남기지 않는다. MDC는 사용하지 않으며 로그에는 `X-Guid`와 MCP가 받은 `X-Request-Id`만 남긴다. request/response body와 credential도 기본 로그에 남기지 않는다. + +`Authorization`은 `mcp.tool-client.forward-authorization` 설정이 켜진 경우에만 전달한다. MCP는 이 값을 해석하지 않는다. + +## 인증과 권한 + +**이 서버는 인증도 인가도 하지 않는다.** 요청자 신원을 검증하지 않고, Tool 실행 권한을 판단하지 않으며, 사원 식별자를 복호화하지 않는다. 결정과 근거는 [ADR-0006](docs/decisions/ADR-0006-no-authentication-in-mcp.md)이다. + +| 책임 | 주체 | +|---|---| +| 외부 호출자를 Agent Builder로 제한 | OpenShift Route IP allowlist | +| MCP Pod 직접 접근 제한 | 플랫폼 NetworkPolicy | +| 사용자 인증과 Tool 실행 권한 | Agent Builder | +| 사원 식별자 복호화(KMS)와 업무 권한 | Tool Service | + +⚠️ **Route IP allowlist와 NetworkPolicy는 선택 사항이 아니다.** 외부 요청은 Route가 Agent Builder의 고정 egress CIDR만 받고, backend 요청은 ingress controller 또는 허용된 Agent Builder namespace에서만 MCP Pod에 도달한다. 실제 CIDR을 넣지 않은 배포는 운영에 사용할 수 없다. `HelmDeploymentContractTest`가 두 경계가 Chart에서 빠지지 않도록 고정한다. + +## 운영 설정 + +운영 설정은 Helm Chart가 만드는 ConfigMap이 담당한다. `identity`와 bundle 설정을 환경변수로 나열하지 않는 이유는 항목이 흩어질수록 인덱스 실수가 조용한 오라우팅이 되기 때문이다. + +`identity`는 `{배포 이름}-{global.env}`로 template이 조립한다. 현재 Redis cache 구현이 이 값을 사용하지만, Redis key namespace와 공유 정책은 아직 확정되지 않았으므로 [extension-points.md](docs/extension-points.md#운영-적용-전-필수-보완)에서 합의한다. + +- 업무 포트: `SERVER_PORT`(기본 8080) +- management 포트: `MANAGEMENT_SERVER_PORT`(운영 기본 9090) +- 상태: `/actuator/health/liveness`, `/actuator/health/readiness` +- bundle 진단: management 포트의 `/actuator/toolBundles` + +readiness는 첫 Tool discovery 시도가 끝나고 usable in-memory snapshot이 있을 때만 UP이다. 원천 장애 중에도 +기존 memory 또는 Redis last-good이 있으면 서비스를 유지하고, 아무 성공본도 없으면 트래픽을 받지 않는다. + +**MCP 배포 하나는 Tool Service 하나만 본다**([ADR-0007](docs/decisions/ADR-0007-one-mcp-per-tool-service.md)). 대상을 늘리는 방법은 bundle 목록을 늘리는 것이 아니라 배포를 하나 더 만드는 것이다. 외부에서는 같은 host의 고유 path로 각 배포를 노출하고 컨테이너가 그 path를 그대로 처리한다([ADR-0009](docs/decisions/ADR-0009-container-handles-public-mcp-path.md)). 배포는 업무 × 중요도 등급으로 나뉘며, 등급이 replica 수와 PodDisruptionBudget을 정한다. + +배포 정의는 [Helm Chart](deploy/helm/mcp-server/) 하나뿐이다. 배포 토폴로지는 `values.yaml`이, 환경 차이는 `values-{dev,test,prod}.yaml`이 소유한다. 설치할 배포 하나는 `--set`으로 고른다. + +```bash +helm upgrade --install processing-critical-mcp deploy/helm/mcp-server -f deploy/helm/mcp-server/values-dev.yaml --set deploymentKey=processing-critical -n +``` + +**MCP Server와 Tool Service는 같은 namespace에 배포한다.** 그래서 values에는 Tool Service의 이름만 적고 주소는 template이 조립한다. 환경마다 URL을 반복해 적지 않으므로 오타로 엉뚱한 곳을 호출할 수 없다. + +```yaml +deployments: + processing-critical: + name: processing-critical-mcp + service: processing-critical-tools # ← 이름만. 주소는 template이 만든다 + namePrefix: "processing." # ← 업무 단위. 등급을 넣지 않는다 + tier: critical + publicPath: /mcp/processing-critical # ← 같은 환경 host 안에서 유일 +``` + +배포가 10개든 20개든 파일 수는 늘지 않는다. 자세한 사용법은 [deploy/README.md](deploy/README.md)에 있다. + +평문 manifest가 필요하면 `helm template`으로 만든다. 별도 YAML을 저장소에 두지 않는다 — 두 벌은 반드시 어긋난다. + +빌드·이미지·배포 실행 방식은 사내 표준 CI/CD가 담당하며 이 저장소가 정하지 않는다. 배포 시 알아야 할 앱 제약은 [deploy/README.md](deploy/README.md)에 정리했다. + +## 문서 R&R + +| 문서 | 책임 | +|---|---| +| [README](README.md) | 프로젝트 진입점과 실행 방법 | +| [architecture.md](docs/architecture.md) | 현재 코드 구조, 요청 흐름, 내부 책임과 장애 동작 | +| [Agent Builder-MCP contracts](docs/contracts/agent-builder-mcp/README.md) | Agent Builder와의 HTTP/JSON-RPC wire 계약 | +| [Tool Service-MCP contracts](docs/contracts/tool-service-mcp/README.md) | 매니페스트와 Tool 실행 wire 계약 | +| [decisions](docs/decisions/README.md) | 결정 이유와 대안 이력 | +| [extension-points.md](docs/extension-points.md) | 아직 미합의인 항목과 운영 보완 작업 | +| [codex-workflow.md](docs/codex-workflow.md) | 저장소 작업 규칙과 공개 정책 | + +Superseded/Rejected 문서는 이력일 뿐 현재 구현 근거가 아니다. 코드나 공개 계약을 변경할 때는 가까운 테스트와 해당 현재 계약을 함께 수정한다. 변경을 마치기 전에 실행할 검증 명령은 [AGENTS.md](AGENTS.md)의 완료 기준이 정본이다. + diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..6d67bd5 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,230 @@ +# AX HUB MCP Server 설계 설명 + +## 책임 경계 + +```text +Agent Builder (판단, Tool 선택) + -> JSON-RPC 2.0 / Streamable HTTP +OpenShift Route (공유 host, 배포별 public path로 Service 선택, rewrite 없음) + -> 배포별 MCP Service +MCP HTTP Transport (transport/http: filter, controller, correlation, 오류 변환) + -> JSON-RPC Parser (envelope/method/params 정규화) + -> Handler Registry (method dispatch) + -> Execute Layer (metadata, validation, routing, flow control) + -> ToolClient (REST, timeout, header propagation) +Tool Service (Business Rule, Legacy/MCI/EAI 연계) +``` + +MCP는 Agent Builder가 `tools/call`에 명시한 단일 Tool을 실행한다. Tool 추천, 사용자 의도 해석, 업무 데이터 재가공, LLM reasoning은 이 경계 밖이다. + +**인증과 인가도 이 경계 밖이다**([ADR-0006](decisions/ADR-0006-no-authentication-in-mcp.md)). 외부 호출자 제한은 Route IP allowlist가, Pod 직접 접근 제한은 NetworkPolicy가, 사용자 인증과 Tool 권한은 Agent Builder가, 사원 식별자 복호화와 업무 권한은 Tool Service가 담당한다. MCP는 요청 형식과 `inputSchema`만 검증한다. + +## 전체 실행 흐름 + +1. Agent Builder가 배포별 공개 URL `https://{host}{publicPath}`을 호출한다. OpenShift Route는 host와 path로 MCP Service만 선택하고 원래 path를 컨테이너에 전달한다([ADR-0009](decisions/ADR-0009-container-handles-public-mcp-path.md)). 요청 body·header·Tool 이름은 이 선택에 관여하지 않는다. +2. 컨테이너의 `mcp.endpoint-path` 전용 `McpExchangeFilter`가 header를 검증/추출하고 요청 전체 deadline을 포함한 `McpRequestContext`를 만든다. 호출자 헤더 다섯 개(`guid`, `x-request-id`, `mcp-session-id`, `employee-no`, `virtual-employee-no`)는 모두 선택값이며, 응답과 downstream Tool 호출에 그대로 전파한다. `guid`는 요청 하나의 end-to-end 상관 값, `x-request-id`는 개별 HTTP 요청 식별자다. +3. filter는 크기가 제한된 repeatable request body에서 `method`만 관찰용으로 읽고 `mcp_http_request_received` 로그를 남긴다. body, header 값, credential은 로그에 저장하지 않는다. +4. `McpProtocolVersionValidator`가 `initialize`를 제외한 요청의 `MCP-Protocol-Version`을 supported versions와 대조한다. 누락·불일치는 Controller 진입 전 HTTP 400으로 종료한다. +5. `JsonRpcRequestParser`가 envelope를 정규화하고 JSON-RPC 2.0, method, id, params shape를 최종 검증한다. + JSON-RPC version, 표준 오류 번호와 MCP method 이름은 MCP Java SDK 2.0 상수를 참조한다. +6. `McpMethodHandlerRegistry`가 method를 명시적 handler에 연결한다. +7. `tools/list`는 `ToolRegistryService`의 in-memory snapshot에서 실행 metadata를 얻는다. 요청 경로는 Redis를 호출하지 않으므로 Redis 장애·지연이 응답에 영향을 주지 않으며, snapshot이 비어 있는 기동 직후에만 Tool catalog provider를 한 번 조회한다. 이후 `ToolsListHandler`가 MCP SDK의 `Tool`과 `ListToolsResult`로 변환한다. local 기본 구성은 Tool Service 매니페스트를 먼저 조회하고, 최초 실패 시 bundle별 local manifest sample을 cold-start fallback으로 사용한다. 운영은 이 배포가 보는 Tool Service 매니페스트의 사용 가능한 성공본만 원천으로 사용한다. +8. `tools/call`은 `ToolsCallHandler`가 표준 MCP의 `params.name`과 object인 `params.arguments`를 검증하고 추출한다. +9. `ToolExecutionService`가 표준 Tool name으로 metadata를 확정하고 argument schema를 검증한다. `ToolRoutingService`는 snapshot에 저장된 정확한 Tool endpoint와 metadata timeout으로 HTTP 요청을 만든다. Agent Builder가 보낸 `arguments` 객체는 JSON raw body로 전달하며 MCP가 Tool을 대체 선택하지 않는다. +10. `arguments`의 어떤 field도 outbound URL 선택에 사용하지 않는다. Portal registry는 Tool Server의 `serviceDomain`과 `manifestPath`만 제공하고, Tool별 실행 endpoint는 Tool Server manifest의 top-level `endpoint` 또는 `_meta.endpoint`에서 가져온다. manifest endpoint가 절대 HTTP(S) URL이면 Tool Server가 제공한 실행 주소 원천으로 허용하고, 상대 경로이면 Portal registry의 `serviceDomain` 뒤에 붙인다. +11. `HttpToolClient`가 JDK 공유 HTTP client의 connection pool을 사용해 correlation 헤더와 함께 POST를 실행한다. arguments는 JSON body로 전달하며 Tool read timeout은 metadata timeout과 요청 전체 deadline의 남은 시간 이하로 제한한다. Authorization 전달은 설정으로 통제한다. +12. Tool 응답은 요청 payload와 분리해 `response.data`만 사용한다. plain text는 그대로, JSON object/array는 compact JSON string으로 MCP SDK `CallToolResult`/`TextContent`의 `result.content[0].text`에 넣고 outer JSON serializer가 escaping을 처리한다. 호출 소요 시간(ms)은 `result.content[0]._meta.searchTime`으로 반환하고, 정상 결과에도 `isError: false`를 명시한다. Tool 실행·timeout·권한 오류는 JSON-RPC error가 아니라 `isError: true` result로 변환한다. JSON-RPC envelope/params/method 및 서버 구성 오류는 최상위 JSON-RPC `error`로 반환한다. +13. local과 운영 모두 같은 `name` lookup, endpoint/timeout, inputSchema validation 경로를 사용한다. +14. Agent Builder가 `Accept: application/json, text/event-stream`을 보내도 서버는 단일 `application/json` JSON-RPC response를 반환한다. filter는 status와 소요 시간을 `mcp_http_response_completed` 로그로 남기며 응답 body는 저장하지 않는다. +15. 모든 예외는 `JsonRpcException`/`McpExceptionHandler`에서 표준 error로 변환하고, filter가 ThreadLocal을 반드시 정리한다. + +## 주요 클래스별 책임 + +| 클래스 | 패키지 | 책임 | +|---|---|---| +| `McpController` | `transport/http` | `mcp.endpoint-path`의 단일 공개 endpoint, parser/handler 연결, notification 202와 initialize UUID header 선택 | +| `McpRequestContextFactory` | `transport/http` | 호출자 헤더 5종 추출. correlation 값 형식 검증, 사원 식별자는 해석하지 않고 주입 위험 문자만 차단 | +| `McpRequestContextHolder` | `context` | 요청 수명 ThreadLocal 저장; 세션 저장소가 아님 | +| `JsonRpcRequestParser` | `jsonrpc` | JSON-RPC envelope shape 검증과 내부 request 정규화 | +| `McpMethodHandlerRegistry` | `method` | `Handler` 전략과 method dispatch를 한 경계에서 관리 | +| `ToolRegistryService` | `registry` | 요청 경로(memory 전용)와 배경 갱신 경로(provider 조회 후 memory→Redis 저장) 분리, single-flight refresh, 공유 cache warm start | +| `ToolsListHandler` | `method` | 실행 metadata를 MCP 공개 Tool로 변환하고 `_meta` 제거. 공개 필드 목록은 [계약 v0.3](contracts/agent-builder-mcp/protocol-v0.3-streaming-policy.md#toolslist)이 정본 | +| `LocalFileToolRegistryClient` | `registry` | 매니페스트 조회를 끈 local profile에서 legacy JSON/manifest fixture를 읽어 테스트 Tool 목록을 제공 | +| `ToolBundleDiscovery` | `registry` | 구현상 N개 Tool Service 매니페스트를 병렬 조회·검증하고 bundle별 last-good 상태를 유지. 최초 원격 조회 실패 시에만 설정된 local manifest fallback을 사용하며, 운영 배포는 1개 Bundle만 사용 | +| `ToolBundleRegistryClient` | `registry` | 구현상 모든 bundle의 사용 가능한 성공본을 중복·총량 검증 후 하나의 snapshot으로 병합. 운영 배포에서는 단일 Bundle 결과를 채택 | +| `RedisToolRegistryCache` | `registry` | best-effort Redis snapshot, 실제 read/write 실패를 cache miss로 격리 | +| `ToolRegistryRefreshScheduler` | `registry` | 기동 preload와 주기 refresh; 실패 시 애플리케이션 생존 | +| `ToolArgumentValidator` | `execute` | 기존 required/type 오류 계약을 보존하고 MCP SDK JSON Schema 2020-12 검증 적용 | +| `ToolExecutionService` | `execute` | 이름 기반 metadata 해석, argument validation, 단일 Tool 실행, HTTP 경계 로그와 오류 mapping | +| `ToolRoutingService` | `execute` | 단일 POST endpoint와 timeout 확정, 기본 URI 검증 | +| `ToolClient` | `toolclient` | Tool 호출 port와 해당 경계의 `ToolRequest`/`ToolResponse`/실패 타입 소유 | +| `HttpToolClient` | `toolclient` | HTTP 호출, headers, timeout, JSON/text 응답 처리 | +| `ToolBundleStatusEndpoint` | `observability` | management port의 Actuator `toolBundles` 상태 조회 | +| `ToolCatalogHealthIndicator` | `observability` | readiness group 판정. 첫 조회 시도가 끝나고 usable in-memory snapshot이 있을 때만 UP | +| `McpExchangeFilter` | `transport/http` | 설정된 MCP endpoint 전처리, request 크기 제한, correlation, HTTP 요청·응답 경계 로그 | +| `McpProtocolVersionValidator` | `transport/http` | `initialize` 이후 HTTP `MCP-Protocol-Version`의 지원 여부 검증; 서버 상태를 저장하지 않음 | +| `TraceLogger` | `observability` | context의 guid/requestId를 직접 포함하는 최소 key=value 경계 로그. 사원 식별자는 기록하지 않음 | +| `McpExceptionHandler` | `transport/http` | JSON parse, JSON-RPC, 예상 밖 오류의 표준 response 변환 | + +Spring Boot 3.5가 관리하는 Jackson 2 databind 모델과 annotation API는 `com.fasterxml.jackson.*` namespace를 사용한다. Registry 응답의 unknown field 무시는 회귀 테스트로 검증한다. + +MCP Java SDK는 protocol 상수, 표준 result 모델과 JSON Schema validator에만 사용한다. SDK/Spring AI MCP +Starter와 transport는 활성화하지 않으며 기존 `/mcp`, 보안, correlation, Registry, Tool 실행 경계를 유지한다. +상세 도입 범위와 업그레이드 검증 기준은 [MCP Java SDK 선택적 도입 설계](mcp-java-sdk-adoption.md)를 따른다. + +## 소스 구성 원칙 + +- Spring component, 외부 adapter, 교체 가능한 port 구현은 책임별 독립 파일로 유지한다. +- 특정 서비스나 port에서만 의미가 있는 immutable record, enum, 예외는 소유 타입 안에 둔다. +- `ToolClient`가 request/response/failure 타입을, `ToolExecutionService`가 실행 result를 소유한다. +- `McpMethodHandlerRegistry`는 handler 계약을, `ToolRegistryClient`는 원천 목록 조회 port를 소유한다. +- bean이나 동작을 제공하지 않는 빈 configuration class는 두지 않는다. Spring Boot auto-configuration과 application class의 scheduling 설정을 그대로 사용한다. +- 파일 수를 줄이기 위해 서로 다른 서비스 책임을 합치지는 않는다. transport, Registry, execution, Tool client, observability 경계는 계속 분리한다. + +### 패키지 경계 + +| 패키지 | 책임 | +|---|---| +| `transport/http` | HTTP로 들어오고 나가는 경계 전부. filter, controller, 본문 wrapper, protocol version 검증, context 생성, 오류 응답 변환 | +| `context` | 요청 수명 동안 공유하는 값과 ThreadLocal holder. 전송 방식을 모른다 | +| `jsonrpc` | JSON-RPC envelope 모델과 파싱·오류 코드 | +| `method` | MCP method별 handler와 dispatch | +| `execute` / `toolclient` | 단일 Tool 실행(응용 서비스)과 outbound port·adapter | +| `registry` | Tool 목록의 원천 조회, 병합, 캐시 | +| `observability` | 경계 로그, health indicator, Actuator 상태 endpoint | + +**`jakarta.servlet` 의존은 `transport` 패키지 안에서만 허용한다.** MCP는 stdio 등 다른 transport를 가질 수 있는 +프로토콜이므로, 서블릿 타입이 이 경계 밖으로 새면 전송 방식이 응용 계층에 굳어진다. +이 규칙은 `PackageBoundaryContractTest`가 강제한다. + +## Stateless 보장 + +- `HttpSession`/Spring Session 의존성이나 API를 사용하지 않는다. +- `mcp-session-id`는 요청 context와 downstream correlation header에만 사용한다. +- initialize 응답의 `Mcp-Session-Id`는 Agent Builder가 이후 요청에 전달하는 opaque correlation 값이다. 서버는 이를 발급했는지·notification을 받았는지·session readiness를 저장하거나 검증하지 않는다. +- Tool metadata의 in-memory cache는 업무/사용자 세션 상태가 아닌 재구성 가능한 read-only snapshot이다. +- replica가 달라져도 동일 요청 계약을 수행할 수 있다. +- HTTP와 Tool 호출 경계 로그는 requestId/guid로 연결하지만 업무·세션 상태를 저장하지 않는다. + +## HTTP 경계 로그 + +- 모든 MCP method(`initialize`, `notifications/initialized`, `tools/list`, `tools/call`)는 설정된 공개 path의 POST body에 있는 JSON-RPC `method`로 식별된다. Filter는 이 값과 HTTP status, 소요 시간만 요청·응답 경계 로그에 남긴다. +- `guid`가 있으면 end-to-end 흐름 전체에 그대로 사용하고, 없으면 UUID를 생성한다. `x-request-id`도 있으면 그대로 사용하고 없으면 생성해 response header와 downstream Tool header에 전파한다. +- MDC는 사용하지 않는다. `TraceLogger`가 `McpRequestContextHolder`에서 guid와 requestId를 읽어 각 메시지에 직접 포함한다. +- Authorization/Cookie/API key, session 식별자, 요청·응답 body는 logger에 남기지 않는다. +- **`employee-no`와 `virtual-employee-no`는 암호문이라도 로그에 남기지 않는다.** 개인 식별자이며, 암호화는 저장·전송 보호이지 로그 기록 허가가 아니다. +- 수신 request body는 `mcp.trace.max-body-bytes`로 제한한다. 제한을 넘으면 Controller에 전달하지 않고 JSON-RPC `Invalid Request`로 종료한다. 이 설정은 로그 capture 크기가 아니라 입력 경계 보호 정책이다. +- 현재 구현은 애플리케이션 로그만 제공하며 불변 감사 저장소가 아니다. 보존·위변조 방지·재처리가 필요한 규제 감사 요건이 확정되면 그때 별도 durable sink를 설계한다. +- 응답을 쓰는 중 `IOException`이 나면 `mcp_http_response_undeliverable` event로 남긴다. 대개 Agent Builder가 먼저 연결을 끊은 경우이며, 이 로그가 없으면 결과 유실 자체를 관측할 수 없다. + +## 요청 시간 예산 + +Agent Builder는 응답을 **300초**까지만 기다리고 연결을 끊는다. MCP의 예산은 그보다 짧아야 한다. +같거나 길면 MCP가 응답을 완성해도 받을 상대가 이미 사라진 뒤다. + +| 계층 | 값 | 근거 | +|---|---|---| +| Agent Builder 대기 한도 | 300초 | 외부 제약. Agent가 MCP를 호출한 시점부터 잰다 ([ADR-0004](decisions/ADR-0004-execution-guardrails.md)) | +| MCP 요청 전체 예산 `request-deadline-millis` | 270초 | 30초 여유. MCP 시계는 요청이 도착한 뒤 출발하므로 그만큼 더 안전하다 | +| Tool 개별 timeout 상한 `maxToolTimeoutMillis` | **30초** | 매니페스트 선언값의 상한. **실질적으로 이 값이 요청 시간을 결정한다** | + +Tool 호출 직전마다 `remainingMillis()`로 남은 예산을 계산해 read timeout을 그 이하로 깎는다. +따라서 Tool 하나가 자기 timeout을 다 써도 요청 전체 예산을 넘지 않는다. + +**270초는 실제로는 거의 도달하지 않는 backstop이다.** 한 요청은 Tool을 정확히 하나만 실행하고, +그 Tool의 timeout은 30초로 상한이 걸려 있다. 따라서 정상 경로의 최대 소요는 연결 1초 + 읽기 30초 +수준이다. 270초가 의미를 갖는 것은 `maxToolTimeoutMillis`를 크게 올릴 때뿐이며, +그때는 이 표 전체를 다시 계산해야 한다. + +이 관계 때문에 graceful shutdown 시간도 300초가 아니라 실질 상한(약 31초)에 맞춘다. +`spring.lifecycle.timeout-per-shutdown-phase`(40초) < `terminationGracePeriodSeconds`(45초) 순서를 지켜, +진행 중인 Tool 호출이 배포 중에 잘려 부작용만 남는 상황을 줄인다. + +연결이 이미 끊긴 뒤 Tool 결과가 도착하는 경우는 **완전히 막을 수 없다.** MCP는 결과를 저장했다가 +나중에 전달하지 않는다(stateless, [ADR-0001](decisions/ADR-0001-stateless-execution-boundary.md)). +중복 실행 방지는 Tool Service의 책임이다. retry에서 같은 `guid`를 재사용해 멱등성 키로 삼을지는 +[미합의 항목](extension-points.md)이며, 합의 전에는 MCP가 이를 보장한다고 가정하지 않는다. + +## Protocol version 협상과 검증 + +- 서버는 `mcp.protocol.supported-versions`와 `mcp.protocol.preferred-version`으로 지원 버전을 명시적으로 관리한다. preferred version은 반드시 supported versions에 포함되어야 한다. +- `initialize` 응답은 요청의 JSON-RPC `id`를 그대로 반환하며, preferred version과 `serverInfo(name/title/version)`, `capabilities.tools.listChanged=false`를 제공한다. +- 이 서버는 stateless이므로 협상 결과를 session에 저장하지 않는다. `initialize` 이후 Agent Builder는 모든 MCP HTTP 요청에 `MCP-Protocol-Version: `을 포함해야 하며, 서버는 매 요청을 독립적으로 검증한다. +- header가 누락되거나 지원하지 않는 값이면 JSON-RPC error가 아닌 HTTP `400 Bad Request`를 반환한다. 오류 body는 `error`, `message`, `supportedVersions`, `guid`를 포함해 호출자가 올바른 header를 진단할 수 있게 한다. + +## Initialize lifecycle correlation + +- `initialize`의 JSON-RPC result는 server protocol/capability 정보를 제공하고, HTTP response header `Mcp-Session-Id`에는 새 UUID를 제공한다. +- Agent Builder는 이 값을 `notifications/initialized`, `tools/list`, `tools/call`의 `Mcp-Session-Id` header에 보낸다. 각 HTTP 요청은 별도 `x-request-id`를 유지한다. +- Agent Builder는 MCP 2025-11-25 lifecycle에 따라 `notifications/initialized`를 보낸다. 서버는 이를 저장하거나 이후 요청의 readiness gate로 사용하지 않는다. +- `InitializedNotificationHandler`는 id 없는 notification을 HTTP 202으로 수용한다. 이는 Tool 실행 준비 상태를 메모리에 세우는 동작이 아니므로 replica 간 affinity가 필요 없다. + +## Tool metadata 갱신 장애 시나리오 + +요청 경로는 memory만 읽으므로 Redis 상태가 등장하지 않는다. + +| Memory | Tool Service aggregate | 결과 | +|---|---|---| +| hit | 무관 | memory 반환. **Redis를 호출하지 않는다** | +| miss (기동 직후) | 확정 가능 | provider 직접 조회 후 memory 저장 | +| miss (기동 직후) | 확정 불가 | Redis에 다른 replica의 snapshot이 있으면 채택, 없으면 `-32003 Tool registry unavailable` | + +readiness는 첫 discovery 시도 완료와 usable in-memory snapshot을 모두 요구한다. 원천 조회가 실패해도 기존 +memory 또는 Redis last-good을 채택했다면 UP이며, 둘 다 없어 `-32003`만 반환할 상태라면 DOWN이다. 따라서 +rolling update 중 새 Pod이 빈 catalog로 기존 정상 Pod을 대체하지 않는다. 정상 매니페스트가 빈 Tool 목록을 +반환한 경우에는 그 빈 목록도 성공적으로 확정된 전체 상태이므로 usable snapshot이다. + +배경 갱신 경로의 동작은 다음과 같다. + +| Tool Service aggregate | 기존 memory | Redis | 결과 | +|---|---|---|---| +| 확정 가능 | 무관 | 무관 | memory 갱신 후 Redis 저장(best-effort). **성공한 결과만 저장한다** | +| 확정 불가 | hit | 무관 | 현재 memory 유지. 더 오래된 Redis 값으로 덮어쓰지 않는다 | +| 확정 불가 | miss | hit | Redis의 공유 last-good snapshot으로 warm start | +| 확정 불가 | miss | miss/장애 | `-32003`을 반환하고 다음 주기에 재시도 | + +각 bundle은 이번 성공본 또는 직전 성공본이 있어야 aggregate를 확정할 수 있다. 조회 실패는 Tool 삭제로 해석하지 않으며, 성공한 매니페스트에서 빠진 경우에만 삭제를 반영한다. 이름 충돌이나 총량 상한 초과도 전체 갱신 실패로 처리한다. 동시에 여러 refresh가 들어오면 single-flight로 하나의 원천 조회 결과를 공유한다. + +캐시에서 Tool을 찾지 못하면 stale snapshot 가능성을 고려해 원천을 한 번 더 조회한 뒤 `-32001`을 결정한다. 반대로 캐시에는 있던 Tool이 실행 시점에 upstream 404 또는 410을 반환하면 삭제된 Tool을 아직 들고 있는 stale snapshot 신호로 보고, 현재 요청은 Tool 실행 실패로 유지한 채 해당 route의 manifest refresh를 best-effort로 즉시 시도한다. 같은 route에서 삭제된 Tool 호출이 몰릴 때 Tool Server manifest 호출이 폭증하지 않도록 짧은 cooldown을 적용한다. +Redis는 요청 경로의 의존성이 아닌 선택적인 warm-start cache다. Tool snapshot은 route별 key(`key-prefix:identity:v2:route:{routeToken}`)로 분리해 서로 다른 route의 Tool 목록이 섞이지 않게 하며, Portal registry fallback key와도 분리한다. key 형식, TTL, 공유 범위, 고가용성·보안 정책은 +아직 확정하지 않았으며 [extension-points.md](extension-points.md#운영-적용-전-필수-보완)에서 합의한다. 현재 구현값은 +운영 계약이나 장기 설계 결정이 아니다. + +## Local Tool manifest fallback + +로컬 Agent Builder 연동 검증도 실제 Tool Service와 같은 매니페스트 조회 흐름을 먼저 사용한다. `application-local.yml`의 bundle URL을 조회하고, **처음 조회가 실패했을 때만** `fallback-manifest-file`의 manifest sample을 snapshot으로 채택한다. 기본 sample은 프로젝트 루트의 `config/local-core-tools-manifest-sample-v1.json`이다. 원격 조회가 이후 성공하면 즉시 원격 목록으로 교체하며, 이미 확보한 원격 성공본은 local sample로 덮어쓰지 않는다. + +## Portal Registry and Tool manifest refresh + +로컬 검증에서는 `mcp.portal.registry-url`을 `file:./config/local-toolserver-info-sample-v1.json` 같은 Spring resource location으로 지정할 수 있다. 이 경우 MCP는 기동 preload와 주기 endpoint refresh에서 Portal HTTP API를 호출하지 않고 프로젝트 안의 registry JSON을 읽는다. 파일에서 확보한 endpoint 목록 이후의 Tool Server `tool-manifest` 주기 조회, route별 in-memory snapshot 갱신, Redis fallback 규칙은 Portal API를 사용할 때와 동일하다. + +Portal Registry를 사용하는 구성에서는 포털을 route별 Tool Server 목록의 원천으로만 사용한다. MCP는 기동 preload 때 포털 registry API를 먼저 호출해 `serviceDomain`과 `manifestPath`를 확보한 뒤 Tool Server `tool-manifest`를 조회한다. 이후에는 `mcp.registry.refresh-interval-seconds` 주기로 저장된 Tool Server 목록에 대해 manifest만 다시 조회하고, `mcp.portal.refresh-interval-seconds` 주기로 포털 registry만 별도로 갱신한다. 포털 `registryRevision`은 포털 응답 JSON 변경 로그와 Tool Server 목록 변경 진단에 사용하며, Tool Server 내부 tool/schema/revision/endpoint 변경 감지는 MCP의 manifest 주기 조회 결과를 route별 in-memory snapshot에 다시 병합하면서 처리한다. 요청 경로의 `tools/list`와 `tools/call`은 계속 in-memory snapshot만 읽는다. Portal API 조회가 실패하면 이미 확보한 in-memory Tool Server snapshot을 유지하며, cold start처럼 memory가 비어 있을 때만 `mcp.redis.portal-registry-key`의 Redis registry JSON을 fallback으로 읽는다. 이 Portal registry fallback은 route 목록과 Tool Server 목록 확보용이고, route별 Tool snapshot Redis key는 이미 알고 있는 route의 마지막 Tool 목록 fallback에만 사용한다. Redis fallback도 실패하면 Tool Server 원천을 확보하지 못한 것으로 처리하고 다음 주기에서 재시도한다. + +노출 대상 Tool은 그 파일이 정의한다. 목록을 이 문서에 옮겨 적지 않는다. 파일의 공개 필드는 그대로 보존하고 `_meta`와 `endpoint` 실행 정보만 제거해 `tools/list`에 내보낸다. fallback도 원격 매니페스트와 같이 top-level `endpoint` 또는 `_meta.endpoint`를 내부 실행 endpoint로 사용한다. + +이 fixture는 연동 확인용이며 실제 고객·계약·수납·지급 데이터를 담지 않는다. + +운영 profile에서는 `ToolBundleDiscovery`와 `ToolBundleRegistryClient`만 metadata 원천으로 활성화한다. MCP 배포별 `mcp.bundles`가 Tool Service의 매니페스트와 실행 주소를 선언한다. 운영 Helm 설정에는 fallback 파일을 넣지 않는다. Tool Service는 표준 `name`을 소유하고, MCP는 자기 Bundle 안에서 형식·설정된 `namePrefix`·중복을 검증하되 이름을 재작성하지 않는다. 서로 다른 MCP 배포 간 이름의 전역 유일성은 Tool Service·플랫폼의 변경 절차가 보장한다. Redis는 선택적인 공유 last-good cache일 뿐 Tool 목록의 원천이 아니다. + +**`mcp.bundles`는 N개를 지원하지만 운영 배포에서는 항상 한 항목이다.** MCP 배포 하나가 Tool Service 하나만 보기로 했기 때문이다([ADR-0007](decisions/ADR-0007-one-mcp-per-tool-service.md)). 대상을 늘리는 방법은 이 목록을 늘리는 것이 아니라 MCP 배포를 하나 더 만드는 것이다. 그래야 등급이 다른 Tool Service의 조회 실패가 서로의 카탈로그 갱신을 막지 않는다. 다중 bundle 병합 코드는 유지하되 Helm Chart가 1개로 잠그고 `HelmDeploymentContractTest`가 그 사실을 검사한다. + +각 배포는 같은 환경 host의 고유 `publicPath`를 가진 OpenShift Route로 노출된다([ADR-0009](decisions/ADR-0009-container-handles-public-mcp-path.md)). Route는 path로 Service만 선택하고 컨테이너가 같은 값을 `mcp.endpoint-path`로 직접 처리한다. Java 애플리케이션에는 route table이나 다중 Registry를 추가하지 않는다. Deployment·snapshot·readiness·connection pool은 path별로 분리되고, 공유되는 장애 지점은 OpenShift ingress와 DNS다. + +운영 상태는 외부 ingress가 아니라 management port(기본 9090)의 `GET /actuator/toolBundles`로 확인한다. + +## 변경 시 검증 경계 + +- MCP envelope/method 변경: adapter → handler registry → handler 직렬화 테스트 +- `tools/call` 변경: handler params → Registry metadata → argument validator → routing → Tool client → error mapping +- Tool metadata 변경: 매니페스트 역직렬화·bundle 검증 → aggregate 확정 → memory/Redis fallback → refresh scheduler +- correlation 변경: header extractor → filter/context 정리 → response/downstream header +- 공개 path/배포 변경: topology의 path 유일성 → Route host/path/Service → ConfigMap endpoint → Controller·Filter → Agent Builder 등록 URL +- 최종 확인: `.\gradlew.bat clean check`, `bootJar`, 실행 JAR의 initialize → notification → tools/list 흐름 +## Tool list change notification + +`initialize`는 `capabilities.tools.listChanged=false`를 선언한다(`InitializeHandler`의 `ServerCapabilities.builder().tools(false)`). 현재 HTTP 단발 응답 transport가 notification을 push할 수 없으므로, 보내지 못하는 능력을 선언하지 않는 쪽을 택한 것이다. + +내부적으로는 배경 Registry refresh가 기존 route snapshot과 다른 Tool 목록을 성공적으로 확보하면 `ToolListChangedEvent`가 표준 `notifications/tools/list_changed` JSON-RPC notification envelope를 만든다. 이 이벤트는 아직 소비되지 않는다. SSE/Streamable HTTP 전송 계층이 추가되면 이 이벤트를 route별 Agent 연결에 전달하고 선언을 `true`로 바꾼다. 그때까지 Agent Builder는 자체 주기로 `tools/list`를 다시 호출해야 한다. + + +- 임시 검증에서 Agent↔MCP와 MCP↔Tool Service payload를 확인해야 하면 `mcp.trace.payload-logging-enabled=true`를 켠다. 이 로그는 JSON 한 줄 형태로 요청·응답 본문을 남기므로 운영 기본값은 false이며, 검증 후 즉시 꺼야 한다. diff --git a/docs/codex-workflow.md b/docs/codex-workflow.md new file mode 100644 index 0000000..90ee940 --- /dev/null +++ b/docs/codex-workflow.md @@ -0,0 +1,60 @@ +# Codex 활용 및 저장소 공개 정책 + +## 목적과 책임 + +| 항목 | 소비자 | 저장소 포함 | +|---|---|---:| +| `AGENTS.md` | Codex의 모든 작업 | 예 | +| `.agents/skills/` | 조건에 맞는 Codex 작업 | 예 | +| `.codex/config.toml` | 신뢰된 프로젝트에서의 Codex 실행 환경 | 기본 아니오 | +| `docs/` | 개발자와 리뷰어 | 예 | +| `src/` | 애플리케이션 빌드와 테스트 | 예 | +| `deploy/` | 배포 플랫폼 | Secret이 없을 때만 예 | +| `samples/` | 개발자와 테스트 | 가짜 데이터일 때만 예 | + +루트의 `AGENTS.md`, `.agents/`, `.codex/`는 Codex의 표준 탐색 지점이다. 보기 좋게 다른 하위 폴더로 옮기지 않는다. 사람을 위한 설명은 이 문서와 `README.md`에 둔다. + +## 일상 작업 흐름 + +1. 일반 작업은 루트 `AGENTS.md` 규칙을 따른다. +2. JSON-RPC, MCP method, Tool Registry, Tool 실행, trace log, Spring profile, OpenShift 배포를 변경할 때는 `$verify-mcp-server-change`를 명시적으로 호출한다. +3. Skill은 코드와 관련 테스트를 읽고 영향 계약을 확인한 뒤 최소 변경과 Gradle 테스트를 요구한다. +4. 반복 작업이 세 번 이상 안정적으로 반복되면 새 skill 후보로 검토한다. 임시 작업, 일회성 지침, 개인 메모는 skill로 만들지 않는다. +5. 작업 중 발견한 규칙은 재현·검토된 뒤에만 `AGENTS.md`, skill reference, 또는 설계 문서에 반영한다. + +예시: + +```text +$verify-mcp-server-change +tools/call의 인자 검증을 변경하고 관련 테스트와 문서를 갱신해 줘. +``` + +## Codex 설정 정책 + +개인 전역 Codex 설정에는 선호 모델, approval policy, sandbox mode, 개인 MCP 서버, 로컬 경로, 인증 정보를 둔다. 이 내용은 저장소에 올리지 않는다. + +프로젝트 `.codex/config.toml`은 다음 조건을 모두 충족할 때만 추가하고 Git에 포함한다. + +- 모든 팀원이 동일하게 적용해야 한다. +- 프로젝트 고유의 설정이다. +- 비밀정보, 개인 경로, 개인 권한 선호, 개인 MCP 연결이 없다. +- 일반 코드 변경처럼 리뷰할 수 있다. + +현재 이 프로젝트는 위 조건에 해당하는 공유 Codex 실행 설정이 없으므로 `.codex/config.toml`을 사용하지 않는다. 프로젝트 설정이 필요한 시점에는 팀 검토 후 `.gitignore`의 해당 예외 규칙을 함께 변경한다. + +## GitHub 게시 전 점검 + +1. 기본 공개 범위는 private로 한다. 공개 전환은 조직 정책, 내부 명칭, 배포 정보, 계약 문서, 샘플 데이터 검토 후 별도 결정한다. +2. `AGENTS.md`, `.agents/skills/`, 소스, 테스트, 가짜 샘플, 비밀정보 없는 배포 명세와 문서는 커밋한다. +3. `.env`, 인증서, keystore, Secret manifest, 실제 고객·운영 데이터, 개인 Codex 설정은 커밋하지 않는다. +4. 첫 push 전에 Secret 검색을 실행하고, GitHub에서는 secret scanning, push protection, Dependabot, 기본 브랜치 보호를 활성화한다. +5. 외부 공개가 확정되면 `LICENSE`, `SECURITY.md`, `CONTRIBUTING.md`와 공개용 샘플·문서를 추가한다. + +## 구조 확장 기준 + +- `docs/decisions/`: 장기 설계 결정이 실제로 발생할 때 ADR을 추가한다. +- `src//AGENTS.md`: 특정 하위 모듈의 명령이나 규칙이 루트와 달라질 때만 추가한다. +- `.agents/skills//`: 반복되고 안정적인 작업 절차가 생길 때만 추가한다. +- `.codex/hooks/`: 지침과 테스트로 보장할 수 없는 결정적 정책을 강제해야 할 때만 추가한다. + +빈 폴더나 자동 누적 `lessons.md`는 만들지 않는다. diff --git a/docs/contracts/agent-builder-mcp/README.md b/docs/contracts/agent-builder-mcp/README.md new file mode 100644 index 0000000..6e6ac14 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/README.md @@ -0,0 +1,16 @@ +# Agent Builder-MCP 계약 문서 + +이 디렉터리는 현재 구현 계약과 목표 합의 기준선을 분리해 관리한다. + +| 문서 | 상태 | 용도 | +|---|---|---| +| [protocol-v0.3-streaming-policy.md](protocol-v0.3-streaming-policy.md) | Implemented | `text/event-stream` Accept를 수용하는 동기 JSON 현재 계약 | +| [protocol-v0.2-agentbuilder.md](protocol-v0.2-agentbuilder.md) | Superseded | streaming 정책 도입 전 non-streaming 계약 | +| [protocol-v1-agreement-baseline.md](protocol-v1-agreement-baseline.md) | Partial Agreement | 2026-07-10 협의에서 확정된 목표 원칙만 기록 | + +`protocol-v1-agreement-baseline.md`는 아직 실행 가능한 전체 wire contract가 아니다. Agent Builder의 전체 JSON 샘플과 미확정 항목이 승인되기 전까지 현재 구현을 변경하는 직접 근거로 사용하지 않는다. + +현재 구현 예시는 [examples/agentbuilder-v0.3](examples/agentbuilder-v0.3/)에서 관리한다. `initialize` 이후 요청에는 `MCP-Protocol-Version` HTTP header가 필요하다. +현재 공개 주소는 환경별 host와 배포별 path를 합친 `https://{mcpHost}{publicPath}`이며, 각 URL을 독립 MCP로 등록한다. 컨테이너가 공개 path를 직접 처리하는 기준은 [ADR-0009](../../decisions/ADR-0009-container-handles-public-mcp-path.md)이 정본이다. + +Agent Builder가 실제 Tool을 호출하며 남긴 관찰용 JSON-RPC 로그는 [observed-samples/2026-07-13](observed-samples/2026-07-13/)에 분리해 보관한다. 이 로그는 구현 계약이나 자동화 테스트 fixture가 아니다. diff --git a/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/initialize-request.json b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/initialize-request.json new file mode 100644 index 0000000..8691731 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/initialize-request.json @@ -0,0 +1,13 @@ +{ + "jsonrpc": "2.0", + "id": 1, + "method": "initialize", + "params": { + "protocolVersion": "2025-11-25", + "capabilities": {}, + "clientInfo": { + "name": "toolbox-executor", + "version": "0.1.0" + } + } +} diff --git a/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/initialize-response.json b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/initialize-response.json new file mode 100644 index 0000000..b53bf6a --- /dev/null +++ b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/initialize-response.json @@ -0,0 +1,9 @@ +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "protocolVersion": "2025-11-25", + "serverInfo": {}, + "capabilities": {} + } +} diff --git a/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/initialized-notification.json b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/initialized-notification.json new file mode 100644 index 0000000..f3936d5 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/initialized-notification.json @@ -0,0 +1,5 @@ +{ + "jsonrpc": "2.0", + "method": "notifications/initialized", + "params": {} +} diff --git a/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/tools-call-execution-error-response.json b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/tools-call-execution-error-response.json new file mode 100644 index 0000000..9d8d772 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/tools-call-execution-error-response.json @@ -0,0 +1,13 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "result": { + "content": [ + { + "type": "text", + "text": "customer.search@1.0.0: timed out" + } + ], + "isError": true + } +} diff --git a/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/tools-call-request.json b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/tools-call-request.json new file mode 100644 index 0000000..3390f67 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/tools-call-request.json @@ -0,0 +1,11 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "customer.search", + "arguments": { + "customerNo": "1234567890" + } + } +} diff --git a/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/tools-call-success-response.json b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/tools-call-success-response.json new file mode 100644 index 0000000..5923637 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.2/tools-call-success-response.json @@ -0,0 +1,16 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "result": { + "content": [ + { + "type": "text", + "text": "{\"customerName\":\"Hong\"}" + } + ], + "structuredContent": { + "customerName": "Hong" + }, + "isError": false + } +} diff --git a/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/initialize-response.json b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/initialize-response.json new file mode 100644 index 0000000..d4fcbd6 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/initialize-response.json @@ -0,0 +1,17 @@ +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "protocolVersion": "2025-11-25", + "capabilities": { + "tools": { + "listChanged": false + } + }, + "serverInfo": { + "name": "shl-axhub-mcp-server-external", + "title": "SHL AX HUB MCP Server (EXTERNAL)", + "version": "1.0.0" + } + } +} diff --git a/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-call-execution-error-response.json b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-call-execution-error-response.json new file mode 100644 index 0000000..9d8d772 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-call-execution-error-response.json @@ -0,0 +1,13 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "result": { + "content": [ + { + "type": "text", + "text": "customer.search@1.0.0: timed out" + } + ], + "isError": true + } +} diff --git a/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-call-invalid-params-response.json b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-call-invalid-params-response.json new file mode 100644 index 0000000..5cea45a --- /dev/null +++ b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-call-invalid-params-response.json @@ -0,0 +1,8 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "error": { + "code": -32602, + "message": "Invalid params: 'query' is required" + } +} diff --git a/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-call-request.json b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-call-request.json new file mode 100644 index 0000000..e08ffce --- /dev/null +++ b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-call-request.json @@ -0,0 +1,12 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "processing", + "arguments": { + "query": "processing system information inquiry", + "category": "processing" + } + } +} diff --git a/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-call-success-response.json b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-call-success-response.json new file mode 100644 index 0000000..4f44eec --- /dev/null +++ b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-call-success-response.json @@ -0,0 +1,16 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "result": { + "content": [ + { + "type": "text", + "text": "processing complete", + "_meta": { + "searchTime": 976.1 + } + } + ], + "isError": false + } +} diff --git a/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-list-response.json b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-list-response.json new file mode 100644 index 0000000..a53eaa9 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/examples/agentbuilder-v0.3/tools-list-response.json @@ -0,0 +1,67 @@ +{ + "jsonrpc": "2.0", + "id": 2, + "result": { + "tools": [ + { + "name": "insurance.processing.test", + "title": "처리계 연계 점검", + "description": "처리계 연계 경로와 요청·응답 형식을 점검하는 테스트 전용 도구입니다. 실제 보험 업무 데이터는 처리하지 않습니다.", + "inputSchema": { + "type": "object", + "properties": { + "requestId": { + "type": "string", + "description": "테스트 요청 식별자입니다." + } + } + }, + "annotations": { + "readOnlyHint": true, + "destructiveHint": false, + "idempotentHint": true, + "openWorldHint": false + } + }, + { + "name": "insurance.corebanking.test", + "description": "계정계 연계 경로와 요청·응답 형식을 점검하는 테스트 전용 도구입니다. 실제 계약·수납·지급 처리는 수행하지 않습니다.", + "inputSchema": { + "type": "object", + "properties": { + "requestId": { + "type": "string", + "description": "테스트 요청 식별자입니다." + } + } + } + }, + { + "name": "insurance.information.test", + "description": "정보계 연계 경로와 요청·응답 형식을 점검하는 테스트 전용 도구입니다. 실제 고객·계약 정보를 조회하지 않습니다.", + "inputSchema": { + "type": "object", + "properties": { + "requestId": { + "type": "string", + "description": "테스트 요청 식별자입니다." + } + } + } + }, + { + "name": "insurance.channel.test", + "description": "채널계 연계 경로와 요청·응답 형식을 점검하는 테스트 전용 도구입니다. 실제 고객 채널 업무를 수행하지 않습니다.", + "inputSchema": { + "type": "object", + "properties": { + "requestId": { + "type": "string", + "description": "테스트 요청 식별자입니다." + } + } + } + } + ] + } +} diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-initialize-request.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-initialize-request.json new file mode 100644 index 0000000..15a192b --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-initialize-request.json @@ -0,0 +1,14 @@ +{ + "jsonrpc": "2.0", + "id": 1, + "method": "initialize", + "params": { + "protocolVersion": "2025-06-18", + "capabilities": {}, + "clientInfo": { + "name": "toolbox-executor", + "version": "0.1.0" + } + } +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-initialize-response.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-initialize-response.json new file mode 100644 index 0000000..f15b53e --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-initialize-response.json @@ -0,0 +1,34 @@ +{ + "result": { + "protocolVersion": "2025-06-18", + "capabilities": { + "tools": { + "listChanged": true + }, + "prompts": { + "listChanged": true + }, + "resources": { + "listChanged": true + } + }, + "serverInfo": { + "name": "exa-search-server", + "title": "Exa", + "version": "3.2.1", + "websiteUrl": "", + "icons": [ + { + "src": "", + "mimeType": "image/png", + "sizes": [ + "32x32" + ] + } + ] + } + }, + "jsonrpc": "2.0", + "id": 1 +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-initialized-notification.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-initialized-notification.json new file mode 100644 index 0000000..9ed0b56 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-initialized-notification.json @@ -0,0 +1,5 @@ +{ + "jsonrpc": "2.0", + "method": "notifications/initialized" +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-tools-call-request.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-tools-call-request.json new file mode 100644 index 0000000..346a926 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-tools-call-request.json @@ -0,0 +1,13 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "web_search_exa", + "arguments": { + "query": "most popular useless github repository stars useless repo", + "numResults": 10 + } + } +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-tools-call-response.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-tools-call-response.json new file mode 100644 index 0000000..24e88b5 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316-tools-call-response.json @@ -0,0 +1,16 @@ +{ + "result": { + "content": [ + { + "type": "text", + "text": "Title: btahir/uselesshooks\nURL: N/A\nAuthor: N/A\nHighlights:\n# btahir/us\n...\n- Stars: 125\n- Forks: 9\n- Watchers: 125\n- Openissues: 3\n- License: MIT License\n- Default branch: main\n- Created: 2022-12-18T03:03:19Z\n\n---\n\nTitle: Useless-Garbage-Institute/useless-garbage\nURL: 2015-08-27T22:14:06.000Z\nAuthor: N/A\nHighlights:\n# Repository: Useless-Garbage-Institute/useless-garbage\n...\nThe most profoundly useless javascript library ever invented.\n...\n- Stars: 6\n- Forks: 1\n- Watchers: 6\n- Open issues: 1\n- Primary language: JavaScript\n- Languages: JavaScript\n- Default branch: master\n- Created: 2015-08-27T22:14:06Z\n- Last push: 2015-09-01T01:14:37Z\n- Contributors: 2 (top: kriztynna, cgalbiati)\n...\nThe useless-garbage library is theonly npm module that is guaranteed to have no redeemable functionality whatsoever. There are plenty of helpful JavaScript libraries out there, and some that are of questionable utility, but none that are share our commitment to utter uselessness.\n\n---\n\nTitle: tomekw/whatever\nURL: N/A\nAuthor: N/A\nHighlights:\n- Stars: 281\n- Forks: 115\n- Watchers: 281\n- Open issues: 2\n- Default branch: master\n- Created: 2014-10-10T15:51:31Z\n\n---\n\nTitle:thecodersroom/the-button-that-does-nothing\nURL: 2025-10-06T18:39:22.000Z\nAuthor: N/A\nHighlights:\n# Repository: thecodersroom/the-button-that-does-nothing\n...\nthat looks important\n...\nliterally does nothing\n...\n- Stars: 21\n- Forks: 67\n- Watchers: 0\n- Open issues: 24\n- Primary language: JavaScript\n- Languages: JavaScript (45.4%), CSS (41.9%), HTML (12.7%)\n- License: MIT License (MIT)\n- Topics: css, hacktoberfest, hacktoberfest-accepted, html, javascript\n- Default branch: main\n- Homepage: Created: 2025-10-06T18:39:22Z\n- Last push: 2025-11-04T09:02:47Z\n- Contributors: 60 (top: AbdulKhadhar, AdZard69, Moksh-Mutreja, AshaSaini-033, akshith2855, kronpatel, ahmedrazabaloch, AhishRagav, Nl-T-lN, vanshikap21)\n...\nbuilt entirely with **\n\n---\n\nTitle: GitHub - niltok64/the-useless-collection: A collection of software that serve no purpose other than waste your time. Forking is encouraged!\nURL: 2021-11-30T09:35:25.000Z\nAuthor: niltok64\nHighlights:\n64/the\n...\nuseless-collection\n...\n[\nStar\n1\n]()\n*\nA collection of software that serve no purpose other than waste your time. Forking is encouraged!\n[niltok64.github.io/the-useless-collection/]()\n### License\n...\nstar\n]() [\n0\n...\n://github.com/niltok64/the-useless-collection/forks)\n...\n://github.com/niltok64/the-useless-collection/branches) [\n...\n://github.com/niltok64/the-useless-collection/tags) [\nActivity\n...\n://github.\n...\n/nilt\n...\nthe-useless-collection\n...\n[\n**1**\nstar\n]()\n...\n### Watchers\n\n---\n\nTitle: GitHub - needless-org/needless: The JavaScript library you never asked for, never needed, and probably shouldn't use. But here we are!\nURL: 2023-09-05T14:04:16.000Z\nAuthor: needless-org\nHighlights:\nGitHub - needless-org/needless: The JavaScript library you neverasked for, never needed, and probably shouldn't use. But here we are!\n...\n[Skip to\n...\nneedless-org/needless)\n...\nhttps://github\n...\ncom/login?return_to=/needless-org/needless)\n...\n[\nStar\n1\n]()\n*\nThe JavaScript library you neverasked for, never needed, and probably shouldn't use. But here we are!\n...\n[\n1\nstar\n]() [\n0\nforks\n]() [\nBranches\n]() [\nTags\n]() [\nActivity\n]()\n[\n...\nneedless-\n...\nneedless)\n...\nThe JavaScript library you never asked for, never needed,and probably shouldn't use. But here we are!\n...\n\"My project is running too\n...\nwish there was\n...\nadd some completely unnecessary\n...\nno further!\n...\nIntroducing `needless-js`, the world'sfirst and foremost pointless library. We bring the \"Why?\" into \"Why is this even a thing?\".\n## Features\n...\n1. **Absolutely Useless**: Doesn't fix any problems because it doesn't know what problems are.\n2. **Hilariously Redundant**: Why have one function when you can have ten doing the same thing?\n3. **Zero Dependencies**: Mainly because no other library wants to be associated with us.\n4. **Eco-friendly**: Uses 0% CPU because it does absolutely nothing.\n## Installation\n...\n[\n**1**\nstar\n...\n]()\n\n---\n\nTitle: GitHub - terremoth/awesome-hilarious-repos\nURL: N/A\nAuthor: N/A\nHighlights:\nAwesome Hilarious Github Repositories. Awesome license. GitHub contributors. List of all (?) available and funniest Github repos. Contribute if you know others!\n\n---\n\nTitle: SuavePirate/Xamarin.Yeet\nURL: 2020-02-22T21:16:23.000Z\nAuthor: N/A\nHighlights:\n# Repository: SuavePirate/Xamarin.Yeet\n...\nAn absolutelyuseless tool to yeet your components off the screen.\n...\n- Stars: 2\n- Forks: 1\n- Watchers: 1\n- Open issues: 0\n- Primary language: C#\n- Languages: C#\n- License: MIT License (MIT)\n- Default branch: master\n- Created: 2020-02-22T21:16:23Z\n- Last push: 2020-02-22T21:31:11Z\n- Contributors: 1 (top: SuavePirate)\n...\nAn absolutely useless tool to yeet your components off the screen.\n\n---\n\nTitle: nico-garnier/useless-repo\nURL: 2020-12-03T11:49:46.000Z\nAuthor: N/A\nHighlights:\n# Repository: nico-garnier/useless-repo\n...\n- Stars:1\n- Forks: 0\n- Watchers: 2\n- Open issues: 0\n- Default branch: main\n- Created: 2020-12-03T11:49:46Z\n- Last push: 2020-12-03T14:16:57Z\n- Contributors: 2 (top: nico-garnier, eilenilec)\n...\n# useless-repo\n...\nFor github stat on top collaborators only.\n\n---\n\nTitle: elierotenberg/useless | GitHub | Open Source Insights\nURL: N/A\nAuthor: N/A\nHighlights:\nelierotenberg/useless | GitHub | Open Source Insights\n...\n# elierotenberg/useless\n...\n33 stars", + "_meta": { + "searchTime": 1071.9 + } + } + ] + }, + "jsonrpc": "2.0", + "id": 3 +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316.md b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316.md new file mode 100644 index 0000000..629c4dd --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/01-exa-web-search-exa-165316.md @@ -0,0 +1,183 @@ +# 관찰 로그 01 - exa / `web_search_exa` + +- 출처: `MCP_툴_호출_통신_로그_(JSON-RPC) (1).pdf` +- 원본 생성 시각: 2026-07-13 17:10:33 UTC +- 성격: Agent Builder 솔루션에서 수행한 관찰용 실행 로그. 본 문서는 구현 계약이나 테스트 fixture가 아니다. + +## 헤더 및 실행 메타데이터 + +| 항목 | 원본 기록 값 | +|---|---| +| transport type | `mcp-http` | +| request_id | `045992d3-9683-4409-9613-e355a3eb05e1` | +| tool_uid | `f44207bd-9afb-4bbe-88d7-1cadf9e2779b` | +| Tool version | `2.0` | +| 실행 시각 | 2026-07-13 16:53:16 UTC | +| 결과 | ok · 1896ms · truncated=False | +| JSON-RPC 프레임 수 | 5 | +| lifecycle | `initialize → notifications/initialized → tools/call` | + +### HTTP 헤더 기록 범위 + +원본 PDF에는 개별 HTTP request/response header 값이 기록되어 있지 않다. 원본 표의 `request_id`, `tool_uid`, `version`은 실행 메타데이터이며 HTTP header라고 단정하지 않는다. + +원본 공통 안내에는 시크릿 및 인증 header가 로깅 전에 `[REDACTED]`로 마스킹되었다고 명시되어 있다. 따라서 Authorization, `Mcp-Session-Id` 등 실제 HTTP header 값은 이 문서에 포함하지 않는다. + +## JSON-RPC 통신 전문 + +아래는 원본 PDF의 JSON-RPC 프레임을 순서대로 옮긴 전사본이다. 긴 `result.content[].text` 문자열은 PDF의 시각적 줄바꿈을 보존했으므로, 이 블록 전체를 기계 실행용 단일 JSON payload로 사용하지 않는다. + +```text +16:53:16 요청 → initialize +{ +"jsonrpc": "2.0", +"id": 1, +"method": "initialize", +"params": { +"protocolVersion": "2025-06-18", +"capabilities": {}, +"clientInfo": { +"name": "toolbox-executor", +"version": "0.1.0" +} +} +} +16:53:16 ← 응답 initialize +{ +"result": { +"protocolVersion": "2025-06-18", +"capabilities": { +"tools": { +"listChanged": true +}, +"prompts": { +"listChanged": true +}, +"resources": { +"listChanged": true +} +}, +"serverInfo": { +"name": "exa-search-server", +"title": "Exa", +"version": "3.2.1", +"websiteUrl": "", +"icons": [ +{ +"src": "", +"mimeType": "image/png", +"sizes": [ +"32x32" +] +} +] +} +}, +"jsonrpc": "2.0", +"id": 1 +} +16:53:16 요청 → notifications/initialized +{ +"jsonrpc": "2.0", +"method": "notifications/initialized" +} +16:53:17 요청 → tools/call +{ +"jsonrpc": "2.0", +"id": 3, +"method": "tools/call", +"params": { +"name": "web_search_exa", +"arguments": { +"query": "most popular useless github repository stars useless repo", +"numResults": 10.0 +} +} +} +16:53:18 ← 응답 tools/call +{ +"result": { +"content": [ +{ +"type": "text", +"text": "Title: btahir/uselesshooks\nURL: N/A\nAuthor: N/A\nHighlights:\n# btahir/us\n...\n- Stars: 125\n- Forks: 9\n- Watchers: 125\n- Open +issues: 3\n- License: MIT License\n- Default branch: main\n- Created: 2022-12-18T03:03:19Z\n\n---\n\n +Title: Useless-Garbage-Institute/useless-garbage\nURL: 2015-08-27T22:14:06.000Z\nAuthor: N/A\nHighlights:\n# Repository: Useles +s-Garbage-Institute/useless-garbage\n...\nThe most profoundly useless javascript library ever invente +d.\n...\n- Stars: 6\n- Forks: 1\n- Watchers: 6\n- Open issues: 1\n- Primary language: JavaScript\n- L +anguages: JavaScript\n- Default branch: master\n- Created: 2015-08-27T22:14:06Z\n- Last push: 2015-09 +-01T01:14:37Z\n- Contributors: 2 (top: kriztynna, cgalbiati)\n...\nThe useless-garbage library is the +only npm module that is guaranteed to have no redeemable functionality whatsoever. There are plenty o +f helpful JavaScript libraries out there, and some that are of questionable utility, but none that ar +e share our commitment to utter uselessness.\n\n---\n\nTitle: tomekw/whatever\nURL: N/A\nAuthor: N/A\nHighlights:\n- Stars: 281\n- Forks: 115\n- Watcher +s: 281\n- Open issues: 2\n- Default branch: master\n- Created: 2014-10-10T15:51:31Z\n\n---\n\nTitle: +thecodersroom/the-button-that-does-nothing\nURL: 2025-10-06T18:39:22.000Z\nAuthor: N/A\nHighlights:\n# Repository: thecodersro +om/the-button-that-does-nothing\n...\nthat looks important\n...\nliterally does nothing\n...\n- Star +s: 21\n- Forks: 67\n- Watchers: 0\n- Open issues: 24\n- Primary language: JavaScript\n- Languages: Ja +vaScript (45.4%), CSS (41.9%), HTML (12.7%)\n- License: MIT License (MIT)\n- Topics: css, hacktoberfe +st, hacktoberfest-accepted, html, javascript\n- Default branch: main\n- Homepage: Created: 2025-10-06T18:39:22Z\n- Last push: 2025-11-0 +4T09:02:47Z\n- Contributors: 60 (top: AbdulKhadhar, AdZard69, Moksh-Mutreja, AshaSaini-033, akshith28 +55, kronpatel, ahmedrazabaloch, AhishRagav, Nl-T-lN, vanshikap21)\n...\nbuilt entirely with **\n\n--- +\n\nTitle: GitHub - niltok64/the-useless-collection: A collection of software that serve no purpose o +ther than waste your time. Forking is encouraged!\nURL: 2021-11-30T09:35:25.000Z\nAuthor: niltok64\nHighlights:\n64/the\n...\nuseless-col +lection\n...\n[\nStar\n1\n]()\n* +\nA collection of software that serve no purpose other than waste your time. Forking is encouraged!\n +[niltok64.github.io/the-useless-collection/]()\n# +## License\n...\nstar\n]() [\n0 +\n...\n://github.com/niltok64/the-useless-collection/forks)\n...\n://github.com/niltok64/the-useless- +collection/branches) [\n...\n://github.com/niltok64/the-useless-collection/tags) [\nActivity +\n...\n://github.\n...\n/nilt\n...\nthe-useless-collection\n...\n[\n**1**\nstar\n]()\n...\n### Watchers\n\n---\n\nTitle: GitHub - needless- +org/needless: The JavaScript library you never asked for, never needed, and probably shouldn't use. B +ut here we are!\nURL: 2023-09-05T14:04:16.000Z +\nAuthor: needless-org\nHighlights:\nGitHub - needless-org/needless: The JavaScript library you never +asked for, never needed, and probably shouldn't use. But here we are!\n...\n[Skip to\n...\nneedless-o +rg/needless)\n...\nhttps://github\n...\ncom/login?return_to=/needless-org/needless)\n...\n[\nStar\n1 +\n]()\n*\nThe JavaScript library you never +asked for, never needed, and probably shouldn't use. But here we are!\n...\n[\n1\nstar\n]() [\n0\nforks\n]() [\nBranches\n]() [\nTags\n]() [\nActivity\n]()\n[\n...\nneedless-\n...\nneedless)\n...\nThe JavaScript library you never asked for, never needed, +and probably shouldn't use. But here we are!\n...\n\"My project is running too\n...\nwish there was +\n...\nadd some completely unnecessary\n...\nno further!\n...\nIntroducing `needless-js`, the world's +first and foremost pointless library. We bring the \"Why?\" into \"Why is this even a thing?\".\n## F +eatures\n...\n1. **Absolutely Useless**: Doesn't fix any problems because it doesn't know what proble +ms are.\n2. **Hilariously Redundant**: Why have one function when you can have ten doing the same thi +ng?\n3. **Zero Dependencies**: Mainly because no other library wants to be associated with us.\n4. ** +Eco-friendly**: Uses 0% CPU because it does absolutely nothing.\n## Installation\n...\n[\n**1**\nstar +\n...\n]()\n\n---\n\nTitle: GitHub - terremoth/a +wesome-hilarious-repos\nURL: N/A\n +Author: N/A\nHighlights:\nAwesome Hilarious Github Repositories. Awesome license. GitHub contributor +s. List of all (?) available and funniest Github repos. Contribute if you know others!\n\n---\n\nTitl +e: SuavePirate/Xamarin.Yeet\nURL: 2020-02-2 +2T21:16:23.000Z\nAuthor: N/A\nHighlights:\n# Repository: SuavePirate/Xamarin.Yeet\n...\nAn absolutely +useless tool to yeet your components off the screen.\n...\n- Stars: 2\n- Forks: 1\n- Watchers: 1\n- O +pen issues: 0\n- Primary language: C#\n- Languages: C#\n- License: MIT License (MIT)\n- Default branc +h: master\n- Created: 2020-02-22T21:16:23Z\n- Last push: 2020-02-22T21:31:11Z\n- Contributors: 1 (to +p: SuavePirate)\n...\nAn absolutely useless tool to yeet your components off the screen.\n\n---\n\nTi +tle: nico-garnier/useless-repo\nURL: 2020- +12-03T11:49:46.000Z\nAuthor: N/A\nHighlights:\n# Repository: nico-garnier/useless-repo\n...\n- Stars: +1\n- Forks: 0\n- Watchers: 2\n- Open issues: 0\n- Default branch: main\n- Created: 2020-12-03T11:49:4 +6Z\n- Last push: 2020-12-03T14:16:57Z\n- Contributors: 2 (top: nico-garnier, eilenilec)\n...\n# usele +ss-repo\n...\nFor github stat on top collaborators only.\n\n---\n\nTitle: elierotenberg/useless | Git +Hub | Open Source Insights\nURL: N/A\nAuthor: N/A\nHighlights:\nelierotenberg/useless | GitHub | Open Source Insights\n...\n# eliero +tenberg/useless\n...\n33 stars", +"_meta": { +"searchTime": 1071.9 +} +} +] +}, +"jsonrpc": "2.0", +"id": 3 +} +``` + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-initialize-request.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-initialize-request.json new file mode 100644 index 0000000..15a192b --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-initialize-request.json @@ -0,0 +1,14 @@ +{ + "jsonrpc": "2.0", + "id": 1, + "method": "initialize", + "params": { + "protocolVersion": "2025-06-18", + "capabilities": {}, + "clientInfo": { + "name": "toolbox-executor", + "version": "0.1.0" + } + } +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-initialize-response.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-initialize-response.json new file mode 100644 index 0000000..f15b53e --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-initialize-response.json @@ -0,0 +1,34 @@ +{ + "result": { + "protocolVersion": "2025-06-18", + "capabilities": { + "tools": { + "listChanged": true + }, + "prompts": { + "listChanged": true + }, + "resources": { + "listChanged": true + } + }, + "serverInfo": { + "name": "exa-search-server", + "title": "Exa", + "version": "3.2.1", + "websiteUrl": "", + "icons": [ + { + "src": "", + "mimeType": "image/png", + "sizes": [ + "32x32" + ] + } + ] + } + }, + "jsonrpc": "2.0", + "id": 1 +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-initialized-notification.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-initialized-notification.json new file mode 100644 index 0000000..9ed0b56 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-initialized-notification.json @@ -0,0 +1,5 @@ +{ + "jsonrpc": "2.0", + "method": "notifications/initialized" +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-tools-call-request.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-tools-call-request.json new file mode 100644 index 0000000..2ab6acc --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-tools-call-request.json @@ -0,0 +1,13 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "web_search_exa", + "arguments": { + "query": "site:github.com \"does nothing\" stars", + "numResults": 10 + } + } +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-tools-call-response.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-tools-call-response.json new file mode 100644 index 0000000..307a7db --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324-tools-call-response.json @@ -0,0 +1,16 @@ +{ + "result": { + "content": [ + { + "type": "text", + "text": "Title: michaelb/do-nothing.vim\nURL: N/A\nAuthor: N/A\nHighlights:\nA vim plugin that does nothing. Because why not\n...\n- Stars: 121\n- Forks: 4\n- Watchers: 121\n- Open issues: 1\n- License: MIT License\n- Default branch: main\n- Created: 2021-07-06T07:35:05Z\n...\nThis plugin doesn't do anything.\n\n---\n\nTitle: silicakes/nada-js\nURL: N/A\nAuthor: N/A\nHighlights:\nA Library that does nothing\n...\n- Stars: 32\n- Forks: 0\n- Watchers: 32\n- Open issues: 3\n- License: MITLicense\n- Default branch: main\n- Created: 2019-05-29T22:52:59Z\n...\n### A Library that does nothing in or for your project\n...\nNadaJS gives a single guarantee: Aside from taking space, it will do absolutely nothing.\nNo matter what kind of project, architecture or constraints you might have, nadaJS always gets nothing done.\n\n---\n\nTitle: GitHub - azr/donothing: does nothing !\nURL: 2012-10-25T16:10:49.000Z\nAuthor: azr\nHighlights:\nGitHub - az\n...\ndonothing: does nothing !\n...\n[\nStar\n1\n]()\n...\n*\ndoes nothing !\n### License\n...\n[\n1\n...\nstar\n]() [\n0\n...\n://github.com/azr/donothing/forks) [\n...\n://github.com/azr/donothing/branches\n...\nTags\n](\n...\n://github.com/azr/donothing/tags\n...\n://github.com/azr/donothing/activity)\n...\n://github.com/\n...\n=/azr/donothing)\n...\ndoes nothing !\n...\n[\n**1**\nstar\n]()\n\n---\n\nTitle: imjakechapman/TheNothingApp\nURL: 2014-06-19T22:35:01.000Z\nAuthor: N/A\nHighlights:\nThe app that does literally nothing.\n...\n- Stars: 19\n- Forks: 2\n- Watchers: 19\n- Open issues: 2\n-Primary language: Swift\n- Languages: Swift (71.3%), Java (28.7%)\n- Default branch: master\n- Homepage: thenothingapp.com\n- Created: 2014-06-19T22:35:01Z\n- Last push: 2015-06-22T22:07:41Z\n- Contributors: 2 (top: imjakechapman, thiagokimo)\n...\nThe app that does literally nothing, hackernews/designernews/twitter approved best application for doing jack-diddley-squat.\n\n---\n\nTitle: thecodersroom/the-button-that-does-nothing\nURL: 2025-10-06T18:39:22.000Z\nAuthor: N/A\nHighlights:\n- Stars: 21\n- Forks: 67\n- Watchers:0\n- Open issues: 24\n- Primary language: JavaScript\n- Languages: JavaScript (45.4%), CSS (41.9%), HTML (12.7%)\n- License: MIT License (MIT)\n- Topics: css, hacktoberfest, hacktoberfest-accepted, html, javascript\n- Default branch: main\n- Homepage: Created: 2025-10-06T18:39:22Z\n- Last push: 2025-11-04T09:02:47Z\n- Contributors: 60(top: AbdulKhadhar, AdZard69, Moksh-Mutreja, AshaSaini-033, akshith2855, kronpatel, ahmedrazabaloch,AhishRagav, Nl-T-lN, vanshikap21)\n\n---\n\nTitle: seeschloss/nothing-to-see-here\nURL: N/A\nAuthor: N/A\nHighlights:\nAn NPM package which does nothing\n...\n- Stars: 1\n- Forks: 0\n- Watchers: 1\n- Open issues: 0\n- License: MIT License\n- Default branch: master\n- Created: 2015-01-21T08:32:44Z\n...\n## Usage ##\n\n var nothing = require('nothing-to-see-here');\n // Do nothing with nothing, since it does nothing at all.\n\n---\n\nTitle: 10xly/do-nothing\nURL: N/A\nAuthor: N/A\nHighlights:\n- Stars: 1\n- Forks: 0\n- Watchers: 1\n- Open issues: 0\n- Default branch: main\n- Created: 2024-09-06T19:20:09Z\n- Fork: yes\n...\nDo nothing.\n...\nIt's just another noop\n\n---\n\nTitle: Searchcode, repositories, users, issues, pull requests...\nURL: 2025-07-22T16:46:01.000Z\nAuthor: techsiddhi\nHighlights:\n.com/\n...\n](https://\n...\n* [Notifications]()You must be signed in to change notification settings\n* [Fork0]()\n* [Star1]()\n...\n[1star]()[0forks]()[Branches]()[Tags]()[Activity]()\n...\n[Star]()\n...\n/activity)\n...\n[**1**star]()\n### Watchers\n[**0**watching]()\n\n---\n\nTitle: NicusorN5/DoNothing\nURL: 2023-08-19T15:20:52.000Z\nAuthor: N/A\nHighlights:\nThis does nothing. Literally nothing.\n...\n- Stars: 0\n- Forks: 0\n- Watchers: 0\n- Open issues: 0\n- Primary language: Assembly\n- Languages: Assembly\n- License: MIT License (MIT)\n- Topics: assembly, nothing\n- Default branch: main\n- Created: 2023-08-19T15:20:52Z\n- Last push: 2023-08-19T15:29:03Z\n- Contributors: 1 (top: NicusorN5)\n- Releases: 1\n- Latest release: release (2023-08-19T15:29:03Z)\n- Archived: true\n...\nThis does nothing. Literally nothing.\n\n---\n\nTitle: README.md\nURL: N/A\nAuthor: N/A\nHighlights:\n# does_nothing : A library that does nothing\n...\n- `function a()`\n - Description: Doessome meaningless caluculation.\n - Input: nothing.\n - Output: nothing.\n...\n- `function b()`\n - Description: Does some meaningless caluculation.\n - Input: nothing.\n - Output: nothing.\n...\n- `function c()`\n - Description: Does some meaningless caluculation.\n - Input: nothing.\n - Output: nothing.\n...\nThough functions in this library are completely harmless and consume little cpu resource, not telling users that the program sometimes does a meaningless calculation or computes inefficiently may result in a criminal prosecution as the program may be against users' intention. (in Japan)", + "_meta": { + "searchTime": 976.1 + } + } + ] + }, + "jsonrpc": "2.0", + "id": 3 +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324.md b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324.md new file mode 100644 index 0000000..b01528b --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/02-exa-web-search-exa-165324.md @@ -0,0 +1,176 @@ +# 관찰 로그 02 - exa / `web_search_exa` + +- 출처: `MCP_툴_호출_통신_로그_(JSON-RPC) (1).pdf` +- 원본 생성 시각: 2026-07-13 17:10:33 UTC +- 성격: Agent Builder 솔루션에서 수행한 관찰용 실행 로그. 본 문서는 구현 계약이나 테스트 fixture가 아니다. + +## 헤더 및 실행 메타데이터 + +| 항목 | 원본 기록 값 | +|---|---| +| transport type | `mcp-http` | +| request_id | `536d9a7e-be3e-4847-8878-f71ae1d690ba` | +| tool_uid | `f44207bd-9afb-4bbe-88d7-1cadf9e2779b` | +| Tool version | `2.0` | +| 실행 시각 | 2026-07-13 16:53:24 UTC | +| 결과 | ok · 1768ms · truncated=False | +| JSON-RPC 프레임 수 | 5 | +| lifecycle | `initialize → notifications/initialized → tools/call` | + +### HTTP 헤더 기록 범위 + +원본 PDF에는 개별 HTTP request/response header 값이 기록되어 있지 않다. 원본 표의 `request_id`, `tool_uid`, `version`은 실행 메타데이터이며 HTTP header라고 단정하지 않는다. + +원본 공통 안내에는 시크릿 및 인증 header가 로깅 전에 `[REDACTED]`로 마스킹되었다고 명시되어 있다. 따라서 Authorization, `Mcp-Session-Id` 등 실제 HTTP header 값은 이 문서에 포함하지 않는다. + +## JSON-RPC 통신 전문 + +아래는 원본 PDF의 JSON-RPC 프레임을 순서대로 옮긴 전사본이다. 긴 `result.content[].text` 문자열은 PDF의 시각적 줄바꿈을 보존했으므로, 이 블록 전체를 기계 실행용 단일 JSON payload로 사용하지 않는다. + +```text +16:53:24 요청 → initialize +{ +"jsonrpc": "2.0", +"id": 1, +"method": "initialize", +"params": { +"protocolVersion": "2025-06-18", +"capabilities": {}, +"clientInfo": { +"name": "toolbox-executor", +"version": "0.1.0" +} +} +} +16:53:24 ← 응답 initialize +{ +"result": { +"protocolVersion": "2025-06-18", +"capabilities": { +"tools": { +"listChanged": true +}, +"prompts": { +"listChanged": true +}, +"resources": { +"listChanged": true +} +}, +"serverInfo": { +"name": "exa-search-server", +"title": "Exa", +"version": "3.2.1", +"websiteUrl": "", +"icons": [ +{ +"src": "", +"mimeType": "image/png", +"sizes": [ +"32x32" +] +} +] +} +}, +"jsonrpc": "2.0", +"id": 1 +} +16:53:24 요청 → notifications/initialized +{ +"jsonrpc": "2.0", +"method": "notifications/initialized" +} +16:53:24 요청 → tools/call +{ +"jsonrpc": "2.0", +"id": 3, +"method": "tools/call", +"params": { +"name": "web_search_exa", +"arguments": { +"query": "site:github.com \"does nothing\" stars", +"numResults": 10.0 +} +} +} +16:53:25 ← 응답 tools/call +{ +"result": { +"content": [ +{ +"type": "text", +"text": "Title: michaelb/do-nothing.vim\nURL: N/A\nAuthor: N/A\nHighlights:\nA vim plugin that does nothing. Because why not\n...\n- Star +s: 121\n- Forks: 4\n- Watchers: 121\n- Open issues: 1\n- License: MIT License\n- Default branch: main +\n- Created: 2021-07-06T07:35:05Z\n...\nThis plugin doesn't do anything.\n\n---\n\nTitle: silicakes/n +ada-js\nURL: N/A\nAuthor: N/A\nHighlights:\nA Libr +ary that does nothing\n...\n- Stars: 32\n- Forks: 0\n- Watchers: 32\n- Open issues: 3\n- License: MIT +License\n- Default branch: main\n- Created: 2019-05-29T22:52:59Z\n...\n### A Library that does nothin +g in or for your project\n...\nNadaJS gives a single guarantee: Aside from taking space, it will do a +bsolutely nothing.\nNo matter what kind of project, architecture or constraints you might have, nadaJ +S always gets nothing done.\n\n---\n\nTitle: GitHub - azr/donothing: does nothing !\nURL: 2012-10-25T16:10:49.000Z\nAuthor: azr\nHighlights:\nGitHub - az +\n...\ndonothing: does nothing !\n...\n[\nStar\n1\n]()\n...\n*\ndoes nothing !\n### License\n...\n[\n1\n...\nstar\n]() [\n0\n...\n://github.com/azr/donothing/forks) [\n...\n://github.com/azr/donothing/branch +es\n...\nTags\n](\n...\n://github.com/azr/donothing/tags\n...\n://github.com/azr/donothing/activity) +\n...\n://github.com/\n...\n=/azr/donothing)\n...\ndoes nothing !\n...\n[\n**1**\nstar\n]()\n\n---\n\nTitle: imjakechapman/TheNothingApp\nURL: 2014-06-19T22:35:01.000Z\nAuthor: N/A\nHighlights:\nTh +e app that does literally nothing.\n...\n- Stars: 19\n- Forks: 2\n- Watchers: 19\n- Open issues: 2\n- +Primary language: Swift\n- Languages: Swift (71.3%), Java (28.7%)\n- Default branch: master\n- Homepa +ge: thenothingapp.com\n- Created: 2014-06-19T22:35:01Z\n- Last push: 2015-06-22T22:07:41Z\n- Contribu +tors: 2 (top: imjakechapman, thiagokimo)\n...\nThe app that does literally nothing, hackernews/design +ernews/twitter approved best application for doing jack-diddley-squat.\n\n---\n\nTitle: thecodersroo +m/the-button-that-does-nothing\nURL: 2025-10-06T18:39:22.000Z\nAuthor: N/A\nHighlights:\n- Stars: 21\n- Forks: 67\n- Watchers: +0\n- Open issues: 24\n- Primary language: JavaScript\n- Languages: JavaScript (45.4%), CSS (41.9%), H +TML (12.7%)\n- License: MIT License (MIT)\n- Topics: css, hacktoberfest, hacktoberfest-accepted, htm +l, javascript\n- Default branch: main\n- Homepage: Created: 2025-10-06T18:39:22Z\n- Last push: 2025-11-04T09:02:47Z\n- Contributors: 60 +(top: AbdulKhadhar, AdZard69, Moksh-Mutreja, AshaSaini-033, akshith2855, kronpatel, ahmedrazabaloch, +AhishRagav, Nl-T-lN, vanshikap21)\n\n---\n\nTitle: seeschloss/nothing-to-see-here\nURL: N/A\nAuthor: N/A\nHighlights:\nAn NPM package whic +h does nothing\n...\n- Stars: 1\n- Forks: 0\n- Watchers: 1\n- Open issues: 0\n- License: MIT License +\n- Default branch: master\n- Created: 2015-01-21T08:32:44Z\n...\n## Usage ##\n\n var nothing = requi +re('nothing-to-see-here');\n // Do nothing with nothing, since it does nothing at all.\n\n---\n\nTitl +e: 10xly/do-nothing\nURL: N/A\nAuthor: N/A\nHighlig +hts:\n- Stars: 1\n- Forks: 0\n- Watchers: 1\n- Open issues: 0\n- Default branch: main\n- Created: 202 +4-09-06T19:20:09Z\n- Fork: yes\n...\nDo nothing.\n...\nIt's just another noop\n\n---\n\nTitle: Search +code, repositories, users, issues, pull requests...\nURL: 2025-07-22T16:46:01.000Z\nAuthor: techsiddhi\nHighlights:\n.com/\n...\n](https:// +\n...\n* [Notifications]()You must be si +gned in to change notification settings\n* [Fork0]()\n* [Star1]()\n...\n[1star] +()[0forks]()[Branches]()[Tags]()[Activity]()\n...\n[Star]()\n...\n/activity) +\n...\n[**1**star]()\n### Watchers\n[**0**watc +hing]()\n\n---\n\nTitle: NicusorN5/DoNothing\nUR +L: 2023-08-19T15:20:52.000Z\nAuthor: N/A\nHighli +ghts:\nThis does nothing. Literally nothing.\n...\n- Stars: 0\n- Forks: 0\n- Watchers: 0\n- Open issu +es: 0\n- Primary language: Assembly\n- Languages: Assembly\n- License: MIT License (MIT)\n- Topics: a +ssembly, nothing\n- Default branch: main\n- Created: 2023-08-19T15:20:52Z\n- Last push: 2023-08-19T1 +5:29:03Z\n- Contributors: 1 (top: NicusorN5)\n- Releases: 1\n- Latest release: release (2023-08-19T1 +5:29:03Z)\n- Archived: true\n...\nThis does nothing. Literally nothing.\n\n---\n\nTitle: README.md\nU +RL: N/A\nAuthor: N/A\nH +ighlights:\n# does_nothing : A library that does nothing\n...\n- `function a()`\n - Description: Does +some meaningless caluculation.\n - Input: nothing.\n - Output: nothing.\n...\n- `function b()`\n - De +scription: Does some meaningless caluculation.\n - Input: nothing.\n - Output: nothing.\n...\n- `func +tion c()`\n - Description: Does some meaningless caluculation.\n - Input: nothing.\n - Output: nothin +g.\n...\nThough functions in this library are completely harmless and consume little cpu resource, no +t telling users that the program sometimes does a meaningless calculation or computes inefficiently m +ay result in a criminal prosecution as the program may be against users' intention. (in Japan)", +"_meta": { +"searchTime": 976.1 +} +} +] +}, +"jsonrpc": "2.0", +"id": 3 +} +``` + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-initialize-request.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-initialize-request.json new file mode 100644 index 0000000..15a192b --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-initialize-request.json @@ -0,0 +1,14 @@ +{ + "jsonrpc": "2.0", + "id": 1, + "method": "initialize", + "params": { + "protocolVersion": "2025-06-18", + "capabilities": {}, + "clientInfo": { + "name": "toolbox-executor", + "version": "0.1.0" + } + } +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-initialize-response.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-initialize-response.json new file mode 100644 index 0000000..f15b53e --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-initialize-response.json @@ -0,0 +1,34 @@ +{ + "result": { + "protocolVersion": "2025-06-18", + "capabilities": { + "tools": { + "listChanged": true + }, + "prompts": { + "listChanged": true + }, + "resources": { + "listChanged": true + } + }, + "serverInfo": { + "name": "exa-search-server", + "title": "Exa", + "version": "3.2.1", + "websiteUrl": "", + "icons": [ + { + "src": "", + "mimeType": "image/png", + "sizes": [ + "32x32" + ] + } + ] + } + }, + "jsonrpc": "2.0", + "id": 1 +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-initialized-notification.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-initialized-notification.json new file mode 100644 index 0000000..9ed0b56 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-initialized-notification.json @@ -0,0 +1,5 @@ +{ + "jsonrpc": "2.0", + "method": "notifications/initialized" +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-tools-call-request.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-tools-call-request.json new file mode 100644 index 0000000..b303112 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-tools-call-request.json @@ -0,0 +1,13 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "web_search_exa", + "arguments": { + "query": "site:github.com \"useless\" \"stars\" \"forks\" repository useless", + "numResults": 10 + } + } +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-tools-call-response.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-tools-call-response.json new file mode 100644 index 0000000..e109a59 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331-tools-call-response.json @@ -0,0 +1,16 @@ +{ + "result": { + "content": [ + { + "type": "text", + "text": "Title: gianmarco-mameli/uselessrepo\nURL: 2023-04-17T12:26:41.000Z\nAuthor: N/A\nHighlights:\n# Repository: gianmarco-mameli/uselessrepo\n...\nThis useless repo is created for versioning a version\n...\n- Stars: 3\n- Forks:2\n- Watchers: 1\n- Open issues: 0\n- Default branch: main\n- Created: 2023-04-17T12:26:41Z\n- Last push: 2025-05-09T07:38:26Z\n- Contributors: 3 (top: gianmarco-mameli, s0ys4uc3, CrownKingClown)\n...\n# uselessrepo\n...\nThis useless repo is created for versioning a version\n\n---\n\nTitle: tinkerhub/useless_project_temp\nURL: N/A\nAuthor: N/A\nHighlights:\n# tinkerhub/useless_project_temp\n...\n- Stars: 15\n- Forks: 854\n- Watchers: 15\n- Open issues: 42\n- Default branch: main\n- Created: 2024-10-23T10:26:22Z\n\n---\n\nTitle: btahir/uselesshooks\nURL: N/A\nAuthor: N/A\nHighlights:\n# btahir/uselesshooks\n...\nA Collection of U\n...\ness React Hooks to impress your coworkers\n...\n- Stars: 125\n- Forks: 9\n- Watchers: 125\n- Open issues: 3\n- License: MIT License\n- Defaultbranch: main\n- Created: 2022-12-18T03:03:19Z\n\n---\n\nTitle: dorktoast/turd\nURL: N/A\nAuthor: N/A\nHighlights:\nThe Useless Repo (Duh)\n...\n- Stars: 2\n- Forks: 0\n- Watchers: 2\n- Open issues: 0\n- Default branch: master\n- Created: 2023-08-22T08:54:42Z\n\n##\n...\n# TURD: The Useless Repo (Duh)\n...\nThis is the most useless repo on github. Insidethis repo you will find scripts that make your soul hurt.\n\n---\n\nTitle: elierotenberg/useless\nURL: 2020-05-10T09:53:12.000Z\nAuthor: N/A\nHighlights:\n# Repository: elierotenberg/useless\n...\nUseless React hooks\n...\n- Stars: 33\n- Forks: 1\n- Watchers: 1\n- Open issues: 6\n- Primary language: TypeScript\n- Languages: TypeScript (68.7%), JavaScript (31.3%)\n- Default branch: master\n- Created: 2020-05-10T09:53:12Z\n- Last push: 2022-03-26T16:38:59Z\n- Contributors: 1 (top: elierotenberg)\n...\nThis is a library of useless hooks for common non-use-cases.\n\n---\n\nTitle: GitHub - niltok64/the-useless-collection: A collection of softwarethat serve no purpose other than waste your time. Forking is encouraged!\nURL: 2021-11-30T09:35:25.000Z\nAuthor: niltok64\nHighlights:\nGitHub - niltok64/the-useless-collection: A collection of software that serve no purpose other than waste your time. Forking is encouraged!\n[Skip to content](#start-of-content)\n## Navigation Menu\nToggle navigation\n...\n](.\n...\n/\n**\n[the-useless-collection]()\n**\nPublic\n* [Notifications\n]() You must be signed in to change notification settings\n* [Fork\n0\n...\n]()\n*\n...\n[\nStar\n1\n]()\n*\nA collection of software that serve no purpose other than waste your time. Forking is encouraged!\n[niltok64.github.io/the-useless-collection/]()\n### License\n...\nstar\n]() [\n0\n...\nforks\n]() [\nBranches\n]() [\nTags\n]() [\nActivity\n]()\n[\n...\nA collection of software that serve no purpose other than waste your time. Forking is encouraged!\n...\nRequires Python 3.9for building.\n## Usage\n...\nTo use on Unix-based systems run \"pyinstaller main.\n...\n--onefile\"\n...\nline in any of the folders. You can also use the executables in\n...\n`automated-build/` folder to build all the programs at once.\n## About\nA collection of software that serve no purpose other than waste your time. Forking is encouraged!\n[niltok64.github.io/the-useless-collection/]()\n...\nuseless-collection/activity)\n...\n[\n**1**\nstar\n]()\n### Watchers\n...\n[\n**1**\n...\ncom/niltok64/the-useless-collection/watchers)\n...\n[\n**0**\nforks\n]()\n[\n\n---\n\nTitle: erikvorhes/Useless-JS\nURL: N/A\nAuthor: N/A\nHighlights:\n# erikvorhes/Useless-JS\n...\nScripts that do nothing or overcomplicate things.\n...\n- Stars: 8\n- Forks: 3\n- Watchers: 8\n- Openissues: 1\n- License: Do What The F*ck You Want To Public License\n- Default branch: master\n- Created: 2011-08-19T14:09:26Z\n\n##\n...\n# Useless JS\n...\nThis is a collection of scripts that don't really do anything useful.\n...\nI've created a couple script files to get us started. Please add your own!\n\n---\n\nTitle: stac47/libuseless\nURL: N/A\nAuthor: stac47\nHighlights:\n# stac47/libuseless\n...\nThe most useless C++ library in the world\n...\n- Stars: 0\n- Forks: 0\n- Watchers: 0\n- Open issues: 0\n- License: GNU General Public Licensev3.0\n- Default branch: main\n- Created: 2021-01-29T13:34:01Z\n...\nThe most useless C++ library in the world\n\n---\n\nTitle: jeku/useless\nURL: 2012-08-02T14:05:01.000Z\nAuthor: jeku\nHighlights:\n# Repository: jeku/useless\n\nquite useless\n...\n- Stars:1\n- Forks: 0\n- Watchers: 1\n- Open issues: 0\n- Default branch: master\n- Created: 2012-08-02T14:05:01Z\n- Last push: 2012-08-02T14:05:01Z\n- Contributors: 1 (top: jeku)\n\n---\n\nTitle: barelyhuman/useless\nURL: N/A\nAuthor: N/A\nHighlights:\n# barelyhuman/useless\n...\nA set of useless utilities for javascript\n...\n- Stars: 6\n- Forks: 0\n- Watchers: 6\n- Open issues: 0\n- License: MIT License\n- Default branch: dev\n- Created: 2022-04-14T08:52:31Z\n\n## Languages\n...\n## README\n\n \n \n A set of useless utilities for javascript \n\n## Documentation\n...\nalready exist somewhere\n...\nand I'm just writing\n...\nto feel good about having my own set of utilties.", + "_meta": { + "searchTime": 1216.7 + } + } + ] + }, + "jsonrpc": "2.0", + "id": 3 +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331.md b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331.md new file mode 100644 index 0000000..25bcdaf --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/03-exa-web-search-exa-165331.md @@ -0,0 +1,178 @@ +# 관찰 로그 03 - exa / `web_search_exa` + +- 출처: `MCP_툴_호출_통신_로그_(JSON-RPC) (1).pdf` +- 원본 생성 시각: 2026-07-13 17:10:33 UTC +- 성격: Agent Builder 솔루션에서 수행한 관찰용 실행 로그. 본 문서는 구현 계약이나 테스트 fixture가 아니다. + +## 헤더 및 실행 메타데이터 + +| 항목 | 원본 기록 값 | +|---|---| +| transport type | `mcp-http` | +| request_id | `5720da6c-68cc-44f3-8a1f-73088bddc23d` | +| tool_uid | `f44207bd-9afb-4bbe-88d7-1cadf9e2779b` | +| Tool version | `2.0` | +| 실행 시각 | 2026-07-13 16:53:31 UTC | +| 결과 | ok · 2070ms · truncated=False | +| JSON-RPC 프레임 수 | 5 | +| lifecycle | `initialize → notifications/initialized → tools/call` | + +### HTTP 헤더 기록 범위 + +원본 PDF에는 개별 HTTP request/response header 값이 기록되어 있지 않다. 원본 표의 `request_id`, `tool_uid`, `version`은 실행 메타데이터이며 HTTP header라고 단정하지 않는다. + +원본 공통 안내에는 시크릿 및 인증 header가 로깅 전에 `[REDACTED]`로 마스킹되었다고 명시되어 있다. 따라서 Authorization, `Mcp-Session-Id` 등 실제 HTTP header 값은 이 문서에 포함하지 않는다. + +## JSON-RPC 통신 전문 + +아래는 원본 PDF의 JSON-RPC 프레임을 순서대로 옮긴 전사본이다. 긴 `result.content[].text` 문자열은 PDF의 시각적 줄바꿈을 보존했으므로, 이 블록 전체를 기계 실행용 단일 JSON payload로 사용하지 않는다. + +```text +16:53:31 요청 → initialize +{ +"jsonrpc": "2.0", +"id": 1, +"method": "initialize", +"params": { +"protocolVersion": "2025-06-18", +"capabilities": {}, +"clientInfo": { +"name": "toolbox-executor", +"version": "0.1.0" +} +} +} +16:53:31 ← 응답 initialize +{ +"result": { +"protocolVersion": "2025-06-18", +"capabilities": { +"tools": { +"listChanged": true +}, +"prompts": { +"listChanged": true +}, +"resources": { +"listChanged": true +} +}, +"serverInfo": { +"name": "exa-search-server", +"title": "Exa", +"version": "3.2.1", +"websiteUrl": "", +"icons": [ +{ +"src": "", +"mimeType": "image/png", +"sizes": [ +"32x32" +] +} +] +} +}, +"jsonrpc": "2.0", +"id": 1 +} +16:53:31 요청 → notifications/initialized +{ +"jsonrpc": "2.0", +"method": "notifications/initialized" +} +16:53:31 요청 → tools/call +{ +"jsonrpc": "2.0", +"id": 3, +"method": "tools/call", +"params": { +"name": "web_search_exa", +"arguments": { +"query": "site:github.com \"useless\" \"stars\" \"forks\" repository useless", +"numResults": 10.0 +} +} +} +16:53:33 ← 응답 tools/call +{ +"result": { +"content": [ +{ +"type": "text", +"text": "Title: gianmarco-mameli/uselessrepo\nURL: 2023-04-17T12:26:41.000Z\nAuthor: N/A\nHighlights:\n# Repository: gianmarco-mamel +i/uselessrepo\n...\nThis useless repo is created for versioning a version\n...\n- Stars: 3\n- Forks: +2\n- Watchers: 1\n- Open issues: 0\n- Default branch: main\n- Created: 2023-04-17T12:26:41Z\n- Last p +ush: 2025-05-09T07:38:26Z\n- Contributors: 3 (top: gianmarco-mameli, s0ys4uc3, CrownKingClown)\n...\n +# uselessrepo\n...\nThis useless repo is created for versioning a version\n\n---\n\nTitle: tinkerhub/ +useless_project_temp\nURL: N/A\nAutho +r: N/A\nHighlights:\n# tinkerhub/useless_project_temp\n...\n- Stars: 15\n- Forks: 854\n- Watchers: 15 +\n- Open issues: 42\n- Default branch: main\n- Created: 2024-10-23T10:26:22Z\n\n---\n\nTitle: btahir/ +uselesshooks\nURL: N/A\nAuthor: N/A\nHighlight +s:\n# btahir/uselesshooks\n...\nA Collection of U\n...\ness React Hooks to impress your coworkers +\n...\n- Stars: 125\n- Forks: 9\n- Watchers: 125\n- Open issues: 3\n- License: MIT License\n- Default +branch: main\n- Created: 2022-12-18T03:03:19Z\n\n---\n\nTitle: dorktoast/turd\nURL: N/A\nAuthor: N/A\nHighlights:\nThe Useless Repo (Duh)\n...\n- Stars: 2 +\n- Forks: 0\n- Watchers: 2\n- Open issues: 0\n- Default branch: master\n- Created: 2023-08-22T08:54: +42Z\n\n##\n...\n# TURD: The Useless Repo (Duh)\n...\nThis is the most useless repo on github. Inside +this repo you will find scripts that make your soul hurt.\n\n---\n\nTitle: elierotenberg/useless\nUR +L: 2020-05-10T09:53:12.000Z\nAuthor: N/A\nHigh +lights:\n# Repository: elierotenberg/useless\n...\nUseless React hooks\n...\n- Stars: 33\n- Forks: 1 +\n- Watchers: 1\n- Open issues: 6\n- Primary language: TypeScript\n- Languages: TypeScript (68.7%), J +avaScript (31.3%)\n- Default branch: master\n- Created: 2020-05-10T09:53:12Z\n- Last push: 2022-03-26 +T16:38:59Z\n- Contributors: 1 (top: elierotenberg)\n...\nThis is a library of useless hooks for commo +n non-use-cases.\n\n---\n\nTitle: GitHub - niltok64/the-useless-collection: A collection of software +that serve no purpose other than waste your time. Forking is encouraged!\nURL: 2021-11-30T09:35:25.000Z\nAuthor: niltok64\nHighlights:\nG +itHub - niltok64/the-useless-collection: A collection of software that serve no purpose other than wa +ste your time. Forking is encouraged!\n[Skip to content](#start-of-content)\n## Navigation Menu\nTogg +le navigation\n...\n](.\n...\n/\n**\n[the-useless-collection]()\n**\nPublic\n* [Notifications\n]() You must be signed in to change notification settings\n* [Fork\n0 +\n...\n]()\n*\n...\n[\nStar\n1 +\n]()\n*\nA collection of softwa +re that serve no purpose other than waste your time. Forking is encouraged!\n[niltok64.github.io/the- +useless-collection/]()\n### License\n...\nstar\n] +() [\n0\n...\nforks\n]() [\nBranches\n]() [\nTags\n]() [\nActiv +ity\n]()\n[\n...\nA collection of softwa +re that serve no purpose other than waste your time. Forking is encouraged!\n...\nRequires Python 3.9 +for building.\n## Usage\n...\nTo use on Unix-based systems run \"pyinstaller main.\n...\n--onefile +\"\n...\nline in any of the folders. You can also use the executables in\n...\n`automated-build/` fol +der to build all the programs at once.\n## About\nA collection of software that serve no purpose othe +r than waste your time. Forking is encouraged!\n[niltok64.github.io/the-useless-collection/]()\n...\nuseless-collection/activity)\n...\n[\n**1**\ns +tar\n]()\n### Watchers\n...\n[\n**1** +\n...\ncom/niltok64/the-useless-collection/watchers)\n...\n[\n**0**\nforks\n]()\n[\n\n---\n\nTitle: erikvorhes/Useless-JS\nURL: N/A\nAuthor: N/A\nHighlights:\n# erikvorhes/Useless-JS\n...\nS +cripts that do nothing or overcomplicate things.\n...\n- Stars: 8\n- Forks: 3\n- Watchers: 8\n- Open +issues: 1\n- License: Do What The F*ck You Want To Public License\n- Default branch: master\n- Create +d: 2011-08-19T14:09:26Z\n\n##\n...\n# Useless JS\n...\nThis is a collection of scripts that don't rea +lly do anything useful.\n...\nI've created a couple script files to get us started. Please add your o +wn!\n\n---\n\nTitle: stac47/libuseless\nURL: N/A\n +Author: stac47\nHighlights:\n# stac47/libuseless\n...\nThe most useless C++ library in the world +\n...\n- Stars: 0\n- Forks: 0\n- Watchers: 0\n- Open issues: 0\n- License: GNU General Public License +v3.0\n- Default branch: main\n- Created: 2021-01-29T13:34:01Z\n...\nThe most useless C++ library in t +he world\n\n---\n\nTitle: jeku/useless\nURL: 2012-08-02 +T14:05:01.000Z\nAuthor: jeku\nHighlights:\n# Repository: jeku/useless\n\nquite useless\n...\n- Stars: +1\n- Forks: 0\n- Watchers: 1\n- Open issues: 0\n- Default branch: master\n- Created: 2012-08-02T14:0 +5:01Z\n- Last push: 2012-08-02T14:05:01Z\n- Contributors: 1 (top: jeku)\n\n---\n\nTitle: barelyhuman/ +useless\nURL: N/A\nAuthor: N/A\nHighlights:\n# b +arelyhuman/useless\n...\nA set of useless utilities for javascript\n...\n- Stars: 6\n- Forks: 0\n- Wa +tchers: 6\n- Open issues: 0\n- License: MIT License\n- Default branch: dev\n- Created: 2022-04-14T08: +52:31Z\n\n## Languages\n...\n## README\n\n \n \n A set of useless utilities for javascript \n\n## Doc +umentation\n...\nalready exist somewhere\n...\nand I'm just writing\n...\nto feel good about having m +y own set of utilties.", +"_meta": { +"searchTime": 1216.7 +} +} +] +}, +"jsonrpc": "2.0", +"id": 3 +} +``` diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search-initialize-request.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search-initialize-request.json new file mode 100644 index 0000000..15a192b --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search-initialize-request.json @@ -0,0 +1,14 @@ +{ + "jsonrpc": "2.0", + "id": 1, + "method": "initialize", + "params": { + "protocolVersion": "2025-06-18", + "capabilities": {}, + "clientInfo": { + "name": "toolbox-executor", + "version": "0.1.0" + } + } +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search-initialize-response.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search-initialize-response.json new file mode 100644 index 0000000..f03e5e7 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search-initialize-response.json @@ -0,0 +1,27 @@ +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "protocolVersion": "2025-06-18", + "capabilities": { + "tools": { + "listChanged": true + }, + "prompts": { + "listChanged": true + }, + "resources": { + "listChanged": true + }, + "logging": {} + }, + "serverInfo": { + "name": "searchapi", + "title": "SearchAPI MCP Server", + "version": "1.0.0", + "websiteUrl": "" + }, + "instructions": "Use the available tools to get real-time search results. Each tool corresponds to a specific use case, which may be a full search engine or a specialized feature of an engine." + } +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search-tools-call-request.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search-tools-call-request.json new file mode 100644 index 0000000..2b7ca36 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search-tools-call-request.json @@ -0,0 +1,13 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "youtube_search", + "arguments": { + "q": "EBS 공식 유튜브 채널", + "gl": "KR" + } + } +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search-tools-call-response-visible-transcript.txt b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search-tools-call-response-visible-transcript.txt new file mode 100644 index 0000000..d4790ee --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search-tools-call-response-visible-transcript.txt @@ -0,0 +1,12 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "result": { + "content": [ + { + "type": "text", + "text": "{\n \"search_metadata\": {\n \"id\": \"search_Z18NJlvnOYI636jLXk3BOm7g\",\n \"status\": \"Success\",\n \"created_at\": \"2026-07-13T17:02:43Z\",\n \"request_time_taken\": 1.12,\n \"parsing_time_taken\": 0.04,\n \"total_time_taken\": 1.15,\n \"request_url\": \"" + } + ] + } +} diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search.md b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search.md new file mode 100644 index 0000000..bc1202a --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/04-searchapi-youtube-search.md @@ -0,0 +1,174 @@ +# 관찰 로그 04 - searchapi / `youtube_search` + +- 출처: `MCP_툴_호출_통신_로그_(JSON-RPC) (1).pdf` +- 원본 생성 시각: 2026-07-13 17:10:33 UTC +- 성격: Agent Builder 솔루션에서 수행한 관찰용 실행 로그. 본 문서는 구현 계약이나 테스트 fixture가 아니다. + +## 헤더 및 실행 메타데이터 + +| 항목 | 원본 기록 값 | +|---|---| +| transport type | `mcp-http` | +| request_id | `2ab618c9-8f2f-4163-ad11-d7118bc4d3ae` | +| tool_uid | `28553975-d471-4b67-a210-61cc636d537d` | +| Tool version | `2.0` | +| 실행 시각 | 2026-07-13 17:02:42 UTC | +| 결과 | ok · 2200ms · truncated=False | +| JSON-RPC 프레임 수 | 4 | +| lifecycle | `initialize → tools/call` | + +### HTTP 헤더 기록 범위 + +원본 PDF에는 개별 HTTP request/response header 값이 기록되어 있지 않다. 원본 표의 `request_id`, `tool_uid`, `version`은 실행 메타데이터이며 HTTP header라고 단정하지 않는다. + +원본 공통 안내에는 시크릿 및 인증 header가 로깅 전에 `[REDACTED]`로 마스킹되었다고 명시되어 있다. 따라서 Authorization, `Mcp-Session-Id` 등 실제 HTTP header 값은 이 문서에 포함하지 않는다. + +## JSON-RPC 통신 전문 + +아래는 원본 PDF의 JSON-RPC 프레임을 순서대로 옮긴 전사본이다. 긴 `result.content[].text` 문자열은 PDF의 시각적 줄바꿈을 보존했으므로, 이 블록 전체를 기계 실행용 단일 JSON payload로 사용하지 않는다. + +> 원본 PDF 자체가 `tools/call` 성공 응답의 끝부분을 `[+22537B]>`로 접어 표시한다. 따라서 이 문서는 PDF에 표시된 전문을 보존한 것이며, 접힌 22,537바이트의 원본 응답 데이터를 복원한 것은 아니다. + +```text +17:02:42 요청 → initialize +{ +"jsonrpc": "2.0", +"id": 1, +"method": "initialize", +"params": { +"protocolVersion": "2025-06-18", +"capabilities": {}, +"clientInfo": { +"name": "toolbox-executor", +"version": "0.1.0" +} +} +} +17:02:42 ← 응답 initialize +{ +"jsonrpc": "2.0", +"id": 1, +"result": { +"protocolVersion": "2025-06-18", +"capabilities": { +"tools": { +"listChanged": true +}, +"prompts": { +"listChanged": true +}, +"resources": { +"listChanged": true +}, +"logging": {} +}, +"serverInfo": { +"name": "searchapi", +"title": "SearchAPI MCP Server", +"version": "1.0.0", +"websiteUrl": "" +}, +"instructions": "Use the available tools to get real-time search results. Each tool corresponds t +o a specific use case, which may be a full search engine or a specialized feature of an engine." +} +} +17:02:42 요청 → tools/call +{ +"jsonrpc": "2.0", +"id": 3, +"method": "tools/call", +"params": { +"name": "youtube_search", +"arguments": { +"q": "EBS 공식 유튜브 채널", +"gl": "KR" +} +} +} +17:02:44 ← 응답 tools/call +{"jsonrpc": "2.0", "id": 3, "result": {"content": [{"type": "text", "text": "{\n \"search_metadata +\": {\n \"id\": \"search_Z18NJlvnOYI636jLXk3BOm7g\",\n \"status\": \"Success\",\n \"created_ +at\": \"2026-07-13T17:02:43Z\",\n \"request_time_taken\": 1.12,\n \"parsing_time_taken\": 0.0 +4,\n \"total_time_taken\": 1.15,\n \"request_url\": \"",\n \"htm +l_url\": \"",\n +\"json_url\": \""\n },\n +\"search_parameters\": {\n \"engine\": \"youtube\",\n \"q\": \"EBS 공식 유튜브 채널\",\n \"hl +\": \"en\",\n \"gl\": \"KR\"\n },\n \"search_information\": {\n \"total_results\": 6938629\n +},\n \"channels\": [\n {\n \"position\": 1,\n \"id\": \"UCFCtZJTuJhE18k8IXwmXTYQ\",\n +\"title\": \"EBS Documentary\",\n \"link\": \"",\n +\"description\": \"EBS offers a wide range of high-quality documentaries\\ndealing with subjects, suc +h as knowledge, science, culture and others.\",\n \"is_verified\": true,\n \"subscribers\": +5410000.0,\n \"thumbnail\": {\n \"static\": \"",\n \"r +ich\": \""\n }\n },\n {\n \"position\": 2,\n \"id +\": \"UC-swf20n5xdKW0waeLpXPFQ\",\n \"title\": \"EBS\",\n \"link\": \"",\n \"description\": \"EBS 공식 유튜브 채널 EBS 입니다. 언제나 여러분 곁엔 EBS가 그리 +고 언제나 EBS 곁엔 여러분이!\",\n \"subscribers\": 698000,\n \"thumbnail\": {\n \"stati +c\": \"",\n \"rich\": \""\n }\n +},\n {\n \"position\": 4,\n \"id\": \"UCNjQBiTSdoj2tCQLBGXFksw\",\n \"title\": \"EB +S 라디오 공식 채널\",\n \"link\": \"",\n \"description\": +\"책 읽어주는 라디오 + 외국어 라디오 (서울 수도권 104.5MHz) 한국교육방송 EBS 라디오 공식 운영 채널 입니다.\",\n +\"subscribers\": 208000,\n \"thumbnail\": {\n \"static\": \"",\n +\"rich\": \""\n }\n },\n {\n \"position\": 6,\n \"id\": \"U +CL44YGs2BXxtM4GZRH-wnrQ\",\n \"title\": \"EBS 지식채널e\",\n \"link\": \"",\n \"description\": \"우리 삶 속에서 잠깐, 5분 의미있는 순간으로 만드는 채널 공유하 +고 쌓여가는 지식 지식채널e 공식홈페이지 ...\",\n \"subscribers\": 147000,\n \"thumbnail\": {\n +\"static\": \"",\n \"rich\": \""\n +}\n },\n {\n \"position\": 8,\n \"id\": \"UCiFYUP4_TI70yCkkVJAlxoA\",\n \"title +\": \"EBS Collection - Nature\",\n \"link\": \"",\n +\"description\": \"Chosen among more than 310,000 digitalized sources from EBS archive, EBS Collectio +n gives you exclusive access to intriguing ...\",\n \"subscribers\": 1340000.0,\n \"thumbna +il\": {\n \"static\": \"",\n \"rich\": \""\n +}\n },\n {\n \"position\": 9,\n \"id\": \"UCl_tB4AqPkkxuYcJQHz6dMw\",\n \"title +\": \"EBSCulture (EBS 교양)\",\n \"link\": \"",\n \"d +escription\": \"Knowledge and information are becoming more important in all areas of today's societ +y. EBS provides the information to make ...\",\n \"is_verified\": true,\n \"subscribers\": +3020000.0,\n \"thumbnail\": {\n \"static\": \"",\n \"rich\": +\""\n }\n },\n {\n \"position\": 10,\n \"id\": \"UCbeZPOz8u +aHstEIbkqBOnGg\",\n \"title\": \"EBS 세계테마기행\",\n \"link\": \"",\n \"description\": \"EBS 세계테마기행 공식 유튜브 채널 : (구독하기) ⛵세계를 여행하며 만나는 다양한 문화와 풍경!\",\n \"subscribers\": 162000,\n \"thumb +nail\": {\n \"static\": \"",\n \"rich\": \""\n }\n },\n {\n \"position\": 11,\n \"id\": \"UCuuA38hvvuipqXFIP3BfL +EA\",\n \"title\": \"EBS 지식\",\n \"link\": \"",\n +\"description\": \"일상 속 지식 한 스푼! 각 분야의 전문가로 구성된 연사들의 강연까지! EBS의 고품격 지식·강연 프로 +그램 속 다양한 지식들을 큐레이팅 ...\",\n \"subscribers\": 298000,\n \"thumbnail\": {\n +\"static\": \"",\n \"rich\": \""\n +}\n },\n {\n \"position\": 13,\n \"id\": \"UC2dDb6up1sIc-5geTvNtgHA\",\n \"title +\": \"EBS 최고의 요리비결\",\n \"link\": \"",\n \"description\": \"이 채널은 \\\"EBS 최고의 요리비결\\\" 공식 유튜브 채널입니다. EBS 최고의 요리비 +결은 지난 20년 동안 요리의 대가들이 출연하여 누구나 ...\",\n \"subscribers\": 104000,\n \"thumbnai +l\": {\n \"static\": \"",\n \"rich\": \""\n +}\n },\n {\n \"position\": 14,\n \"id\": \"UC2DBKKki_gtyrrgT7HYU1CA\",\n \"title +\": \"EBS 국제다큐영화제 공식 채널\",\n \"link\": \"",\n +\"description\": \"EBS국제다큐영화제 EIDF 공식 Youtube 채널입니다. This is the official YouTube EIDF Chan +nel.\",\n \"subscribers\": 10100.0,\n \"thumbnail\": {\n \"static\": \"",\n \"rich\": \""\n }\n },\n {\n \"position\": 1 +5,\n \"id\": \"UCN3RfsR18gsH8PLI6R6PYSQ\",\n \"title\": \"EBS뉴스\",\n \"link\": \"",\n \"description\": \"한국교육방송공사 EBS 뉴스 채널입니다. EBS 뉴 +스의 TV 방송시간은 월~금 낮 12시, 저녁 6시 10분입니다. Republic of Korea's ...\",\n \"subscribers\": 5 +9900.0,\n \"thumbnail\": {\n \"static\": \"",\n \"rich +\": \" +``` diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-initialize-request.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-initialize-request.json new file mode 100644 index 0000000..15a192b --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-initialize-request.json @@ -0,0 +1,14 @@ +{ + "jsonrpc": "2.0", + "id": 1, + "method": "initialize", + "params": { + "protocolVersion": "2025-06-18", + "capabilities": {}, + "clientInfo": { + "name": "toolbox-executor", + "version": "0.1.0" + } + } +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-initialize-response.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-initialize-response.json new file mode 100644 index 0000000..2dbaa1e --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-initialize-response.json @@ -0,0 +1,30 @@ +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "protocolVersion": "2025-06-18", + "capabilities": { + "experimental": {}, + "logging": {}, + "prompts": { + "listChanged": true + }, + "resources": { + "subscribe": false, + "listChanged": true + }, + "tools": { + "listChanged": true + }, + "extensions": { + "io.modelcontextprotocol/ui": {} + } + }, + "serverInfo": { + "name": "langconnect-rag-mcp", + "version": "3.3.1" + }, + "instructions": "This server provides RAG tools over document collections. Call list_collections() first: it returns collections you can access plus per-collection role and allowed_tools (derived from RBAC scopes). Use search_documents/search_documents_batch/search_documents_with_context for retrieval. Use list_documents to inspect documents. Use add_document_text to add text. Use delete_document/delete_collection only when allowed_tools includes them. Call get_user_info() to get the current user's email and display name." + } +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-initialized-notification.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-initialized-notification.json new file mode 100644 index 0000000..9ed0b56 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-initialized-notification.json @@ -0,0 +1,5 @@ +{ + "jsonrpc": "2.0", + "method": "notifications/initialized" +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-tools-call-request.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-tools-call-request.json new file mode 100644 index 0000000..58ad28f --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-tools-call-request.json @@ -0,0 +1,10 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "list_collections", + "arguments": {} + } +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-tools-call-response.json b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-tools-call-response.json new file mode 100644 index 0000000..f6ed813 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections-tools-call-response.json @@ -0,0 +1,40 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "result": { + "content": [ + { + "type": "text", + "text": "{\"data\":[{\"name\":\"test\",\"id\":\"1caf198a-444b-4a89-a235-23e82bc3d68a\",\"metadata\":{\"description\":\"col\"},\"role\":0,\"allowed_tools\":[\"add_document_text\",\"delete_collection\",\"delete_document\",\"list_documents\",\"search_documents\",\"search_documents_batch\",\"search_documents_with_context\"],\"document_count\":2,\"chunk_count\":119}],\"success\":true,\"error\":null,\"request_id\":\"b3fa0787-dce3-449b-aff0-51a8d882e81d\"}" + } + ], + "structuredContent": { + "data": [ + { + "name": "test", + "id": "1caf198a-444b-4a89-a235-23e82bc3d68a", + "metadata": { + "description": "col" + }, + "role": 0, + "allowed_tools": [ + "add_document_text", + "delete_collection", + "delete_document", + "list_documents", + "search_documents", + "search_documents_batch", + "search_documents_with_context" + ], + "document_count": 2, + "chunk_count": 119 + } + ], + "success": true, + "error": null, + "request_id": "b3fa0787-dce3-449b-aff0-51a8d882e81d" + }, + "isError": false + } +} + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections.md b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections.md new file mode 100644 index 0000000..44ce6ec --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/05-langconnect-list-collections.md @@ -0,0 +1,140 @@ +# 관찰 로그 05 - langconnect / `list_collections` + +- 출처: `MCP_툴_호출_통신_로그_(JSON-RPC) (1).pdf` +- 원본 생성 시각: 2026-07-13 17:10:33 UTC +- 성격: Agent Builder 솔루션에서 수행한 관찰용 실행 로그. 본 문서는 구현 계약이나 테스트 fixture가 아니다. + +## 헤더 및 실행 메타데이터 + +| 항목 | 원본 기록 값 | +|---|---| +| transport type | `mcp-http` | +| request_id | `ac3d3c06-882e-4416-be34-a20c5f91662f` | +| tool_uid | `636e8cd0-3114-467f-b305-14e2c9cda744` | +| Tool version | `1.0` | +| 실행 시각 | 2026-07-13 17:08:46 UTC | +| 결과 | ok · 346ms · truncated=False | +| JSON-RPC 프레임 수 | 5 | +| lifecycle | `initialize → notifications/initialized → tools/call` | + +### HTTP 헤더 기록 범위 + +원본 PDF에는 개별 HTTP request/response header 값이 기록되어 있지 않다. 원본 표의 `request_id`, `tool_uid`, `version`은 실행 메타데이터이며 HTTP header라고 단정하지 않는다. + +원본 공통 안내에는 시크릿 및 인증 header가 로깅 전에 `[REDACTED]`로 마스킹되었다고 명시되어 있다. 따라서 Authorization, `Mcp-Session-Id` 등 실제 HTTP header 값은 이 문서에 포함하지 않는다. + +## JSON-RPC 통신 전문 + +아래는 원본 PDF의 JSON-RPC 프레임을 순서대로 옮긴 전사본이다. 긴 `result.content[].text` 문자열은 PDF의 시각적 줄바꿈을 보존했으므로, 이 블록 전체를 기계 실행용 단일 JSON payload로 사용하지 않는다. + +```text +17:08:46 요청 → initialize +{ +"jsonrpc": "2.0", +"id": 1, +"method": "initialize", +"params": { +"protocolVersion": "2025-06-18", +"capabilities": {}, +"clientInfo": { +"name": "toolbox-executor", +"version": "0.1.0" +} +} +} +17:08:46 ← 응답 initialize +{ +"jsonrpc": "2.0", +"id": 1, +"result": { +"protocolVersion": "2025-06-18", +"capabilities": { +"experimental": {}, +"logging": {}, +"prompts": { +"listChanged": true +}, +"resources": { +"subscribe": false, +"listChanged": true +}, +"tools": { +"listChanged": true +}, +"extensions": { +"io.modelcontextprotocol/ui": {} +} +}, +"serverInfo": { +"name": "langconnect-rag-mcp", +"version": "3.3.1" +}, +"instructions": "This server provides RAG tools over document collections. Call list_collections +() first: it returns collections you can access plus per-collection role and allowed_tools (derived f +rom RBAC scopes). Use search_documents/search_documents_batch/search_documents_with_context for retri +eval. Use list_documents to inspect documents. Use add_document_text to add text. Use delete_documen +t/delete_collection only when allowed_tools includes them. Call get_user_info() to get the current us +er's email and display name." +} +} +17:08:46 요청 → notifications/initialized +{ +"jsonrpc": "2.0", +"method": "notifications/initialized" +} +17:08:46 요청 → tools/call +{ +"jsonrpc": "2.0", +"id": 3, +"method": "tools/call", +"params": { +"name": "list_collections", +"arguments": {} +} +} +17:08:47 ← 응답 tools/call +{ +"jsonrpc": "2.0", +"id": 3, +"result": { +"content": [ +{ +"type": "text", +"text": "{\"data\":[{\"name\":\"test\",\"id\":\"1caf198a-444b-4a89-a235-23e82bc3d68a\",\"meta +data\":{\"description\":\"col\"},\"role\":0,\"allowed_tools\":[\"add_document_text\",\"delete_collect +ion\",\"delete_document\",\"list_documents\",\"search_documents\",\"search_documents_batch\",\"search +_documents_with_context\"],\"document_count\":2,\"chunk_count\":119}],\"success\":true,\"error\":nul +l,\"request_id\":\"b3fa0787-dce3-449b-aff0-51a8d882e81d\"}" +} +], +"structuredContent": { +"data": [ +{ +"name": "test", +"id": "1caf198a-444b-4a89-a235-23e82bc3d68a", +"metadata": { +"description": "col" +}, +"role": 0, +"allowed_tools": [ +"add_document_text", +"delete_collection", +"delete_document", +"list_documents", +"search_documents", +"search_documents_batch", +"search_documents_with_context" +], +"document_count": 2, +"chunk_count": 119 +} +], +"success": true, +"error": null, +"request_id": "b3fa0787-dce3-449b-aff0-51a8d882e81d" +}, +"isError": false +} +} +``` + diff --git a/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/README.md b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/README.md new file mode 100644 index 0000000..562b7bf --- /dev/null +++ b/docs/contracts/agent-builder-mcp/observed-samples/2026-07-13/README.md @@ -0,0 +1,30 @@ +# Agent Builder Tool 호출 관찰 로그 + +- 출처: `MCP_툴_호출_통신_로그_(JSON-RPC) (1).pdf` +- 원본 생성 시각: 2026-07-13 17:10:33 UTC +- 목적: Agent Builder 솔루션이 실제 Tool을 호출하며 남긴 JSON-RPC 흐름을 샘플별로 보존 +- 성격: 관찰 기록. 현재 구현 계약, 목표 계약 또는 자동화 테스트 fixture로 사용하지 않는다. + +원본 PDF는 시크릿 및 인증 header를 `[REDACTED]` 처리했다고 명시한다. 개별 HTTP request/response header 자체는 제공하지 않으므로, 각 문서에는 원본에 기록된 실행 메타데이터와 header 기록 범위를 분리해 표시한다. + +| # | 서버 | Tool | 시각(UTC) | 프레임 | 결과 | 파일 | +|---:|---|---|---|---:|---|---| +| 1 | exa | `web_search_exa` | 16:53:16 | 5 | ok · 1896ms | [01](01-exa-web-search-exa-165316.md) | +| 2 | exa | `web_search_exa` | 16:53:24 | 5 | ok · 1768ms | [02](02-exa-web-search-exa-165324.md) | +| 3 | exa | `web_search_exa` | 16:53:31 | 5 | ok · 2070ms | [03](03-exa-web-search-exa-165331.md) | +| 4 | searchapi | `youtube_search` | 17:02:42 | 4 | ok · 2200ms | [04](04-searchapi-youtube-search.md) | +| 5 | langconnect | `list_collections` | 17:08:46 | 5 | ok · 346ms | [05](05-langconnect-list-collections.md) | + +## JSON 프레임 파일 + +각 요청과 응답은 아래의 독립 JSON 파일로 분리했다. PDF의 시각적 줄바꿈을 제거한 뒤 JSON 문법 검증을 통과한 프레임만 원래 JSON-RPC 구조로 저장했다. + +- [01 Exa](01-exa-web-search-exa-165316-initialize-request.json): `initialize` 요청·응답, `notifications/initialized`, `tools/call` 요청·응답 +- [02 Exa](02-exa-web-search-exa-165324-initialize-request.json): `initialize` 요청·응답, `notifications/initialized`, `tools/call` 요청·응답 +- [03 Exa](03-exa-web-search-exa-165331-initialize-request.json): `initialize` 요청·응답, `notifications/initialized`, `tools/call` 요청·응답 +- [04 SearchAPI](04-searchapi-youtube-search-initialize-request.json): `initialize` 요청·응답, `tools/call` 요청, `tools/call` 응답의 PDF 표시 전사본 +- [05 LangConnect](05-langconnect-list-collections-initialize-request.json): `initialize` 요청·응답, `notifications/initialized`, `tools/call` 요청·응답 + +SearchAPI의 `tools/call` 응답은 원본 PDF가 마지막 22,537바이트를 접어 표시하므로, +[visible transcript](04-searchapi-youtube-search-tools-call-response-visible-transcript.txt)로 저장했다. +끝부분이 없는 전사본이므로 실행 가능한 JSON-RPC 응답이나 `.json` fixture로 취급하지 않는다. diff --git a/docs/contracts/agent-builder-mcp/protocol-v0.2-agentbuilder.md b/docs/contracts/agent-builder-mcp/protocol-v0.2-agentbuilder.md new file mode 100644 index 0000000..72a9ec6 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/protocol-v0.2-agentbuilder.md @@ -0,0 +1,44 @@ +# Agent Builder-MCP 이전 non-streaming 계약 v0.2 + +> 상태: v0.3으로 대체됨. 이 문서는 streaming 정책 도입 전 계약 기록이며, 신규 연동에는 사용하지 않는다. + +- 상태: Superseded +- 기준일: 2026-07-16 +- 구현 endpoint: `POST /mcp` +- JSON-RPC: `2.0` +- protocolVersion: `2025-11-25` + +> 이 문서는 교체된 고정 endpoint 시점의 이력이다. 현재 공개 URL과 path 처리는 [v0.3](protocol-v0.3-streaming-policy.md)과 [ADR-0009](../../decisions/ADR-0009-container-handles-public-mcp-path.md)을 따른다. + +이 계약은 Agent Builder에서 받은 JSON-RPC/MCP 호출·응답 예시를 현재 stateless MCP 실행 계층에 반영한 범위다. 서버는 `mcp-session-id`를 요청 correlation에만 사용하며 `Mcp-Session-Id`를 발급하거나 세션 상태를 저장하지 않는다. + +## 범위와 HTTP 정책 + +- 이 버전은 non-streaming 요청에 한정한다. 호출 클라이언트는 `Accept: application/json`을 사용한다. +- 기존 NDJSON streaming 구현과 progress frame은 변경하지 않았다. streaming의 SSE/재개/cancel 계약은 별도 승인 후 반영한다. +- `Content-Type: application/json` 또는 `application/json-rpc`을 사용한다. +- `notifications/initialized`는 Agent Builder가 stateless 서버에 대해 생략할 수 있다. 전송될 경우 표준 lifecycle을 수용하고 HTTP `202 Accepted`와 빈 body를 반환한다. + +## initialize + +Agent Builder는 연결 초기화 시 [요청 예시](examples/agentbuilder-v0.2/initialize-request.json)를 전송한다. 응답은 [응답 예시](examples/agentbuilder-v0.2/initialize-response.json)처럼 `jsonrpc`, `id`, `result.protocolVersion`만 의미 있는 값을 가진다. `serverInfo`와 `capabilities`는 빈 객체다. + +서버는 protocol version으로 `2025-11-25`을 반환한다. 현재 `MCP-Protocol-Version` HTTP 헤더의 수신·검증은 범위 밖이다. + +## notifications/initialized + +초기화 완료 notification의 body는 [예시](examples/agentbuilder-v0.2/initialized-notification.json)와 같다. JSON-RPC notification에는 `id`가 없으며, 서버는 실행 결과 JSON-RPC body를 만들지 않는다. Agent Builder가 stateless 정책으로 notification을 보내지 않아도 Tool 호출은 가능하다. + +## tools/list + +`tools/list` handler는 계속 제공한다. Agent Builder가 사전 등록한 Tool만 사용할 때는 이 호출을 생략할 수 있다. 현재 pagination과 `listChanged` notification은 제공하지 않는다. + +## tools/call + +호출 request는 [예시](examples/agentbuilder-v0.2/tools-call-request.json)처럼 `params.name`과 object 형식의 `params.arguments`를 사용한다. version은 Agent Builder가 보내지 않는다. 서버는 Registry에서 같은 name의 활성 version이 정확히 하나일 때만 이를 해소해 실행한다. 두 개 이상이면 임의 version을 선택하지 않고 오류로 처리한다. + +성공 응답은 [예시](examples/agentbuilder-v0.2/tools-call-success-response.json)처럼 `content`, 선택적 `structuredContent`, `isError: false`를 반환한다. Tool endpoint 실행·timeout·권한 오류는 [예시](examples/agentbuilder-v0.2/tools-call-execution-error-response.json)처럼 HTTP/JSON-RPC transport error 대신 `result.isError: true`로 반환한다. 잘못된 JSON-RPC envelope, 알 수 없는 method, 잘못된 name/arguments는 기존 JSON-RPC `error`를 사용한다. + +## 호환성 메모 + +- UID execution key 검토안은 [ADR-0005](../../decisions/ADR-0005-standard-tool-name.md)에서 폐기되었다. 신규 계약은 표준 MCP `name`을 실행 식별자로 사용한다. diff --git a/docs/contracts/agent-builder-mcp/protocol-v0.3-streaming-policy.md b/docs/contracts/agent-builder-mcp/protocol-v0.3-streaming-policy.md new file mode 100644 index 0000000..2011810 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/protocol-v0.3-streaming-policy.md @@ -0,0 +1,82 @@ +# Agent Builder-MCP 동기 JSON 계약 v0.3 + +- 상태: Implemented +- 기준일: 2026-07-16 +- 공개 endpoint: `POST https://{mcpHost}{publicPath}` +- 컨테이너 endpoint: 공개 URL과 동일한 `POST {publicPath}` +- JSON-RPC: `2.0` +- protocolVersion: `2025-11-25` + +이 계약의 현재 구현은 stateless MCP 실행 계층의 transport를 동기 JSON으로 고정한다. 현재 in-memory snapshot의 표준 Tool name metadata를 조회해 확정된 endpoint로 POST하며, `Mcp-Session-Id`는 lifecycle correlation 값일 뿐 서버는 initialize 성공 시 이를 발급하지만 대화·readiness 상태를 저장하지 않는다. + +한 환경은 공개 host를 공유하지만 path마다 독립된 MCP Deployment와 Tool Service에 연결된다. Agent Builder는 각 공개 URL을 별도 MCP로 등록하고 initialize한다. URL 사이에는 session ID, Tool 목록, lifecycle 상태를 공유하지 않는다. Route는 path를 바꾸지 않으며 컨테이너가 같은 path를 처리한다. 이 매핑은 [ADR-0009](../../decisions/ADR-0009-container-handles-public-mcp-path.md)이 정본이며 JSON-RPC payload에는 영향을 주지 않는다. + +## HTTP 선택 정책 + +- Agent Builder는 `Accept: application/json, text/event-stream`을 보낸다. +- 서버는 항상 `Content-Type: application/json`과 단일 JSON-RPC response를 반환한다. +- `Accept`는 수용 가능 형식의 선언이며, `text/event-stream`이 포함되어도 응답 transport를 바꾸지 않는다. +- 독립적인 server-push SSE channel은 제공하지 않으므로 공개 endpoint의 `GET`은 `405 Method Not Allowed`다. +- `initialize` 요청에는 `MCP-Protocol-Version` header를 요구하지 않는다. +- `initialize` 이후 `notifications/initialized`, `tools/list`, `tools/call` 요청에는 정확히 `MCP-Protocol-Version: 2025-11-25`이 필수다. `version` 등 임의 header는 대체하지 않는다. header가 없거나 지원하지 않는 값이면 server는 JSON-RPC body 대신 HTTP `400 Bad Request`와 `error`, `message`, `supportedVersions`, `guid`를 가진 JSON 오류 body를 반환한다. + +## 호출자 식별 header + +`MCP-Protocol-Version` 외에 Agent Builder가 보내는 header는 다섯 개이며 **모두 선택값**이다. + +| header | 형식 | 서버 동작 | +|---|---|---| +| `guid` | UUID | 없으면 서버가 생성한다. 응답 header와 오류 body에 되돌려준다 | +| `x-request-id` | 안전 문자 1~128자 | 없으면 서버가 생성한다. 응답 header에 되돌려준다 | +| `mcp-session-id` | 안전 문자 1~128자 | initialize lifecycle 상관 값. 서버는 저장하지 않는다 | +| `employee-no` | 암호화된 사원번호 | 해석하지 않는다 | +| `virtual-employee-no` | 암호화된 가상사원번호 | 해석하지 않는다 | + +사원 식별자 둘은 **불투명 값**이다. MCP는 복호화·검증·저장하지 않고 Tool Service로 그대로 전달한다. +값의 의미는 보지 않되, 개행이나 공백이 섞여 downstream 요청 header를 조작하는 것은 거부한다 +(출력 가능 문자 1~2048자가 아니면 `-32600`). + +암호화된 값이라도 **로그에 남기지 않는다.** 로그에 나가는 상관 값은 `guid`와 `x-request-id`뿐이다. + +## initialize와 notification + +`initialize`는 [v0.2 요청 예시](examples/agentbuilder-v0.2/initialize-request.json)를 그대로 사용하며, 응답은 [v0.3 응답 예시](examples/agentbuilder-v0.3/initialize-response.json)처럼 원 요청 `id`, `protocolVersion: 2025-11-25`, `serverInfo(name/title/version)`, `capabilities.tools.listChanged: false`를 반환한다. HTTP response header에는 새 UUID `Mcp-Session-Id`가 포함된다. Agent Builder는 응답 version을 이후 모든 HTTP 요청의 `MCP-Protocol-Version` header에 사용하고, session ID를 `notifications/initialized` 및 이후 Tool 요청의 correlation header로 보낸다. MCP 2025-11-25 lifecycle에 따라 Agent Builder는 `notifications/initialized`를 반드시 보내고 두 header를 포함한다. 서버는 notification을 HTTP `202 Accepted`와 빈 body로 수용하되 stateless 원칙상 수신 여부를 저장하거나 이후 요청을 차단하는 readiness gate로 사용하지 않는다. + +## tools/list + +`tools/list`는 `result.tools`에 현재 snapshot의 공개 Tool 필드(`name`, `title`, `description`, `inputSchema`, `outputSchema`, `annotations`)를 반환한다. `_meta`의 version, endpoint, HTTP method, timeout, cache 설정은 실행·운영 metadata이므로 MCP 공개 응답에 포함하지 않는다. + +현재 `tools/call`은 `structuredContent`를 반환하거나 Tool 응답을 `outputSchema`로 검증하지 않는다. 따라서 `outputSchema`를 가진 Tool 정의를 그대로 노출하는 동작은 현재 코드의 사실이지만 MCP 2025-11-25의 구조화 출력 계약을 완전히 충족하지 않는다. 운영 Tool은 구조화 출력 지원이 도입되기 전까지 `outputSchema`를 생략해야 한다. + +원천은 profile이 정한다. local은 Tool Service 매니페스트를 먼저 조회하고 최초 실패 시 `config/local-core-tools-manifest-sample-v1.json` fallback을 사용한다(파일이 곧 목록이므로 여기에 Tool 이름을 옮겨 적지 않는다). 운영은 설정된 Tool Service 매니페스트뿐이다. + +## 동기 Tool 호출 + +기본 Tool 호출은 [요청 예시](examples/agentbuilder-v0.3/tools-call-request.json)처럼 `params.name`과 object `params.arguments`를 사용한다. name은 `tools/list`와 실행 사이의 유일한 식별자다. MCP는 snapshot metadata에서 endpoint를 확정하고 arguments 전체를 JSON body로 전달한다. 성공 및 Tool 실행 실패는 각각 [성공 응답](examples/agentbuilder-v0.3/tools-call-success-response.json), [실행 실패 응답](examples/agentbuilder-v0.3/tools-call-execution-error-response.json)처럼 `application/json` JSON-RPC response로 반환한다. + +성공 응답은 Tool의 plain text를 `result.content[0].text`, 소요 시간(ms)을 `result.content[0]._meta.searchTime`, 성공 여부를 `result.isError: false`에 넣는다. JSON object/array 응답은 compact JSON 문자열로 `text`에 보존하며, outer JSON serializer가 올바른 quote escaping을 수행한다. 실행·timeout·권한 실패는 `result.isError: true`이며, JSON-RPC envelope/params/method 오류는 기존 JSON-RPC `error`다. Registry의 `inputSchema`는 모든 `tools/call`에서 Tool 호출 전에 검증한다. + +## tools/call 성공·오류 응답 기준 + +Agent Builder는 HTTP 상태만으로 성공 여부를 판단하지 않고 JSON-RPC body의 최상위 `result` 또는 `error`를 확인해야 한다. 일반적인 JSON-RPC 요청 오류는 HTTP `200 OK`와 함께 최상위 `error`로 반환될 수 있다. `-32602`의 `error.message`는 `Invalid params: <상세 원인>` 형식이며, 예를 들어 필수 `query`가 없으면 `Invalid params: 'query' is required`를 반환한다. 선택적인 `error.data`에는 `guid`와 상세 원인을 추가로 담을 수 있다. 단, `MCP-Protocol-Version` 누락·미지원처럼 HTTP transport 단계에서 거부된 요청은 HTTP `400 Bad Request`다. + +| 상황 | HTTP 상태 | JSON-RPC body | `isError` | 현재 구현의 처리 주체 | +|---|---:|---|---|---| +| Tool 정상 완료 | 200 | `result.content` | 반드시 `false` | `ToolsCallHandler` | +| Tool Service timeout, upstream 4xx/5xx, downstream 권한 거부 | 200 | `result.content` | 반드시 `true` | `ToolsCallHandler` | +| Tool이 실행된 뒤 업무 검증·업무 규칙으로 실패 | 200 | `result.content` | 반드시 `true` | Tool Service 또는 실행 계층 | +| JSON 문법 오류 | 200 | 최상위 `error` (`-32700`) | 없음 | `McpExceptionHandler` | +| JSON-RPC envelope 오류 | 200 | 최상위 `error` (`-32600`) | 없음 | `JsonRpcRequestParser` | +| 알 수 없는 MCP method 또는 Tool | 200 | 최상위 `error` (`-32601` 또는 Tool 조회 오류) | 없음 | method/registry 계층 | +| `params.name` 누락, `params.arguments` 형식 오류, 공개된 inputSchema의 필수 값 누락 | 200 | 최상위 `error` (`-32602`) | 없음 | Adapter/parameter/schema validator | +| 서버 설정·Registry 장애 등 서버가 Tool 호출을 시작할 수 없는 경우 | 200 | 최상위 `error` (`-32603` 또는 서버 정의 오류) | 없음 | transport/execute 계층 | +| `MCP-Protocol-Version` 누락 또는 미지원 | 400 | transport 오류 body | 없음 | `McpProtocolVersionValidator` | + +모든 routing은 공통 `name`/`arguments` 형식과 선택된 Tool의 `inputSchema`를 실행 전에 검증한다. Tool Service가 반환한 HTTP 400은 검증을 통과해 Tool 실행을 시작한 뒤의 실패이므로 `result.isError: true`로 반환한다. + +실행 가능한 응답 형태는 [성공 예시](examples/agentbuilder-v0.3/tools-call-success-response.json), [Tool 실행 실패 예시](examples/agentbuilder-v0.3/tools-call-execution-error-response.json), [잘못된 인자 예시](examples/agentbuilder-v0.3/tools-call-invalid-params-response.json)를 따른다. + +## 호환성 메모 + +- v0.2의 일반 JSON 요청·응답 형식은 그대로 호환된다. +- Agent Builder의 기존 `Accept: application/json, text/event-stream` header는 계속 수용한다. diff --git a/docs/contracts/agent-builder-mcp/protocol-v1-agreement-baseline.md b/docs/contracts/agent-builder-mcp/protocol-v1-agreement-baseline.md new file mode 100644 index 0000000..c0c74f8 --- /dev/null +++ b/docs/contracts/agent-builder-mcp/protocol-v1-agreement-baseline.md @@ -0,0 +1,56 @@ +# Agent Builder-MCP 목표 계약 v1 합의 기준선 + +- 상태: Partial Agreement +- 합의 기준일: 2026-07-10 +- 목적: 확정된 목표 제약만 기록하고 미확정 payload의 추측 구현을 방지 + +## Normative 합의 사항 + +### 책임 경계 + +- Agent Builder가 Tool을 선택한다. +- MCP Server는 요청에 명시된 Tool만 검증·실행한다. +- MCP Server는 stateless하며 `mcp-session-id`를 대화 상태로 사용하지 않는다. + +### Tool 노출과 호출 단위 + +- Agent Builder가 LLM에 노출하는 Tool은 최대 50개다. +- Agent Builder-MCP 목표 호출은 요청 하나당 Tool 하나다. + +### Tool 식별 + +- 표준 MCP Tool `name`을 `tools/list`와 `tools/call` 사이의 시스템 간 실행 key로 사용한다. +- Tool Service가 전체 MCP 범위에서 고유한 namespaced name을 선언하고 MCP Server는 이를 재작성하지 않는다. +- Agent Builder UID는 Agent Builder 내부 관리에만 사용하고 MCP wire contract에 포함하지 않는다. + +### 실행 가드레일 + +- 전체 상호작용 상한은 300초다. +- MCP Server는 3만 자 기준으로 원문 응답을 임의 절단하지 않는다. +- idempotency가 확인되지 않은 write/update Tool은 자동 retry하지 않는다. + +## 아직 Normative가 아닌 항목 + +다음 항목은 목표 v1의 일부로 구현하면 안 된다. + +- 최종 method 이름 (`tool/call`, `tools/call` 또는 별도 vendor method) +- 최종 Tool Call parameter와 result field 이름 +- `initialize` 전체 request/response +- Tool name 변경·폐기 시 rolling 호환 기간과 Agent Builder 내부 mapping lifecycle +- 사원 식별자 header를 언젠가 필수로 승격할지 여부 (현재 계약에서는 선택값이며 MCP는 검증하지 않는다) +- HTTP status와 JSON-RPC/업무 error code 매핑 +- read retry 조건과 idempotency key +- 300초 timeout budget과 cancellation protocol +- 대용량 response의 최대 크기와 continuation 방식 +- streaming media type과 framing + +## 요청·응답 규격 처리 원칙 + +목표 v1의 확정 JSON 예시는 아직 제공하지 않는다. 미확정 field를 임의로 채운 JSON은 사실상 새로운 계약 결정이 되기 때문이다. + +Agent Builder의 전체 payload와 위 미확정 항목이 승인되면 다음 순서로 갱신한다. + +1. 이 문서 상태를 `Approved`로 변경한다. +2. 목표 v1 JSON example과 schema를 추가한다. +3. 관련 ADR을 추가하거나 기존 ADR의 구현 보류 조건을 해제한다. +4. 코드와 테스트 변경을 별도 작업으로 수행한다. diff --git a/docs/contracts/tool-service-mcp/README.md b/docs/contracts/tool-service-mcp/README.md new file mode 100644 index 0000000..fcfdadd --- /dev/null +++ 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)을 따른다. diff --git a/docs/contracts/tool-service-mcp/TEMP-tool-list-loading-guide.md b/docs/contracts/tool-service-mcp/TEMP-tool-list-loading-guide.md new file mode 100644 index 0000000..a88a376 --- /dev/null +++ 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를 AtomicReference snapshot에 저장 +``` + +실제 memory 저장소는 `ToolRegistryService`의 `AtomicReference>`다. + +- 매니페스트 조회·검증에 **성공했을 때만** 새 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)을 참고한다. diff --git 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 new file mode 100644 index 0000000..2e91897 --- /dev/null +++ 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 + } + ] +} diff --git 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 new file mode 100644 index 0000000..0698c85 --- /dev/null +++ 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 + } + } + ] +} diff --git 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 new file mode 100644 index 0000000..2b58699 --- /dev/null +++ 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 diff --git a/docs/contracts/tool-service-mcp/protocol-v0.2-bundle-discovery.md b/docs/contracts/tool-service-mcp/protocol-v0.2-bundle-discovery.md new file mode 100644 index 0000000..27728fe --- /dev/null +++ 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: <설정에 따라 전달> + + +``` + +- 호출자 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`: 불필요한 내부 주소 노출 방지 diff --git a/docs/decisions/ADR-0001-stateless-execution-boundary.md b/docs/decisions/ADR-0001-stateless-execution-boundary.md new file mode 100644 index 0000000..7fea2c3 --- /dev/null +++ b/docs/decisions/ADR-0001-stateless-execution-boundary.md @@ -0,0 +1,23 @@ +# ADR-0001 Stateless 실행 책임 경계 + +- 상태: Accepted +- 결정일: 2026-07-10 +- 관련 논의: [DISC-20260710-001](../discussions/DISC-20260710-001-agentbuilder-mcp-interface.md) + +## 배경 + +Agent Builder는 사용자 의도와 업무 맥락을 바탕으로 실행할 Tool을 결정하고, MCP Server는 요청된 Tool을 안전하게 검증·실행하는 계층이다. + +## 결정 + +- MCP Server는 서버 측 대화 세션을 보관하지 않는 stateless 실행 계층으로 유지한다. +- Tool 선택, 의도 분류, 대체 Tool 탐색은 Agent Builder 책임이다. +- MCP Server는 요청에 명시된 Tool만 Registry metadata에 따라 검증하고 실행한다. +- `mcp-session-id`가 사용되더라도 대화 상태가 아닌 correlation 값으로 취급한다. +- Business Rule은 Tool Service 책임으로 유지한다. + +## 영향 + +- MCP Server에 LLM inference, intent classification 또는 autonomous tool selection을 추가하지 않는다. +- 인증·권한 책임은 이 결정 이후 [ADR-0006](ADR-0006-no-authentication-in-mcp.md)에서 확정했다. MCP는 인증·인가하지 않는다. +- 현재 구현은 이 결정과 대체로 일치하므로 즉시 코드 변경하지 않는다. diff --git a/docs/decisions/ADR-0002-tool-exposure-and-single-call.md b/docs/decisions/ADR-0002-tool-exposure-and-single-call.md new file mode 100644 index 0000000..ff170d7 --- /dev/null +++ b/docs/decisions/ADR-0002-tool-exposure-and-single-call.md @@ -0,0 +1,32 @@ +# ADR-0002 Agent Builder Tool 노출 제한과 단일 Tool 호출 + +- 상태: Accepted +- 결정일: 2026-07-10 +- 관련 논의: [DISC-20260710-001](../discussions/DISC-20260710-001-agentbuilder-mcp-interface.md) + +## 배경 + +많은 Tool을 한 번에 LLM context에 노출하면 Tool 식별과 선택 정확도가 저하될 수 있다. 또한 한 요청에서 여러 Tool을 실행하면 timeout, 부분 성공, 순서 의존성과 오류 계약이 복잡해진다. + +## 결정 + +- Agent Builder가 사용자·Agent·업무 맥락에 맞는 Tool을 선택한다. +- Agent Builder가 한 시점에 LLM에 노출하는 활성 Tool은 최대 50개다. +- 목표 Agent Builder-MCP 호출 모델은 요청 하나당 Tool 하나다. +- MCP Server는 50개 선별 로직이나 LLM 기반 우선순위 판단을 구현하지 않는다. + +## 영향 + +- 50개 선별은 Agent Builder 변경 사항이며 MCP 코드 변경 대상이 아니다. +- 요청 하나당 Tool 하나라는 결정은 그대로 유효하다. + +### 결정 당시의 envelope 기록 (현재 구현 아님) + +결정 시점에는 최종 field 이름이 미확정이어서 `params.toolCalls[]` 배열 envelope를 유지하고, +원소를 정확히 한 개만 허용해 단일 호출을 강제했다. 빈 배열과 2개 이상은 `-32602`로 거절했다. + +이 envelope는 [ADR-0005](ADR-0005-standard-tool-name.md)와 +[계약 v0.3](../contracts/agent-builder-mcp/protocol-v0.3-streaming-policy.md)에서 +표준 MCP `params.name` + `params.arguments`로 대체되었다. +**현재 코드에 `toolCalls`는 존재하지 않는다.** 배열이 사라졌으므로 "정확히 한 개" 검증도 +필요 없어졌고, 단일 호출 결정은 envelope 구조 자체로 만족된다. diff --git a/docs/decisions/ADR-0003-builder-tool-uid.md b/docs/decisions/ADR-0003-builder-tool-uid.md new file mode 100644 index 0000000..f58da92 --- /dev/null +++ b/docs/decisions/ADR-0003-builder-tool-uid.md @@ -0,0 +1,29 @@ +# ADR-0003 Builder Tool UID를 시스템 간 식별 키로 사용 + +- 상태: Superseded +- 결정일: 2026-07-10 +- 관련 논의: [DISC-20260710-001](../discussions/DISC-20260710-001-agentbuilder-mcp-interface.md) +- 대체 결정: [ADR-0005](ADR-0005-standard-tool-name.md) + +> 이 문서는 당시 검토 이력을 보존한다. 현재 구현과 신규 연동에는 ADR-0005를 적용한다. + +## 배경 + +Tool name은 중복 또는 변경 가능성이 있으므로 Agent Builder Tool Registry가 부여한 고유 식별자를 시스템 간 mapping key로 사용할 필요가 있다. + +## 결정 + +- Agent Builder Tool Registry가 Custom Tool에 부여한 UID를 Agent Builder-MCP 사이의 Tool 식별 키로 사용한다. +- MCP Server는 UID를 Registry metadata의 Tool name, version, endpoint와 매핑하여 실행한다. +- Tool name과 version은 설명 및 검증 metadata로 유지할 수 있지만 시스템 간 기본 mapping key 역할은 UID가 담당한다. + +## 구현 보류 조건 + +다음 항목은 아직 결정되지 않았으므로 코드 변경 조건이 충족되지 않았다. + +- UID 생성 시점과 Agent Builder/MCP 전달 시점 +- version 변경, 비활성화, 삭제, 재등록 시 UID 규칙 +- 환경별 UID 승격 또는 분리 규칙 +- 목표 요청 payload의 UID field 이름 + +이 보류안은 ADR-0005로 대체되었으며 현재 모델에 UID field를 두지 않는다. diff --git a/docs/decisions/ADR-0004-execution-guardrails.md b/docs/decisions/ADR-0004-execution-guardrails.md new file mode 100644 index 0000000..fb115b8 --- /dev/null +++ b/docs/decisions/ADR-0004-execution-guardrails.md @@ -0,0 +1,30 @@ +# ADR-0004 실행 가드레일 + +- 상태: Accepted +- 결정일: 2026-07-10 +- 관련 논의: [DISC-20260710-001](../discussions/DISC-20260710-001-agentbuilder-mcp-interface.md) + +## 결정 + +- Agent Builder-MCP 상호작용에는 300초 hard limit을 둔다. +- MCP Server는 3만 자 기준으로 Tool Service의 원문 응답을 임의 절단하지 않는다. +- write/update 성격의 Tool은 idempotency가 보장되지 않으면 자동 retry하지 않는다. + +## 해석 경계 + +- 300초는 전체 상한 원칙이며 모든 계층의 socket read timeout을 무조건 300초로 설정한다는 의미가 아니다. +- 원문 미절단은 response body를 무제한 허용한다는 의미가 아니다. +- read Tool이 항상 retry 가능하다는 결정은 아니다. + +## 구현 보류 조건 + +다음 세부 계약이 확정되기 전에는 timeout 또는 retry 코드를 변경하지 않는다. + +- ~~Agent Builder, ingress, MCP, Tool Service별 timeout budget~~ → + **확정 (2026-08-01).** Agent Builder 300초(호출 시점 기준) > MCP 270초 > Tool 30초. + 배분과 근거는 [architecture.md의 요청 시간 예산](../architecture.md#요청-시간-예산)이 정본이다. +- client disconnect와 downstream cancellation 전파 +- response body 최대 크기와 pagination/continuation 정책 +- Tool별 idempotency/retryable metadata와 오류 코드 + +현재 구현에는 3만 자 절단 및 자동 retry가 없으므로 두 원칙에 대한 즉시 코드 변경은 없다. diff --git a/docs/decisions/ADR-0005-standard-tool-name.md b/docs/decisions/ADR-0005-standard-tool-name.md new file mode 100644 index 0000000..97700d7 --- /dev/null +++ b/docs/decisions/ADR-0005-standard-tool-name.md @@ -0,0 +1,25 @@ +# ADR-0005 표준 MCP Tool name을 실행 식별자로 사용 + +- 상태: Accepted +- 결정일: 2026-07-30 +- 대체 대상: [ADR-0003](ADR-0003-builder-tool-uid.md) + +## 배경 + +Tool의 원천 정보는 각 Tool Service가 소유하고 MCP Server가 매니페스트를 pull한다. +Agent Builder의 UID는 Agent Builder 내부 관리 개념이므로 MCP와 Tool Service 사이의 계약으로 +전파하면 표준 `tools/list`와 `tools/call` 외에 별도 식별자 동기화가 필요해진다. + +## 결정 + +- `tools/list`가 노출하고 `tools/call.params.name`이 전달하는 표준 MCP Tool `name`을 실행 식별자로 사용한다. +- Tool Service가 전체 MCP 범위에서 고유한 namespaced name을 직접 선언한다. +- 허용 형식은 MCP 표준에 맞춘 1~64자의 영문·숫자와 `_`, `-`, `.`, `/`다. +- MCP Server는 이름을 재작성하지 않고 형식, bundle의 `namePrefix`, 전체 중복을 검증한다. +- Agent Builder 내부 UID는 Agent Builder가 자체 관리하며 MCP metadata와 실행 요청에 요구하지 않는다. + +## 결과 + +- 표준 MCP 계약만으로 목록과 실행 대상을 연결한다. +- Tool 이름 변경은 식별자 변경이므로 Tool Service와 Agent Builder의 rolling 호환 기간이 필요하다. +- 이름 충돌이나 전체 Tool 수 상한 초과 시 일부 목록을 노출하지 않고 기존 정상 snapshot을 유지한다. diff --git a/docs/decisions/ADR-0006-no-authentication-in-mcp.md b/docs/decisions/ADR-0006-no-authentication-in-mcp.md new file mode 100644 index 0000000..b7c5007 --- /dev/null +++ b/docs/decisions/ADR-0006-no-authentication-in-mcp.md @@ -0,0 +1,77 @@ +# ADR-0006 MCP Server는 인증·인가를 하지 않는다 + +- 상태: Accepted +- 결정일: 2026-08-01 +- 관련 결정: [ADR-0001](ADR-0001-stateless-execution-boundary.md) + +## 배경 + +Tool 실행 권한은 Agent Builder가 Agent를 구성할 때 이미 확인하고 넘어온다. +MCP Server는 Agent Builder가 지정한 Tool을 검증·실행하는 계층이므로 권한을 다시 판단할 근거가 없다. + +문제는 MCP가 **판단하지 않는 계층인 동시에 집행 지점**이라는 데 있다. +MCP는 이 배포에 속한 모든 Tool Service에 도달할 수 있는 유일한 경로다. +따라서 "MCP는 아무것도 하지 않는다"는 결정은, 그러면 **누가 하는가**를 함께 적지 않으면 +세 계층이 서로 상대가 확인했다고 가정하는 공백을 만든다. + +이 문서는 그 공백을 막기 위해 책임 소재를 명시한다. + +## 결정 + +MCP Server는 인증(authentication)과 인가(authorization)를 수행하지 않는다. + +- 요청자의 신원을 검증하지 않는다. +- Tool 실행 권한을 판단하지 않는다. +- `employee-no`·`virtual-employee-no`를 복호화·검증·저장하지 않는다. +- Authorization 헤더를 해석하지 않는다. `mcp.tool-client.forward-authorization`이 켜져 있으면 + 값을 그대로 전달만 한다. + +이에 따라 무검증 JWT decode 구현(`JwtClaimExtractor`, `UnverifiedJwtClaimExtractor`)을 삭제한다. +검증하지 않는 인증 코드는 없는 것보다 나쁘다. 이후 누군가 그 claim을 판단 근거로 쓸 여지를 남기고, +코드베이스에 인증이 처리되고 있다는 잘못된 인상을 준다. + +## 책임 소재 + +| 책임 | 주체 | 근거 | +|---|---|---| +| 호출자가 Agent Builder인지 보장 | **플랫폼(NetworkPolicy)** | Helm Chart의 `templates/networkpolicy.yaml`. 환경별 허용 namespace는 `values-{env}.yaml`의 `global.agentBuilderNamespace` | +| 사용자 인증, Tool 실행 권한 판단 | **Agent Builder** | Agent 구성 시점에 확인 | +| 사원 식별자 복호화와 업무 권한 집행 | **Tool Service** | KMS에서 발급받은 키 사용 | +| 요청 형식·schema 검증, 단일 Tool 실행 | **MCP Server** | ADR-0001 | + +## 이 결정이 성립하기 위한 전제 + +**전제 1 — 네트워크가 호출자를 고정한다.** +MCP는 요청자를 확인하지 않으므로, `/mcp`에 도달할 수 있다는 것 자체가 곧 인가다. +NetworkPolicy로 Agent Builder namespace만 8080에 접근하도록 제한한다. +**이 정책 없이 배포하면 클러스터 안의 어떤 Pod이든 Tool을 실행할 수 있다.** +정책은 선택적 강화가 아니라 이 ADR의 성립 조건이다. +그래서 Helm Chart에 비활성화 스위치를 두지 않았고, `HelmDeploymentContractTest`가 +조건부 렌더링이 들어오는 것까지 막는다. values 한 줄로 인가가 사라지지 않게 하기 위해서다. + +**전제 2 — 사원 식별자의 신뢰는 Tool Service가 확보한다.** +`employee-no`·`virtual-employee-no`는 암호화되어 전달되고, 복호화 키는 사내 KMS에서 발급받는다. +MCP는 키를 갖지 않으므로 값을 읽을 수 없고, 따라서 위조 여부도 판별할 수 없다. + +Tool 파트가 확인할 항목: + +- 복호화는 KMS 키로만 가능하므로 **기밀성**은 확보된다. + **위조 방지**는 암호화 키의 배포 범위에 달려 있다. 암호화 키를 널리 배포하면 + 임의의 사원번호를 스스로 암호화해 넣을 수 있으므로, 키 배포 범위를 신뢰 경계와 맞춘다. +- 동일한 암호문의 재사용(replay)을 허용할지, 만료·nonce를 둘지 결정한다. +- 두 헤더가 모두 없는 요청의 처리 방침을 정한다. 현재 계약에서 두 값은 선택값이다. + +**전제 3 — 감사 추적은 세 계층의 로그를 합쳐야 완성된다.** +MCP 로그에는 `guid`와 `x-request-id`만 남는다. +사원 식별자는 개인 식별자이므로 암호문이라도 기록하지 않는다. +따라서 "누가 조회했는가"는 MCP 로그만으로 답할 수 없다. +`guid`를 Agent Builder·MCP·Tool Service가 공통 상관 키로 사용해 세 로그를 연결한다. +규제 감사 요건이 확정되면 별도 durable sink를 설계한다. + +## 영향 + +- MCP에 인증 코드를 추가하지 않는다. 필요가 생기면 이 ADR을 대체하는 새 ADR을 먼저 쓴다. +- NetworkPolicy는 배포 필수 구성요소다. 누락은 설정 실수가 아니라 보안 결함으로 다룬다. +- 인증 모델이 token 기반으로 바뀌면 이 결정과 전제 1을 함께 재검토한다. +- `forward-authorization` 설정은 유지한다. 검증이 아니라 통과 전달이며, + Tool Service가 자체 인증을 도입할 때 필요한 연결점이다. diff --git a/docs/decisions/ADR-0007-one-mcp-per-tool-service.md b/docs/decisions/ADR-0007-one-mcp-per-tool-service.md new file mode 100644 index 0000000..ac54cc9 --- /dev/null +++ b/docs/decisions/ADR-0007-one-mcp-per-tool-service.md @@ -0,0 +1,96 @@ +# ADR-0007 MCP 배포 하나는 Tool Service 하나만 본다 + +- 상태: Accepted +- 결정일: 2026-08-02 +- 관련: [ADR-0001](ADR-0001-stateless-execution-boundary.md), [ADR-0002](ADR-0002-tool-exposure-and-single-call.md), [ADR-0009](ADR-0009-container-handles-public-mcp-path.md), [계약 v0.2](../contracts/tool-service-mcp/protocol-v0.2-bundle-discovery.md) + +외부에서 여러 MCP를 하나의 host 아래 path로 묶는 방식은 [ADR-0009](ADR-0009-container-handles-public-mcp-path.md)이 +소유한다. OpenShift Route가 원래 path를 유지한 채 각각의 독립 배포로 연결하므로 이 ADR의 1:1 결정은 그대로 유지된다. + +## 배경 + +MCP 설정의 `mcp.bundles`는 여러 Tool Service를 하나의 카탈로그로 병합할 수 있다. 이 능력을 실제로 쓸지, +즉 MCP와 Tool Service를 M:N으로 묶을지는 결정되지 않은 상태였다. + +고객 요구는 **Tool의 군집화**다. MCP 자체를 군집화해 달라는 요구가 아니다. 요구의 목적은 가용성이며, +중요한 Tool은 다운이 없어야 한다는 것이다. 분할 기준은 먼저 업무로 나누고, 그 안에서 중단 시 업무 +영향도와 가용성 위험도로 다시 나누는 형태다. 예: 처리계-중요, 처리계-비중요, 정보계-중요, +정보계-비중요. 여기서 위험도는 보안·권한 정책이 아니라 **서비스 중단 위험**을 뜻한다. 업무 정책은 +Tool Service가 관리하며 이 배포 등급의 범위가 아니다. + +Tool 목록이 확정되지 않아 Tool Service가 몇 개가 될지 모르며, 10~20개 이상이 될 수 있다. + +## 결정 + +1. **MCP 배포 하나는 Tool Service를 정확히 하나 본다.** `mcp.bundles`는 항상 한 항목이다. +2. 배포 단위의 분할 축은 **업무 × 등급(tier)** 이다. 등급은 `critical`과 `standard`로 둔다. +3. 등급은 **배포 속성일 뿐 wire 계약에 나타나지 않는다.** Tool 이름·`namePrefix`·매니페스트에 등급을 넣지 않는다. +4. 다중 bundle 병합 코드는 **삭제하지 않고 유지**하되, 배포 설정에서 bundle 1개로 잠근다. + +## 근거 + +### 등급이 다른 Tool Service를 한 MCP가 보면 격리가 깨진다 + +`ToolBundleRegistryClient.fetchTools()`는 사용 가능한 성공본이 없는 bundle이 하나라도 있으면 +카탈로그 전체 교체를 거부한다(계약 v0.2 §1, §7). 한 MCP가 중요·비중요 Tool Service를 함께 보면 +**비중요 쪽 조회가 확정되지 않는 동안 중요 Tool의 카탈로그 갱신까지 멈춘다.** 직전 성공본으로 +서빙은 계속되지만 변경 반영은 막힌다. + +여기에 두 Tool Service 호출이 같은 프로세스의 HTTP connection pool과 스레드를 공유하므로, +비중요 쪽 지연이 중요 쪽 여유를 잠식한다. + +**병합은 가용성 요구와 정면으로 충돌한다.** 등급을 나눈 목적을 배포 구조가 되돌려 놓는다. + +### 병합해서 얻는 것이 없다 + +MCP에는 업무 로직이 없다. 여러 Tool Service를 하나로 합치는 일이 MCP 안에서 일어나야 할 +기술적 이유가 없다. Agent Builder는 MCP를 개별 등록하면서 하위 Tool 정보를 자기 DB에 저장하고, +사용자 요청을 판단한 뒤 **해당 Tool을 가진 MCP로 호출을 보낸다.** 여러 Tool 묶음을 아우르는 일은 +Tool 선택을 이미 수행하는 Agent Builder 계층에서 끝난다. + +런타임에 공유되는 공통 Tool Service도 없다. Tool 파트의 `tool-common`은 각 Tool Service 프로젝트가 +함께 빌드하는 **빌드 타임 라이브러리**이지 별도로 뜨는 서비스가 아니다. 1:1을 깨야 할 사례가 남지 않는다. + +### 1:1이라야 등급별로 다른 비용을 쓸 수 있다 + +한 MCP가 등급을 섞어 들고 있으면 그 배포 전체에 중요 등급 기준을 적용해야 한다. 나뉘어 있으면 +`critical`에만 replica 여유와 PodDisruptionBudget을 주고 `standard`는 최소로 둘 수 있다. +**분할의 실질 이득은 격리 자체보다 여기에 있다.** + +다만 배포를 나누는 것만으로 가용성이 생기지는 않는다. 같은 노드 배치, 같은 namespace의 쿼터, +공통 Redis·클러스터 장애는 분할로 막히지 않는다. 등급 분리가 의미를 가지려면 replica 하한, +PodDisruptionBudget, anti-affinity와 usable Tool snapshot 기반 readiness가 함께 가야 한다. Chart의 +`tiers` 설정과 `HelmDeploymentContractTest`가 test·prod의 정적 values를 검사하며, 실제 렌더링 결과는 +배포 파이프라인의 `helm lint`와 `helm template`이 확인한다. + +## 전제 + +아래가 깨지면 이 결정을 재검토한다. + +1. Agent Builder는 MCP를 개별 등록하고, 한 Agent가 여러 MCP의 Tool을 사용할 수 있다. +2. Tool 호출은 한 요청에 하나이며([ADR-0002](ADR-0002-tool-exposure-and-single-call.md)) 그 Tool을 가진 MCP로 직접 간다. +3. 런타임에 공유되는 공통 Tool Service가 없다. + +## 영향 + +- **배포 수 = Tool Service 수**다. 10~20개를 전제로 Helm values는 토폴로지를 한 파일에 모으고 + 배포 시 `deploymentKey`로 하나를 고른다. 배포가 늘어도 파일 수는 변하지 않는다. +- 계약 v0.2 §7의 병합 규칙 중 bundle 간 이름 충돌(6번)과 `maxToolsTotal`(3번 후단)은 운영에서 발동하지 않는다. + 규칙 자체는 계약에 남는다. +- **Tool 이름의 전역 유일성은 Tool Service 책임으로 남는다.** 서로 다른 MCP가 같은 `namePrefix`를 + 쓰는 것을 MCP는 막지 못한다. 등급으로 나뉜 두 배포가 같은 업무 prefix(`processing.`)를 공유하는 것은 + 의도된 구성이며, 그 안에서 Tool 이름이 겹치지 않아야 한다. +- Tool을 다른 등급으로 옮기면 그 Tool을 제공하는 **MCP endpoint가 바뀐다.** Agent Builder가 Tool 정보를 + DB에 보관하므로 반영에는 재등록 또는 다음 `tools/list` 주기가 필요하다. 등급은 자주 바꾸지 않는 값으로 다룬다. +- [ADR-0002](ADR-0002-tool-exposure-and-single-call.md)의 Tool 노출 상한 50개는 한 Agent가 여러 MCP에서 + 가져온 Tool의 **합계**에 적용된다. MCP를 나눈다고 상한이 늘지 않는다. + +## 채택하지 않은 대안 + +**M:N — 한 MCP가 여러 Tool Service를 본다.** 배포 수는 줄지만 위의 격리 문제가 그대로 남는다. +가용성이 분할의 목적이므로 목적과 수단이 어긋난다. + +**코드에서 bundle 1개를 강제한다.** `McpProperties`에 검증을 넣으면 다중 bundle 병합 코드가 +도달 불가능해진다. 전제 3이 깨질 때 되돌리는 비용이 커지고, 이미 작성·테스트된 경로를 죽은 코드로 +만든다. 1:1은 애플리케이션 불변식이 아니라 **배포 결정**이므로 배포 정의에서 잠그는 편이 맞다. +이 선택은 검증 위치를 옮긴 것이지 검증을 뺀 것이 아니다. diff --git a/docs/decisions/ADR-0008-shared-host-path-routing.md b/docs/decisions/ADR-0008-shared-host-path-routing.md new file mode 100644 index 0000000..df98720 --- /dev/null +++ b/docs/decisions/ADR-0008-shared-host-path-routing.md @@ -0,0 +1,53 @@ +# ADR-0008 공유 host의 path를 독립 MCP 배포로 연결한다 + +- 상태: Accepted +- 결정일: 2026-08-05 +- 관련: [ADR-0006](ADR-0006-no-authentication-in-mcp.md), [ADR-0007](ADR-0007-one-mcp-per-tool-service.md) + +## 배경 + +Agent Builder에는 하나의 HTTPS host를 제공하고 업무별 MCP를 `/mcp/core`, `/mcp/process`, +`/mcp/information` 같은 path로 구분해야 한다. 이를 하나의 애플리케이션 프로세스에서 처리하면 +Registry snapshot·Redis cache·readiness·connection 자원을 route별로 다시 나눠야 하고, 한 프로세스의 +장애와 배포가 모든 Tool Service에 전파된다. + +## 결정 + +1. 환경마다 공개 MCP host를 하나 둔다. +2. `deployments..publicPath`는 한 MCP Deployment를 가리키며 topology 전체에서 유일하다. +3. OpenShift Route가 공개 path를 해당 MCP Service로 전달하고 내부 고정 endpoint `/mcp`로 rewrite한다. +4. MCP 애플리케이션과 Tool Service의 1:1 매핑, Registry snapshot, Redis key와 readiness는 배포별로 유지한다. +5. Agent Builder는 각 공개 URL을 독립 MCP endpoint로 등록하고 endpoint별로 initialize한다. +6. 요청 body·header·Tool 이름은 어느 MCP Service로 보낼지 결정하지 못한다. 대상은 Helm topology만 정한다. + +```text +https://{host}/mcp/core -> core MCP /mcp -> core Tool Service +https://{host}/mcp/process -> process MCP /mcp -> process Tool Service +https://{host}/mcp/information -> information MCP /mcp -> information Tool Service +``` + +가용성 등급으로 같은 업무를 둘로 나누면 path도 구분한다. 예를 들어 +`/mcp/process-critical`과 `/mcp/process-standard`는 서로 다른 MCP Deployment와 Tool Service를 가리킨다. + +## 근거 + +- 외부 URL은 한 host로 단순화하면서 내부 장애 범위는 업무·가용성 등급별로 유지한다. +- 현재 Java transport·Registry·cache 코드를 route-aware Gateway로 바꾸지 않아도 된다. +- 한 Tool Service의 조회 실패나 부하가 다른 MCP의 readiness와 snapshot 갱신을 막지 않는다. +- 공개 path와 Service 매핑을 한 topology에서 검토하고 계약 테스트로 중복·형식을 막을 수 있다. + +## 영향 + +- 하나의 Helm release는 Deployment·Service·Route를 하나씩 만든다. 여러 release의 Route가 같은 host와 서로 다른 path를 사용한다. +- OpenShift Router가 TLS를 종료하고 path를 rewrite하므로 backend 애플리케이션은 계속 `POST /mcp`만 처리한다. +- 공개 URL 변경 시 Agent Builder 재등록 또는 endpoint 설정 변경이 필요하다. +- Gateway 기능은 OpenShift Route가 소유한다. MCP Java 프로세스는 Tool 선택이나 다른 MCP로의 proxy를 하지 않는다. +- 실제 환경 host와 인증서·TLS 종료 방식은 플랫폼 적용 전에 확정해야 한다. + +## 채택하지 않은 대안 + +**하나의 MCP 프로세스가 모든 path를 처리한다.** 배포 수는 줄지만 전역 장애 범위와 noisy neighbor가 생기고, +route별 Registry·cache·readiness를 새로 구현해야 하므로 채택하지 않았다. + +**Tool Service가 MCP protocol을 직접 구현하고 중앙 Gateway가 raw proxy한다.** Tool Service 계약과 책임이 +크게 바뀌며 현재의 공통 MCP 검증 계층이 중복되므로 채택하지 않았다. diff --git a/docs/decisions/ADR-0009-container-handles-public-mcp-path.md b/docs/decisions/ADR-0009-container-handles-public-mcp-path.md new file mode 100644 index 0000000..da305c3 --- /dev/null +++ b/docs/decisions/ADR-0009-container-handles-public-mcp-path.md @@ -0,0 +1,36 @@ +# ADR-0009 컨테이너가 공개 MCP path를 직접 처리한다 + +- 상태: Accepted +- 결정일: 2026-08-05 +- 대체: [ADR-0008](ADR-0008-shared-host-path-routing.md) +- 관련: [ADR-0007](ADR-0007-one-mcp-per-tool-service.md) + +## 배경 + +Agent Builder는 `/mcp/core`, `/mcp/process`, `/mcp/information`처럼 sub path까지 포함한 URL을 각각의 MCP로 등록한다. 각 URL은 독립 MCP 컨테이너와 Tool Service에 연결된다. 공개 path를 OpenShift Route가 내부 `/mcp`로 바꾸면 Agent Builder가 등록한 경로와 컨테이너가 처리한 경로가 달라져 운영 추적과 설정 검증이 어려워진다. + +## 결정 + +1. `deployments..publicPath`는 Agent Builder 등록 URL과 컨테이너 endpoint가 함께 사용하는 단일 정본이다. +2. OpenShift Route는 host와 path로 독립 MCP Service만 선택하고 path를 rewrite하지 않는다. +3. Helm ConfigMap이 `publicPath`를 `mcp.endpoint-path`로 주입하고, Controller와 Filter가 그 경로만 처리한다. +4. MCP 컨테이너 하나는 endpoint와 Tool Service를 각각 하나만 가진다. 하나의 Java 프로세스에서 path별 Registry를 선택하지 않는다. +5. 요청 body·header·Tool name은 컨테이너 선택에 관여하지 않는다. + +```text +https://{host}/mcp/core -> core MCP /mcp/core -> core Tool Service +https://{host}/mcp/process -> process MCP /mcp/process -> process Tool Service +https://{host}/mcp/information -> information MCP /mcp/information -> information Tool Service +``` + +## 영향 + +- 같은 host에서 여러 Service를 사용하므로 OpenShift Route의 path 기반 Service 선택은 유지한다. +- rewrite annotation은 사용하지 않는다. access log와 애플리케이션 log가 같은 path를 본다. +- `publicPath` 변경은 Route와 애플리케이션 endpoint를 함께 바꾸며 Agent Builder 등록 정보도 갱신해야 한다. +- Registry snapshot, Redis namespace, readiness, connection pool과 장애 범위는 배포별로 계속 분리된다. +- JSON-RPC payload와 Tool Service wire 계약은 바뀌지 않는다. + +## 대체한 결정 + +ADR-0008의 공유 host와 독립 Deployment 원칙은 유지한다. 공개 path를 내부 `/mcp`로 rewrite한다는 부분만 이 ADR이 대체한다. diff --git a/docs/decisions/README.md b/docs/decisions/README.md new file mode 100644 index 0000000..4244e76 --- /dev/null +++ b/docs/decisions/README.md @@ -0,0 +1,23 @@ +# Architecture Decision Records + +장기 설계 결정은 ADR로 관리한다. + +- `Accepted`: 확정된 결정 +- `Superseded`: 후속 ADR로 대체된 결정 +- `Rejected`: 검토했으나 채택하지 않은 결정 + +결정이 변경되면 기존 ADR을 삭제하거나 의미를 덮어쓰지 않고 새 ADR에서 대체 관계를 기록한다. + +## 결정 목록 + +| ADR | 제목 | 상태 | +|---|---|---| +| [ADR-0001](ADR-0001-stateless-execution-boundary.md) | Stateless 실행 책임 경계 | Accepted | +| [ADR-0002](ADR-0002-tool-exposure-and-single-call.md) | Agent Builder Tool 노출 제한과 단일 Tool 호출 | Accepted | +| [ADR-0003](ADR-0003-builder-tool-uid.md) | Builder Tool UID를 시스템 간 식별 키로 사용 | Superseded | +| [ADR-0004](ADR-0004-execution-guardrails.md) | 300초, Raw Data, unsafe retry 실행 가드레일 | Accepted | +| [ADR-0005](ADR-0005-standard-tool-name.md) | 표준 MCP Tool name을 실행 식별자로 사용 | Accepted | +| [ADR-0006](ADR-0006-no-authentication-in-mcp.md) | MCP Server는 인증·인가를 하지 않는다 | Accepted | +| [ADR-0007](ADR-0007-one-mcp-per-tool-service.md) | MCP 배포 하나는 Tool Service 하나만 본다 | Accepted | +| [ADR-0008](ADR-0008-shared-host-path-routing.md) | 공유 host의 path를 독립 MCP 배포로 연결 | Superseded | +| [ADR-0009](ADR-0009-container-handles-public-mcp-path.md) | 컨테이너가 공개 MCP path를 직접 처리 | Accepted | diff --git a/docs/discussions/DISC-20260710-001-agentbuilder-mcp-interface.md b/docs/discussions/DISC-20260710-001-agentbuilder-mcp-interface.md new file mode 100644 index 0000000..6d8abdc --- /dev/null +++ b/docs/discussions/DISC-20260710-001-agentbuilder-mcp-interface.md @@ -0,0 +1,50 @@ +# DISC-20260710-001 Agent Builder-MCP 인터페이스 협의 기록 + +- 상태: Closed / Historical +- 회의 기준일: 2026-07-10 +- 원본: `20260710_AgentBuilder_MCP_통신규약분석협의_회의록.pptx` +- 원본 위치: 저장소 외부의 통제된 AX HUB 업무 자료 영역 +- 보안 등급: 내부용 + +이 문서는 당시 논의의 출발점만 보존한다. 현재 동작이나 미합의 사항의 정본으로 사용하지 않는다. + +## 현재 정본 + +| 주제 | 정본 | +|---|---| +| 현재 Agent Builder wire 계약 | [동기 JSON v0.3](../contracts/agent-builder-mcp/protocol-v0.3-streaming-policy.md) | +| Stateless 책임 | [ADR-0001](../decisions/ADR-0001-stateless-execution-boundary.md) | +| 단일 Tool 실행 | [ADR-0002](../decisions/ADR-0002-tool-exposure-and-single-call.md) | +| 실행 식별자 | [ADR-0005](../decisions/ADR-0005-standard-tool-name.md) | +| Timeout·retry | [ADR-0004](../decisions/ADR-0004-execution-guardrails.md), [요청 시간 예산](../architecture.md#요청-시간-예산) | +| 인증·인가 경계 | [ADR-0006](../decisions/ADR-0006-no-authentication-in-mcp.md) | +| 아직 합의하지 않은 사항 | [extension-points.md](../extension-points.md) | + +## 회의 당시 확인한 방향 + +1. MCP Server는 stateless 실행 계층이며 Tool을 자율 선택하지 않는다. +2. Agent Builder가 LLM에 노출할 Tool을 선택하고 최대 50개로 제한한다. +3. 요청 하나는 Tool 하나만 실행한다. +4. 전체 상호작용은 300초를 넘기지 않는다. +5. MCP는 3만 자라는 임의 기준으로 Tool 원문 응답을 자르지 않는다. +6. 멱등성이 확인되지 않은 write/update Tool은 자동 retry하지 않는다. + +## 회의 이후 달라진 결정 + +- 회의에서 검토한 Builder Tool UID는 MCP wire 식별자로 사용하지 않는다. 표준 MCP `name`을 사용한다. +- 당시 예시의 `tool/call`, `toolId/contract`, `toolCalls[]`는 현재 계약이 아니다. 현재는 표준 `tools/call`의 `params.name`과 `params.arguments`를 사용한다. +- MCP의 JWT decode·인증·인가 구현은 제거했다. NetworkPolicy가 호출자를 제한하고, Agent Builder와 Tool Service가 각자의 권한을 집행한다. +- MCP 요청 deadline 기본값은 270초이고 Tool timeout 상한은 30초다. 300초는 Agent Builder를 포함한 전체 상한이다. +- streaming 실행 경로는 제거했다. 기존 `Accept: application/json, text/event-stream`은 수용하지만 응답은 단일 `application/json`이다. + +## 남은 논의의 관리 위치 + +오류 노출, cancellation, retry와 멱등성, 대용량 응답, 식별자 lifecycle, 운영 보완 사항은 +[extension-points.md](../extension-points.md)에서만 관리한다. 이 문서에는 이후 상태를 중복 기록하지 않는다. + +## 변경 이력 + +| 일자 | 내용 | +|---|---| +| 2026-07-13 | 회의 자료 분석과 초기 변경 범위 기록 | +| 2026-08-01 | 후속 ADR·현재 계약이 확정되어 역사 문서로 종결하고 정본 링크만 유지 | diff --git a/docs/discussions/README.md b/docs/discussions/README.md new file mode 100644 index 0000000..67ffd31 --- /dev/null +++ b/docs/discussions/README.md @@ -0,0 +1,14 @@ +# 협의 및 검토 기록 + +이 디렉터리는 회의, 검토, 분석 당시의 사실과 쟁점을 보존한다. + +- 협의 기록은 최종 인터페이스 규격이 아니다. +- 확정된 장기 설계 결정은 `../decisions/`의 ADR로 분리한다. +- 현재 구현 계약과 목표 계약은 `../contracts/`에서 관리한다. +- 후속 협의가 끝나면 원문을 덮어쓰지 않고 관련 ADR과 계약 문서 링크를 추가한다. + +## 기록 목록 + +| ID | 제목 | 상태 | 기준일 | +|---|---|---|---| +| [DISC-20260710-001](DISC-20260710-001-agentbuilder-mcp-interface.md) | Agent Builder-MCP 인터페이스 협의 분석 | Open | 2026-07-10 | diff --git a/docs/extension-points.md b/docs/extension-points.md new file mode 100644 index 0000000..1bb1bc4 --- /dev/null +++ b/docs/extension-points.md @@ -0,0 +1,92 @@ +# 미합의 항목과 확장 포인트 + +이 문서는 **아직 결정되지 않았거나 운영 적용 전에 보완할 내용만** 관리한다. 현재 동작 설명은 [architecture.md](architecture.md), Agent Builder wire 계약은 [v0.3](contracts/agent-builder-mcp/protocol-v0.3-streaming-policy.md), Tool Service wire 계약은 [bundle 조회 v0.2](contracts/tool-service-mcp/protocol-v0.2-bundle-discovery.md)가 정본이다. + +결정이 끝난 항목은 ADR 또는 현재 계약으로 옮기고 이 목록에서 제거한다. 목표안인 [Agent Builder-MCP v1 기준선](contracts/agent-builder-mcp/protocol-v1-agreement-baseline.md)은 전체 payload가 승인되기 전까지 구현 근거가 아니다. + +## Agent Builder와 합의할 항목 + +1. 여러 MCP protocol version 공존 시 fallback·upgrade와 공지 정책 +2. Tool name 변경·폐기 시 구·신 이름의 rolling 호환 기간과 Agent 재등록 정책 +3. Agent Builder가 `tools/list`를 다시 읽는 **주기**. 주기적으로 읽는다는 것까지는 확인됐고 값은 미정이다. + Agent Builder는 MCP 등록 시점에 Tool 정보를 자기 DB에 저장해 계속 사용하므로, Tool 변경이 실제로 반영되기까지 + 걸리는 시간은 **MCP의 매니페스트 갱신 주기 + Agent Builder의 조회 주기**다. 두 값을 각자 정하면 합이 얼마인지 + 아무도 모르게 되므로 함께 정한다 +4. Agent Builder 내부 UID와 표준 MCP `name`의 lifecycle. UID는 MCP wire 계약에 포함하지 않음 +5. Agent별 최대 50개 Tool 선별 로직과 권한 거부 시 Agent Builder가 사용자에게 보일 응답 +6. client disconnect 시 downstream cancellation 계약. 현재 MCP는 이미 시작한 Tool 호출을 취소하지 않는다 + (계층별 budget 배분은 [architecture.md의 요청 시간 예산](architecture.md#요청-시간-예산)에서 확정) +7. Tool 원본 오류·업무 코드·PII를 Agent Builder에 노출하거나 마스킹하는 기준 +8. response 크기, pagination/continuation과 대용량 결과 정책 +9. retry가 같은 업무 요청인지 판별하는 규칙과 `guid` 재사용 여부. 같은 `guid`를 재사용하기로 합의한 뒤에만 Tool Service의 멱등성 키로 사용 +10. `employee-no`·`virtual-employee-no`가 둘 다 없는 요청을 Agent Builder가 보낼 수 있는지, 언젠가 필수로 승격할지 +11. **주기 `tools/list`가 실패했을 때 DB의 Tool 정보를 어떻게 처리하는가.** 직전 목록을 유지하는지, 비우는지에 따라 + MCP 재기동·배포 중 수십 초 공백이 Agent에 그대로 드러날 수 있다. 중요 등급 MCP의 replica 하한과 PodDisruptionBudget은 + 이 답과 무관하게 [ADR-0007](decisions/ADR-0007-one-mcp-per-tool-service.md)에서 이미 강제하지만, + 답에 따라 비중요 등급의 배포 방식도 달라진다 +12. 같은 환경 host의 여러 공개 path를 Agent Builder에 등록·변경·폐기하는 절차와 주체. path 처리는 + [ADR-0009](decisions/ADR-0009-container-handles-public-mcp-path.md)로 확정했지만, 배포 수가 Tool Service 수와 같아 + 10~20개 이상일 때의 등록 자동화는 미정이다 + +인증 주체는 [ADR-0006](decisions/ADR-0006-no-authentication-in-mcp.md)에서 확정했다. MCP는 인증·인가를 하지 않는다. + +## Tool Service와 합의할 항목 + +1. `GET {manifestUrl}` 제공, 인증 방식과 NetworkPolicy 범위 +2. Tool name namespace, 변경·폐기 절차와 하위 호환 기간 +3. 허용할 JSON Schema 2020-12 keyword, 원격 `$ref`와 `format` 정책 +4. Tool별 timeout, 권한 scope, write Tool의 idempotency 보장 +5. `outputSchema`/`structuredContent` 도입 여부와 응답 검증 실패 의미 +6. 매니페스트 revision·ETag/304 및 즉시 refresh 알림의 필요성 +7. 사원 식별자 검증 방식: KMS 키 배포 범위(위조 방지 가능 여부), 동일 암호문 재사용 허용 여부, 만료·nonce 도입 여부. + [ADR-0006](decisions/ADR-0006-no-authentication-in-mcp.md) 전제 2가 이 항목에 의존한다 +8. Tool 이름의 **전역 유일성 보장 방법**. 등급으로 나뉜 두 Tool Service가 같은 업무 `namePrefix`를 공유하므로 + (`처리계-중요`와 `처리계-비중요`가 모두 `processing.`), 그 안에서 이름이 겹치지 않게 하는 것은 Tool Service 책임이다. + MCP는 자기 bundle의 prefix만 검증하며 다른 MCP의 이름을 알지 못한다([ADR-0007](decisions/ADR-0007-one-mcp-per-tool-service.md)) +9. Tool의 **가용성 등급 분류 기준과 변경 절차**. 이 문서에서 위험도는 보안 정책이 아니라 중단 시 업무 + 영향도를 뜻한다. 등급이 바뀌면 그 Tool을 제공하는 MCP endpoint가 바뀌므로 Agent Builder 반영이 + 필요하다. 자주 바뀌지 않는 값으로 다룰 수 있는지 확인한다 + +MCP와 Tool Service를 1:1로 묶는 결정은 [ADR-0007](decisions/ADR-0007-one-mcp-per-tool-service.md)에서 확정했다. + +현재 서버는 `tools/call` 결과를 `content[0].text`로만 반환한다. `structuredContent`를 지원하기 전까지 운영 매니페스트에는 `outputSchema`를 사용하지 않는다. + +## 플랫폼·DevOps와 확인할 항목 + +배포 정의를 이 저장소가 어디까지 소유하는지 확정되지 않았다. +현재는 [Helm Chart](../deploy/helm/mcp-server/)만 두고 있으며, 빌드·배포 실행 방식은 정의하지 않는다. + +1. **Helm Chart를 어디에 두는가.** 앱 저장소인가 배포 전용 저장소인가 +2. 환경별 namespace 명명 규칙과 Agent Builder namespace. + 후자는 Route를 우회한 Pod 직접 접근의 허용 출처이므로 [ADR-0006](decisions/ADR-0006-no-authentication-in-mcp.md)의 전제와 직결된다 +3. 사내 Nexus에 `io.modelcontextprotocol.sdk:mcp-json-jackson2:2.0.0`과 Spring Boot 3.5.11가 있는가. + 없으면 라이브러리 반입이 선행되어야 한다 +4. 사내 registry의 JDK 21 빌드·실행 이미지 이름. 현재 `Dockerfile`은 외부 이미지를 쓴다 +5. 소스 개행 표준(CRLF)과 `gradlew`의 관계. + shell script가 CRLF이면 Linux 컨테이너에서 실행되지 않으므로 예외 또는 우회 방식이 필요하다 +6. 환경별 실제 `global.mcpHost`, 인증서와 TLS termination 책임 +7. Agent Builder의 실제 고정 egress CIDR과 Route `ip_allowlist` 값 +8. 대상 OpenShift의 ingress namespace label과 IngressController endpoint publishing 방식이 Chart의 NetworkPolicy 전제와 맞는지 + +## 운영 적용 전 필수 보완 + +| 영역 | 현재 상태 | 필요한 결정·구현 | +|---|---|---| +| egress | 절대 HTTP(S) 여부만 검증 | host allowlist, redirect·DNS rebinding 방어, mTLS/NetworkPolicy | +| 장애 격리 | timeout과 last-good 제공 | 측정 후 bulkhead·circuit breaker·제한적 retry 결정 | +| 관측성 | 경계 로그와 bundle Actuator 제공 | Micrometer/OpenTelemetry/SIEM 지표와 경보 기준 | +| 감사 | 일반 애플리케이션 로그만 제공 | 보존 대상·기간·암호화·위변조 방지·유실 정책 확정 후 durable sink | +| 용량 | request body 1 MiB 제한 | response 크기, JSON depth, 동시 실행 수, connection pool 부하 기준 | +| Redis | 요청 경로 밖의 선택 cache. Tool snapshot cache는 route별 key(`key-prefix:identity:v2:route:{routeToken}`)로 분리하고, Portal registry fallback key와도 분리한다. Portal registry fallback key 기본값은 `axhub:mcp:portal-registry`이며 운영에서는 `mcp.redis.portal-registry-key`로 포털 저장 key와 반드시 맞춘다. | Redis 사용 여부, key namespace·schema version·TTL·공유 범위, TLS/ACL, Sentinel/Cluster, rolling upgrade 정책 | +| 종료 | Spring graceful shutdown | 신규 요청 차단과 진행 중 Tool 호출 drain 검증 | +| 가용성 | test·prod critical의 replica·PDB·노드 분산 values를 정적 테스트가 검사하고 usable snapshot으로 readiness 판정. 공개 Route도 배포마다 분리 | `helm lint/template`, 노드 분산 실제 확인, 배포 창 분리, 쿼터 산정. 공유 ingress·DNS 장애는 path 분할로 막히지 않는다 | + +## 코드 확장 경계 + +- 새 MCP method: `McpMethodHandlerRegistry.Handler` 구현 하나를 추가하고 SDK method 상수를 사용한다. +- Tool metadata: 새 원천을 만들지 말고 local fixture 또는 Tool Service 매니페스트 계약을 확장한다. +- Tool protocol: 실제 두 번째 protocol이 필요할 때만 `ToolClient` 구현을 추가한다. +- 인증: 추가하지 않는다. 필요가 생기면 [ADR-0006](decisions/ADR-0006-no-authentication-in-mcp.md)을 대체하는 ADR을 먼저 쓴다. +- 규제 감사: 저장·전달 보장이 합의된 뒤 HTTP/Tool 경계에 durable sink를 연결한다. + +새 interface, mapper, DTO, cache 계층은 현재 경계로 해결할 수 없는 요구가 확인되기 전에는 추가하지 않는다. diff --git a/docs/mcp-java-sdk-adoption.md b/docs/mcp-java-sdk-adoption.md new file mode 100644 index 0000000..e0f94b6 --- /dev/null +++ b/docs/mcp-java-sdk-adoption.md @@ -0,0 +1,144 @@ +# MCP Java SDK 선택적 도입 설계 + +- 상태: 적용 완료 +- 적용 버전: `io.modelcontextprotocol.sdk:mcp-json-jackson2:2.0.0` +- 대상 런타임: Java 21, Spring Boot 3.5.11 +- 적용 원칙: 외부 계약과 AX HUB 고유 실행 경계는 유지하고, 표준 프로토콜 모델과 JSON Schema 검증만 SDK에 위임한다. + +## 1. 도입 결론 + +이 프로젝트는 MCP Java SDK의 서버 Starter나 HTTP transport를 사용하지 않는다. 현재 `/mcp` endpoint는 +Agent Builder와 합의한 동기 JSON, `Mcp-Session-Id`, protocol version HTTP 400, trace 계약을 이미 구현하고 +있으므로 SDK transport를 함께 활성화하면 같은 endpoint에 두 프로토콜 처리 경로가 생길 수 있기 때문이다. + +대신 실제 사용 모듈인 `mcp-json-jackson2`에 직접 의존한다. 이 모듈이 `mcp-core`를 전이 제공하므로 aggregate artifact를 별도로 선언하지 않는다. 적용 범위는 다음과 같다. + +| 적용 영역 | SDK 타입/기능 | 기존 코드에서의 사용 위치 | +|---|---|---| +| MCP method 이름 | `McpSchema.METHOD_*` | handler와 protocol validator | +| JSON-RPC 버전과 표준 오류 번호 | `McpSchema.JSONRPC_VERSION`, `McpSchema.ErrorCodes` | request parser, response, error enum | +| initialize 결과 | `McpSchema.InitializeResult`, `Implementation`, `ServerCapabilities` | `InitializeHandler` | +| tools/list 결과 | `McpSchema.ListToolsResult`, `Tool` | `ToolsListHandler` | +| tools/call 결과 | `McpSchema.CallToolResult`, `TextContent` | `ToolsCallHandler` | +| Tool arguments schema 검증 | `DefaultJsonSchemaValidator` | `ToolArgumentValidator` | + +이 서버는 Spring AI API를 사용하지 않으므로 Spring AI BOM을 두지 않는다. MCP SDK 버전은 `2.0.0`으로 직접 +고정한다. Starter를 추가하지 않았기 때문에 Spring AI MCP auto-configuration, 별도 `/mcp` mapping, +SSE/Streamable transport bean은 생성되지 않는다. + +## 2. 전체 요청 경계 + +```text +Agent Builder + -> 기존 McpExchangeFilter + - 호출자 header 추출 (guid, request-id, session, 사원 식별자) + - guid, x-request-id, MCP Session correlation + - protocol version HTTP header 검증 + - HTTP/Tool 경계 trace log + -> 기존 McpController + -> 기존 JsonRpcRequestParser / McpMethodHandlerRegistry + -> Handler + - initialize: SDK InitializeResult 생성 + - tools/list: 기존 Registry metadata -> SDK Tool/ListToolsResult + - tools/call: 기존 실행 결과 -> SDK CallToolResult/TextContent + -> 기존 JsonRpcResponse envelope + -> application/json 응답 +``` + +Tool 실행 경로는 다음과 같다. + +```text +tools/call + -> 기존 ToolsCallHandler params 검증 + -> 기존 ToolRegistryService + -> 기존 basic contract + SDK JSON Schema 검증 + -> SDK JSON Schema 2020-12 검증 + -> 기존 ToolRoutingService / ToolClient + -> 기존 timeout·correlation 처리 (MCP는 인증·인가하지 않음) +``` + +SDK 모델은 handler의 표준 MCP payload를 만드는 데만 사용한다. SDK server가 요청을 dispatch하거나 Tool Service를 +호출하지 않는다. + +## 3. SDK와 기존 소스의 책임 경계 + +### SDK에 위임한 책임 + +- 표준 MCP method 문자열과 JSON-RPC 상수 +- initialize, Tool definition, list result, call result의 표준 필드 구조 +- text content의 `type: "text"` 표현 +- JSON Schema 2020-12 기반 arguments 검증과 schema 컴파일 재사용 +- `minLength`, `pattern`, `enum`, `additionalProperties`, 중첩 객체 등 기존 기본 validator보다 넓은 schema keyword + +### 기존 구현이 계속 소유하는 책임 + +- `/mcp` HTTP mapping과 항상 `application/json`을 반환하는 transport 정책 +- `Accept: application/json, text/event-stream` 수용 +- `Mcp-Session-Id` 생성과 stateless correlation +- `MCP-Protocol-Version` 누락·미지원 시 HTTP 400 처리 +- JSON-RPC parse/invalid request/invalid params의 현재 오류 envelope와 메시지 +- Tool Service 매니페스트 pull, Redis/memory fallback, local fixture +- Tool endpoint/timeout/version 진단 정보와 dynamic metadata +- 호출자 header 추출·검증과 Tool Service bypass 정책 (인증·인가는 하지 않음, ADR-0006) +- `guid`·`x-request-id` 전파, 요청 context 정리, HTTP/Tool 경계 로그 +- Tool 선택 금지, exactly-one Tool 실행, outbound routing과 업무 오류 변환 + +## 4. 기존 계약 보존 방법 + +| 위험 | 회피 방식 | +|---|---| +| SDK Starter가 기존 `/mcp`와 충돌 | Starter를 사용하지 않고 core 모델과 Jackson 2 validator만 의존 | +| SDK가 Tool 검증 실패를 `isError=true`로 바꿈 | SDK server handler를 사용하지 않고 검증 실패를 기존 `-32602 Invalid params`로 변환 | +| 기존 required/type 오류 문구 변경 | 공개된 기본 검증을 SDK보다 먼저 실행해 기존 메시지를 그대로 유지 | +| `Mcp-Session-Id`/protocol header 동작 변경 | 기존 filter, controller, validator를 유지 | +| `tools/call` 결과 필드 위치 변경 | 직렬화 계약 테스트로 `content[0]._meta.searchTime`과 `isError`를 고정 | +| local tools/list 공개 필드 누락 | SDK `Tool` 변환 전 `_meta`만 제거하고 title/outputSchema/annotations를 직렬화 비교 | +| Registry의 기존 Tool에 inputSchema 누락 | SDK 필수 조건을 만족하는 빈 object schema로 정규화 | +| dynamic Registry를 annotation Tool로 고정 | `@McpTool`을 사용하지 않고 요청마다 기존 Registry service를 조회 | +| correlation·Trace 기능이 SDK 내부로 사라짐 | transport와 실행 orchestration을 기존 코드에 유지 | +| SDK 업그레이드로 wire payload 변경 | SDK 버전을 명시하고 initialize/list/call golden serialization 테스트를 통과한 경우에만 변경 | + +## 5. JSON Schema 검증 정책 + +SDK 검증은 `ToolExecutionService`가 Registry 기반 argument validation을 수행하는 위치에 연결했다. +검증 순서는 다음과 같다. + +1. 기존 object/required/basic type 검증으로 공개된 오류 문구를 보존한다. +2. SDK JSON Schema validator로 나머지 2020-12 keyword를 검증한다. +3. 실패하면 Tool Service를 호출하지 않고 기존 `JsonRpcException(INVALID_PARAMS)`으로 종료한다. SDK 원문 오류는 + 입력값을 포함할 수 있으므로 외부에는 `arguments do not match inputSchema`만 반환한다. + +SDK validator는 Spring singleton으로 한 번 생성되며 동일 schema의 컴파일 결과를 재사용한다. Registry가 제공하는 +schema 자체의 허용 dialect와 `$ref` 원격 해석 정책은 운영 Registry 계약으로 별도 통제해야 한다. + +## 6. 의도적으로 도입하지 않은 SDK 기능 + +- `spring-ai-starter-mcp-server-webmvc` +- SDK sync/async/stateless server와 transport provider +- SSE 또는 Streamable HTTP 응답 +- SDK authorization/security 구현 +- annotation 기반 정적 `@McpTool` 등록 +- SDK가 소유하는 Tool lifecycle, list-changed notification +- Resources, Prompts, Sampling, Elicitation + +이 기능들은 현재 요구사항을 해결하지 않거나 기존 계약과 중복된다. 실제 필요가 생기면 별도 ADR과 Agent Builder +contract test를 먼저 추가한다. + +## 7. 변경 및 검증 기준 + +SDK 버전을 올릴 때는 다음을 모두 확인한다. + +1. Spring Boot/Java/MCP Java SDK 조합의 dependency resolution +2. SDK `McpSchema` 필드와 Jackson 2 직렬화 변경 여부 +3. initialize, tools/list, tools/call 성공·실패 JSON의 기존 예제 일치 +4. JSON-RPC 오류 code/message/data 및 HTTP status +5. `Accept`에 `text/event-stream`이 있어도 JSON 응답을 유지하는지 +6. `Mcp-Session-Id`, protocol version, `guid`, `x-request-id` 전파 +7. local profile, Registry 장애 fallback, Redis 비필수 동작 +8. `.\gradlew.bat clean test` + +참고: + +- [MCP Java SDK](https://github.com/modelcontextprotocol/java-sdk) +- [Spring AI 2.0 Upgrade Notes](https://docs.spring.io/spring-ai/reference/upgrade-notes.html) +- [Spring AI MCP Server](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html)