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): 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.py
index 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 reads
each 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:
return
for 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__.py
index 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_HINTS
from repowise.core.registry.plugins import load_plugins
from repowise.server.mcp_server._tool_selection import snapshot_full_surface
load_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.toml
index 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.py
index 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 MCPToolRegistry
class _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) > 0
diff --git a/uv.lock b/uv.lock
index 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" },