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.

10.4 KB
Raw Blame
"""What each tool actually puts on the wire, pinned at the serialization seam.

Every other budget and projection suite in this directory asserts on the
Python dict a tool returns. Nothing asserted on what the MCP SDK then makes of
that dict, so the step a client actually reads had no test at all.

It is worth pinning because the wire does not match what the tool definitions
suggest. ``func_metadata`` builds a tool's output schema from the return
annotation of the callable it is handed, resolving it with
``inspect.signature(func, eval_str=True)``. It never gets to resolve anything
here. Three middleware layers preserve the tool's signature by snapshotting
``__signature__`` — ``_failure_shield.py`` innermost, then ``_rounding.py``
and ``_savings/wrapper.py`` — and each takes that snapshot with ``eval_str``
left at its default, so the annotations in it stay unevaluated strings.
``inspect.signature`` returns a pre-built ``__signature__`` verbatim and
ignores ``eval_str``, and ``functools.wraps`` copies the attribute outward, so
every layer carries it. The SDK therefore sees the *string* ``"dict"``, which
matches none of its cases and falls through to the catch-all that wraps the
payload.

Because all three snapshot the same way, removing any one of them changes
nothing; the behaviour only moves if none of them is left.

So every tool serves ``structuredContent`` as ``{"result": <payload>}``, and
two things follow that are not legible from the tool definitions:

* every tool serves both representations, so every payload crosses the wire
  twice;
* the tools that declare ``-> dict[str, Any]`` in order to serve a bare
  structured payload do not get one, and are served exactly like the ones
  declaring ``-> dict``.

The second point is what makes these tests worth having. Let the annotations
resolve and the bare-``dict`` tools serve **no** ``structuredContent`` at all
while the parameterized ones serve an unwrapped payload. That is a silent
change to every client, reachable from an edit that looks like typing or
signature hygiene, in modules none of these tools mention.

The seam under test is ``FuncMetadata.convert_result``, which is what
``FastMCP.call_tool`` uses to build the ``CallToolResult``. It reads only the
callable's signature, so these tests need no index, no fixture and no I/O.
The registered callable hands it a ``CallToolResult`` already built by
``wire_result`` (compact text, the same structured copy), which it validates
against the output schema and passes through.
"""

from __future__ import annotations

import inspect
import json

import pytest
from mcp.server.fastmcp.utilities.func_metadata import func_metadata
from mcp.types import CallToolResult

from repowise.core.registry import mcp_tool_registry

# The registered surface. Pinned as a count because `ensure_full_surface`
# swallows a per-module ImportError and only logs it: a tool module that stops
# importing would quietly drop out of the registry, shrinking what the loops
# below cover while leaving them green.
EXPECTED_TOOL_COUNT = 18

# A payload shaped like a real tool reply: str keys, nested containers and a
# `_meta` envelope. Any mapping validates against the SDK's wrapping model, so
# this exercises serialization rather than any one tool's own schema.
SAMPLE_PAYLOAD = {
    "answer": "resolved in one call",
    "citations": ["packages/core/src/repowise/core/ingestion/parser.py"],
    "rows": [{"path": "a/b.py", "lines": [10, 20]}],
    "_meta": {"timing_ms": 1.5, "complete": "1 body served whole"},
}


def _registry_entries():
    """The bare tool functions, in name order."""
    from repowise.server.mcp_server import ensure_full_surface

    ensure_full_surface()
    tools = mcp_tool_registry.tools()
    assert tools, "tool registry is empty — ensure_full_surface broken?"
    return sorted(tools, key=lambda fn: fn.__name__)


def _registered_callables():
    """What the server hands FastMCP, not the bare tool functions.

    `mcp_tool_registry.apply` registers `middleware(entry.fn)`, so building a
    schema from the bare function measures something the client never sees.
    """
    from repowise.server.mcp_server import registered_tool

    return [registered_tool(fn) for fn in _registry_entries()]


def _convert(fn):
    """Return ``(text_blocks, structured_or_None)`` exactly as the server would."""
    from repowise.server.mcp_server import wire_result

    result = func_metadata(fn).convert_result(wire_result(dict(SAMPLE_PAYLOAD)))
    if isinstance(result, CallToolResult):
        return list(result.content), result.structuredContent
    if isinstance(result, tuple):
        blocks, structured = result
        return list(blocks), structured
    return list(result), None


def test_the_whole_registered_surface_is_under_test():
    """Guard the loops below against silently covering fewer tools."""
    names = [fn.__name__ for fn in _registry_entries()]
    assert len(names) == EXPECTED_TOOL_COUNT, (
        f"expected {EXPECTED_TOOL_COUNT} registered tools, found {len(names)}: "
        f"{names}. A tool module failing to import is logged and skipped, so a "
        "shrinking surface otherwise leaves this file green while testing less."
    )


def test_every_tool_serves_a_readable_text_representation():
    """No client loses access to a usable response, whatever it consumes.

    The text block is the representation every MCP client is guaranteed, so it
    has to be present, non-empty, and a faithful rendering of what the tool
    returned rather than a summary or a repr.
    """
    broken = {}
    for fn in _registered_callables():
        blocks, _structured = _convert(fn)
        if not blocks or not (blocks[0].text or "").strip():
            broken[fn.__name__] = "no usable text block"
            continue
        try:
            if json.loads(blocks[0].text) != SAMPLE_PAYLOAD:
                broken[fn.__name__] = "text block is not a faithful rendering"
        except json.JSONDecodeError:
            broken[fn.__name__] = "text block is not valid JSON"
    assert not broken, (
        f"tools whose text representation a client could not use: {broken}. "
        "Every client is guaranteed the text block and nothing else."
    )


def test_every_tool_serves_structured_content_wrapped_in_result():
    """The structured half of the envelope, and the shape clients must unwrap.

    A consumer of structured output reads ``structuredContent["result"]``, not
    ``structuredContent``. Both facts are pinned so that changing either is a
    deliberate, reviewed wire change rather than a side effect.

    A failure here is far more likely to come from the installed SDK version
    or from the ``__signature__`` snapshots described in the module docstring
    than from the named tool, so check those before the tool.
    """
    wrong = {}
    for fn in _registered_callables():
        blocks, structured = _convert(fn)
        if structured is None:
            wrong[fn.__name__] = "serves no structuredContent at all"
        elif set(structured) != {"result"}:
            wrong[fn.__name__] = f"keyed {sorted(structured)}, not ['result']"
        elif structured["result"] != json.loads(blocks[0].text):
            wrong[fn.__name__] = "structured and text representations disagree"
    assert not wrong, (
        f"structured output moved: {wrong}. Suspect, in order: the installed "
        "mcp version, the __signature__ snapshots in _failure_shield.py / "
        "_rounding.py / _savings/wrapper.py, then the tool itself."
    )


def test_declared_structured_annotations_do_not_reach_the_wire():
    """The declared return type is not what the SDK sees, and this records it.

    Some tools declare ``-> dict[str, Any]`` to serve a bare structured
    payload. The registered callable presents its annotations unevaluated, so
    the declaration never matches and their output is wrapped like everything
    else — it is inert.

    The declaring set is derived from the source rather than listed here, so
    that a tool added to or removed from it cannot make the module docstring
    quietly untrue. This exists to fail the moment the declaration starts
    mattering, not to endorse it.
    """
    declaring = sorted(
        fn.__name__
        for fn in _registry_entries()
        if "dict[" in str(fn.__annotations__.get("return", ""))
    )
    assert declaring, (
        "no tool declares a parameterized return annotation any more; the "
        "module docstring's account of an inert declaration is now stale."
    )
    registered = {fn.__name__: fn for fn in _registered_callables()}
    reaching = {}
    for name in declaring:
        annotation = inspect.signature(registered[name], eval_str=True).return_annotation
        if not isinstance(annotation, str):
            reaching[name] = repr(annotation)
    assert not reaching, (
        f"these tools now expose an evaluated return annotation: {reaching}. "
        "Their structuredContent is no longer wrapped in 'result', and every "
        "tool declaring a bare `dict` has stopped serving structuredContent "
        "entirely. That is a wire change for every client."
    )


def test_every_tool_serves_compact_text():
    """The text block is what a text-forwarding client hands its model."""
    expected = json.dumps(SAMPLE_PAYLOAD, separators=(",", ":"))
    loose = {}
    for fn in _registered_callables():
        blocks, _structured = _convert(fn)
        if blocks[0].text != expected or "\n" in blocks[0].text:
            loose[fn.__name__] = blocks[0].text[:80]
    assert not loose, f"text blocks carry indentation or spacing: {loose}"


def test_pretty_json_env_restores_the_indented_text(monkeypatch):
    from repowise.server.mcp_server import PRETTY_JSON_ENV

    monkeypatch.setenv(PRETTY_JSON_ENV, "1")
    blocks, structured = _convert(_registered_callables()[0])

    assert blocks[0].text.startswith('{\n  "answer"')
    assert structured == {"result": SAMPLE_PAYLOAD}


@pytest.mark.asyncio
async def test_only_the_registered_callable_changes_shape():
    """Tests and the CLI await the middleware-wrapped tool and need the dict."""
    from repowise.server.mcp_server import registered_tool, tool_middleware

    async def get_risk(targets: list[str]) -> dict:
        return {"targets": {}, "_meta": {}}

    bare = await tool_middleware(get_risk)(["a.py"])
    served = await registered_tool(get_risk)(["a.py"])

    assert isinstance(bare, dict)
    assert isinstance(served, CallToolResult)
    assert json.loads(served.content[0].text) == bare
    assert served.structuredContent == {"result": bare}