Over-Reach Detector

Over-Reach Detector（MCP サーバー）

AI コーディングエージェントが、宣言されたタスクの範囲外のファイルを変更した場合に検出して報告します。標準の stdio トランスポートを介して、Cursor、Claude Code、その他の MCP 対応 AI コーディングエージェントに接続できるように設計されています。

次の 2 つを比較します。

1. 宣言された範囲 — タスクで変更が許可されているファイル（fnmatch グロブ形式）とカテゴリ（テスト、ドキュメント、インフラ、設定、コード）。
2. 実際の差分 — AI が実際に変更したファイル。

実際の差分が宣言された範囲を超えている場合、ツールは status=over_reach を返し、該当するファイルとカテゴリを一覧表示します。

このツールが行うこと、行わないこと

over-reach-detector は監査・開示ツールであり、サンドボックスでも変更を阻止するツールでもありません。

宣言されたタスクの範囲と、AI コーディングエージェントが実際に変更したファイルやカテゴリを比較します。実際の変更が宣言された範囲を超えている場合、その不一致を報告します。

このツール自体がファイルの書き込みを防ぐことはありません。変更を取り消すか、承認するか、阻止するかも判断しません。適用、ロールバック、人によるレビューは、呼び出し側が行う責任があります。

インストール

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 エージェントに登録します。

• 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 グロブのリスト（例：["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：宣言されたグロブに一致しないファイル
• category_overreach：宣言されたカテゴリの集合に含まれないと推定されたカテゴリ

スコープの規律

現在のスコープ：CLI + MCP stdio サーバー + 1 つのツール。Python のみ。fnmatch ベースのグロブ。

対象外（禁止事項）：コード品質レビュー、セキュリティ監査、完全性のガバナンス、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 を参照してください。