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
feat(mcp): add set_finding_status, the durable write half of findings triage (#2043)
Nehal kanak kuniyil thottathil71ef0b514a2e
diff --git a/docs/agent/INTEGRATIONS.md b/docs/agent/INTEGRATIONS.mdindex aa24d513c..4ccf56061 100644--- a/docs/agent/INTEGRATIONS.md+++ b/docs/agent/INTEGRATIONS.md@@ -73,10 +73,10 @@ name for a host at this tier, which is the point of the tier.## The MCP surface-repowise registers **seventeen MCP tools**. A single-repo server advertises **ten**+repowise registers **eighteen MCP tools**. A single-repo server advertises **ten**of them by default, and workspace mode adds one more automatically for **eleven**. A-further **six** are off by default, enabled through the `mcp.tools` config block or-`--tools +name`. The `lean` profile trims the default surface to **six** tools+further **seven** are off by default, enabled through the `mcp.tools` config block+or `--tools +name`. The `lean` profile trims the default surface to **six** tools(seven in workspace mode) for agents on a tight context budget.Per-tool detail: [MCP_TOOLS.md](MCP_TOOLS.md).diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.mdindex d80e06fce..3a9cdfc4f 100644--- a/docs/agent/MCP_TOOLS.md+++ b/docs/agent/MCP_TOOLS.md@@ -2,7 +2,7 @@repowise exposes a curated set of tools via the [Model Context Protocol](https://modelcontextprotocol.io) (MCP). These tools give AI coding assistants (Claude Code, Codex, Cursor, Cline, Windsurf) structured access to your codebase intelligence: dependency graph, git history, documentation, and architectural decisions.-17 tools are registered in total. A single-repo server advertises 10 by default: exactly the canonical tools. Workspace mode adds the `list_repos` discovery utility, for 11. 6 specialist tools are opt-in where eligible. The surface is configurable; see [Configuring the tool surface](#configuring-the-tool-surface).+18 tools are registered in total. A single-repo server advertises 10 by default: exactly the canonical tools. Workspace mode adds the `list_repos` discovery utility, for 11. 7 specialist tools are opt-in where eligible. The surface is configurable; see [Configuring the tool surface](#configuring-the-tool-surface).**Start the MCP server:**@@ -35,13 +35,14 @@ repowise mcp --transport sse --port 7338 # legacy SSE transport**Workspace discovery utility (default in workspace mode, 1)**[list_repos](#list_repos)-**Opt-in specialists (6; workspace eligibility still applies)**+**Opt-in specialists (7; workspace eligibility still applies)**[get_architecture](#get_architecture) ·[get_blast_radius](#get_blast_radius) ·[get_dependency_path](#get_dependency_path) ·[get_execution_flows](#get_execution_flows) ·[generate_refactoring_code](#generate_refactoring_code) ·-[get_conformance](#get_conformance)+[get_conformance](#get_conformance) ·+[set_finding_status](#set_finding_status)Also see [Configuring the tool surface](#configuring-the-tool-surface), [Reversible truncation](#reversible-truncation-_metaomitted) and [Unrecognised arguments](#unrecognised-arguments-ignored_arguments).@@ -1310,6 +1311,28 @@ Turns one structured refactoring plan from `get_health(include=["refactoring"])`generate_refactoring_code(suggestion_id="a1b2c3d4")```+#### `set_finding_status`++Records a durable disposition on one refactoring plan — the write half of the findings triage loop. `get_health(include=["refactoring"])` and the generated task prompts ask an agent to flag false positives, but until this tool there was nowhere to record that verdict from inside the agent loop. The status is stored on the plan row, and the analyzer's finalizer never re-emits a `false_positive` plan, so the triage survives every later run.++| Parameter | Type | Required | Description |+|-----------|------|----------|-------------|+| `suggestion_id` | string | Yes | The `id` or `public_id` of a plan from `get_health(include=["refactoring"])` |+| `status` | string | Yes | One of `open`, `acknowledged`, `resolved`, `false_positive` |+| `repo` | string | No | *(workspace only)* Target repo alias |+| `reason` | string | No | Free-text audit note stored on the row (defaults to `"agent"`) |++- `false_positive` — the plan is wrong for this repository; it is never re-emitted on future runs.+- `acknowledged` — real, but the team is consciously not acting now; stays visible, stops counting as unheard.+- `resolved` — the change landed (or the code moved on); a person-resolved plan stays resolved even if the detector still fires.+- `open` — reset a prior decision.++**When to use:** After `get_health(include=["refactoring"])` surfaces a plan you have judged, so the verdict becomes durable state instead of a one-off remark.++```+set_finding_status(suggestion_id="a1b2c3d4", status="false_positive", reason="false alarm: the class is a DTO")+```+---## Workspace Modediff --git a/packages/cli/README.md b/packages/cli/README.mdindex f75c237ef..c58b742eb 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -356,7 +356,7 @@ repowise mcp --transport streamable-httprepowise mcp --transport sse```-Exposes 17 registered MCP tools (11 advertised by default in single-repo mode:+Exposes 18 registered MCP tools (11 advertised by default in single-repo mode:ten flagship tools plus `list_repos`) for querying wiki pages, symbols, thedependency graph, git analytics, ownership data, hotspots, dead code findings,code health, change risk, and decision intelligence. Full surface:diff --git a/packages/cli/src/repowise/cli/commands/mcp_cmd.py b/packages/cli/src/repowise/cli/commands/mcp_cmd.pyindex ef7e1832f..900c4268e 100644--- a/packages/cli/src/repowise/cli/commands/mcp_cmd.py+++ b/packages/cli/src/repowise/cli/commands/mcp_cmd.py@@ -149,7 +149,7 @@ def mcp_command(Exposes a curated set of tools for querying the repowise wiki via the MCPprotocol: ten by default in single-repo mode, plus one more by default- in workspace mode. Six more are opt-in via ``--tools`` or the+ in workspace mode. Seven more are opt-in via ``--tools`` or the``mcp.tools`` config block. Supports stdio(for Claude Code, Codex, Cursor), streamable HTTP, and legacy SSEtransports.diff --git a/packages/server/README.md b/packages/server/README.mdindex c4ed2e681..ce64a96ab 100644--- a/packages/server/README.md+++ b/packages/server/README.md@@ -11,7 +11,7 @@ FastAPI REST API, webhook handlers, MCP server, and background job scheduler for| Component | Description ||-----------|-------------|| **REST API** | FastAPI application with full CRUD for repos, pages (with version history), symbols, jobs, git analytics, dead code, decisions, graph intelligence, blast radius, costs, knowledge map, security findings, providers, chat, CLAUDE.md generation, and multi-repo workspace |-| **MCP Server** | 17 registered MCP tools (10 advertised by default in single-repo mode: the canonical set) for AI coding assistants (Claude Code, Cursor, Cline) |+| **MCP Server** | 18 registered MCP tools (10 advertised by default in single-repo mode: the canonical set) for AI coding assistants (Claude Code, Cursor, Cline) || **Webhooks** | GitHub and GitLab push event handlers — trigger sync jobs automatically on push || **Scheduler** | APScheduler background jobs — polling fallback (auto-syncs diverged repos), stale page detection |@@ -232,9 +232,9 @@ Job progress events (`JobProgressEvent`) carry: `event` type, `file` currently b## MCP Server-repowise registers 17 MCP tools and advertises **10 by default** in single-repo+repowise registers 18 MCP tools and advertises **10 by default** in single-repomode (10 advertised by default, exactly the canonical set). Workspace mode adds-`list_repos`; six specialist tools are opt-in where eligible. See+`list_repos`; seven specialist tools are opt-in where eligible. See[`docs/agent/MCP_TOOLS.md`](../../docs/agent/MCP_TOOLS.md).Start the MCP server via:diff --git a/packages/server/src/repowise/server/mcp_server/__init__.py b/packages/server/src/repowise/server/mcp_server/__init__.pyindex 69a37042b..f63f7656d 100644--- a/packages/server/src/repowise/server/mcp_server/__init__.py+++ b/packages/server/src/repowise/server/mcp_server/__init__.py@@ -53,6 +53,7 @@ from repowise.server.mcp_server import _state#: imports; individually they are what a single-tool consumer pays for._TOOL_MODULES: dict[str, str] = {"generate_refactoring_code": "tool_refactoring",+ "set_finding_status": "tool_findings","get_answer": "tool_answer","get_architecture": "tool_architecture","get_blast_radius": "tool_blast_radius",diff --git a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py b/packages/server/src/repowise/server/mcp_server/_budget/contracts.pyindex 8fbc0cb14..dfec9c0d8 100644--- a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py+++ b/packages/server/src/repowise/server/mcp_server/_budget/contracts.py@@ -340,6 +340,20 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {expansion_argument=None,protected=("suggestion_id", "resolved", "error"),),+ # Same shape as generate_refactoring_code: a small fixed write response+ # whose fields are all load-bearing. No shed order — nothing to rank.+ "set_finding_status": ResponseBudgetContract(+ "blocks",+ expansion_argument=None,+ protected=(+ "id",+ "public_id",+ "status",+ "status_reason",+ "status_changed_at",+ "note",+ ),+ ),}diff --git a/packages/server/src/repowise/server/mcp_server/tool_findings.py b/packages/server/src/repowise/server/mcp_server/tool_findings.pynew file mode 100644index 000000000..ffacdd081--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_findings.py@@ -0,0 +1,117 @@+"""MCP tool: set_finding_status — record a disposition on a refactoring plan.++The missing write half of the findings lifecycle (#1535). ``get_health``+surfaces refactoring plans read-only, and the generated task prompts tell an+agent to "flag false positives" — but until now there was nowhere to flag+them *to* from inside the agent loop. This tool closes the loop: an agent+that judged a plan wrong records ``false_positive`` (or ``acknowledged`` /+``resolved``), and the finalizer ("finalize_refactoring_suggestions") never+re-emits a ``false_positive`` plan, so the triage is durable across runs —+the same suppression the REST PATCH path gives the web UI.+"""++from __future__ import annotations++from typing import Any++from repowise.core.persistence.crud import (+ get_refactoring_suggestion,+ get_refactoring_suggestions,+ update_refactoring_suggestion_status,+)+from repowise.core.persistence.database import get_session+from repowise.core.registry import mcp_tool_registry as mcp+from repowise.server.mcp_server._helpers import _get_repo, _resolve_repo_context+from repowise.server.mcp_server._meta import build_meta as _build_meta++# One triage vocabulary for every layer (shared with health findings and the+# REST PATCH surface) — see crud/analysis/refactoring.py.+ALLOWED_STATUSES = ("open", "acknowledged", "resolved", "false_positive")+++ default=False,+ tier="specialist",+ surface_order=235,+ trust_kind="user",+ artifact_type="finding",+ presentation="status",+ safety="mutating",+)+async def set_finding_status(+ suggestion_id: str,+ status: str,+ repo: str | None = None,+ reason: str = "agent",+) -> dict[str, Any]:+ """Record a durable disposition on one refactoring plan.++ The write side of the findings triage loop: after reviewing a plan from+ ``get_health(include=["refactoring"])`` (use the plan's ``id`` or its+ content-derived ``public_id``), record what you decided so the judgment+ survives every later analysis run.++ - ``false_positive`` — the plan is wrong for this repository; it is+ never re-emitted on future runs (the analyzer's finalizer suppresses+ the kernel), so a wrong suggestion stops coming back instead of being+ re-proposed forever.+ - ``acknowledged`` — real, but the team is consciously not acting now;+ stays visible, stops counting as unheard.+ - ``resolved`` — the change landed (or the code moved on); a plan a+ person resolved stays resolved even if the detector still fires.+ - ``open`` — reset a prior decision.++ ``reason`` is a free-text note stored on the row for audit. Returns the+ new status and its timestamp; raises on an unknown status or an id that+ does not belong to this repository.+ """+ if status not in ALLOWED_STATUSES:+ raise ValueError(+ f"unknown finding status: {status!r}; expected one of {ALLOWED_STATUSES}"+ )++ ctx = await _resolve_repo_context(repo)+ async with get_session(ctx.session_factory) as session:+ repository = await _get_repo(session)+ row = await get_refactoring_suggestion(session, repository.id, suggestion_id)+ if row is None:+ # Same fallback as generate_refactoring_code: a deep link may carry+ # the display id ("<alias> <file>:<symbol>") rather than a storage+ # or content id — match it against the rendered plan ids.+ from repowise.server.mcp_server.tool_health import _refactoring_plan_id++ candidates = await get_refactoring_suggestions(session, repository.id)+ row = next(+ (+ candidate+ for candidate in candidates+ if _refactoring_plan_id(candidate, ctx.alias or repository.name)+ == suggestion_id+ ),+ None,+ )+ if row is None:+ raise ValueError(+ f"refactoring plan not found: {suggestion_id!r} (in this repository)"+ )+ updated = await update_refactoring_suggestion_status(+ session, repository.id, row.id, status, reason=reason+ )+ await session.commit()++ return {+ "id": updated.id,+ "public_id": updated.public_id,+ "status": updated.status,+ "status_reason": updated.status_reason,+ "status_changed_at": updated.status_changed_at.isoformat()+ if updated.status_changed_at+ else None,+ "note": (+ "Recorded. A false_positive plan will not be re-emitted by "+ "future analysis runs."+ if status == "false_positive"+ else "Recorded."+ ),+ "_meta": _build_meta(repository=repository),+ }diff --git a/tests/fixtures/mcp/tool_response_shapes.json b/tests/fixtures/mcp/tool_response_shapes.jsonindex 7bc8ad69a..41165444a 100644--- a/tests/fixtures/mcp/tool_response_shapes.json+++ b/tests/fixtures/mcp/tool_response_shapes.json@@ -1746,5 +1746,17 @@"title": null}]+ },+ "set_finding_status": {+ "_meta": {+ "contract_version": null,+ "embedder_degraded": null+ },+ "id": null,+ "note": null,+ "public_id": null,+ "status": null,+ "status_changed_at": null,+ "status_reason": null}}diff --git a/tests/unit/server/test_tool_findings.py b/tests/unit/server/test_tool_findings.pynew file mode 100644index 000000000..ef9ee34c2--- /dev/null+++ b/tests/unit/server/test_tool_findings.py@@ -0,0 +1,122 @@+"""set_finding_status (MCP) records dispositions through the shared writer.++The CRUD lifecycle is pinned in test_refactoring_lifecycle.py; these tests+cover the tool layer: it validates the vocabulary, resolves the plan by+storage id or display id, routes through update_refactoring_suggestion_status+(the single writer), and surfaces the resulting status.+"""++from __future__ import annotations++from unittest.mock import AsyncMock, patch++import pytest++from repowise.server.mcp_server.tool_findings import set_finding_status+++class _Row:+ def __init__(self, status: str = "false_positive", status_reason: str = "agent"):+ self.id = "row-1"+ self.public_id = "plan-1"+ self.status = status+ self.status_reason = status_reason+ self.status_changed_at = None+++class _Repo:+ id = "repo-1"+ name = "acme"+++def ctx():+ """Fake _resolve_repo_context result + session plumbing."""+ fake_session = AsyncMock()+ fake_session.__aenter__.return_value = fake_session+ fake_session.__aexit__.return_value = False++ fake_ctx = type(+ "Ctx",+ (),+ {"session_factory": object(), "alias": "acme", "path": "/tmp/acme"},+ )()++ with (+ patch(+ "repowise.server.mcp_server.tool_findings._resolve_repo_context",+ new=AsyncMock(return_value=fake_ctx),+ ),+ patch(+ "repowise.server.mcp_server.tool_findings.get_session",+ side_effect=lambda _f: fake_session,+ ),+ patch(+ "repowise.server.mcp_server.tool_findings._get_repo",+ new=AsyncMock(return_value=_Repo()),+ ),+ ):+ yield fake_session+++async def test_unknown_status_raises(ctx):+ with pytest.raises(ValueError, match=r"unknown finding status: 'bogus'"):+ await set_finding_status("row-1", "bogus")+++async def test_missing_plan_raises(ctx):+ with patch(+ "repowise.server.mcp_server.tool_findings.get_refactoring_suggestion",+ new=AsyncMock(return_value=None),+ ), patch(+ "repowise.server.mcp_server.tool_findings.get_refactoring_suggestions",+ new=AsyncMock(return_value=[]),+ ), pytest.raises(ValueError, match="refactoring plan not found"):+ await set_finding_status("absent", "resolved")+++async def test_write_goes_through_the_shared_writer(ctx):+ """The tool must route through update_refactoring_suggestion_status — the+ same writer the REST PATCH and the pipeline use — so a false_positive+ recorded here is suppressed by the finalizer the same way."""+ update = AsyncMock(return_value=_Row())+ with patch(+ "repowise.server.mcp_server.tool_findings.get_refactoring_suggestion",+ new=AsyncMock(return_value=_Row()),+ ), patch(+ "repowise.server.mcp_server.tool_findings.update_refactoring_suggestion_status",+ update,+ ):+ out = await set_finding_status("row-1", "false_positive", reason="dup of #12")++ update.assert_awaited_once()+ call = update.await_args.args+ assert call[1] == "repo-1" # repo id+ assert call[2] == "row-1" # row id+ assert call[3] == "false_positive"+ assert update.await_args.kwargs["reason"] == "dup of #12"+ assert out["status"] == "false_positive"+ assert out["id"] == "row-1"+ assert "not be re-emitted" in out["note"]+++async def test_display_id_fallback(ctx):+ """A deep link may carry the display id (\"<alias> <file>:<symbol>\")+ rather than a storage or content id; the tool falls back like+ generate_refactoring_code does."""+ with patch(+ "repowise.server.mcp_server.tool_findings.get_refactoring_suggestion",+ new=AsyncMock(return_value=None),+ ), patch(+ "repowise.server.mcp_server.tool_findings.get_refactoring_suggestions",+ new=AsyncMock(return_value=[_Row()]),+ ), patch(+ "repowise.server.mcp_server.tool_health._refactoring_plan_id",+ new=lambda _c, _alias: "acme a.py:Foo",+ ), patch(+ "repowise.server.mcp_server.tool_findings.update_refactoring_suggestion_status",+ new=AsyncMock(return_value=_Row(status="acknowledged")),+ ):+ out = await set_finding_status("acme a.py:Foo", "acknowledged")++ assert out["status"] == "acknowledged"diff --git a/website/concepts.md b/website/concepts.mdindex 418527612..d82a58b35 100644--- a/website/concepts.md+++ b/website/concepts.md@@ -161,7 +161,7 @@ The dependency graph is loaded into memory at server startup for fast traversal.## The MCP server-The MCP server sits on top of the persistence layer and exposes everything to AI coding assistants through 17 registered tools: 11 by default in a single repository, 13 by default in workspace mode, and four opt-in tools. It's the primary interface between repowise and Claude Code, Codex, Cursor, Cline, or any other MCP-compatible editor.+The MCP server sits on top of the persistence layer and exposes everything to AI coding assistants through 18 registered tools: 11 by default in a single repository, 13 by default in workspace mode, and five opt-in tools. It's the primary interface between repowise and Claude Code, Codex, Cursor, Cline, or any other MCP-compatible editor.When you run `repowise mcp`, the server starts in stdio mode and your editor can begin calling tools. The tools are designed to answer the questions an AI needs to make good decisions about your code — not just "what is this file" but "should I edit it", "why is it structured this way", and "what will break if I change it".diff --git a/website/index.md b/website/index.mdindex b86401047..91c1e65d2 100644--- a/website/index.md+++ b/website/index.md@@ -24,7 +24,7 @@ repowise generates and maintains a structured wiki for any codebase. It tracks c| **Git intelligence** | Churn hotspots, ownership, bus factor, change patterns || **Dead code detection** | Finds confirmed unused exports, functions, and types || **Decision intelligence** | Captures *why* code is structured the way it is |-| **MCP server** | 11 default tools (10 flagship + `list_repos`) for AI assistants; 17 registered |+| **MCP server** | 11 default tools (10 flagship + `list_repos`) for AI assistants; 18 registered || **Web dashboard** | Browse wiki, search, and explore architecture diagrams || **Multi-language** | 16 AST languages (11 Full tier): Python, TypeScript, JavaScript, Go, Rust, Java, C/C++, Kotlin, Ruby, C#, Swift, Scala, PHP, Dart, Shell |diff --git a/website/mcp-server.md b/website/mcp-server.mdindex 791c3e976..ae99bb019 100644--- a/website/mcp-server.md+++ b/website/mcp-server.md@@ -22,7 +22,7 @@ Connect repowise to Claude Code, Codex, Cursor, Cline, or any MCP-compatible edi## Overview-The MCP (Model Context Protocol) server is how repowise talks to AI coding assistants. It registers 17 tools: a curated 10-tool default surface in a single repository, `list_repos` added by default in workspace mode, and six opt-in specialists subject to mode eligibility. Once connected, your editor's AI can query your codebase wiki for synthesized answers, symbols, docs, ownership, file and change-risk signals, code health, and architectural decisions.+The MCP (Model Context Protocol) server is how repowise talks to AI coding assistants. It registers 18 tools: a curated 10-tool default surface in a single repository, `list_repos` added by default in workspace mode, and seven opt-in specialists subject to mode eligibility. Once connected, your editor's AI can query your codebase wiki for synthesized answers, symbols, docs, ownership, file and change-risk signals, code health, and architectural decisions.Start the server with: