Over-Reach Detector

越权检测器（MCP 服务）

检测并报告 AI 编码 Agent 是否修改了其声明任务范围之外的文件。旨在通过标准 stdio 传输接入 Cursor、Claude Code 和其他兼容 MCP 的 AI 编码 Agent。

比较以下两项：

1. 声明的范围 — 任务允许修改的文件（采用 fnmatch glob）和类别（tests、docs、infra、config、code）。
2. 实际差异 — AI 实际修改的文件。

如果实际差异超出声明的范围，工具会返回 status=over_reach，并列出违规文件和类别。

此工具能做什么，不能做什么

over-reach-detector 是审计和披露工具，不是沙箱，也不会阻止操作。

它会比较声明的任务范围与 AI 编码 Agent 实际更改的文件和类别。如果实际更改超出声明的范围，它会报告这一不匹配。

它本身不会阻止文件写入，也不会决定是否撤销、批准或阻止更改。执行、回滚或人工审核仍由调用方负责。

安装

从 PyPI 安装：

pip install over-reach-detector

从源代码安装：

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

快速开始

运行所有测试：python -m pytest -v

直接试用 CLI：python -m over_reach_detector.detector --input fixtures/example_pr_1.json --format markdown

用作 MCP 服务

启动服务（stdio 传输）：over-reach-detector（或从源代码运行 python -m over_reach_detector.server）

向你的 AI Agent 注册：

• Cursor：在 ~/.cursor/mcp.json 中添加以下内容（执行 pip install over-reach-detector 后）：

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

开发版 / 从源代码运行：使用 "command": "python", "args": ["-m", "over_reach_detector.server"]（从仓库根目录运行）。

• Claude Code：执行 pip install over-reach-detector 后，运行 claude mcp add over-reach-detector over-reach-detector（写入 ~/.claude.json）。开发版 / 从源代码运行：claude mcp add over-reach-detector /absolute/path/to/python -m over_reach_detector.server。

工具

check_scope_tool 接收以下参数：

• declared_files：fnmatch glob 列表（例如 ["docs/*.md", "tests/*.py"]）
• declared_categories：从 ["tests", "docs", "infra", "config", "code"] 中选取的类别子集
• actual_files：AI 修改的文件路径列表
• output_format："json"（默认）或 "markdown"

返回的报告包含：

• status：in_scope（在声明的范围内）| over_reach（报告不匹配）| empty
• file_overreach：与任何声明的 glob 都不匹配的文件
• category_overreach：推断出的、超出声明集合的类别

范围约束

当前范围：CLI + MCP stdio 服务 + 1 个工具。仅支持 Python。基于 fnmatch 的 glob。

范围之外（禁止）：代码质量审查、安全审计、完整性治理、Python 以外的语言、多工具 MCP 服务、HTTP/SSE 传输、GitHub Actions 集成。这些功能特意留待后续版本实现，或永不实现。

使用示例

直接从 Python 调用 check_scope_tool（与 MCP 服务公开的逻辑相同）：

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"]

许可证

MIT — 参见 LICENSE。