Type the MCPServer handler pipeline: tool/resource/prompt return types

The chain from user @tool()-decorated functions through to CallToolResult is typed as Any end-to-end, hiding a wrong public return type and dead code.

Tool call chain

FuncMetadata.convert_result() returns exactly three shapes:

• CallToolResult (when the user returned one directly)
• Sequence[ContentBlock] (unstructured)
• tuple[Sequence[ContentBlock], dict[str, Any]] (unstructured + structured)

But every step of the chain is -> Any:

• FuncMetadata.convert_result() — -> Any
• Tool.run() — -> Any
• ToolManager.call_tool() — -> Any
• MCPServer.call_tool() — declared -> Sequence[ContentBlock] | dict[str, Any], wrong — never returns dict

Root cause: the convert_result: bool flag on Tool.run() / ToolManager.call_tool() toggles the return type, which is unrepresentable. The False path isn't used in production (only server.py:405, always True).

Symptoms:

• Dead code + TODO acknowledging the wrong type at server.py:317-324
• # type: ignore[arg-type] shoving tuple elements into CallToolResult at server.py:314-315

Prompt / Resource

• PromptResult already includes Awaitable, but Prompt.fn is typed Callable[..., PromptResult | Awaitable[PromptResult]] — doubly wrapped
• ResourceTemplate.matches() returns dict[str, Any] | None but values are always str (regex groupdict + unquote)

User-facing return types

What you can return from @tool() is undocumented. A strict bound is impossible (_convert_to_content() ends with pydantic_core.to_json(fallback=str) — everything works), but the docstrings should enumerate what gets first-class handling (str/primitives/BaseModel/ContentBlock/Image/Audio/CallToolResult/list/tuple) vs what gets JSON-dumped.

Related

• #1207 — excessive generics (reason to not introduce Tool[ReturnT]; a TypeAlias for the converted result is sufficient)
• #2153 — handler error semantics
• #2201 — Tasks support (adds CreateTaskResult to the converted-result union)

_{AI Disclaimer}

Bắt đầu với FuncMetadata.convert_result(), Tool.run(), ToolManager.call_tool() và MCPServer.call_tool() để lần theo chuỗi giá trị trả về của công cụ và flag convert_result. Sau đó kiểm tra Prompt.fn, PromptResult và ResourceTemplate.matches() để tìm các điểm không khớp về annotation đã nêu. Công việc được xem là hoàn tất khi pipeline handler có các kiểu public chính xác, các đường dẫn typing không còn dùng hoặc không đúng đã được xử lý và cách xử lý giá trị trả về hướng đến người dùng đã được ghi lại.