feat(mcp): add help tool for cheaper, more guided agent workflows

Author: orenlab

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [2.0.0b4]
+
+In development.
+
+### MCP server
+
+- Add bounded MCP `help(topic=...)` as an uncertainty-recovery tool for workflow, baseline, suppressions, latest-run semantics, review state, and changed-scope routing.
+
 ## [2.0.0b3]
 
 2.0.0b3 is the release where CodeClone stops looking like "a strong analyzer with extras" and starts looking like a

README.md

@@ -167,7 +167,7 @@ codeclone-mcp --transport stdio
 codeclone-mcp --transport streamable-http --port 8000
 ```
 
-20 tools + 10 resources — deterministic, baseline-aware, and read-only.
+21 tools + 10 resources — deterministic, baseline-aware, and read-only.
 Never mutates source files, baselines, or repo state.
 
 Payloads are optimized for LLM context: compact summaries by default, full detail on demand.
@@ -177,6 +177,9 @@ Recommended agent flow:
 `analyze_repository` or `analyze_changed_paths` → `get_run_summary` or `get_production_triage` →
 `list_hotspots` or `check_*` → `get_finding` → `get_remediation`
 
+If workflow or contract meaning is unclear, `help(topic=...)` returns a compact
+semantic guide with the safest next step and canonical doc links.
+
 Docs:
 [MCP usage guide](https://orenlab.github.io/codeclone/mcp/)
 ·
@@ -277,7 +280,7 @@ Dynamic/runtime false positives are resolved via explicit inline suppressions, n
 {
   "report_schema_version": "2.2",
   "meta": {
-    "codeclone_version": "2.0.0b3",
+    "codeclone_version": "2.0.0b4",
     "project_name": "...",
     "scan_root": ".",
     "report_mode": "full",

benchmarks/run_docker_benchmark.sh

@@ -2,7 +2,7 @@
 set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-IMAGE_TAG="${IMAGE_TAG:-codeclone-benchmark:2.0.0b2}"
+IMAGE_TAG="${IMAGE_TAG:-codeclone-benchmark:2.0.0b4}"
 OUT_DIR="${OUT_DIR:-$ROOT_DIR/.cache/benchmarks}"
 OUTPUT_BASENAME="${OUTPUT_BASENAME:-codeclone-benchmark.json}"
 CPUSET="${CPUSET:-0}"

codeclone/mcp_server.py

@@ -34,6 +34,7 @@
     "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 "
+    "help(topic=...) when workflow or contract semantics are unclear. 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 "
@@ -273,6 +274,27 @@ def get_production_triage(
             max_suggestions=max_suggestions,
         )
 
+    @tool(
+        title="Help",
+        description=(
+            "Return a compact semantic guide for a supported CodeClone topic, "
+            "with next-step routing and canonical doc links. Use this when "
+            "workflow or contract meaning is unclear. This is bounded guidance, "
+            "not a full manual. Supported topics: workflow, suppressions, "
+            "baseline, latest_runs, review_state, changed_scope."
+        ),
+        annotations=read_only_tool,
+        structured_output=True,
+    )
+    def help(
+        topic: str,
+        detail: str = "compact",
+    ) -> dict[str, object]:
+        return service.get_help(
+            topic=topic,  # type: ignore[arg-type]
+            detail=detail,  # type: ignore[arg-type]
+        )
+
     @tool(
         title="Evaluate Gates",
         description=(