mcp-tester

*/list_changed 알림 및 기타 프로토콜 기능에 대한 클라이언트 준수 여부를 테스트하기 위한 계측된 MCP 서버입니다.

목적

PR mcaps-microsoft/msx-mcp#321은 notifications/tools/list_changed를 통한 동적 도구 노출을 제안했습니다. 해당 PR은 "Copilot CLI가 세션 시작 시 tools/list를 캐싱하고 notifications/tools/list_changed를 무시한다"는 주장과 함께 닫혔지만, 이를 입증하거나 반박하기 위한 계측된 실험은 수행된 적이 없습니다.

이 저장소는 해당 주장을 테스트하고, 모든 MCP 클라이언트의 list_changed 준수 여부를 실제 증거를 통해 확인할 수 있는 장치를 제공합니다.

기능

1. Probe MCP 서버 (src/server.ts) -- stdio 파이프의 모든 JSON-RPC 메시지를 기록하는 자체 계측 MCP 서버입니다. 알파 상태의 도구, 리소스 및 프롬프트를 노출하며, 이를 베타 상태로 교체하고 해당 */list_changed 알림을 전송하는 트리거 도구를 포함합니다.

2. 자동화된 클라이언트 드라이버 (src/driver.ts) -- 전체 변이 주기를 통해 서버를 구동하는 SDK 기반 MCP Client입니다. 이것은 제어(control) 역할을 합니다. 즉, 양쪽 엔드포인트가 사양을 준수할 때 프로토콜이 작동함을 증명합니다. 이 동작에서 벗어나는 클라이언트는 준수하지 않는 것으로 간주됩니다.

3. 로그 분석기 (src/analyze.ts) -- JSONL 로그를 읽고 특정 질문에 답하는 마크다운 증거 표를 생성합니다: 클라이언트가 알림을 받았는가? 다시 가져왔는가(re-fetch)? 새 항목을 호출할 수 있는가? 제거된 항목을 여전히 호출할 수 있는가?

4. 인간 프로토콜 (PROTOCOL.md) -- Copilot CLI 또는 기타 MCP 클라이언트에 대해 동일한 테스트를 실행하기 위한 단계별 지침입니다.

빠른 시작

git clone https://github.com/ericchansen/mcp-tester.git
cd mcp-tester
npm install
npm run build

자동화된 제어(SDK 클라이언트) 실행

npm run driver -- --domain all

이 명령은 프로브 서버를 생성하고, 도구, 리소스 및 프롬프트에 대한 전체 변이 프로토콜을 실행하며, 결과를 보고합니다. 세 가지 도메인 모두 완전한 준수 상태로 통과하는 것을 확인할 수 있습니다.

로그 분석

npm run analyze -- path/to/log.jsonl --domain tools

자체 MCP 클라이언트 테스트

Copilot CLI 또는 기타 MCP 클라이언트를 이 프로브에 대해 테스트하는 단계별 지침은 PROTOCOL.md를 참조하십시오.

저장소 구조

mcp-tester/
|-- README.md          # This file
|-- PROTOCOL.md        # Human-driven test procedure
|-- LICENSE            # MIT
|-- package.json
|-- tsconfig.json
|-- src/
|   |-- server.ts      # Probe MCP server (stdio)
|   |-- logger.ts      # JSONL stdio tap + log writer
|   |-- analyze.ts     # CLI: parses log -> markdown evidence table
|   +-- driver.ts      # CLI: spawns server, drives it via SDK Client
+-- results/
    +-- copilot-cli/
        +-- .gitkeep   # Committed experiment results go here

프로브 작동 방식

초기 상태 (알파)

추가로 5개의 영구 도구: mcptester_mutate_tools, mcptester_mutate_resources, mcptester_mutate_prompts, mcptester_status.

변이 후 (베타)

mcptester_mutate_* 도구가 호출되면:

1. 알파 항목이 제거됩니다 (SDK handle.remove() 사용).

2. 베타 항목이 등록됩니다.

3. SDK가 자동으로 해당 notifications/*/list_changed를 전송합니다.

4. debouncedNotificationMethods가 제거 및 등록을 단일 알림으로 병합합니다.

로깅

모든 JSON-RPC 메시지(인바운드 및 아웃바운드)는 JSONL 파일에 기록됩니다. 로거는 SDK 전송 이전에 설치된 Transform 스트림을 통해 process.stdin 및 process.stdout을 가로채므로, 프로토콜을 방해하지 않고 모든 바이트를 확인합니다.

제한 사항

• stdio 전송만 지원 -- 아직 HTTP/SSE 테스트는 지원하지 않음

• 세 가지 list_changed 흐름만 지원 -- 향후 샘플링, 도출, 루트, 진행률, 완료에 대한 테스트 계획됨

• 단일 서버 테스트 -- 한 번에 하나의 MCP 서버 연결만 테스트함

라이선스

MIT