MCPcrunch 🔍

Comprehensive security auditing and conformance testing framework for the OpenMCP Specification.

Inspired by 42Crunch for OpenAPI, MCPcrunch applies deterministic, semantic, and contract-level validation to ensure your MCP specifications are robust, secure, and production-ready.

🚀 Key Features

• Security Audit — 17+ deterministic rules covering Format (FMT), Data Quality (DAT), and Security (SEC). Instant 0–100 security score.
• Conformance Testing — 13 static tests and 40 runtime test definitions across 10 categories. Validates that specs and servers implement the OpenMCP contract correctly.
• Weighted Scoring — Severity-based conformance score (0–100) with letter grades (A/B/C/D/F).
• Semantic Analysis — LLM-powered (Gemini/OpenAI) detection of adversarial threats like prompt injection and sensitive field leakage.
• Dual Interface — Full-featured CLI and first-class Python API.
• Rich Reporting — Beautiful terminal output with summary tables, score/grade display, and JSON export.

🛠 Installation

pip install mcpcrunch

📖 Quick Start

Security Audit (CLI)

# Deterministic audit
mcpcrunch spec.json --schema schema.json

# With semantic analysis
mcpcrunch spec.json --schema schema.json --llm gemini --api-key $GEMINI_API_KEY

Conformance Testing (CLI)

# Static conformance tests (no server needed)
mcpcrunch conformance spec.json --schema schema.json --static-only

# Full suite against a live server
mcpcrunch conformance spec.json --server-url https://api.example.com/mcp --bearer-token $TOKEN

# Export JSON report
mcpcrunch conformance spec.json --schema schema.json --static-only --output report.json

Python API

import json
from mcpcrunch import MCPcrunch, ConformanceRunner

# ── Security Audit ──
crunch = MCPcrunch("schema.json")
with open("spec.json") as f:
    spec = json.load(f)

report = crunch.audit(spec)
print(f"Security Score: {report.overall_score}/100")

# ── Conformance Testing ──
runner = ConformanceRunner(spec_path="spec.json", schema_path="schema.json")
conf = runner.run_static()

print(f"Conformance Score: {conf.summary.score}/100")
print(f"Grade: {conf.summary.grade}")
print(f"Passed: {conf.summary.passed}/{conf.summary.total_tests}")

🧪 Conformance Test Catalog

Static Tests (no server required)

Scoring

Conformance score is penalty-based (starts at 100):

Grades: A (90–100) · B (75–89) · C (60–74) · D (40–59) · F (0–39)

📋 Security Audit Rules

For the full list of 17+ validation rules, see validations.md.

• FMT — Format integrity, versioning, URI strictness
• DAT — Data boundaries, context window protection, strict schemas
• SEC — Authentication binding, transport security, API key safety
• ADV — Adversarial threat prevention (semantic/LLM-based)

📂 Examples

See examples/ for complete usage demonstrations:

🧪 Testing

# Run the full test suite (236 tests)
pytest tests/

# Run with verbose output
pytest tests/ -v

📦 Requirements

• Python ≥ 3.10
• jsonschema ≥ 4.20.0
• pydantic ≥ 2.5.0
• rich ≥ 13.7.0
• httpx ≥ 0.27.0

📄 License

MIT — see LICENSE.

Built with ❤️ for the AI Agent Ecosystem by Anish Chelliah CR · ProdMCP