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): name get_architecture and get_blast_radius in the server instructions only when they are served (#4707)

Raghav Chamadiyaeb2c645bc91c
diff --git a/packages/server/src/repowise/server/mcp_server/_server.py b/packages/server/src/repowise/server/mcp_server/_server.py
index bbb0e5a72..2e7ba892d 100644
--- a/packages/server/src/repowise/server/mcp_server/_server.py
+++ b/packages/server/src/repowise/server/mcp_server/_server.py
@@ -6,6 +6,7 @@ import asyncio
import contextlib
import os
import weakref
+from collections.abc import Iterable
from contextlib import asynccontextmanager
from typing import Any, NoReturn
@@ -744,35 +745,50 @@ class _RepowiseMCP(FastMCP):
current_principal.reset(reset)
+# Hosts that defer tool schemas show the model only tool names and this
+# string, so it says when to call; tests pin the key lines and a length cap.
+_INSTRUCTIONS = (
+ "repowise indexes this repository's code graph, git history and "
+ "decisions. One call here often replaces several text searches and "
+ "file reads.\n"
+ "- Use search_codebase(query) to find an identifier or literal: it "
+ "returns `lines` (path, line, kind, text; definitions first) read from "
+ "live files, and `complete: true` means that is every match. Path-like "
+ "and concept queries rank files.\n"
+ '- Use get_context(targets=[symbol], include=["references"]) before a '
+ "rename or an update-all-callers change: it lists the definition, "
+ "imports and calls, and a `complete` list is the whole edit set.\n"
+ "- Use get_answer(question) for a how/where/why question: one cited "
+ "answer.\n"
+ "- Use get_risk before a non-trivial edit to a widely imported file, "
+ "get_change_risk before committing a multi-file change, and get_why "
+ "before changing an established pattern. Skip them for one-line fixes.\n"
+ "- Targets with uncommitted edits are flagged; the index is stale for "
+ "them until `repowise update --working-tree` runs.\n"
+ "If the tools report that the repo has no index, tell the user to run "
+ "'repowise init --yes --no-prose' in the repo root; it needs no API key "
+ "and makes no model calls. Suggest it, "
+ "do not run it yourself."
+)
+
+#: Opt-in workspace tools, named only once the selected surface has them.
+_WORKSPACE_TOOL_LINES = {
+ "get_architecture": "get_architecture for the workspace's coupling and architecture score",
+ "get_blast_radius": "get_blast_radius for the services a change reaches in other repos",
+}
+
+
+def _instructions(enabled: Iterable[str] = ()) -> str:
+ """The server instructions, naming a workspace tool only when it is served."""
+ lines = [line for name, line in _WORKSPACE_TOOL_LINES.items() if name in enabled]
+ if not lines:
+ return _INSTRUCTIONS
+ return f"{_INSTRUCTIONS}\nIn this workspace, use {' and '.join(lines)}."
+
+
mcp = _RepowiseMCP(
"repowise",
- # Hosts that defer tool schemas show the model only tool names and this
- # string, so it says when to call; tests pin the key lines and a length cap.
- instructions=(
- "repowise indexes this repository's code graph, git history and "
- "decisions. One call here often replaces several text searches and "
- "file reads.\n"
- "- Use search_codebase(query) to find an identifier or literal: it "
- "returns `lines` (path, line, kind, text; definitions first) read from "
- "live files, and `complete: true` means that is every match. Path-like "
- "and concept queries rank files.\n"
- '- Use get_context(targets=[symbol], include=["references"]) before a '
- "rename or an update-all-callers change: it lists the definition, "
- "imports and calls, and a `complete` list is the whole edit set.\n"
- "- Use get_answer(question) for a how/where/why question: one cited "
- "answer.\n"
- "- Use get_risk before a non-trivial edit to a widely imported file, "
- "get_change_risk before committing a multi-file change, and get_why "
- "before changing an established pattern. Skip them for one-line fixes.\n"
- "- Targets with uncommitted edits are flagged; the index is stale for "
- "them until `repowise update --working-tree` runs.\n"
- "In workspace mode, get_architecture and get_blast_radius are also "
- "available. If the tools "
- "report that the repo has no index, tell the user to run "
- "'repowise init --yes --no-prose' in the repo root; it needs no API key "
- "and makes no model calls. Suggest it, "
- "do not run it yourself."
- ),
+ instructions=_instructions(),
lifespan=_lifespan,
)
_share_lifespan(mcp._mcp_server)
@@ -805,7 +821,8 @@ def create_mcp_server(
# surface before it can advertise (or trim) it.
ensure_full_surface()
- apply_tool_selection(mcp, repo_path=repo_path, override=tools)
+ enabled = apply_tool_selection(mcp, repo_path=repo_path, override=tools)
+ mcp._mcp_server.instructions = _instructions(enabled)
return mcp
@@ -1015,7 +1032,8 @@ def run_mcp(
from repowise.server.mcp_server._tool_selection import apply_tool_selection
ensure_full_surface()
- apply_tool_selection(mcp, repo_path=repo_path, override=tools)
+ enabled = apply_tool_selection(mcp, repo_path=repo_path, override=tools)
+ mcp._mcp_server.instructions = _instructions(enabled)
except BaseExceptionGroup as group:
_raise_group_leaf(group, transport)
diff --git a/tests/unit/server/mcp/test_server_instructions.py b/tests/unit/server/mcp/test_server_instructions.py
index d5899fceb..8bfb87ab5 100644
--- a/tests/unit/server/mcp/test_server_instructions.py
+++ b/tests/unit/server/mcp/test_server_instructions.py
@@ -6,6 +6,10 @@ truncate long instructions, so the guidance that matters is pinned here.
from __future__ import annotations
+from typing import Any
+
+import pytest
+
from repowise.server.mcp_server import mcp
# Well under the 2,000 chars some hosts keep.
@@ -29,7 +33,30 @@ def test_instructions_keep_the_no_index_and_workspace_guidance() -> None:
text = mcp.instructions
assert "repowise init --yes" in text
assert "do not run it yourself" in text
- assert "get_architecture" in text and "get_blast_radius" in text
+
+
[email protected](("override", "named"), [(None, False), ("all", True)])
+def test_workspace_tools_are_named_only_when_served(
+ tmp_path: Any, monkeypatch: Any, override: str | None, named: bool
+) -> None:
+ # Both are opt-in, so a default workspace server must not advertise them.
+ from repowise.server.mcp_server import _state, _tool_selection, create_mcp_server
+
+ monkeypatch.setattr(_tool_selection, "_is_workspace", lambda _path: True)
+ monkeypatch.setattr(_state, "_repo_path", _state._repo_path)
+ monkeypatch.setattr(_state, "_force_single_repo", _state._force_single_repo)
+ monkeypatch.setattr(mcp._mcp_server, "instructions", mcp.instructions)
+ try:
+ server = create_mcp_server(str(tmp_path), tools=override)
+ served = {t.name for t in server._tool_manager.list_tools()}
+ for tool in ("get_architecture", "get_blast_radius"):
+ assert (tool in served) is named
+ assert (tool in server.instructions) is named
+ assert len(server.instructions) < _MAX_INSTRUCTIONS_CHARS
+ finally:
+ if _tool_selection._full_surface is not None:
+ mcp._tool_manager._tools = dict(_tool_selection._full_surface)
+ _tool_selection._selected_surface = None
def test_handshake_reports_the_repowise_version_not_the_sdk_version() -> None: