feat(mcp): make get_conformance and generate_refactoring_code opt-in

Both tools were advertised on the default surface, but neither is a good
default. generate_refactoring_code returns an error until the repo sets
refactoring.llm.enabled, so it added schema weight for a tool most repos
can't call. get_conformance needs the workspace graph and is niche enough
that it shouldn't take a default slot; its findings still surface in the
get_risk PR-mode directive without opting the tool in.

Flip both to default=False. get_conformance keeps requires_workspace=True,
so it can only be opted in inside a workspace. Default single-repo drops
from 11 to 10 tools, workspace default from 14 to 12, opt-in grows to 4.

Updates the surface docs (MCP_TOOLS.md, CONFIG.md), the module docstring,
and adds a selection regression test.

Author: RaghavChamadiya

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
 

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,17 +30,17 @@ 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).
 
 ---
 
 ## Configuring the tool surface
 
 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
 
 ---

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

packages/server/src/repowise/server/mcp_server/tool_conformance.py

@@ -21,7 +21,7 @@
 _MCP_CYCLE_LIMIT = 25
 
 
-@mcp.tool(requires_workspace=True)
+@mcp.tool(default=False, requires_workspace=True)
 async def get_conformance(repo: str | None = None) -> dict[str, Any]:
     """Architecture conformance — dependency-rule violations + cycles.
 

packages/server/src/repowise/server/mcp_server/tool_refactoring.py

@@ -57,7 +57,7 @@ def _loads(value: Any) -> dict[str, Any]:
     return sug
 
 
-@mcp.tool()
+@mcp.tool(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.
 

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"