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>
3.6 KiB
3.6 KiB
ADR-0008 공유 host의 path를 독립 MCP 배포로 연결한다
이 문서는 검토 이력을 보존한다. 결정 3의 "공개 path를 내부 고정 endpoint
/mcp로 rewrite한다"는 ADR-0009이 대체했고, 결정 4의 1:1 매핑은 ADR-0013이 대체했다.
배경
Agent Builder에는 하나의 HTTPS host를 제공하고 업무별 MCP를 /mcp/core, /mcp/process,
/mcp/information 같은 path로 구분해야 한다. 이를 하나의 애플리케이션 프로세스에서 처리하면
Registry snapshot·Redis cache·readiness·connection 자원을 route별로 다시 나눠야 하고, 한 프로세스의
장애와 배포가 모든 Tool Service에 전파된다.
결정
- 환경마다 공개 MCP host를 하나 둔다.
deployments.<key>.publicPath는 한 MCP Deployment를 가리키며 topology 전체에서 유일하다.- OpenShift Route가 공개 path를 해당 MCP Service로 전달하고 내부 고정 endpoint
/mcp로 rewrite한다. - MCP 애플리케이션과 Tool Service의 1:1 매핑, Registry snapshot, Redis key와 readiness는 배포별로 유지한다.
- Agent Builder는 각 공개 URL을 독립 MCP endpoint로 등록하고 endpoint별로 initialize한다.
- 요청 body·header·Tool 이름은 어느 MCP Service로 보낼지 결정하지 못한다. 대상은 Helm topology만 정한다.
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 검증 계층이 중복되므로 채택하지 않았다.