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.

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.md
index 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. `get
get_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.md
index 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.py
index 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_block
from repowise.core.analysis.health.scope import DEFAULT_SCOPE
from repowise.core.analysis.health.worth import LOW_PRIORITY_LABEL, finding_priorities
from repowise.core.persistence.crud import get_health_finding_by_public_id, get_health_findings
+from repowise.core.persistence.crud.analysis.actions import load_action
from repowise.core.persistence.crud.analysis.fix_first import load_fix_first
from repowise.core.persistence.models import HealthFinding
from 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_FOUND
await _attach_repository_analysis_meta(session, repository, result["_meta"])
return result
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/tool.py b/packages/server/src/repowise/server/mcp_server/tool_health/tool.py
index 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 or
plan, 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.py
index 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.asyncio
diff --git a/tests/unit/server/mcp/test_overview_next_actions.py b/tests/unit/server/mcp/test_overview_next_actions.py
index 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.asyncio
async def test_a_failed_read_is_omitted_with_a_reason(setup_mcp, monkeypatch):
from repowise.server.mcp_server import get_overview