feat(mcp): harden MCP helper semantics and make the budget-first workflow explicit

- stabilize compact MCP clone and finding ids with collision-safe hashed short-id helpers
- factor JSON/resource serialization and derived-section projection into shared MCP helpers, reducing service coupling without changing canonical report contracts
- make the MCP workflow explicitly budget-aware and triage-first in server instructions, tool descriptions, README, and MCP docs
- lock the new guidance and helper behavior with updated MCP server/service tests
- refresh uv.lock to the current dependency lock state

Author: orenlab

README.md

@@ -44,7 +44,7 @@ Live sample report:
 - **Baseline governance** — known debt stays accepted; CI blocks only new clones and metric regressions
 - **Reports** — interactive HTML, deterministic JSON/TXT plus Markdown and SARIF projections from one canonical report
 - **MCP server** — optional MCP surface for AI agents, IDEs, and MCP-capable clients; read-only with respect to repo and
-  persisted artifacts
+  persisted artifacts, budget-aware, and designed as a guided control surface for agentic development
 - **CI-first** — deterministic output, stable ordering, exit code contract, pre-commit support
 - **Fast** — incremental caching, parallel processing, warm-run optimization, and reproducible benchmark coverage
 
@@ -170,6 +170,10 @@ codeclone-mcp --transport streamable-http --port 8000
 20 tools + 10 resources — deterministic, baseline-aware, and read-only. Never mutates source files, baselines, or repo
 state.
 Payloads are optimised for LLM context: compact summaries by default, full detail on demand.
+The cheapest useful path is also the most obvious path: first-pass triage stays compact, and deeper detail is explicit.
+Recommended budget-first flow for agents: `analyze_repository` or
+`analyze_changed_paths` → `get_run_summary` or `get_production_triage` →
+`list_hotspots` or `check_*` → `get_finding` → `get_remediation`.
 
 Docs:
 [MCP usage guide](https://orenlab.github.io/codeclone/mcp/)

codeclone/mcp_server.py

@@ -29,10 +29,16 @@
 
 _SERVER_INSTRUCTIONS = (
     "CodeClone MCP is a deterministic, baseline-aware, read-only analysis server "
-    "for Python repositories. Use analyze_repository first, then query the latest "
-    "or a specific run with summary, finding, hotspot, gate, and report-section "
-    "tools. Pass an absolute repository root to analysis tools. This server "
-    "never updates baselines and never mutates source files."
+    "for Python repositories. Use analyze_repository first for full runs or "
+    "analyze_changed_paths for PR-style review, then prefer get_run_summary or "
+    "get_production_triage for the first pass. Use list_hotspots or focused "
+    "check_* tools before broader list_findings calls, then drill into one "
+    "finding with get_finding or get_remediation. Use "
+    "get_report_section(section='metrics_detail', family=..., limit=...) for "
+    "bounded metrics drill-down, and prefer generate_pr_summary(format='markdown') "
+    "unless machine JSON is required. Pass an absolute repository root to "
+    "analysis tools. This server never updates baselines and never mutates "
+    "source files."
 )
 _MCP_INSTALL_HINT = (
     "CodeClone MCP support requires the optional 'mcp' extra. "
@@ -115,8 +121,9 @@ def resource(
         description=(
             "Run a deterministic CodeClone analysis for a repository and register "
             "the result as the latest MCP run. Pass an absolute repository root: "
-            "relative roots like '.' are rejected in MCP. Tip: set "
-            "cache_policy='off' to bypass cache and get fully fresh results."
+            "relative roots like '.' are rejected in MCP. Then prefer "
+            "get_run_summary or get_production_triage for the first pass. Tip: "
+            "set cache_policy='off' to bypass cache and get fully fresh results."
         ),
         annotations=session_tool,
         structured_output=True,
@@ -175,8 +182,10 @@ def analyze_repository(
         description=(
             "Run a deterministic CodeClone analysis and return a changed-files "
             "projection using explicit paths or a git diff ref. Pass an absolute "
-            "repository root: relative roots like '.' are rejected in MCP. Tip: "
-            "set cache_policy='off' to bypass cache and get fully fresh results."
+            "repository root: relative roots like '.' are rejected in MCP. Then "
+            "prefer get_report_section(section='changed') or get_production_triage "
+            "before broader finding lists. Tip: set cache_policy='off' to bypass "
+            "cache and get fully fresh results."
         ),
         annotations=session_tool,
         structured_output=True,
@@ -233,7 +242,8 @@ def analyze_changed_paths(
     @tool(
         title="Get Run Summary",
         description=(
-            "Return the stored compact MCP summary for the latest or specified run."
+            "Return the stored compact MCP summary for the latest or specified "
+            "run. Start here when you want the cheapest run-level snapshot."
         ),
         annotations=read_only_tool,
         structured_output=True,
@@ -246,7 +256,8 @@ def get_run_summary(run_id: str | None = None) -> dict[str, object]:
         description=(
             "Return a production-first triage view over a stored run: health, "
             "cache freshness, production hotspots, and production suggestions, "
-            "while keeping global source-kind counters visible."
+            "while keeping global source-kind counters visible. Use this as the "
+            "default first-pass review on noisy repositories."
         ),
         annotations=read_only_tool,
         structured_output=True,
@@ -302,9 +313,10 @@ def evaluate_gates(
         title="Get Report Section",
         description=(
             "Return a canonical CodeClone report section for the latest or "
-            "specified MCP run. The 'metrics' section returns only the "
-            "summary, while 'metrics_detail' returns paginated item slices or "
-            "summary+hint when unfiltered."
+            "specified MCP run. Prefer specific sections instead of 'all' unless "
+            "you truly need the full canonical report. The 'metrics' section "
+            "returns only the summary, while 'metrics_detail' returns paginated "
+            "item slices or summary+hint when unfiltered."
         ),
         annotations=read_only_tool,
         structured_output=True,
@@ -330,7 +342,9 @@ def get_report_section(
         title="List Findings",
         description=(
             "List canonical finding groups with deterministic ordering, optional "
-            "filters, pagination, and compact summary cards by default."
+            "filters, pagination, and compact summary cards by default. Prefer "
+            "list_hotspots or focused check_* tools for first-pass triage; use "
+            "this when you need a broader filtered list."
         ),
         annotations=read_only_tool,
         structured_output=True,
@@ -372,7 +386,9 @@ def list_findings(
         title="Get Finding",
         description=(
             "Return a single canonical finding group by short or full id. "
-            "Normal detail is the default."
+            "Normal detail is the default. Use this after list_hotspots, "
+            "list_findings, or check_* instead of requesting larger lists at "
+            "higher detail."
         ),
         annotations=read_only_tool,
         structured_output=True,
@@ -392,7 +408,8 @@ def get_finding(
         title="Get Remediation",
         description=(
             "Return actionable remediation guidance for a single finding. "
-            "Normal detail is the default."
+            "Normal detail is the default. Use this when you need the fix packet "
+            "for one finding without pulling larger detail lists."
         ),
         annotations=read_only_tool,
         structured_output=True,
@@ -412,7 +429,8 @@ def get_remediation(
         title="List Hotspots",
         description=(
             "Return one of the derived CodeClone hotlists for the latest or "
-            "specified MCP run, using compact summary cards by default."
+            "specified MCP run, using compact summary cards by default. Prefer "
+            "this for first-pass triage before broader list_findings calls."
         ),
         annotations=read_only_tool,
         structured_output=True,
@@ -464,7 +482,9 @@ def compare_runs(
         description=(
             "Return complexity hotspots from a compatible stored run. "
             "Use analyze_repository first if no full run is available. When "
-            "filtering by root without run_id, pass an absolute root."
+            "filtering by root without run_id, pass an absolute root. Prefer "
+            "this narrower tool instead of list_findings when you only need "
+            "complexity hotspots."
         ),
         annotations=read_only_tool,
         structured_output=True,
@@ -491,7 +511,9 @@ def check_complexity(
         description=(
             "Return clone findings from a compatible stored run. "
             "Use analyze_repository first if no compatible run is available. "
-            "When filtering by root without run_id, pass an absolute root."
+            "When filtering by root without run_id, pass an absolute root. "
+            "Prefer this narrower tool instead of list_findings when you only "
+            "need clone findings."
         ),
         annotations=read_only_tool,
         structured_output=True,
@@ -520,7 +542,9 @@ def check_clones(
         description=(
             "Return coupling hotspots from a compatible stored run. "
             "Use analyze_repository first if no full run is available. When "
-            "filtering by root without run_id, pass an absolute root."
+            "filtering by root without run_id, pass an absolute root. Prefer "
+            "this narrower tool instead of list_findings when you only need "
+            "coupling hotspots."
         ),
         annotations=read_only_tool,
         structured_output=True,
@@ -545,7 +569,9 @@ def check_coupling(
         description=(
             "Return cohesion hotspots from a compatible stored run. "
             "Use analyze_repository first if no full run is available. When "
-            "filtering by root without run_id, pass an absolute root."
+            "filtering by root without run_id, pass an absolute root. Prefer "
+            "this narrower tool instead of list_findings when you only need "
+            "cohesion hotspots."
         ),
         annotations=read_only_tool,
         structured_output=True,
@@ -570,7 +596,9 @@ def check_cohesion(
         description=(
             "Return dead-code findings from a compatible stored run. "
             "Use analyze_repository first if no full run is available. When "
-            "filtering by root without run_id, pass an absolute root."
+            "filtering by root without run_id, pass an absolute root. Prefer "
+            "this narrower tool instead of list_findings when you only need "
+            "dead-code findings."
         ),
         annotations=read_only_tool,
         structured_output=True,
@@ -594,7 +622,11 @@ def check_dead_code(
 
     @tool(
         title="Generate PR Summary",
-        description="Generate a PR-friendly CodeClone summary for changed files.",
+        description=(
+            "Generate a PR-friendly CodeClone summary for changed files. Prefer "
+            "format='markdown' for compact LLM-facing output; use 'json' only "
+            "for machine post-processing."
+        ),
         annotations=read_only_tool,
         structured_output=True,
     )