MCP Failure Lab

Model Context Protocol 서버를 위한 카오스 엔지니어링 및 복원력 테스트 툴킷입니다.

문서 · 프로젝트 페이지

빠른 시작

리포지토리를 클론하거나 패키지를 전역으로 설치하지 않고도 실제 결정적 지연 시나리오를 실행할 수 있습니다:

npx mcp-failure-lab demo

출력 예시:

MCP Failure Lab — Demo
Running a real 500ms delay scenario...

Scenario: Deterministic delay demo
Outcome: success
Duration: ~500 ms
Assertions: passed

정확한 지속 시간은 실행마다 약간 다를 수 있습니다. API 키나 외부 MCP 서버가 필요하지 않습니다.

사용 가능한 명령 표시:

npx mcp-failure-lab --help

stdio를 통해 내장 MCP 서버 시작:

npx mcp-failure-lab serve

Related MCP server: mcp-chaos-rig

목적

MCP Failure Lab은 서버 작성자가 지연, 중단(hanging) 도구, 취소, 전송 손실을 결정적으로 재현할 수 있도록 도와줍니다.

타임아웃 처리, 취소 정리, 전송 손실 복구, 어서션, CI 결과를 테스트하기 위한 제어된 실패 동작을 제공합니다.

현재 범위

MCP Failure Lab은 명령줄에서 자체 내장 MCP 서버에 대해 결정적 JSON 시나리오를 실행합니다.

현재 사용 가능한 기능:

• ping, delay, hang, disconnect 도구

• stdio를 통한 MCP 통신

• 코드 우선 및 JSON 시나리오 정의

• 결과 및 최대 지속 시간 어서션

• MCP 결과 어서션

• 사후 조건 검증을 위한 순차적 옵저버 호출

• 콘솔 및 JSON 보고

• 기계 판독 가능한 명령 오류

• CI 친화적인 종료 코드

• 단위, 통합, 엔드투엔드 테스트

구현되지 않은 기능:

• 외부 MCP 클라이언트 오케스트레이션

• 대상 클라이언트 어댑터

• Streamable HTTP

• JUnit 보고

• 잘못된 메시지, 중복 응답, 세션 손실 결함

MCP Failure Lab은 현재 범용 프록시나 외부 MCP 클라이언트 테스트 오케스트레이터가 아닙니다.

작동 방식

MCP Failure Lab은 내장 MCP 클라이언트와 서버를 통해 결정적 시나리오를 실행합니다. 시나리오는 ping, delay, hang, disconnect를 호출하고 관찰된 결과와 지속 시간을 기록한 다음 선언된 기대치를 평가합니다.

선택적 옵저버 호출은 동일한 MCP 클라이언트 연결에서 순차적으로 실행되어 별도의 도구 경로를 통해 사후 조건을 검증합니다.

다이어그램, 책임, 구현 경계는 아키텍처 문서를 참조하세요.

문서

전체 가이드와 참조 자료는 mcplab.dev/docs에서 확인할 수 있습니다.

• 시작하기

• 시나리오

• 결함 도구

• CLI 참조

• 보고

• 아키텍처

• 예제

• 문제 해결

요구 사항

• Node.js 22.19.0 이상

• npm

프로토콜 호환성

MCP Failure Lab은 기본적으로 MCP 2026-07-28을 대상으로 합니다. CLI 서버는 SDK v2 시대 인식 stdio 진입점을 사용하며, 내장 시나리오 클라이언트는 2026-07-28을 고정하여 최신 동작이 명시적으로 실행되도록 합니다.

서버는 호환성을 위해 2025-11-25 초기화 흐름도 수용합니다. 해당 레거시 경로는 통합 테스트로 계속 다루어지지만, 새로운 개발은 2026-07-28을 대상으로 합니다. 기존 ping, delay, hang, disconnect 결함 도구는 두 시대에서 동일한 사용자 대면 동작을 제공합니다. 서버 시작 요청에 의존하는 프로토콜 기능은 시대에 따라 다르며 이러한 결함 도구의 범위를 벗어납니다.

설치

npx로 패키지를 직접 실행:

npx mcp-failure-lab demo

전역 설치가 필요하지 않습니다.

명령을 전역으로 설치하려면:

npm install -g mcp-failure-lab

CLI

# Run the built-in demonstration
npx mcp-failure-lab demo

# Display command help
npx mcp-failure-lab --help

# Display the installed version
npx mcp-failure-lab --version

# Start the MCP server over stdio
npx mcp-failure-lab serve

serve 프로세스는 MCP 클라이언트를 기다립니다. Ctrl+C를 눌러 정상적으로 종료하세요.

시나리오 실행

시나리오 파일은 JSON을 사용합니다:

{
  "name": "bounded delay succeeds",
  "call": {
    "tool": "delay",
    "args": {
      "delayMs": 250
    }
  },
  "timeoutMs": 1000,
  "expect": {
    "outcome": "success",
    "maxDurationMs": 500
  }
}

리포지토리 체크아웃에서 포함된 시나리오를 실행:

npm run dev -- run examples/scenarios/delay-success.json

기계 판독 가능한 출력 생성:

npm run dev -- run examples/scenarios/delay-success.json --report json

명령은 다음 코드로 종료됩니다:

결과 어서션, 옵저버 호출, 보고 형식, 타임아웃 동작에 대한 자세한 내용은 시나리오 및 보고 문서를 참조하세요.

결함 도구

인수와 동작에 대한 자세한 내용은 결함 도구 참조를 참조하세요.

서버 검사

게시된 패키지에 대해 MCP Inspector 실행:

npx @modelcontextprotocol/inspector npx mcp-failure-lab serve

stdio로 연결하고 사용 가능한 도구를 나열한 다음 ping, delay, hang, disconnect를 호출하세요.

Inspector URL에 포함된 임시 인증 토큰을 공유하거나 커밋하지 마세요.

외부 통합 검증

MCP Failure Lab은 독립적인 Python MCP 클라이언트를 사용하는 Future AGI 시뮬레이션으로 독립적으로 검증되었습니다. 실험은 stdio를 통해 실제 hang 도구를 호출하고 시뮬레이션된 에이전트 응답을 평가하기 전에 클라이언트 측 타임아웃을 적용했습니다.

이는 공식 Future AGI 통합이나 보증이 아닌 외부 검증 예시입니다.

결과와 재현 절차는 Future AGI 예제를 참조하세요.

개발

리포지토리를 클론하고 의존성을 설치:

git clone https://github.com/anilloutombam/mcp-failure-lab.git
cd mcp-failure-lab
npm install

개발 CLI 실행:

npm run dev -- --help

풀 리퀘스트를 열기 전에 다음을 실행:

npm run format:check
npm run typecheck
npm test
npm run build

기여 워크플로는 CONTRIBUTING.md를 참조하세요.

로드맵

계획된 작업은 GitHub Issues에서 추적됩니다.

로드맵 항목은 명시적으로 사용 가능하다고 문서화되지 않는 한 현재 구현의 일부가 아닙니다.

라이선스

MIT