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): make get_conformance and generate_refactoring_code opt-in (#875)

Raghav Chamadiya5e49dcf57c33
diff --git a/docs/CONFIG.md b/docs/CONFIG.md
index 8851e44ab..d4d89bea2 100644
--- a/docs/CONFIG.md
+++ b/docs/CONFIG.md
@@ -150,7 +150,7 @@ distill:
### The `mcp:` block
Controls 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 workspace
mode), 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:` block
diff --git a/docs/MCP_TOOLS.md b/docs/MCP_TOOLS.md
index 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_refactoring
The 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_behaviora
Architecture 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__.py
index 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, and
diff --git a/packages/server/src/repowise/server/mcp_server/tool_conformance.py b/packages/server/src/repowise/server/mcp_server/tool_conformance.py
index 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.py
index 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.py
index 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"