Files

Deploy Gateway / deploy (push) Successful in 2m52s

Details

계약 테스트는 docs/contracts 아래 예제를 golden example로 읽는다.
docs/와 README.md가 ignore되어 있어 예제 파일이 사라졌고 9건이
실패하고 있었다. 문서가 온전했던 마지막 상태(3de052a)에서 복원하고
.gitignore에서 두 항목을 제거한다. 에이전트 산출물인
docs/superpowers/ 제외는 유지한다.

initialize 응답의 capabilities.tools.listChanged를 문서는 true로
적고 있었으나 InitializeHandler는 false를 낸다. 현재 HTTP 단발 응답
transport가 notification을 push할 수 없으므로 false가 맞다. 예제와
architecture.md를 코드에 맞추고, ToolListChangedEvent가 발행되지만
아직 소비되지 않는다는 점과 SSE 도입 시 true로 바꾼다는 조건을
남긴다.

169개 테스트 전부 통과.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-15 17:16:13 +09:00

3.6 KiB

Raw 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 Blame History