유닛 테스트는 통과하는데, Claude에 연결하면 망가진다

MCP (Model Context Protocol) 서버를 작성해 본 사람이라면, 누구나 한 번쯤 이런 경험을 했을 것입니다.

• vitest / pytest는 모두 그린 (Green)
• 그런데 Claude나 Cursor에 연결하면, 도구(tool)를 호출할 수 없거나, 목록에 나타나지 않거나, 연결이 끊김

원인은 대개 다음 중 하나입니다.

• stdout 오염: stdio 트랜스포트(transport)에서 stdout은 프로토콜 전용입니다. console.log를 통한 디버그 출력 한 줄만으로도 JSON-RPC가 깨집니다.
• 도구 스키마(tool schema) 부정확: inputSchema가 object 타입이 아니거나, required 정의가 누락됨.
• capability 선언 누락: tools/resources/prompts를 구현했음에도 선언하지 않음.
• 에러 처리: 필수 인자(argument) 누락 시 graceful하게 실패하지 않고 크래시(crash)가 발생함.

이러한 문제들은 언어 레벨의 유닛 테스트(unit test)로는 검출할 수 없습니다. 망가진 것은 로직이 아니라 '프로토콜과의 경계'이기 때문입니다. 공개된 MCP 서버는 2만 개가 넘는다고 알려져 있지만, 이 경계를 검증할 표준적인 수단이 없었습니다.

mcp-testbench: 프로토콜 레벨의 테스트 러너

그래서 만든 것이 mcp-testbench입니다. 진정한 MCP 클라이언트로서 서버에 접속하여, 프로토콜 그 자체를 검증합니다. 서버의 구현 언어는 상관없습니다 (TypeScript / Python / Go / Rust 무엇이든 OK).

# 설치 불필요. stdio 서버를 지정하기만 하면 됩니다
npx mcp-testbench run --server "npx -y @modelcontextprotocol/server-everything"

이것만으로 10개의 내장 적합성 체크 (C000~C040)가 실행됩니다. 핸드셰이크(handshake) 완료, 서버 이름/버전 공개, capability 선언, tools/list의 타당성, 모든 도구의 설명과 JSON Schema, 필수 인자 누락 시의 graceful한 실패 등이 포함됩니다.

자신의 도구 테스트는 YAML로 작성

# mcptest.config.yaml
server:
command: "node dist/index.js" # 또는 url: "http://localhost:3000/mcp"
...

대응하는 기대값은 ok / error / result.contains / result.matches (정규 표현식) / result.equals / maxDurationMs 입니다. 테스트 코드를 작성할 필요 없이, YAML만으로 완결됩니다.

CI에는 4줄이면 충분

GitHub Action이 포함되어 있어, 임의의 MCP 서버 리포지토리에 4줄로 도입할 수 있습니다.

- uses: kero168/mcp-testbench@main
with:
server: "node dist/index.js"

실패 시에는 GitHub Actions의 어노테이션(annotation)으로 각 PR에 표시되며, exit code 1로 파이프라인을 중단시킵니다. GitLab 등에는 --reporter json을 사용하세요.

로드맵 및 모집

• mcp-testbench audit — 도구 설명의 lint, 선언과 실제 동작의 괴리 검사 (보안용)
• 스냅샷 테스트 (snapshot test) / 커버리지 리포트 (coverage report) / JUnit 리포터 (reporter)

good first issue를 준비해 두었습니다. MCP 서버를 작성하고 계신 분이라면, 꼭 한 번 npx mcp-testbench run을 자신의 서버를 향해 쏴보시기 바랍니다. 어떻게 망가지는지 흥미롭다면 (흥미롭지 않더라도) Issue로 알려주시면 기쁘겠습니다.

Discussion