Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(mcp): get_health(fix_id) opens the act_ ids get_overview hands out (#3544)
Raghav Chamadiya93ff34eb32e1
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.mdindex 30d018351..1ff10f915 100644--- a/docs/agent/MCP_TOOLS.md+++ b/docs/agent/MCP_TOOLS.md@@ -326,7 +326,7 @@ Code-health scores and findings from the stored analysis, across defect risk, ma| `only` | list[string] | none | Keep just these top-level keys; identity, totals and recovery fields always survive. An unknown key is named in `unknown_only_keys` with `unknown_only_keys_hint` || `limit` | int | `20` | Max rows in every ranked list, capped at 50; `0` for none. `fix_first` shows five unless `limit` is passed with `only=["fix_first"]`, which pages up to 25; `refactoring_plans` up to 25 || `cursor` | int | `0` | Offset into a ranked list (and into `fix_first` when named in `only`); the `recovery` block names the next call |-| `fix_id` | string | none | Open one `fix_first` item in full |+| `fix_id` | string | none | Open one `fix_first` item (`fix1_...`) in full, or one `get_overview` `next_actions` action (`act_...`) with its `details` and `commands` (`mode: "action"`) || `finding_id`, `plan_id` | string | none | Open one finding or refactoring plan by id. With `plan_id`, `include=["recipe"]` adds `plan.recipe`: the plan's preconditions, ordered steps, postconditions and what it must not do || `opportunity_id` | string | none | Open one opportunity: `perf...` for performance, `refop...` for a refactoring || `refactoring_view` | string | `"diversified"` | `diversified`, `canonical` or `file_spread` |@@ -349,6 +349,7 @@ The response is bounded. Pair `include` with `only` to keep one block, e.g. `getget_health(only=["fix_first"], limit=25)get_health(only=["fix_first"], limit=25, cursor=25)get_health(fix_id="fix1_...")+get_health(fix_id="act_...")get_health(include=["refactoring"], only=["refactoring_plans"], limit=15, refactoring_scope="all")get_health(targets=["src/api/server.py"], include=["signals"])get_health(include=["performance"], only=["performance_summary"])diff --git a/docs/reference/MCP_RESPONSE_FIELDS.md b/docs/reference/MCP_RESPONSE_FIELDS.mdindex 03bcaa82d..7123d197d 100644--- a/docs/reference/MCP_RESPONSE_FIELDS.md+++ b/docs/reference/MCP_RESPONSE_FIELDS.md@@ -302,7 +302,7 @@ The `candidates` and `history` lanes shed first under budget pressure, so an abs| `entry_points` | Detected entry points || `architecture` | Layer names and file counts in stack order, test layer left out || `code_health`, `git_health` | Repo-level health and history summaries |-| `next_actions` | Per horizon (week, quarter): the first three stored actions (`id`, `tier`, `title`, `impact`, `done_when`, `target`) with `total` and `by_tier` |+| `next_actions` | Per horizon (week, quarter): the first three stored actions (`id`, `tier`, `title`, `impact`, `done_when`, `target`) with `total` and `by_tier`. `get_health(fix_id="act_...")` opens one in full || `more` | Names the opt-in blocks || `workspace` | Workspace mode footer |@@ -314,7 +314,7 @@ Opt-in blocks: `outline` (wiki page tree, two levels), `tour` (`guided_tour`, `r### Modes and identity-`mode` is `dashboard` (no targets), `targeted`, `fix_item` (`fix_id`), or `conflict` (two selectors passed). `unresolved` names targets that matched nothing, with a reason: `not_indexed`, `no_such_path`, `excluded`, `not_measured`, `no_such_module` (which also returns `known_modules`). A `no_such_path` entry adds `removed_by_commit` and `moved_to` (the file or files that replaced it) when git history explains the miss. `mode`, `_meta`, `unresolved`, `known_modules` and every kept list's `*_total` survive any `only` projection. `scope` and `counts` are echoed on the response.+`mode` is `dashboard` (no targets), `targeted`, `fix_item` (`fix_id`), `action` (an `act_` `fix_id`: the Do next action with its `details` and `commands`), or `conflict` (two selectors passed). `unresolved` names targets that matched nothing, with a reason: `not_indexed`, `no_such_path`, `excluded`, `not_measured`, `no_such_module` (which also returns `known_modules`). A `no_such_path` entry adds `removed_by_commit` and `moved_to` (the file or files that replaced it) when git history explains the miss. `mode`, `_meta`, `unresolved`, `known_modules` and every kept list's `*_total` survive any `only` projection. `scope` and `counts` are echoed on the response.`_meta.health_analysis` labels the result as stored analysis that this call did not recompute. Its `status` is `available`, `provenance_unknown` (metrics exist but no row recorded their commit) or `unavailable`. `_meta.health_analyzed_at` and `_meta.health_analyzed_commit` date the health pass, which can lag indexing; `_meta.health_analyzed_commits_distinct` appears when rows come from several passes.diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/details.py b/packages/server/src/repowise/server/mcp_server/tool_health/details.pyindex 230c463f7..b701dfc65 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health/details.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health/details.py@@ -12,6 +12,7 @@ from repowise.core.analysis.health.refactoring.serving import evidence_blockfrom repowise.core.analysis.health.scope import DEFAULT_SCOPEfrom repowise.core.analysis.health.worth import LOW_PRIORITY_LABEL, finding_prioritiesfrom repowise.core.persistence.crud import get_health_finding_by_public_id, get_health_findings+from repowise.core.persistence.crud.analysis.actions import load_actionfrom repowise.core.persistence.crud.analysis.fix_first import load_fix_firstfrom repowise.core.persistence.models import HealthFindingfrom repowise.server.mcp_server._meta import build_meta as _build_meta@@ -116,8 +117,23 @@ async def _finding_detail_response(return result+#: Prefix of the Do next action ids ``get_overview``'s ``next_actions`` hands out.+_ACTION_ID_PREFIX = "act_"++_FIX_NOT_FOUND = (+ "get_health() lists the current fix_first ids (fix1_...); "+ "get_overview() lists the next_actions ids (act_...)"+)++async def _fix_detail_response(session: Any, repository: Any, fix_id: str) -> dict[str, Any]:- """One Fix-first item in full: action steps, verify, risk, context."""+ """One Fix-first item in full: action steps, verify, risk, context.++ An ``act_`` id is a Do next action, the same one the REST actions route+ reads: its evidence rows and commands.+ """+ if fix_id.startswith(_ACTION_ID_PREFIX):+ return await _action_detail_response(session, repository, fix_id)item = (await load_fix_first(session, repository.id, item_id=fix_id)).find(fix_id)result = {"mode": "fix_item",@@ -129,7 +145,27 @@ async def _fix_detail_response(session: Any, repository: Any, fix_id: str) -> di),}if item is None:- result["next_action"] = "get_health() lists the current fix_first ids"+ result["next_action"] = _FIX_NOT_FOUND+ await _attach_repository_analysis_meta(session, repository, result["_meta"])+ return result+++async def _action_detail_response(+ session: Any, repository: Any, action_id: str+) -> dict[str, Any]:+ """One Do next action in full, serialized as the REST actions route does."""+ action = await load_action(session, repository.id, action_id)+ result = {+ "mode": "action",+ "fix_id": action_id,+ "action": action.as_dict() if action else None,+ "found": action is not None,+ "_meta": _build_meta(+ repository=repository, targets=[action.target_path] if action and action.target_path else None+ ),+ }+ if action is None:+ result["next_action"] = _FIX_NOT_FOUNDawait _attach_repository_analysis_meta(session, repository, result["_meta"])return resultdiff --git a/packages/server/src/repowise/server/mcp_server/tool_health/tool.py b/packages/server/src/repowise/server/mcp_server/tool_health/tool.pyindex 848951b12..14097d709 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health/tool.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health/tool.py@@ -166,7 +166,7 @@ async def get_health(repo: usually omitted.limit: max rows per ranked list (default 20), ``0`` for none.cursor: offset into a ranked list.- fix_id/finding_id/plan_id: stable ``id`` of an item, finding or plan.+ fix_id/finding_id/plan_id: stable ``id``: item or ``act_``, finding, plan.opportunity_id: ``perf...``/``refop...``: the unit, its steps orplan, evidence paged by ``only=["*_evidence"]``.refactoring_view: ``diversified`` (default)|``canonical``|diff --git a/tests/unit/server/mcp/test_health.py b/tests/unit/server/mcp/test_health.pyindex 3565bc733..16e969f4c 100644--- a/tests/unit/server/mcp/test_health.py+++ b/tests/unit/server/mcp/test_health.py@@ -497,6 +497,7 @@ async def test_get_health_dashboard_leads_with_fix_first(setup_mcp, health_data)assert full["item"]["id"] == lead["id"] and full["item"]["action"]["steps"]missing = await get_health(fix_id="fix1_00000000000000000000")assert missing["found"] is False and missing["item"] is None+ assert "fix1_" in missing["next_action"] and "act_" in missing["next_action"]@pytest.mark.asynciodiff --git a/tests/unit/server/mcp/test_overview_next_actions.py b/tests/unit/server/mcp/test_overview_next_actions.pyindex 58fe713dd..a26e364f7 100644--- a/tests/unit/server/mcp/test_overview_next_actions.py+++ b/tests/unit/server/mcp/test_overview_next_actions.py@@ -54,6 +54,30 @@ async def test_overview_carries_the_stored_actions(setup_mcp, session):assert None not in row["target"].values()+async def test_every_handed_out_action_id_opens_in_get_health(setup_mcp, session):+ """An agent following Do next opens the id it was handed, details and all."""+ from repowise.core.persistence.crud.analysis.actions import load_action+ from repowise.server.mcp_server import get_health, get_overview++ await _seed(session, setup_mcp)+ block = (await get_overview())["next_actions"]+ ids = {a["id"] for h in ("week", "quarter") for a in block[h]["actions"]}+ assert ids, "the seed should produce actions"+ for action_id in ids:+ full = await get_health(fix_id=action_id)+ assert full["mode"] == "action" and full["found"] is True+ # The same serialization the REST actions route renders from.+ expected = (await load_action(session, setup_mcp, action_id)).as_dict()+ assert full["action"] == expected+ assert full["action"]["details"] and full["action"]["commands"]++ missing = await get_health(fix_id="act_0000000000000000")+ assert missing["mode"] == "action" and missing["found"] is False+ assert missing["action"] is None+ assert "act_" in missing["next_action"] and "fix1_" in missing["next_action"]++@pytest.mark.asyncioasync def test_a_failed_read_is_omitted_with_a_reason(setup_mcp, monkeypatch):from repowise.server.mcp_server import get_overview