{
  "markdown": "# MCP Blast-Radius Auditor\n\n<!-- mcp-name: io.github.aos-standard/mcp-blast-radius -->\n\n[![AOS audited](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/aos-standard/catalog/main/attestations/endpoints/aos-standard__mcp-blast-radius.json)](https://github.com/aos-standard/mcp-blast-radius/blob/main/BADGE_CRITERIA.md)\n\n> **See what any MCP server can actually touch — before you add it to your agent.**\n\nNo manifest? You still get the full blast-radius report. Add a manifest to also catch divergences.\n\n> 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.**\n\nStatically 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.\n\n**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.\n\n## Try it in 3 steps\n\n**① Scan your server in one command**\n\n```bash\npip install mcp-blast-radius==0.2.5\nmcp-blast-radius-gate --gate-mode advisory --target-dir /path/to/your-mcp-server\n```\n\nPoint `--target-dir` at your shipping package root (e.g. `src/`). Default scope excludes tests, docs, and scripts.\n\n**② Read the JSON**\n\n| Field | What it means |\n|-------|----------------|\n| `gate_pass` | Scan finished (`advisory` = report either way; `blocking` = exit 1 on divergences) |\n| `blocking_reasons` | Lines starting with `DIVERGENCE:` = declared vs. observed mismatch (if you ship a manifest) |\n| `blast_radius` | Static capability surface (network, subprocess, env, filesystem) |\n| `confidence` labels | `declared` / `observed-static` / `cannot-determine` — static only, upper bounds |\n\nUndeclared capability is usually drift, not malice. Treat network/subprocess counts as **upper bounds**, not confirmed traffic.\n\n**③ Apply for an audit badge (optional, opt-in)**\n\nRan a clean scan and want a signed README badge? [Open a badge application](https://github.com/aos-standard/mcp-blast-radius/issues/new?template=badge-application.yml) — paste your command and JSON. Free, 90-day attestation, no phone-home. Criteria: [BADGE_CRITERIA.md](BADGE_CRITERIA.md).\n\nTo 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](BADGE_CRITERIA.md#verify-any-badge).\n\n---\n\n## Machine-readable metadata\n\n- **Agent Card** (capabilities, limitations, pricing): [agent_card.json](https://raw.githubusercontent.com/aos-standard/mcp-blast-radius/main/packaging/agent_card.json)\n- **Catalog entry** (pricing, install, MCP endpoint): [aos-standard/catalog](https://raw.githubusercontent.com/aos-standard/catalog/main/catalog.json)\n- **Spec**: [AOS-v0.1](https://github.com/aos-standard/AOS-spec)\n\n## Example walkthrough\n\n```bash\ngit clone --depth 1 https://github.com/oraios/serena.git /tmp/serena\nmcp-blast-radius-gate --gate-mode advisory --target-dir /tmp/serena\n```\n\nInspect `blast_radius` and any `DIVERGENCE:` lines in `blocking_reasons`.\n\n## Report a scan question\n\n[Open a GitHub issue](https://github.com/aos-standard/mcp-blast-radius/issues/new) with your JSON output (structured template loads automatically).\n\n## 30-second scan\n\n```bash\npip install mcp-blast-radius\nmcp-blast-radius-gate --gate-mode blocking --target-dir /path/to/mcp-server\n```\n\n`pipx run mcp-blast-radius` starts the **MCP stdio server** (for Claude Desktop / Cursor). For CLI scanning, use `mcp-blast-radius-gate` as above.\n\n- **Red (blocking):** divergence detected — code touches paths or capabilities not declared in manifest.\n- **Green:** no divergences (or no manifest — blast radius report only, advisory pass).\n\n## Install\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install .\n```\n\n## CLI entry\n\n```bash\nmcp-blast-radius          # MCP stdio server\nmcp-blast-radius-gate     # CI gate (default blocking, exit 1 on fail)\n```\n\n### CI blocking gate\n\n```bash\nmcp-blast-radius-gate --gate-mode blocking --target-dir .\n# no divergences → exit 0 / divergences or declaration violations → exit 1\n```\n\n## MCP tools\n\n- `aos_compliance_validate` — scan one MCP server directory (`target_dir` required; `tool_id` optional label)\n- `aos_compliance_self_test` — wiring smoke test\n\nDefault `gate_mode=advisory`. Use `gate_mode=blocking` in CI to fail on divergences.\n\n## What is extracted\n\n| Layer | Scope | Confidence |\n|-------|-------|------------|\n| Dependencies | `requirements.txt`, `pyproject.toml`, `package.json` | `declared` |\n| Python AST | imports, file I/O, network, env, subprocess; MCP tool attribution | `observed-static` / `cannot-determine` |\n| Divergence | manifest `permitted_output_paths` / `oracle_paths` vs observed access | blocking when mismatch |\n\n**Limitations:** Static analysis only. Dynamic imports, `getattr`/`eval`, obfuscation, and native extensions may hide capabilities. We do not claim complete coverage — every finding includes a `confidence` label.\n\n## Environment\n\n| Variable | Purpose |\n|----------|---------|\n| `AOS_VALIDATOR_TARGET_DIR` | Default scan root when `target_dir` is omitted |\n| `AOS_VALIDATOR_MCP_LOG` | JSONL path for local tool call log (never sent externally) |\n| `AOS_VALIDATOR_CALLER` | Caller label (`ci`, `smoke_self_call`, etc.) |\n\n## Example\n\n```bash\naos_compliance_validate target_dir=/path/to/my-mcp-server gate_mode=blocking\n```\n\n## License\n\nMIT\n",
  "bytes": 5645,
  "sha": "e88cc1230a056d37f9f276914e53fa7ae61692e9d70c549d7ce0fdfdf5b86866",
  "repo_slug": "aos-standard/mcp-blast-radius",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aos_standard_mcp_blast_radius_d94ba090/readme"
}