feat(mcp): add compact threshold context for empty design checks

- include threshold_context in empty complexity, coupling, and cohesion check payloads
- report measured_units and highest_below_threshold from canonical metric families
- distinguish run finding thresholds from explicit requested_min filters
- document the compact MCP response hint for agent-oriented triage
- cover empty-check and requested-min cases with focused MCP tests

Author: orenlab

codeclone/mcp_service.py

@@ -295,6 +295,26 @@
     "complexity": "complexity",
     "clones": "clones",
 }
+_DESIGN_CHECK_CONTEXT: Final[dict[str, dict[str, object]]] = {
+    "complexity": {
+        "category": CATEGORY_COMPLEXITY,
+        "metric": "cyclomatic_complexity",
+        "operator": ">",
+        "default_threshold": DEFAULT_REPORT_DESIGN_COMPLEXITY_THRESHOLD,
+    },
+    "coupling": {
+        "category": CATEGORY_COUPLING,
+        "metric": "cbo",
+        "operator": ">",
+        "default_threshold": DEFAULT_REPORT_DESIGN_COUPLING_THRESHOLD,
+    },
+    "cohesion": {
+        "category": CATEGORY_COHESION,
+        "metric": "lcom4",
+        "operator": ">=",
+        "default_threshold": DEFAULT_REPORT_DESIGN_COHESION_THRESHOLD,
+    },
+}
 _VALID_METRICS_DETAIL_FAMILIES = frozenset(
     {
         "complexity",
@@ -2045,6 +2065,13 @@ def check_complexity(
             detail_level=validated_detail,
             max_results=max_results,
             path=path,
+            threshold_context=self._design_threshold_context(
+                record=record,
+                check="complexity",
+                path=path,
+                items=findings,
+                requested_min=min_complexity,
+            ),
         )
 
     def check_clones(
@@ -2163,6 +2190,12 @@ def _check_design_metric(
             detail_level=validated_detail,
             max_results=max_results,
             path=path,
+            threshold_context=self._design_threshold_context(
+                record=record,
+                check=check,
+                path=path,
+                items=findings,
+            ),
         )
 
     def check_dead_code(
@@ -3615,6 +3648,7 @@ def _granular_payload(
         detail_level: DetailLevel,
         max_results: int,
         path: str | None,
+        threshold_context: Mapping[str, object] | None = None,
     ) -> dict[str, object]:
         bounded_items = [dict(item) for item in items[: max(1, max_results)]]
         full_health = dict(self._as_mapping(record.summary.get("health")))
@@ -3625,7 +3659,7 @@ def _granular_payload(
             if relevant_dimension and relevant_dimension in dimensions
             else dict(dimensions)
         )
-        return {
+        payload: dict[str, object] = {
             "run_id": self._short_run_id(record.run_id),
             "check": check,
             "detail_level": detail_level,
@@ -3639,6 +3673,108 @@ def _granular_payload(
             },
             "items": bounded_items,
         }
+        if threshold_context:
+            payload["threshold_context"] = dict(threshold_context)
+        return payload
+
+    def _design_threshold_context(
+        self,
+        *,
+        record: MCPRunRecord,
+        check: str,
+        path: str | None,
+        items: Sequence[Mapping[str, object]],
+        requested_min: int | None = None,
+    ) -> dict[str, object] | None:
+        if items:
+            return None
+        spec = _DESIGN_CHECK_CONTEXT.get(check)
+        if spec is None:
+            return None
+        category = str(spec["category"])
+        metric = str(spec["metric"])
+        operator = str(spec["operator"])
+        normalized_path = self._normalize_relative_path(path or "")
+        metrics = self._as_mapping(record.report_document.get("metrics"))
+        families = self._as_mapping(metrics.get("families"))
+        family = self._as_mapping(families.get(category))
+        metric_items = [
+            self._as_mapping(item)
+            for item in self._as_sequence(family.get("items"))
+            if not normalized_path
+            or self._metric_item_matches_path(
+                self._as_mapping(item),
+                normalized_path,
+            )
+        ]
+        if not metric_items:
+            return None
+        values = [_as_int(item.get(metric), 0) for item in metric_items]
+        finding_threshold = self._design_finding_threshold(
+            record=record,
+            check=check,
+        )
+        threshold = finding_threshold
+        threshold_kind = "finding_threshold"
+        if requested_min is not None and requested_min > finding_threshold:
+            threshold = requested_min
+            threshold_kind = "requested_min"
+        highest_below = self._highest_below_threshold(
+            values=values,
+            operator=operator,
+            threshold=threshold,
+        )
+        payload: dict[str, object] = {
+            "metric": metric,
+            "threshold": threshold,
+            "threshold_kind": threshold_kind,
+            "measured_units": len(metric_items),
+        }
+        if threshold_kind != "finding_threshold":
+            payload["finding_threshold"] = finding_threshold
+        if highest_below is not None:
+            payload["highest_below_threshold"] = highest_below
+        return payload
+
+    def _design_finding_threshold(
+        self,
+        *,
+        record: MCPRunRecord,
+        check: str,
+    ) -> int:
+        spec = _DESIGN_CHECK_CONTEXT[check]
+        category = str(spec["category"])
+        default_threshold = _as_int(spec["default_threshold"])
+        findings = self._as_mapping(record.report_document.get("findings"))
+        thresholds = self._as_mapping(
+            self._as_mapping(findings.get("thresholds")).get("design_findings")
+        )
+        threshold_payload = self._as_mapping(thresholds.get(category))
+        if threshold_payload:
+            return _as_int(threshold_payload.get("value"), default_threshold)
+        request_value = {
+            "complexity": record.request.complexity_threshold,
+            "coupling": record.request.coupling_threshold,
+            "cohesion": record.request.cohesion_threshold,
+        }.get(check)
+        return _as_int(request_value, default_threshold)
+
+    @staticmethod
+    def _highest_below_threshold(
+        *,
+        values: Sequence[int],
+        operator: str,
+        threshold: int,
+    ) -> int | None:
+        if operator == ">":
+            below = [value for value in values if value <= threshold]
+        elif operator == ">=":
+            below = [value for value in values if value < threshold]
+        else:
+            return None
+        if not below:
+            return None
+        return max(below)
 
     @staticmethod
     def _normalized_source_kind(value: object) -> str:

docs/book/20-mcp-interface.md

@@ -96,6 +96,10 @@ Current server characteristics:
       locations plus remediation
     - `detail_level="full"` keeps the compatibility-oriented payload,
       including `priority_factors`, `items`, and per-location `uri`
+    - empty design `check_*` responses may include a compact
+      `threshold_context` (`metric`, `threshold`, `measured_units`,
+      `highest_below_threshold`) so agents can tell whether the run is truly
+      quiet or just below the active threshold
 
 The MCP layer does not introduce a separate analysis engine. It calls the
 current CodeClone pipeline and reuses the canonical report document already

docs/mcp.md

@@ -116,6 +116,10 @@ run-scoped URI templates.
 **Payload conventions:**
 
 - `check_*` responses include only the relevant health dimension.
+- Empty design `check_*` responses may also include a compact
+  `threshold_context` (`metric`, `threshold`, `measured_units`,
+  `highest_below_threshold`) to show whether the run is genuinely quiet or
+  simply below the active threshold.
 - Finding responses use short MCP IDs and relative paths by default;
   `detail_level=full` restores the compatibility payload with URIs.
 - Summary and triage projections keep interpretation compact: `health_scope`

tests/test_mcp_service.py

@@ -2435,9 +2435,9 @@ def _patched_get_finding(
         request=MCPAnalysisRequest(
             root=str(tmp_path),
             respect_pyproject=False,
-            complexity_threshold=1,
-            coupling_threshold=1,
-            cohesion_threshold=1,
+            complexity_threshold=5,
+            coupling_threshold=5,
+            cohesion_threshold=4,
         ),
         comparison_settings=(),
         report_document={
@@ -2514,6 +2514,143 @@ def _patched_get_finding(
         if str(finding.get("family", "")) == "design"
     ]
     assert design_findings == []
+    service._runs.register(fake_design_record)
+    empty_complexity = service.check_complexity(
+        run_id="design",
+        path="pkg/quality.py",
+        detail_level="summary",
+    )
+    requested_complexity = service.check_complexity(
+        run_id="design",
+        path="pkg/quality.py",
+        min_complexity=8,
+        detail_level="summary",
+    )
+    empty_coupling = service.check_coupling(
+        run_id="design",
+        path="pkg/quality.py",
+        detail_level="summary",
+    )
+    empty_cohesion = service.check_cohesion(
+        run_id="design",
+        path="pkg/quality.py",
+        detail_level="summary",
+    )
+    assert empty_complexity["total"] == 0
+    assert empty_complexity["threshold_context"] == {
+        "metric": "cyclomatic_complexity",
+        "threshold": 5,
+        "threshold_kind": "finding_threshold",
+        "measured_units": 1,
+        "highest_below_threshold": 3,
+    }
+    assert requested_complexity["threshold_context"] == {
+        "metric": "cyclomatic_complexity",
+        "threshold": 8,
+        "threshold_kind": "requested_min",
+        "finding_threshold": 5,
+        "measured_units": 1,
+        "highest_below_threshold": 3,
+    }
+    assert empty_coupling["threshold_context"] == {
+        "metric": "cbo",
+        "threshold": 5,
+        "threshold_kind": "finding_threshold",
+        "measured_units": 1,
+        "highest_below_threshold": 2,
+    }
+    assert empty_cohesion["threshold_context"] == {
+        "metric": "lcom4",
+        "threshold": 4,
+        "threshold_kind": "finding_threshold",
+        "measured_units": 1,
+        "highest_below_threshold": 2,
+    }
+    assert (
+        service._design_threshold_context(
+            record=fake_design_record,
+            check="complexity",
+            path="pkg/quality.py",
+            items=({"id": "existing"},),
+        )
+        is None
+    )
+    assert (
+        service._design_threshold_context(
+            record=fake_design_record,
+            check="unknown",
+            path="pkg/quality.py",
+            items=(),
+        )
+        is None
+    )
+    thresholded_report_document = dict(fake_design_record.report_document)
+    thresholded_findings = dict(
+        cast("dict[str, object]", thresholded_report_document["findings"])
+    )
+    thresholded_findings["thresholds"] = {
+        "design_findings": {
+            "complexity": {
+                "metric": "cyclomatic_complexity",
+                "operator": ">",
+                "value": 6,
+            }
+        }
+    }
+    thresholded_report_document["findings"] = thresholded_findings
+    thresholded_record = replace(
+        fake_design_record,
+        report_document=thresholded_report_document,
+    )
+    assert (
+        service._design_finding_threshold(
+            record=thresholded_record,
+            check="complexity",
+        )
+        == 6
+    )
+    no_below_report_document = dict(fake_design_record.report_document)
+    no_below_metrics = dict(
+        cast("dict[str, object]", no_below_report_document["metrics"])
+    )
+    no_below_families = dict(cast("dict[str, object]", no_below_metrics["families"]))
+    no_below_families["complexity"] = {
+        "items": [
+            {
+                "qualname": "pkg.quality:very_hot",
+                "relative_path": "pkg/quality.py",
+                "start_line": 10,
+                "end_line": 20,
+                "cyclomatic_complexity": 9,
+                "nesting_depth": 2,
+                "risk": "high",
+            }
+        ]
+    }
+    no_below_metrics["families"] = no_below_families
+    no_below_report_document["metrics"] = no_below_metrics
+    no_below_record = replace(
+        fake_design_record,
+        report_document=no_below_report_document,
+    )
+    assert service._design_threshold_context(
+        record=no_below_record,
+        check="complexity",
+        path="pkg/quality.py",
+        items=(),
+    ) == {
+        "metric": "cyclomatic_complexity",
+        "threshold": 5,
+        "threshold_kind": "finding_threshold",
+        "measured_units": 1,
+    }
+    assert (
+        service._highest_below_threshold(values=(9,), operator=">", threshold=5) is None
+    )
+    assert (
+        service._highest_below_threshold(values=(1, 2), operator="!=", threshold=5)
+        is None
+    )
     detail_payload = service._project_finding_detail(
         fake_design_record,
         {