{
  "markdown": "# Over-Reach Detector (MCP server)\n\n<!-- mcp-name: io.github.choreoatlas/over-reach-detector -->\n\nDetect and report when AI coding agents change files outside their declared task scope. Designed to plug into Cursor, Claude Code, and other MCP-compatible AI coding agents via the standard stdio transport.\n\nCompares two things:\n\n1. **Declared scope** — the files (as fnmatch globs) and categories (tests, docs, infra, config, code) the task is allowed to touch.\n2. **Actual diff** — the files the AI actually modified.\n\nIf the actual diff exceeds the declared scope, the tool returns `status=over_reach` and lists the offending files and categories.\n\n## What this tool does and does not do\n\n`over-reach-detector` is an audit/disclosure tool, not a sandbox and not a blocker.\n\nIt compares a declared task scope with the actual files/categories changed by an AI coding agent. If the actual changes exceed the declared scope, it reports that mismatch.\n\nIt does not prevent file writes by itself. It does not decide whether to revert, approve, or block a change. The caller remains responsible for enforcement, rollback, or human review.\n\n## Install\n\nFrom PyPI:\n```bash\npip install over-reach-detector\n```\n\nFrom source:\n```bash\ngit clone https://github.com/choreoatlas/over_reach_detector\ncd over_reach_detector\npip install -e .\n```\n\n## Quick start\n\nRun all tests: `python -m pytest -v`\n\nTry the CLI directly: `python -m over_reach_detector.detector --input fixtures/example_pr_1.json --format markdown`\n\n## Use as MCP server\n\nStart the server (stdio transport): `over-reach-detector` (or `python -m over_reach_detector.server` from source)\n\nRegister with your AI agent:\n\n- **Cursor**: in `~/.cursor/mcp.json`, add (after `pip install over-reach-detector`):\n\n```json\n{\n  \"mcpServers\": {\n    \"over-reach-detector\": {\n      \"command\": \"over-reach-detector\"\n    }\n  }\n}\n```\n\n  Dev / from source: use `\"command\": \"python\", \"args\": [\"-m\", \"over_reach_detector.server\"]` (run from repo root).\n\n- **Claude Code**: after `pip install over-reach-detector`, run `claude mcp add over-reach-detector over-reach-detector` (writes to `~/.claude.json`). Dev / from source: `claude mcp add over-reach-detector /absolute/path/to/python -m over_reach_detector.server`.\n\n## The tool\n\n`check_scope_tool` takes:\n\n- `declared_files`: list of fnmatch globs (e.g. `[\"docs/*.md\", \"tests/*.py\"]`)\n- `declared_categories`: subset of `[\"tests\", \"docs\", \"infra\", \"config\", \"code\"]`\n- `actual_files`: list of file paths the AI modified\n- `output_format`: `\"json\"` (default) or `\"markdown\"`\n\nReturns a report with:\n\n- `status`: `in_scope` (within declared scope) | `over_reach` (reported mismatch) | `empty`\n- `file_overreach`: files not matching any declared glob\n- `category_overreach`: inferred categories outside the declared set\n\n## Scope discipline\n\n**Current scope**: CLI + MCP stdio server + 1 tool. Python only. fnmatch-based globs.\n\n**Out of scope (forbidden)**: code quality review, security audit, completeness governance, languages other than Python, multi-tool MCP servers, HTTP/SSE transport, GitHub Actions integration. These are deliberately deferred to later versions or never.\n\n## Example usage\n\nCall `check_scope_tool` directly from Python (same logic the MCP server exposes):\n\n```python\nimport json\nfrom over_reach_detector import server\n\nresult = server.check_scope_tool(\n    declared_files=[\"docs/*.md\"],\n    declared_categories=[\"docs\"],\n    actual_files=[\"docs/a.md\", \"scripts/extra.py\"],\n    output_format=\"json\",\n)\n\nreport = json.loads(result)\nprint(report[\"status\"])          # \"over_reach\"\nprint(report[\"file_overreach\"])  # [\"scripts/extra.py\"]\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 3686,
  "sha": "385a4587ba2bb8f2cc89ec1067b19a99e40ee5f383bf32018f9536dcdc3ce1a6",
  "repo_slug": "choreoatlas/over_reach_detector",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_choreoatlas_over_reach_detecto_ddb3ba91/readme"
}