Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(mcp): get_health metric rows carry structure_deduction and history_deduction (#4108)

Raghav Chamadiyaf00c84fecdc9
diff --git a/docs/reference/MCP_RESPONSE_FIELDS.md b/docs/reference/MCP_RESPONSE_FIELDS.md
index 3805e5a0e..b5d54ff79 100644
--- a/docs/reference/MCP_RESPONSE_FIELDS.md
+++ b/docs/reference/MCP_RESPONSE_FIELDS.md
@@ -101,7 +101,7 @@ The key is absent when every argument was understood. One entry per argument.
| `search_codebase` | `kind`, `mode` (an unknown `mode` runs as `auto`), `pattern` when `query` is also given (entry carries `"superseded_by": "query"`) | Top-level list |
| `get_risk`, `get_change_risk`, `get_overview` | `include` | Top-level list |
| `get_answer` | `include` | `_meta.ignored_arguments`, a map: `{"include": [...]}` |
-| `get_health` | `refactoring_*` and `performance_*` filters, `scope`, `counts` | Top-level flat map of argument to dropped value, e.g. `{"counts": "code-shape"}` |
+| `get_health` | `refactoring_*` and `performance_*` filters, `scope`, `counts` | Top-level flat map of argument to dropped value, e.g. `{"counts": "code-shape"}`. A value that belongs to the other control (`scope="code_shape"`) also gets `ignored_arguments_hint` naming the right one (not on a detail lookup, where neither control applies) |
`get_health` reports a misspelled `only` key under `unknown_only_keys`. A detail lookup (`finding_id`, `plan_id`, `opportunity_id`) also lists `scope` and `counts` there, since a population control has nothing to act on for one stored row.
@@ -377,7 +377,7 @@ Items are ordered by value first, then tier. History markers (churn, ownership,
| `worst_files`, `test_worst_files` | Lowest raw scores, production and test |
| `high_leverage_files` | Ranked by `weighted_deficit`, with `share_of_repo_gap_pct` |
| `top_findings` / `findings`, `test_findings` | Production and test findings; their totals sum to the whole open set |
-| metric row | `score` (defect dimension and headline), `maintainability_score`, `performance_score`, `weighted_deficit` = (8 - score) x NLOC, `is_test`, `has_test_file`, `primary_biomarker`, `total_deduction`, and `withheld_deduction` when part of it comes from a withheld finding type |
+| metric row | `score` (defect dimension and headline), `maintainability_score`, `performance_score`, `weighted_deficit` = (8 - score) x NLOC, `is_test`, `has_test_file`, `primary_biomarker`, `total_deduction`, `structure_deduction` and `history_deduction` (the score is 10 minus both, before the 1.0 floor; history reads 0.0 under `counts="code_shape"`), and `withheld_deduction` when part of it comes from a withheld finding type |
`weighted_deficit` and the gap fields share one unit, score points x NLOC; they compare only with each other. Non-code files score a mechanical 10.0 because no marker reads them; `average_health_code_only` shows the headline without them. `primary_biomarker` prefers a discrete finding over the continuous `coverage_gradient`. Each finding carries a `dimension`; `advisory` findings (`assertion_free_test`, `mock_saturated_test`) never deduct and appear only with `include=["advisory"]`.
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/projection.py b/packages/server/src/repowise/server/mcp_server/tool_health/projection.py
index abf1c9206..9e227b518 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_health/projection.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_health/projection.py
@@ -4,8 +4,8 @@ from __future__ import annotations
from typing import Any
-from repowise.core.analysis.health.counts import DEFAULT_COUNTS
-from repowise.core.analysis.health.scope import DEFAULT_SCOPE
+from repowise.core.analysis.health.counts import COUNTS, DEFAULT_COUNTS
+from repowise.core.analysis.health.scope import DEFAULT_SCOPE, SCOPES
from repowise.server.mcp_server.tool_health.paging import _stamp_collection
from repowise.server.mcp_server.tool_health.request import HealthRequest
@@ -28,6 +28,7 @@ _ALWAYS_KEPT = frozenset(
"unknown_include_keys_emitted",
# A rejected filter value is a caller-error report too.
"ignored_arguments",
+ "ignored_arguments_hint",
"recovery",
}
)
@@ -39,6 +40,9 @@ _UNKNOWN_ONLY_HINT = (
"performance is an `include` value. See docs/agent/MCP_TOOLS.md."
)
+#: Which control accepts each value, to name the right one for a swapped value.
+_CONTROL_OF_VALUE = {**dict.fromkeys(COUNTS, "counts"), **dict.fromkeys(SCOPES, "scope")}
+
_PLAN_COMPANIONS = frozenset(
{"refactoring_plans_status", "refactoring_plans_opportunities_total"}
)
@@ -60,6 +64,13 @@ def _name_rejected_controls(
}
if rejected:
result["ignored_arguments"] = {**result.get("ignored_arguments", {}), **rejected}
+ swapped = [
+ f'{name}="{raw}" is a {other} value: did you mean {other}="{raw}"?'
+ for name, raw in rejected.items()
+ if (other := _CONTROL_OF_VALUE.get(raw)) and other != name
+ ]
+ if swapped:
+ result["ignored_arguments_hint"] = " ".join(swapped)
def _name_uncounted_blocks(result: dict[str, Any], reported_counts: str) -> None:
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/serialize.py b/packages/server/src/repowise/server/mcp_server/tool_health/serialize.py
index dae04211f..ea332ab8e 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_health/serialize.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_health/serialize.py
@@ -185,6 +185,9 @@ def _serialize_metric(
# ``defect_score`` is deliberately absent: it always equals ``score``.
"maintainability_score": _round_opt(getattr(m, "maintainability_score", None)),
"performance_score": _round_opt(getattr(m, "performance_score", None)),
+ # The score's two halves (``10 - structure - history``, before the floor).
+ "structure_deduction": _round_opt(getattr(m, "structure_deduction", None)),
+ "history_deduction": _round_opt(getattr(m, "history_deduction", None)),
# Dominant cause and pre-clamp magnitude; null when the file has no findings.
"primary_biomarker": lead.get("primary_biomarker") if lead else None,
"primary_reason": lead.get("primary_reason") if lead else None,
diff --git a/tests/unit/server/mcp/test_health.py b/tests/unit/server/mcp/test_health.py
index b9e9d31f3..48e6972d7 100644
--- a/tests/unit/server/mcp/test_health.py
+++ b/tests/unit/server/mcp/test_health.py
@@ -2288,6 +2288,53 @@ async def test_a_misspelled_control_is_named_rather_than_silently_defaulted(
assert result["ignored_arguments"] == {"counts": "code-shape", "scope": "prod"}
+async def test_a_value_passed_to_the_other_control_names_the_right_one(
+ setup_mcp, session, populated_db
+):
+ from repowise.server.mcp_server import get_health
+
+ result = await get_health(
+ targets=["src/auth/service.py"], scope="code_shape", only=["metrics"]
+ )
+ assert result["ignored_arguments"] == {"scope": "code_shape"}
+ assert 'counts="code_shape"' in result["ignored_arguments_hint"]
+ reverse = await get_health(counts="production")
+ assert 'scope="production"' in reverse["ignored_arguments_hint"]
+ plain = await get_health(counts="code-shape")
+ assert "ignored_arguments_hint" not in plain
+
+
+async def test_metric_rows_carry_the_structure_and_history_split(
+ setup_mcp, session, populated_db
+):
+ """The two halves the score is ``10 - structure - history`` of, per file."""
+ from repowise.core.persistence.crud import save_health_metrics
+ from repowise.server.mcp_server import get_health
+
+ await save_health_metrics(
+ session,
+ populated_db,
+ [
+ {
+ "file_path": "src/auth/service.py",
+ "score": 3.0,
+ "nloc": 100,
+ "is_test": False,
+ "structure_deduction": 1.0,
+ "history_deduction": 6.0,
+ }
+ ],
+ )
+ row = (await get_health(targets=["src/auth/service.py"]))["metrics"][0]
+ assert (row["structure_deduction"], row["history_deduction"]) == (1.0, 6.0)
+ worst = (await get_health(only=["worst_files"]))["worst_files"][0]
+ assert (worst["structure_deduction"], worst["history_deduction"]) == (1.0, 6.0)
+ shaped = (await get_health(targets=["src/auth/service.py"], counts="code_shape"))["metrics"]
+ assert (shaped[0]["structure_deduction"], shaped[0]["history_deduction"]) == (1.0, 0.0)
+
+
@pytest.mark.asyncio
async def test_a_valid_control_is_not_reported_as_ignored(setup_mcp, session, populated_db):
from repowise.server.mcp_server import get_health