Files

koseokmin cb29b192b4 docs를 저장소로 되돌리고 계약 예제를 복원한다

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>

2026-08-22 23:27:56 +09:00

3.6 KiB

Raw Permalink Blame History

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과 ADR-0009을 따른다.

이 계약은 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는 연결 초기화 시 요청 예시를 전송한다. 응답은 응답 예시처럼 jsonrpc, id, result.protocolVersion만 의미 있는 값을 가진다. serverInfo와 capabilities는 빈 객체다.

서버는 protocol version으로 2025-11-25을 반환한다. 현재 MCP-Protocol-Version HTTP 헤더의 수신·검증은 범위 밖이다.

notifications/initialized

초기화 완료 notification의 body는 예시와 같다. 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는 예시처럼 params.name과 object 형식의 params.arguments를 사용한다. version은 Agent Builder가 보내지 않는다. 서버는 Registry에서 같은 name의 활성 version이 정확히 하나일 때만 이를 해소해 실행한다. 두 개 이상이면 임의 version을 선택하지 않고 오류로 처리한다.

성공 응답은 예시처럼 content, 선택적 structuredContent, isError: false를 반환한다. Tool endpoint 실행·timeout·권한 오류는 예시처럼 HTTP/JSON-RPC transport error 대신 result.isError: true로 반환한다. 잘못된 JSON-RPC envelope, 알 수 없는 method, 잘못된 name/arguments는 기존 JSON-RPC error를 사용한다.

호환성 메모

UID execution key 검토안은 ADR-0005에서 폐기되었다. 신규 계약은 표준 MCP name을 실행 식별자로 사용한다.

3.6 KiB Raw Permalink Blame History