🧾 mcp-proof

영수증과 함께 MCP 서버를 출시하세요.

한 번의 명령으로 모든 MCP 서버를 감사합니다 — 프로토콜 시대와 무관하게 도구, 리소스, 프롬프트를 모두 검사하고, stdio 또는 Streamable HTTP를 지원하며, 클라이언트에게 지문(fingerprint)이 찍힌 재현 가능한 전달 보고서와 함께 유지할 수 있는 CI 회귀 테스트 스위트를 제공합니다.

English · 简体中文

공식 MCP filesystem 서버에 대한 실제 감사: 25개 적합성 검사, MSSS 준수 테이블, 34개 회귀 픽스처 — 모두 통과.

✨ 제공 기능

• 🔍 모든 표면과 두 시대에 걸친 와이어 레벨 프로토콜 검사 — mcp-proof는 서버에 원시 JSON-RPC로 직접 말을 걸고 서버의 시대를 자동 감지합니다: 2026-07-28 모던 시대용 30개 검사(server/discover, _meta 봉투 강제, resultType, 모든 캐시 가능 결과의 ttlMs/cacheScope, -32022 버전 거부, HTTP 라우팅 헤더 강제)와 initialize 핸드셰이크 시대용 25개 검사 — 정확한 오류 코드, 스키마 유효성, 구조화된 출력, stdout 위생, 페이지네이션 안전성, 전용 리소스 및 프롬프트 레인, 그리고 검증된 부정 탐지(negative probe): TOOL-07은 선언된 inputSchema를 명백히 위반하는 입력을 보내고, 서버가 이를 정상적으로 응답하면 최소 재현 코드를 인용하여 경고합니다. 양방향 모두 기능 인지형: 서버가 광고하지 않는 표면은 건너뛰고, 광고하는 표면은 반드시 작동해야 합니다.

• 🛡️ 공개 표준에 연동된 보안 감사 — 6가지 결정적 검사(도구 설명 주입, 보이지 않는/bidi 문자, 자격 증명 유출, 제약 없는 주입 표면, 광고된 셸 실행), 각각 24개 컨트롤 MCP Server Security Standard의 표준 컨트롤 ID에 매핑되며 모든 보고서에 전체 준수 테이블로 렌더링됩니다.

• 📼 클라이언트가 유지하는 회귀 테스트 스위트 — 두 프로토콜 시대 모두에서 기록 가능; SHA-256 출처가 있는 골든 픽스처가 서버의 동작을 고정하고, 리플레이는 모든 드리프트를 등급화합니다(BREAKING / VALUE / COSMETIC / LATENCY), 구조화된 출력을 이해하고, 상태 저장 호출 순서를 보존하며, 바로 붙여넣을 수 있는 GitHub Actions 게이트와 함께 제공됩니다.

• 📄 사람과 기계 모두를 위한 보고서 — 스티키 내비게이션, 검사별 앵커(report.html#SEC-03), 주의/통과 필터, 접을 수 있는 MSSS 매트릭스를 갖춘 자체 포함 HTML; 인쇄용 --pdf. 동일한 버전 관리 모델이 --json(스키마 v1), 모든 CI용 --junit, GitHub Security 탭용 --sarif로 제공됩니다.

• 🔁 설계상 재현 가능 — LLM 호출 없음, API 키 없음. 모든 해시는 동작만으로 계산됩니다 — 타임스탬프와 지연 시간은 별도의 해시되지 않은 관찰 계층에 있으므로 — 동일한 서버 동작은 동일한 보고서 지문을 생성하며, 수용은 신뢰가 아닌 검증입니다.

• 🧯 어노테이션 우선 호출 계획 — MCP 도구 어노테이션은 양방향 모두 이름 휴리스틱보다 우선합니다: readOnlyHint는 정규식이 과도하게 차단할 읽기 전용 도구를 구출하고, destructiveHint는 놓칠 수 있는 변경 도구를 포착합니다; 어노테이션이 없는 도구는 보수적 휴리스틱으로 폴백합니다. mcp-proof plan은 프로덕션에 아무것도 닿기 전에 자동 베이스라인이 무엇을 어떤 근거로 호출할지 정확히 보여줍니다; --include-destructive와 --edge-cases로 더 많은 것을 선택할 수 있습니다.

• 📋 CI용 계약 diff — mcp-proof inspect는 제공되는 표면(기능 + 도구 + 리소스 + 프롬프트, 완전 페이지네이션)을 지문이 찍힌 매니페스트로 고정합니다; mcp-proof diff는 모든 변경을 BREAKING / ADDITIVE / METADATA로 분류하고 breaking 변경 시 0이 아닌 종료 코드를 반환합니다 — 스키마 강화, enum 축소, required 플립, 제거된 출력 필드, 약화된 안전 어노테이션이 모두 포함됩니다.

Related MCP server: MCProbe

🚀 빠른 시작

pip install git+https://github.com/YuCPbit/mcp-proof
mcp-proof run python my_server.py --fixtures fixtures/ --out report.html

실행 중인 HTTP 서버를 감사하려면? mcp-proof run --url http://localhost:8000/mcp --out report.html

종료 코드 0은 다음을 의미합니다: 모든 MUST 검사 통과, 보안 발견 0건, 동작 드리프트 0건 — 한 줄 CI 게이트.

mcp-proof plan python my_server.py                            # what would auto-baselining call, and why
mcp-proof record python my_server.py --fixtures fixtures/    # freeze the behavioural contract
mcp-proof replay --fixtures fixtures/ -- python my_server.py  # fail on any drift
mcp-proof inspect python my_server.py --out baseline.json     # freeze the contract surface
mcp-proof diff baseline.json current.json                     # BREAKING / ADDITIVE / METADATA, exit 1 on breaking

내장 데모 쌍으로 60초 안에 차이를 확인하세요 — 깨끗한 서버와 9개의 심어진 위반이 있는 서버:

mcp-proof run python demo/good_server.py --fixtures demo/fixtures-good --out report-good.html   # → SHIP-READY
mcp-proof run python demo/bad_server.py --out report-bad.html                                    # → 5 MUST failures, 3 security findings

📊 실제 감사, 실제 보고서

🔬 세 가지 레인

모든 레인이 하나의 보고서로 통합됩니다 — 그리고 보고서는 우선순위가 매겨진 수정 목록으로 끝나므로 수정 계획으로도 활용됩니다.

📡 프로토콜 지원

모던 레인은 공식 v2 SDK에 대해 양방향으로 검증됩니다: 공식 클라이언트가 server/discover를 통해 mcp-proof의 직접 작성한 모던 테스트 서버를 채택하고, mcp-proof는 공식 v2 SDK 서버에 대해 두 전송 모두 — stdio 및 SSE 응답이 있는 Streamable HTTP — 세 레인을 모두 완전히 통과시킵니다(scripts/crosscheck_modern_server.py).

모든 언어로 작성된 서버와 작동합니다 — mcp-proof는 코드베이스가 아닌 프로세스(또는 URL)와 통신합니다.

⚙️ 한 단계로 CI

- uses: YuCPbit/mcp-proof@v0.5.0
  with:
    server-command: python my_server.py
    fixtures: fixtures/

서버가 ship-ready가 아니면 작업이 실패하고, 업로드를 위해 mcp-proof-report.html / .json / .junit.xml / .sarif 파일을 남깁니다. 원시 명령을 선호하시나요? mcp-proof run … --junit r.xml --sarif r.sarif 에 mcp-proof diff를 더하면 동일한 게이트입니다.

🏗️ 감사 클린 템플릿 위에 구축

서버를 감사하는 대신 구축 중이신가요? templates/server-starter/는 즉시 이 감사를 통과하는 fastmcp 서버입니다 — 제약된 입력 스키마, 올바른 오류 의미론, 구조화된 출력, 충족하는 검사 ID로 주석이 달린 모든 관행. 복사하고, 도구를 구현하고, 감사하고, 보고서와 함께 출시하세요.

🖥️ 플랫폼

🗺️ 로드맵

🔍 제한 사항

mcp-proof는 결정적으로 증명할 수 있는 것을 증명하며, 어떤 것이 어떤 것인지 명시합니다:

• 보안 검사는 관찰 가능한 프로토콜 및 메타데이터 표면을 다룹니다. 배포, 소스 또는 프로세스 증거가 필요한 MSSS 통제 항목은 항상 수동 검토로 보고되며, 통과로 보고되지 않습니다.

• 자동 베이스라인은 보수적인 이름/설명 휴리스틱으로 도구를 분류합니다. 프로덕션에 대해 기록된 베이스라인을 신뢰하기 전에 fixtures 매니페스트의 건너뛰기 목록을 검토하십시오.

• 의미적 정확성(답변이 의미상 올바른가?)은 설계상 결정적 핵심 범위 밖입니다.

📄 라이선스

MIT — MSSS 규정 준수 섹션의 분류 체계는 MCP Server Security Standard (CC BY-SA 4.0)를 따릅니다.