mcp-resource-subscribe-test

MCP 클라이언트가 resources/subscribe 및 notifications/resources/updated를 올바르게 처리하는지 테스트하기 위한 최소한의 MCP 스트리밍 HTTP 서버입니다.

이 저장소는 Codex CLI, Gemini CLI, OpenCode, GitHub Copilot CLI, Claude Code, Goose, Crush와 같은 CLI AI 에이전트를 위한 재현 가능한 문제/호환성 테스트 환경을 제공합니다.

목적

이 서버는 하나의 고정된 MCP 리소스를 노출합니다:

test://review/status

초기 콘텐츠:

status: pending
version: 1
message: Waiting for simulated review result.

클라이언트가 리소스를 구독하면 서버는 MCP_TEST_UPDATE_DELAY_SECONDS만큼 대기한 후 리소스를 변경하고 다음을 전송합니다:

{
  "method": "notifications/resources/updated",
  "params": {
    "uri": "test://review/status"
  }
}

업데이트된 콘텐츠:

status: reviewed
version: 2
message: Simulated review result is now available.

Related MCP server: mcp-hello-world

도구 호출(Tools/Call) 대신 리소스/구독(Resources/Subscribe)을 사용하는 이유

tools/call은 명시적인 작업에는 유용하지만, 많은 에이전트 워크플로우는 원래 요청 이후 변경되는 컨텍스트에 의존합니다. 모든 소스를 폴링하는 것은 노이즈가 많고 클라이언트별로 다릅니다. MCP 리소스 구독은 알려진 컨텍스트 객체가 변경되어 다시 읽어야 함을 클라이언트가 프로토콜 수준에서 알 수 있는 방법을 제공합니다.

구독 동작이 중요한 예시:

• Copilot 검토 결과

• PR 검토 스레드

• CI 상태

• Codecov 댓글

• GitHub 이슈 토론

• 로컬 빌드/테스트 결과

이 테스트 서버는 클라이언트가 리소스 업데이트를 감지하고, resources/read를 다시 실행하며, 에이전트 루프/모델 컨텍스트에 새로운 콘텐츠를 반영하는지에 초점을 맞춥니다.

시작하기

docker compose up --build

MCP URL:

http://127.0.0.1:8089/mcp

로컬 개발:

npm install
npm run dev

구성

MCP_TEST_SEND_LIST_CHANGED=true인 경우, 서버는 시뮬레이션된 업데이트 후 notifications/resources/list_changed도 전송합니다.

예상되는 클라이언트 동작

이상적인 MCP 클라이언트는 다음 흐름을 따라야 합니다:

initialize
  ↓
resources/list
  ↓
resources/read test://review/status
  ↓
resources/subscribe test://review/status
  ↓
receive notifications/resources/updated
  ↓
resources/read test://review/status again
  ↓
reflect updated status: reviewed in agent context

서버 기능

초기화 응답은 다음을 알립니다:

{
  "resources": {
    "subscribe": true,
    "listChanged": true
  }
}

구현된 MCP 메시지

• initialize

• resources/list

• resources/read

• resources/subscribe

• resources/unsubscribe

• notifications/resources/updated

• MCP_TEST_SEND_LIST_CHANGED=true일 때 notifications/resources/list_changed

도구(Tools)는 구현되지 않았습니다.

로그

서버는 클라이언트 동작을 객관적으로 확인할 수 있도록 각 중요한 메시지를 기록합니다:

[initialize] client connected
[resources/list] requested
[resources/read] uri=test://review/status version=1
[resources/subscribe] uri=test://review/status
[resource/update] uri=test://review/status version=2
[notification/send] notifications/resources/updated uri=test://review/status
[resources/read] uri=test://review/status version=2
[resources/unsubscribe] uri=test://review/status

리소스 구독 지원에 대한 핵심 증거는 다음과 같습니다:

resources/subscribe was received
notification was sent
resources/read was received again after the notification

테스트

npm test

테스트 스위트는 다음을 검증합니다:

• resources/list가 test://review/status를 반환함

• 초기 resources/read가 버전 1을 반환함

• resources/subscribe가 버전 2로의 내부 업데이트를 트리거함

• notifications/resources/updated가 수신됨

• 업데이트된 resources/read가 버전 2를 반환함

클라이언트 호환성 참고 사항

Codex CLI

• MCP 연결:

• resources/list를 호출합니까?

• resources/read를 호출합니까?

• resources/subscribe를 호출합니까?

• notifications/resources/updated를 수신합니까?

• 업데이트 후 리소스를 다시 읽습니까?

• 참고:

Gemini CLI

• MCP 연결:

• resources/list를 호출합니까?

• resources/read를 호출합니까?

• resources/subscribe를 호출합니까?

• notifications/resources/updated를 수신합니까?

• 업데이트 후 리소스를 다시 읽습니까?

• 참고:

OpenCode

• MCP 연결:

• resources/list를 호출합니까?

• resources/read를 호출합니까?

• resources/subscribe를 호출합니까?

• notifications/resources/updated를 수신합니까?

• 업데이트 후 리소스를 다시 읽습니까?

• 참고:

GitHub Copilot CLI

• MCP 연결:

• resources/list를 호출합니까?

• resources/read를 호출합니까?

• resources/subscribe를 호출합니까?

• notifications/resources/updated를 수신합니까?

• 업데이트 후 리소스를 다시 읽습니까?

• 참고:

Claude Code

• MCP 연결:

• resources/list를 호출합니까?

• resources/read를 호출합니까?

• resources/subscribe를 호출합니까?

• notifications/resources/updated를 수신합니까?

• 업데이트 후 리소스를 다시 읽습니까?

• 참고:

Goose

• MCP 연결:

• resources/list를 호출합니까?

• resources/read를 호출합니까?

• resources/subscribe를 호출합니까?

• notifications/resources/updated를 수신합니까?

• 업데이트 후 리소스를 다시 읽습니까?

• 참고:

Crush

• MCP 연결:

• resources/list를 호출합니까?

• resources/read를 호출합니까?

• resources/subscribe를 호출합니까?

• notifications/resources/updated를 수신합니까?

• 업데이트 후 리소스를 다시 읽습니까?

• 참고: