Metadata-Version: 2.4
Name: over-reach-detector
Version: 0.0.4
Summary: Detect when AI code changes exceed declared task scope (MCP server)
Author: ChoreoAtlas
License: MIT
Project-URL: Homepage, https://github.com/choreoatlas/over_reach_detector
Project-URL: Repository, https://github.com/choreoatlas/over_reach_detector
Keywords: mcp,ai,code-review,scope-detection,cursor,claude-code
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Dynamic: license-file

# 越权检测 — 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):
```bash
pip install over-reach-detector
```

From source:
```bash
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`):

```json
{
  "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):

```python
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](LICENSE).
