Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 33 additions & 12 deletions TCT/interfaces/mcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,9 @@
from typing import Any

from fastmcp import FastMCP
from fastmcp.exceptions import ToolError
from fastmcp.server.middleware import Middleware, MiddlewareContext
from fastmcp.tools.tool import ToolResult
from mcp import types as mcp_types
from mcp.shared.exceptions import McpError
from mcp.types import INTERNAL_ERROR, ErrorData

from . import tools as shared_tools
from .invocation import ToolInvocationError, invoke as invoke_tool
Expand All @@ -26,6 +24,28 @@

mcp = FastMCP("TCT")

# Tools that only read data or produce derived copies; everything else may
# mutate the metadata structures passed in. All tools reach out to network
# services, so openWorldHint is always true.
_READ_ONLY_TOOLS = frozenset(
{
"get_translator_resources",
"name_lookup",
"get_name_synonyms",
"batch_name_lookup",
"normalize_nodes",
"get_kp_info",
"get_metakg_data",
"get_api_predicates",
"optimize_query_for_api",
"query_knowledge_provider",
"parallel_query_apis",
"trapi_query_endpoint",
"neighborhood_finder",
"path_finder",
}
)


def _metadata_mapping(value: Any) -> dict[str, Any]:
"""Convert protocol metadata to an ordinary mapping, preserving extras."""
Expand All @@ -42,7 +62,7 @@ class _TraceContextMiddleware(Middleware):

async def on_call_tool(
self,
context: MiddlewareContext[mcp_types.CallToolRequestParams],
context: MiddlewareContext,
call_next: Any,
) -> ToolResult:
message = context.message
Expand Down Expand Up @@ -75,14 +95,15 @@ def invoke(*args: Any, **kwargs: Any) -> Any:
try:
return invoke_tool(tool, *args, _interface="mcp", **kwargs)
except ToolInvocationError as error:
raise McpError(
ErrorData(
code=INTERNAL_ERROR,
message=error.contextual_message,
)
) from error

return mcp.tool()(invoke)
# FastMCP converts ToolError into a protocol-level tool error result
# carrying the contextual message.
raise ToolError(error.contextual_message) from error

annotations = {
"readOnlyHint": tool.__name__ in _READ_ONLY_TOOLS,
"openWorldHint": True,
}
return mcp.tool(annotations=annotations)(invoke)


for _tool in shared_tools.TOOLS:
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ vision = [
"seaborn",
]
mcp = [
"fastmcp>=2.12.2",
"fastmcp>=2.14.7,<3",
]
langfuse = [
"langfuse>=3.63.0",
Expand Down
80 changes: 68 additions & 12 deletions tests/test_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -44,23 +44,25 @@ def test_server_module_is_a_compatible_view_of_the_mcp_adapter():


def test_mcp_adapter_preserves_protocol_error_conversion(monkeypatch):
"""Failures from shared tools remain MCP internal errors for clients."""
from mcp.shared.exceptions import McpError
from mcp.types import INTERNAL_ERROR
"""Failures from shared tools surface as ToolError with contextual messages."""
from fastmcp import Client
from fastmcp.exceptions import ToolError

from TCT.interfaces import tools
from TCT.server import name_lookup

def fail_lookup(*args, **kwargs):
raise ValueError("lookup failed")

monkeypatch.setattr(tools, "lookup", fail_lookup)

with pytest.raises(McpError) as error:
asyncio.run(name_lookup.run({"query": "aspirin"}))
async def call_it():
async with Client(mcp) as client:
await client.call_tool("name_lookup", {"query": "aspirin"})

assert error.value.error.code == INTERNAL_ERROR
assert error.value.error.message == "Name lookup error: lookup failed"
with pytest.raises(ToolError) as error:
asyncio.run(call_it())

assert str(error.value) == "Name lookup error: lookup failed"


def test_mcp_adapter_uses_shared_invocation_boundary(monkeypatch):
Expand Down Expand Up @@ -97,12 +99,21 @@ def test_mcp_middleware_restores_protocol_context_without_schema_arguments(
):
"""Trace metadata surrounds dispatch and never reaches the shared tool."""
from fastmcp.server.middleware import MiddlewareContext
from mcp.types import CallToolRequestParams

from TCT.interfaces import mcp as adapter

calls = []

class FakeParams:
"""Stand-in for the protocol params object, without importing mcp types."""

def __init__(self, arguments, meta=None):
self.arguments = arguments
self.meta = meta

def model_copy(self, *, update=None):
return FakeParams(update.get("arguments", self.arguments), self.meta)

@contextmanager
def fake_trace_context(metadata):
calls.append(("enter", metadata))
Expand All @@ -116,8 +127,7 @@ async def call_next(context):
return "result"

monkeypatch.setattr(adapter, "use_incoming_trace_context", fake_trace_context)
params = CallToolRequestParams(
name="name_lookup",
params = FakeParams(
arguments={
"query": "aspirin",
"_meta": {
Expand All @@ -127,7 +137,7 @@ async def call_next(context):
)
},
},
_meta={"baggage": "session.id=conversation-123"},
meta={"baggage": "session.id=conversation-123"},
)

result = asyncio.run(
Expand Down Expand Up @@ -161,3 +171,49 @@ async def call_next(context):
},
),
]

def test_shared_tools_carry_protocol_annotations():
"""Tool annotations disclose read-only behavior to clients."""
from TCT.interfaces.mcp import _READ_ONLY_TOOLS

async def collect():
return await mcp.get_tools()

tools = asyncio.run(collect())

assert tools["name_lookup"].annotations.readOnlyHint is True
assert tools["add_custom_api_to_metakg"].annotations.readOnlyHint is False
assert all(
tool.annotations.openWorldHint is True for tool in tools.values()
)
assert set(tools) - _READ_ONLY_TOOLS == {
"add_custom_api_to_metakg",
"add_plover_apis_to_metakg",
}

def test_fastmcp_background_task_protocol_is_available():
"""The pinned fastmcp registers async task tools with SEP-1686 metadata."""
from fastmcp import Client, FastMCP
from fastmcp.server.tasks import TaskConfig

server = FastMCP("task-smoke")

@server.tool(task=TaskConfig(mode="optional"))
async def slow_work(n: int = 1) -> str:
return "done" * n

async def run_it():
tool = await server.get_tool("slow_work")
async with Client(server) as client:
task = await client.call_tool("slow_work", {"n": 2}, task=True)
result = await task.result()
status = await client.get_task_status(task.task_id)
return tool, result, status

tool, result, status = asyncio.run(run_it())

assert tool.task_config is not None
assert tool.task_config.mode == "optional"
assert result.is_error is False
assert result.data == "donedone"
assert status.status == "completed"
Loading
Loading