koseokmin
d64516b50a
MCP Java SDK 도입으로 들어온 json-schema-validator는 schema의 $ref가 문서
밖을 가리키면 그 주소로 직접 조회하고, pattern 검증을 백트래킹 기반
java.util.regex로 처리한다. inputSchema는 Tool Service 매니페스트에서 오므로
매니페스트가 서버의 outbound 대상과 CPU 소비를 정할 수 있었다. AGENTS.md의
"outbound 주소는 설정에서만 온다"는 불변식이 이 경로에서 뚫려 있었다.
DefaultJsonSchemaValidator는 SchemaRegistry를 생성자 안에서 만들고 private
final로 들고 있어 정책 주입 지점이 없다. 따라서 SDK 밖에서만 막을 수 있다.
검사는 ToolMetadata의 표준 생성자에 둔다. Portal 매니페스트, local 파일,
Redis snapshot 역직렬화가 모두 이 생성자를 지나므로 우회 경로가 생기지 않는다.
위반은 기존 매니페스트 형식 오류와 같게 다뤄 bundle 단위 실패 격리와
"Redis 실패는 언제나 cache miss" 동작을 그대로 유지한다.
정규식 규칙은 JDK 21.0.11 실측으로 정했다. 통념과 달리 (a+)+는 빠르게 끝나고,
중첩이 아닌 a*a*a*a*a*b와 바깥 반복이 유한한 (.*,){11}P가 폭증했다. 겹치는
문자 집합 판정은 결정 불가능하므로 모양 검사만으로는 부족하고, pattern 필드에
maxLength 동반 선언을 요구해 입력 길이를 묶는 것이 실질적인 상한이 된다.
patternProperties는 key에 길이를 선언할 자리가 없어 사용을 금지한다.
format은 단언되지 않아 format:regex 경로가 실행되지 않는다는 사실도 계약
테스트로 고정했다. SDK 업그레이드로 단언이 켜지면 테스트가 실패한다.
Tool Service는 pattern을 쓰는 필드에 maxLength(<=256)를 선언해야 하므로
매니페스트 수용 조건이 바뀐다. Tool Service 파트와 합의가 필요하다.
근거: ADR-0011, ADR-0012
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Tool Service-MCP 계약 문서
이 디렉터리는 Tool Service와 MCP Server 사이의 metadata 조회·실행 계약을 관리한다.
Agent Builder ──[agent-builder-mcp 계약]──▶ MCP Server ──[tool-service-mcp 계약]──▶ Tool Service
| 문서 | 상태 | 용도 |
|---|---|---|
| protocol-v0.2-bundle-discovery.md | Implemented | Tool Service Bundle의 매니페스트 조회·실행 계약. 구현은 N개 Bundle을 지원하지만 운영 배포는 1개로 고정 |
| TEMP-tool-list-loading-guide.md | Temporary | Tool 개발 파트가 현재 최초 적재·memory snapshot·tools/list 변환 흐름을 이해하기 위한 안내 |
push 등록 방식(v0.1)은 채택하지 않았다. 그 이유는 v0.2 §2에 있다.
현재 원칙
- 운영 Tool metadata의 유일한 원천은 각 Tool Service의 매니페스트다.
localprofile은 Tool Service 매니페스트를 먼저 조회하고, 최초 실패 시config/local-core-tools-manifest-sample-v1.jsonfallback을 사용한다.- 표준 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의 매니페스트, MCP 설정, Actuator 상태 응답을 계약 테스트가 직접 읽는다. 예제와 구현은 같은 변경에서 함께 수정한다.
운영 적용 전에 Tool 개발 파트와 다음 항목을 확정한다.
- MCP → Tool 방향 NetworkPolicy와 매니페스트 인증 방식
- Tool name 변경·폐기 시 rolling 호환 기간
namePrefix, Tool 수, 매니페스트 크기 상한- Tool Service별 timeout과 권한 scope
상세 필드와 장애 처리는 v0.2 계약을 따른다.