aos-standard/mcp-blast-radius

> **See what any MCP server can actually touch — before you add it to your agent.**
No manifest? You still get the full blast-radius report. Add a manifest to also catch divergences.
> Also, if the server declares a manifest: **Catch an MCP server that touches files it said it wouldn't — and block the merge in CI.**
Statically extract what a third-party MCP server can reach (files, network, subprocess, env) via surface-level analysis. Compare against declared boundaries when a manifest is present.
**Scan scope (default):** production package only — excludes tests/, docs/, examples/, scripts/, benchmarks/, .github/, and test_*.py patterns; JSON output includes scan_scope and excluded_file_count. Pass --include-peripheral to scan the full repo.
Try it in 3 steps
**① Scan your server in one command**
Point --target-dir at your shipping package root (e.g. src/). Default scope excludes tests, docs, and scripts.
**② Read the JSON**
| Field | What it means |
|-------|----------------|
| gate_pass | Scan finished (advisory = report either way; blocking = exit 1 on divergences) |
| blocking_reasons | Lines starting with DIVERGENCE: = declared vs. observed mismatch (if you ship a manifest) |
| blast_radius | Static capability surface (network, subprocess, env, filesystem) |
| confidence labels | declared / observed-static / cannot-determine — static only, upper bounds |
Undeclared capability is usually drift, not malice. Treat network/subprocess counts as **upper bounds**, not confirmed traffic.
**③ Apply for an audit badge (optional, opt-in)**
Ran a clean scan and want a signed README badge? Open a badge application — paste your command and JSON. Free, 90-day attestation, no phone-home. Criteria: BADGE_CRITERIA.md.
To verify any published attestation independently: pip install cryptography, then run packaging/scripts/verify_attestation.py (accepts local paths or HTTPS URLs). See BADGE_CRITERIA.md §Verify.
---
Machine-readable metadata
- **Agent Card** (capabilities, limitations, pricing): agent_card.json
- **Catalog entry** (pricing, install, MCP endpoint): aos-standard/catalog
- **Spec**: AOS-v0.1
Example walkthrough
Inspect blast_radius and any DIVERGENCE: lines in blocking_reasons.
Report a scan question
Open a GitHub issue with your JSON output (structured template loads automatically).
30-second scan
pipx run mcp-blast-radius starts the **MCP stdio server** (for Claude Desktop / Cursor). For CLI scanning, use mcp-blast-radius-gate as above.
- **Red (blocking):** divergence detected — code touches paths or capabilities not declared in manifest.
- **Green:** no divergences (or no manifest — blast radius report only, advisory pass).
Install
CLI entry
CI blocking gate
MCP tools
- aos_compliance_validate — scan one MCP server directory (target_dir required; tool_id optional label)