🛡️ MCPResilience

공식 SDK v2 기반의 탄력적이고 스펙을 준수하는 MCP 서버

클라이언트가 말하는 방식대로 MCP를 구사하세요. MCPResilience는 첫 번째 요청에서 레거시 및 모던 프로토콜 시대를 자동 감지합니다 — 그리고 그 차이를 견뎌냅니다.

🔌 클라이언트 모드

MCPResilience는 연결하는 클라이언트가 어떤 프로토콜 시대를 사용하는지 자동 감지합니다 — 구성이 필요 없습니다:

1. ⚡ 모던 무상태(Stateless) 클라이언트 — 첫 요청에 _meta 봉투(io.modelcontextprotocol/protocolVersion + clientInfo)를 담아 보내는 클라이언트는 핸드셰이크를 완전히 건너뜁니다. tools/call이 첫 번째 메시지가 될 수 있습니다.

2. 🤝 레거시 핸드셰이크 클라이언트 — 해당 봉투가 없는 클라이언트는 기존 initialize 흐름을 거치며, initialize가 완료되기 전에 전송되는 모든 요청에 대해 -32600 Invalid request parameters가 적용됩니다.

두 시대의 전체 분류는 프로토콜 지원을 참조하세요.

Related MCP server: mcp-uni

🧠 이 프로젝트의 목적

MCPResilience는 수제 MCP 서버를 공식 SDK로 교체하는 것이 단순한 드롭인 변경이 아니기 때문에 존재합니다 — 와이어 포맷이 순진한 마이그레이션을 깨뜨리는 방식으로 변화합니다. 이 프로젝트는 두 단계로 이 문제를 해결합니다:

1. SDK 마이그레이션 — 수제 MCP 서버 코어를 공식 MCP SDK v2로 교체하고, 2026-07-28 스펙을 대상으로 하여 무상태 코어와 타입 안전한 Pydantic 직렬화를 확보합니다.

2. 호환성 강화 — 마이그레이션이 레거시 핸드셰이크를 사용하는 클라이언트에 대한 지원을 조용히 놓치지 않도록 하고, 업스트림 스키마 격차로 인한 데이터 손실이 없도록 하며, 실험적 Tasks 확장이 진행 중에 깨지지 않도록 합니다.

두 단계 모두 아래에 솔직하게 문서화되어 있으며, 그 과정에서 발견된 업스트림 SDK 버그 하나도 포함됩니다.

📊 주요 결과

모든 Phase 5 호환성 테스트와 Phase 6 벤치마크가 공식 MCP SDK v2에서 엔드투엔드로 통과합니다 — 두 프로토콜 시대와 실험적 Tasks 확장에 대한 완전한 지원, 그리고 식별되어 패치된 업스트림 SDK 버그 하나가 포함됩니다 (알려진 SDK 특이사항 참조).

Tasks 확장: SDK 마이그레이션으로 변경된 사항

🏗️ 작동 방식

Incoming connection
        │
        ▼
  First request received
        │
        ▼
  Does it carry the _meta envelope?
  (protocolVersion + clientInfo)
        │
   ┌────┴────┐
  Yes         No
   │           │
   ▼           ▼
Modern Era   Legacy Era
(stateless)  (handshake required)
   │           │
   ▼           ▼
tools/call   initialize → any request
runs          (initialize enforced,
immediately    notifications/initialized
               not blocked)
   │           │
   └─────┬─────┘
         ▼
  Era locked for the
  life of the connection

📡 프로토콜 지원

무상태 시대 (2026-07-28)

모던 스펙에서 기존의 initialize → notifications/initialized 핸드셰이크는 더 이상 사용되지 않습니다. 서버는 serve_dual_era_loop를 실행합니다:

• 첫 번째 요청에 io.modelcontextprotocol/protocolVersion 및 io.modelcontextprotocol/clientInfo가 포함된 _meta 봉투가 있으면 서버는 모던 무상태 시대로 고정됩니다.

• 클라이언트는 tools/call을 첫 번째 요청으로 보낼 수 있습니다 — initialize 호출이 필요 없습니다.

레거시 시대

첫 번째 요청에 모던 _meta 봉투가 없으면 서버는 레거시 시대로 고정됩니다:

• initialize 이전에 전송된 모든 요청(예: tools/call)은 -32600 Invalid request parameters로 거부됩니다.

• initialize가 응답된 후에는 서버가 추가 요청을 처리하기 전에 notifications/initialized를 기다리지 않습니다.

버전 불일치 처리

_meta 봉투에서 지원되지 않는 프로토콜 버전을 지정하는 모던 요청은 -32022 Unsupported protocol version으로 깔끔하게 거부됩니다 — 연결 자체는 끊기지 않고 유지됩니다.

🧩 Tasks 확장 심층 분석

실험적 Tasks 확장은 마이그레이션에서 가장 많은 와이어 포맷 변화를 겪었습니다 (주요 결과의 비교 표 참조). 특히 주목할 만한 두 가지 동작이 있습니다:

• tasks/get는 이제 메타데이터 전용입니다. 작업 콘텐츠는 tools/call 응답 스트림을 통해서만 전달됩니다. tasks/get을 폴링하면 statusMessage 및 createdAt 같은 상태 필드만 반환됩니다 — 페이로드 자체는 절대 반환되지 않습니다.

• 취소는 설계상 멱등적입니다. 이미 completed 또는 cancelled된 작업을 재취소하면 레거시 서버의 반복 취소 시 -32602 오류와 달리 성공적인 CancelTaskResult를 반환합니다.

알려진 SDK 특이사항

SDK 이슈 #2156 — execution 필드가 tools/list에서 제거됨. 현재 v2026_07_28.Tool에 대한 Pydantic 스키마는 실험적 execution 필드를 정의하지 않으므로, serialize_server_result가 tools/list 응답에서 이를 조용히 제거합니다.

해결 방법: mcp_types.methods.serialize_server_result에 대한 타겟형 monkeypatch가 검증된 출력을 가로채 원래 핸들러 데이터에서 execution 사전을 복원합니다. 이는 임시 방편입니다 — 업스트림 스키마가 해당 필드를 기본적으로 제공하면 제거하세요.

🔧 기술 노트 (사소하지 않았던 부분들)

1. 시대 감지는 첫 번째 요청에서 정확히 한 번 발생합니다. 연결 중간에 업그레이드 경로는 없습니다 — _meta 봉투 없이 연결을 연 클라이언트는 나중에 모던 형태의 요청을 보내기 시작하더라도 해당 연결의 수명 동안 레거시 시대에 머무릅니다.

2. 작업 핸들은 이동했을 뿐만 아니라 그 계약도 변경되었습니다. taskHandle을 최상위 result에서 result._meta로 옮긴 것은 최상위 result 객체를 즉각적인 콘텐츠 출력과 isError 플래그 전용으로 예약할 수 있게 했습니다 — 레거시 형태가 허용했던 것보다 더 깔끔한 분리입니다.

3. monkeypatch는 의도적으로 좁게 범위가 지정됩니다. SDK의 스키마를 전체적으로 포크하거나 래핑하는 대신 누락된 필드 하나를 복원하기 위해 serialize_server_result만 가로챕니다 — 업스트림이 수정을 제공하는 즉시 삭제하기 쉽게 유지합니다.

🛠️ 기술 스택

• 프로토콜: Model Context Protocol 기반 JSON-RPC 2.0, 스펙 2026-07-28

• SDK: 공식 MCP SDK v2 — Pydantic 기반 스키마 검증 및 직렬화

• 서버 코어: Python, 무상태 우선 요청 처리 (serve_dual_era_loop)

• 테스트: Phase 5 호환성 스위트 + Phase 6 벤치마크 실행

🚀 시작하기

git clone https://github.com/HoorShumail/MCPResilience.git
cd MCPResilience
pip install -r requirements.txt

위 명령어를 실제 패키지 구조와 진입점에 맞게 조정하세요.

호환성 스위트와 벤치마크를 실행하려면:

pytest

⚠️ 솔직한 한계

• Tasks 확장은 여전히 업스트림에서 실험적입니다. 핵심 MCP 스펙에서 확정되지 않았으므로 와이어 포맷이 향후 SDK 릴리스에서 다시 변경될 수 있습니다 — 이 서버는 안정적인 대상을 추적하는 것이 아니라 SDK의 현재 실험적 구현을 추적합니다.

• execution 필드 수정은 monkeypatch이지 영구적인 해결책이 아닙니다. 기본 스키마를 수정하는 대신 런타임에 serialize_server_result를 패치합니다 — SDK 이슈 #2156이 업스트림 수정을 제공하면 제거해야 합니다.

• 시대 감지는 첫 요청 전용입니다. 연결 시작 시 레거시 시대에 고정된 클라이언트는 나중에 요청이 모던해 보이더라도 연결 중간에 무상태 시대로 "업그레이드"할 경로가 없습니다.

🙏 감사의 말

• 공식 MCP SDK v2 — Model Context Protocol 유지관리자

• Model Context Protocol 스펙 (2026-07-28)

🧑💻 저자

Hoor Shumail AI | 머신러닝 | 에이전틱 AI | 멀티 에이전트 시스템 | 커리어 인텔리전스

• GitHub: https://github.com/HoorShumail

• LinkedIn: https://www.linkedin.com/in/hoor-shumail-a3a076326/

📜 라이선스

이 프로젝트는 교육, 연구 및 포트폴리오 목적으로 개발되었습니다.

공식 Model Context Protocol SDK를 기반으로 구축되었습니다 — 해당 구성 요소에 적용되는 조건은 해당 SDK의 자체 라이선스와 Model Context Protocol 스펙을 참조하세요.