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}

FuncMetadata.convert_result()、Tool.run()、ToolManager.call_tool()、MCPServer.call_tool()から始めて、ツールの戻り値チェーンとconvert_resultフラグを追跡します。次に、Prompt.fn、PromptResult、ResourceTemplate.matches()を調べ、記載されているアノテーションの不一致を確認します。ハンドラーパイプラインの公開型が正確になり、不要または誤った型付けの経路に対処し、ユーザー向けの戻り値処理が文書化されていれば完了です。