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): make get_conformance and generate_refactoring_code opt-in (#875)
Raghav Chamadiya5e49dcf57c33
diff --git a/docs/CONFIG.md b/docs/CONFIG.mdindex 8851e44ab..d4d89bea2 100644--- a/docs/CONFIG.md+++ b/docs/CONFIG.md@@ -150,7 +150,7 @@ distill:### The `mcp:` blockControls which tools the MCP server advertises. The default surface is curated-(11 tools in single-repo mode, plus 3 workspace-only tools in workspace mode);+(10 tools in single-repo mode, plus 2 workspace-only tools in workspace mode);this block lets you opt extra tools in or trim the set down. The `repowise mcp--tools` / `--all` flags override it for a single launch.@@ -167,10 +167,12 @@ mcp:- `lean` selects the agent-lean profile: `get_answer`, `get_context`,`get_symbol`, `search_codebase`, `get_risk` (plus `list_repos` in workspacemode), small enough that Claude Code can keep every schema always loaded.-- Opt-in tools are `get_dependency_path` and `get_execution_flows`.-- Workspace-only tools (`get_blast_radius`, `get_conformance`,- `get_architecture`) are added automatically in workspace mode and ignored if- named in single-repo mode. See [MCP_TOOLS.md](MCP_TOOLS.md#configuring-the-tool-surface).+- Opt-in tools are `get_dependency_path`, `get_execution_flows`,+ `generate_refactoring_code`, and `get_conformance` (the last only usable in+ workspace mode).+- Workspace-only tools (`get_blast_radius`, `get_architecture`) are added+ automatically in workspace mode and ignored if named in single-repo mode. See+ [MCP_TOOLS.md](MCP_TOOLS.md#configuring-the-tool-surface).### The `decisions:` blockdiff --git a/docs/MCP_TOOLS.md b/docs/MCP_TOOLS.mdindex fc464d177..dd9a6a04b 100644--- a/docs/MCP_TOOLS.md+++ b/docs/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.-16 tools are registered in total. A single-repo server advertises 11 by default: the nine flagship tools below plus `list_repos` and `generate_refactoring_code`. Workspace mode adds 3 more automatically, for 14. Two further tools are off by default everywhere and must be opted in. The surface is configurable; see [Configuring the tool surface](#configuring-the-tool-surface).+16 tools are registered in total. A single-repo server advertises 10 by default: the nine flagship tools below plus `list_repos`. Workspace mode adds 2 more automatically (`get_architecture`, `get_blast_radius`), for 12. Four further tools are off by default everywhere and must be opted in. The surface is configurable; see [Configuring the tool surface](#configuring-the-tool-surface).**Start the MCP server:**@@ -30,7 +30,7 @@ repowise mcp --transport sse --port 7338 # legacy SSE transport| `get_dead_code` | Unreachable code | Cleanup tasks || `get_health` | Code-health marker scores | Before refactoring, find the worst files |-Also always on by default: `list_repos` (repo aliases) and `generate_refactoring_code` (opt-in code generation from a health plan). See [Supplementary tools](#supplementary-tools).+Also always on by default: `list_repos` (repo aliases). See [Supplementary tools](#supplementary-tools).---@@ -38,9 +38,9 @@ Also always on by default: `list_repos` (repo aliases) and `generate_refactoringThe default surface is deliberately small: fewer, richer tools mean fewer round-trips and less schema overhead per task. What a server advertises is resolved from three things: each tool's `default`/`requires_workspace` metadata, whether the server is in workspace mode, and an optional override.-- **Default (single-repo):** 11 tools, the nine flagship tools plus `list_repos` and `generate_refactoring_code` (though `generate_refactoring_code` returns an error until its config flag is set; see below).-- **Default (workspace):** those 11 plus `get_architecture`, `get_blast_radius`, and `get_conformance`, added automatically when the server starts inside a workspace. They are never advertised outside one.-- **Opt-in tools:** `get_dependency_path` and `get_execution_flows` are registered but off by default everywhere. Turn them on per repo.+- **Default (single-repo):** 10 tools, the nine flagship tools plus `list_repos`.+- **Default (workspace):** those 10 plus `get_architecture` and `get_blast_radius`, added automatically when the server starts inside a workspace. They are never advertised outside one.+- **Opt-in tools:** `get_dependency_path`, `get_execution_flows`, `generate_refactoring_code`, and `get_conformance` are registered but off by default. Turn them on per repo; `get_conformance` only does useful work in workspace mode (name it there).**Configure it in `.repowise/config.yaml`** under an `mcp.tools` key. Four shapes are supported:@@ -504,25 +504,6 @@ Lists the repos this server is serving. No parameters.list_repos()```-### `generate_refactoring_code`--Turns one structured refactoring plan from `get_health(include=["refactoring"])` into actual generated code and a unified diff, grounded on the plan plus the real source spans it references. For Extract Class, the result includes an LCOM4 before/after self-check.--**Disabled by default.** Returns `{"error": "disabled", ...}` unless `refactoring.llm.enabled: true` is set in the repo's `.repowise/config.yaml`. When enabled, it uses the repo's configured LLM provider/model (bring your own key) and caches results by a content hash, so an unchanged plan never regenerates.--**Parameters:**--| Parameter | Type | Required | Description |-|-----------|------|----------|-------------|-| `suggestion_id` | string | Yes | The `id` of a plan returned by `get_health(include=["refactoring"])` |-| `repo` | string | No | *(workspace only)* Target repo alias |--**When to use:** After `get_health(include=["refactoring"])` surfaces a plan you want turned into an applyable diff, and your repo has opted into LLM-backed generation.--```-generate_refactoring_code(suggestion_id="a1b2c3d4")-```-### Workspace-only tools*(Available only when the server is started inside a workspace; see [Workspace Mode](#workspace-mode).)*@@ -550,6 +531,8 @@ get_blast_radius(targets=["mono::services/auth"], max_depth=2, include_behavioraArchitecture governance: does the live system graph obey the declared dependency rules, and are there circular service dependencies?+**Opt-in.** Off by default even in workspace mode; enable with `mcp.tools: ["+get_conformance"]`. Named in single-repo mode it is ignored, since it needs the workspace graph. The same findings still surface in the `get_risk` PR-mode directive (`conformance_violations` / `dependency_cycles`) without opting the tool in.+| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| `repo` | string | No | Limit findings to those involving this repo alias |@@ -617,6 +600,25 @@ get_execution_flows()get_execution_flows(entry_point="src/cli/main.py::main", max_depth=4)```+#### `generate_refactoring_code`++Turns one structured refactoring plan from `get_health(include=["refactoring"])` into actual generated code and a unified diff, grounded on the plan plus the real source spans it references. For Extract Class, the result includes an LCOM4 before/after self-check.++**Off by default twice over:** it must be opted into the tool surface (`mcp.tools: ["+generate_refactoring_code"]`), and even then returns `{"error": "disabled", ...}` unless `refactoring.llm.enabled: true` is set in the repo's `.repowise/config.yaml`. When enabled, it uses the repo's configured LLM provider/model (bring your own key) and caches results by a content hash, so an unchanged plan never regenerates.++**Parameters:**++| Parameter | Type | Required | Description |+|-----------|------|----------|-------------|+| `suggestion_id` | string | Yes | The `id` of a plan returned by `get_health(include=["refactoring"])` |+| `repo` | string | No | *(workspace only)* Target repo alias |++**When to use:** After `get_health(include=["refactoring"])` surfaces a plan you want turned into an applyable diff, and your repo has opted into both the tool and LLM-backed generation.++```+generate_refactoring_code(suggestion_id="a1b2c3d4")+```+---## Workspace Mode@@ -633,7 +635,7 @@ The MCP server automatically enriches responses with cross-repo intelligence:- **Package dependencies** between repos- **Cross-repo blast radius** via the workspace-only `get_blast_radius` tool, and a cross-repo `directive` in `get_risk` PR-mode- **Breaking-change guard**: incompatible provider-contract changes and the consumers they endanger, in the `get_risk` PR-mode `breaking_changes` directive-- **Architecture conformance**: declared dependency-rule violations and dependency cycles via the workspace-only `get_conformance` tool, and `conformance_violations` / `dependency_cycles` in the `get_risk` PR-mode directive+- **Architecture conformance**: declared dependency-rule violations and dependency cycles via the workspace-only, opt-in `get_conformance` tool, and `conformance_violations` / `dependency_cycles` in the `get_risk` PR-mode directive- **Architecture metrics**: whole-system coupling (propagation cost), the cyclic core, per-service roles, and a deterministic 1-10 architecture score via the workspace-only `get_architecture` tool---diff --git a/packages/server/src/repowise/server/mcp_server/__init__.py b/packages/server/src/repowise/server/mcp_server/__init__.pyindex d87a9faf4..315b224ec 100644--- a/packages/server/src/repowise/server/mcp_server/__init__.py+++ b/packages/server/src/repowise/server/mcp_server/__init__.py@@ -2,11 +2,12 @@By default a single-repo server exposes ten tools (get_answer, get_context,get_symbol, search_codebase, get_overview, get_risk, get_why, get_dead_code,-get_health, list_repos); three more (get_blast_radius, get_conformance,-get_architecture) are added automatically in workspace mode. Two further tools-(get_dependency_path, get_execution_flows) are registered but off by default and-can be opted in via the ``mcp.tools`` config block or the ``repowise mcp---tools`` flag. The selection layer lives in :mod:`._tool_selection`.+get_health, list_repos); two more (get_blast_radius, get_architecture) are added+automatically in workspace mode. Four further tools (get_dependency_path,+get_execution_flows, generate_refactoring_code, get_conformance) are registered+but off by default and can be opted in via the ``mcp.tools`` config block or the+``repowise mcp --tools`` flag; get_conformance only does useful work in workspace+mode. The selection layer lives in :mod:`._tool_selection`.Exposes the full repowise wiki as queryable tools via the MCP protocol.Supports stdio transport (Claude Code, Cursor, Cline), streamable HTTP, anddiff --git a/packages/server/src/repowise/server/mcp_server/tool_conformance.py b/packages/server/src/repowise/server/mcp_server/tool_conformance.pyindex 5cf38c35e..723957c22 100644--- a/packages/server/src/repowise/server/mcp_server/tool_conformance.py+++ b/packages/server/src/repowise/server/mcp_server/tool_conformance.py@@ -21,7 +21,7 @@ _MCP_VIOLATION_LIMIT = 25_MCP_CYCLE_LIMIT = 25[email protected](requires_workspace=True)[email protected](default=False, requires_workspace=True)async def get_conformance(repo: str | None = None) -> dict[str, Any]:"""Architecture conformance — dependency-rule violations + cycles.diff --git a/packages/server/src/repowise/server/mcp_server/tool_refactoring.py b/packages/server/src/repowise/server/mcp_server/tool_refactoring.pyindex ba558002e..e8290a7c7 100644--- a/packages/server/src/repowise/server/mcp_server/tool_refactoring.py+++ b/packages/server/src/repowise/server/mcp_server/tool_refactoring.py@@ -57,7 +57,7 @@ def _row_to_suggestion(row: Any) -> Any:return sug[email protected](default=False)async def generate_refactoring_code(suggestion_id: str, repo: str | None = None) -> dict:"""Generate refactored code + a unified diff for one refactoring plan.diff --git a/tests/unit/server/mcp/test_tool_selection.py b/tests/unit/server/mcp/test_tool_selection.pyindex f20f8dbf6..ee2f23b24 100644--- a/tests/unit/server/mcp/test_tool_selection.py+++ b/tests/unit/server/mcp/test_tool_selection.py@@ -101,6 +101,37 @@ def test_lean_profile_full_registry():assert workspace == LEAN_TOOLS | {"list_repos"}+def test_conformance_and_refactoring_are_opt_in():+ """generate_refactoring_code and get_conformance are off the default surface.++ Both must be named explicitly to appear; get_conformance stays workspace-gated+ even when opted in.+ """+ import repowise.server.mcp_server # noqa: F401 (registers the tools)+ from repowise.core.registry import mcp_tool_registry++ entries = mcp_tool_registry.entries()++ single = resolve_enabled_tools(entries, is_workspace=False)+ workspace = resolve_enabled_tools(entries, is_workspace=True)+ for surface in (single, workspace):+ assert "generate_refactoring_code" not in surface+ assert "get_conformance" not in surface++ opted_ws = resolve_enabled_tools(+ entries, is_workspace=True, override="+generate_refactoring_code,+get_conformance"+ )+ assert {"generate_refactoring_code", "get_conformance"} <= opted_ws++ # In single-repo mode refactoring can be opted in, but conformance can't:+ # it needs the workspace graph, so an explicit mention is ignored there.+ opted_single = resolve_enabled_tools(+ entries, is_workspace=False, override="+generate_refactoring_code,+get_conformance"+ )+ assert "generate_refactoring_code" in opted_single+ assert "get_conformance" not in opted_single++def test_workspace_only_named_explicitly_is_dropped_single_repo():enabled = resolve_enabled_tools(CATALOG, is_workspace=False, override="get_answer,get_blast_radius"