koseokmin
cb29b192b4
5cfb8a1이 .gitignore에 docs/를 넣고 68개 파일을 지웠다. 그런데
AgentBuilderContractExampleTest, ToolBundleContractExampleTest,
ArchitectureDocumentContractTest는 docs/ 아래 계약 예제와 architecture
문서를 입력으로 직접 읽는다. 그 결과 clean clone에서 테스트 10건이
입력을 찾지 못해 실패했다.
제외 범위를 원래 의도대로 좁힌다. 에이전트 산출물(AGENTS.md, .agents/,
.codex/, docs/superpowers/)은 계속 제외하고 저장소 문서는 추적한다.
문서는 삭제 직전 상태(3de052a)를 기준으로 복원하고, 그 위에 main 코드와
대조해 어긋난 부분을 고쳤다.
- ADR-0007을 Superseded로 바꾸고 ADR-0013을 새로 쓴다. route당 Tool
Service N개가 최종안이며, PortalToolRegistryClient가 이미 route별로
N개를 유지하고 있는데 ADR-0007은 "bundles는 항상 한 항목"을 Accepted
상태로 주장하고 있었다. ADR-0009 결정 4도 부분 대체한다.
- ADR-0008 파일 헤더가 Accepted였으나 ADR-0009가 이미 대체한 상태였다.
- 6078852의 endpoint 소유권 반전이 반영되지 않은 서술을 계약 v0.2,
bundle 설정 예제, Tool 적재 안내에서 고친다.
- Portal registry 계약 v0.1과 route key 규약을 새로 문서화한다. 둘 다
구현은 있는데 계약 문서가 없었다.
- MCP SDK 2.0.0 SBOM을 추가한다.
번호 주석: ADR-0011과 0012는 feature/mcp-integration이 Tool inputSchema
정책에 쓰고 있어 비워 둔다.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2.7 KiB
2.7 KiB
ADR-0009 컨테이너가 공개 MCP path를 직접 처리한다
결정 1·2·3·5는 유효하다. 공개 path를 rewrite하지 않고 컨테이너가 직접 처리한다는 원칙은 그대로다. 결정 4의 "MCP 컨테이너 하나는 endpoint와 Tool Service를 각각 하나만 가진다"만 ADR-0013이 대체하며, 지금은
/mcp+ 동적 route key로 한 컨테이너가 N개 route와 route당 N개 Tool Service를 처리한다.
배경
Agent Builder는 /mcp/core, /mcp/process, /mcp/information처럼 sub path까지 포함한 URL을 각각의 MCP로 등록한다. 각 URL은 독립 MCP 컨테이너와 Tool Service에 연결된다. 공개 path를 OpenShift Route가 내부 /mcp로 바꾸면 Agent Builder가 등록한 경로와 컨테이너가 처리한 경로가 달라져 운영 추적과 설정 검증이 어려워진다.
결정
deployments.<key>.publicPath는 Agent Builder 등록 URL과 컨테이너 endpoint가 함께 사용하는 단일 정본이다.- OpenShift Route는 host와 path로 독립 MCP Service만 선택하고 path를 rewrite하지 않는다.
- Helm ConfigMap이
publicPath를mcp.endpoint-path로 주입하고, Controller와 Filter가 그 경로만 처리한다. - MCP 컨테이너 하나는 endpoint와 Tool Service를 각각 하나만 가진다. 하나의 Java 프로세스에서 path별 Registry를 선택하지 않는다.
- 요청 body·header·Tool name은 컨테이너 선택에 관여하지 않는다.
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이 대체한다.