over-reach-detector 0.0.4

Detect when AI code changes exceed declared task scope (MCP server)

越权检测 — Authority Boundary Detector (MCP server)

Detects when AI code changes exceed declared task scope. Designed to plug into Cursor, Claude Code, and other MCP-compatible AI coding agents via the standard stdio transport.

Compares two things:

1. Declared scope — the files (as fnmatch globs) and categories (tests, docs, infra, config, code) the task is allowed to touch.
2. Actual diff — the files the AI actually modified.

If the actual diff exceeds the declared scope, the tool returns status=over_reach and lists the offending files and categories.

Install

From PyPI (after 0.0.4 release):

pip install over-reach-detector

From source:

git clone https://github.com/choreoatlas/over_reach_detector
cd over_reach_detector
pip install -e .

Quick start

Run all tests: python -m pytest -v

Try the CLI directly: python -m over_reach_detector.detector --input fixtures/example_pr_1.json --format markdown

Use as MCP server

Start the server (stdio transport): over-reach-detector (or python -m over_reach_detector.server from source)

Register with your AI agent:

• Cursor: in ~/.cursor/mcp.json, add (after pip install over-reach-detector):

{
  "mcpServers": {
    "over-reach-detector": {
      "command": "over-reach-detector"
    }
  }
}

Dev / from source: use "command": "python", "args": ["-m", "over_reach_detector.server"] (run from repo root).

• 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.

The tool

check_scope_tool takes:

• declared_files: list of fnmatch globs (e.g. ["docs/*.md", "tests/*.py"])
• declared_categories: subset of ["tests", "docs", "infra", "config", "code"]
• actual_files: list of file paths the AI modified
• output_format: "json" (default) or "markdown"

Returns a report with:

• status: in_scope (safe) | over_reach (block) | empty
• file_overreach: files not matching any declared glob
• category_overreach: inferred categories outside the declared set

Scope discipline

Current scope: CLI + MCP stdio server + 1 tool. Python only. fnmatch-based globs.

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.

Example usage

Call check_scope_tool directly from Python (same logic the MCP server exposes):

import json
from over_reach_detector import server

result = server.check_scope_tool(
    declared_files=["docs/*.md"],
    declared_categories=["docs"],
    actual_files=["docs/a.md", "scripts/extra.py"],
    output_format="json",
)

report = json.loads(result)
print(report["status"])          # "over_reach"
print(report["file_overreach"])  # ["scripts/extra.py"]

License

MIT — see LICENSE.