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): advertise MCP tool annotations built from tool safety (#2762)
Kratos96809f2ac307
diff --git a/packages/core/src/repowise/core/registry/mcp_tool_registry.py b/packages/core/src/repowise/core/registry/mcp_tool_registry.pyindex 635fbac90..88278288e 100644--- a/packages/core/src/repowise/core/registry/mcp_tool_registry.py+++ b/packages/core/src/repowise/core/registry/mcp_tool_registry.py@@ -41,6 +41,25 @@ if TYPE_CHECKING:TOOL_TIERS = frozenset({"canonical", "utility", "specialist"})TOOL_SAFETY_KINDS = frozenset({"read_only", "generative", "mutating"})+# MCP annotation hints per tool safety kind, expressed as plain keyword+# arguments for ``ToolAnnotations``. Kept as dicts (not ``ToolAnnotations``+# instances) because this module lives in ``packages/core``, which does not+# declare the ``mcp`` SDK; the surface layer materialises them with the real+# import and hands the result to :meth:`MCPToolRegistry.apply` via+# ``annotations_for``. ``generative`` tools leave the repository untouched+# but call an external provider (``openWorldHint``), while ``mutating`` tools+# replace earlier decisions, so clients should confirm them+# (``destructiveHint``) even though repeating the same write is idempotent.+SAFETY_TO_ANNOTATION_HINTS: dict[str, dict[str, bool]] = {+ "read_only": {"readOnlyHint": True, "openWorldHint": False},+ "generative": {"readOnlyHint": True, "openWorldHint": True},+ "mutating": {+ "readOnlyHint": False,+ "destructiveHint": True,+ "idempotentHint": True,+ },+}+@dataclass(frozen=True)class ToolRecipe:@@ -176,6 +195,7 @@ class MCPToolRegistry:self,mcp: Any,middleware: Callable[[Callable[..., Any]], Callable[..., Any]] | None = None,+ annotations_for: Callable[[str], Any] | None = None,) -> None:"""Attach every registered tool to *mcp* via ``mcp.tool()``.@@ -189,12 +209,22 @@ class MCPToolRegistry:this way so the registry stays decoupled from it. A signature-preserving wrapper is the caller's responsibility (FastMCP readseach tool's signature to build its schema). Defaults to identity.++ *annotations_for*, when given, maps a tool's safety kind to the+ ``ToolAnnotations`` object the surface layer built from+ :data:`SAFETY_TO_ANNOTATION_HINTS`; returning ``None`` registers+ the tool without annotations."""if mcp in self._applied_to:returnfor entry in self._entries:wrapped = middleware(entry.fn) if middleware is not None else entry.fn- mcp.tool()(wrapped)+ kwargs: dict[str, Any] = {}+ if annotations_for is not None:+ annotations = annotations_for(entry.safety)+ if annotations is not None:+ kwargs["annotations"] = annotations+ mcp.tool(**kwargs)(wrapped)self._applied_to.append(mcp)def reset(self) -> None:diff --git a/packages/server/src/repowise/server/mcp_server/__init__.py b/packages/server/src/repowise/server/mcp_server/__init__.pyindex 73fd53388..e84441661 100644--- a/packages/server/src/repowise/server/mcp_server/__init__.py+++ b/packages/server/src/repowise/server/mcp_server/__init__.py@@ -297,12 +297,21 @@ def ensure_full_surface() -> Any:exc,)+ # The mcp SDK lives above packages/core, so the registry stores plain+ # hint dicts and this surface materialises them into ToolAnnotations.+ from mcp.types import ToolAnnotations+from repowise.core.registry import mcp_tool_registry+ from repowise.core.registry.mcp_tool_registry import SAFETY_TO_ANNOTATION_HINTSfrom repowise.core.registry.plugins import load_pluginsfrom repowise.server.mcp_server._tool_selection import snapshot_full_surfaceload_plugins() # plugin tools register before the surface is attached- mcp_tool_registry.apply(_mcp, middleware=registered_tool)+ mcp_tool_registry.apply(+ _mcp,+ middleware=registered_tool,+ annotations_for=lambda safety: ToolAnnotations(**SAFETY_TO_ANNOTATION_HINTS[safety]),+ )# Snapshot the full registered surface so per-server tool selection# (single-repo vs workspace, config/CLI overrides) can rebuild from it.diff --git a/pyproject.toml b/pyproject.tomlindex 43c3d1e8a..1a47d3270 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -99,7 +99,7 @@ dependencies = [# Server"fastapi>=0.115,<1","uvicorn[standard]>=0.32,<1",- "mcp>=1.0,<2",+ "mcp>=1.7,<2","apscheduler>=3.10,<4","cryptography>=50.0.0,<51",# LLM providers (bundled — no extras needed)diff --git a/tests/unit/registry/test_mcp_tool_registry.py b/tests/unit/registry/test_mcp_tool_registry.pyindex 9c508cd2b..62ff8c260 100644--- a/tests/unit/registry/test_mcp_tool_registry.py+++ b/tests/unit/registry/test_mcp_tool_registry.py@@ -10,12 +10,15 @@ from repowise.core.registry import MCPToolRegistryclass _FakeMCP:- """Minimal stand-in for FastMCP — captures ``mcp.tool()(fn)`` calls."""+ """Minimal stand-in for FastMCP — captures ``mcp.tool(**kw)(fn)`` calls."""def __init__(self) -> None:self.registered: list[Any] = []+ self.registration_kwargs: list[dict[str, Any]] = []++ def tool(self, **kwargs: Any) -> Any:+ self.registration_kwargs.append(kwargs)- def tool(self) -> Any:def _decorator(fn: Any) -> Any:self.registered.append(fn)return fn@@ -111,6 +114,72 @@ def test_reset_clears_tools(registry):assert registry.tools() == []+def test_apply_passes_annotations_per_safety_kind(registry):+ from mcp.types import ToolAnnotations++ from repowise.core.registry.mcp_tool_registry import SAFETY_TO_ANNOTATION_HINTS++ @registry.register(safety="read_only")+ async def reader() -> dict:+ return {}++ @registry.register(safety="generative")+ async def generator() -> dict:+ return {}++ @registry.register(safety="mutating")+ async def mutator() -> dict:+ return {}++ mcp = _FakeMCP()+ registry.apply(+ mcp,+ annotations_for=lambda safety: ToolAnnotations(**SAFETY_TO_ANNOTATION_HINTS[safety]),+ )++ by_tool = dict(+ zip(+ [fn.__name__ for fn in mcp.registered],+ mcp.registration_kwargs,+ strict=True,+ )+ )+ assert by_tool["reader"]["annotations"] == ToolAnnotations(+ readOnlyHint=True, openWorldHint=False+ )+ assert by_tool["generator"]["annotations"] == ToolAnnotations(+ readOnlyHint=True, openWorldHint=True+ )+ assert by_tool["mutator"]["annotations"] == ToolAnnotations(+ readOnlyHint=False, destructiveHint=True, idempotentHint=True+ )+++def test_apply_annotations_reach_a_real_fastmcp_server(registry):+ from mcp.server.fastmcp import FastMCP+ from mcp.types import ToolAnnotations++ @registry.register(safety="mutating")+ async def set_finding_status() -> dict:+ return {}++ server = FastMCP("test")+ from repowise.core.registry.mcp_tool_registry import SAFETY_TO_ANNOTATION_HINTS++ registry.apply(+ server,+ annotations_for=lambda safety: ToolAnnotations(**SAFETY_TO_ANNOTATION_HINTS[safety]),+ )++ import asyncio++ tools = asyncio.run(server.list_tools())+ tool = next(t for t in tools if t.name == "set_finding_status")+ assert tool.annotations is not None+ assert tool.annotations.readOnlyHint is False+ assert tool.annotations.destructiveHint is True++def test_register_stores_available_when_as_is(registry):def needs_flows(facts) -> bool:return facts.counts.get("flows", 0) > 0diff --git a/uv.lock b/uv.lockindex c1fd1b8c1..512b7688b 100644--- a/uv.lock+++ b/uv.lock@@ -3225,7 +3225,7 @@ requires-dist = [{ name = "jinja2", specifier = ">=3.1,<4" },{ name = "lancedb", specifier = ">=0.12,<1" },{ name = "litellm", specifier = ">=1.90.7,<2" },- { name = "mcp", specifier = ">=1.0,<2" },+ { name = "mcp", specifier = ">=1.7,<2" },{ name = "mypy", marker = "extra == 'dev'", specifier = ">=1.11,<2" },{ name = "networkx", specifier = ">=3.3,<4" },{ name = "openai", specifier = ">=1.50,<3" },