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}

Commencez par FuncMetadata.convert_result(), Tool.run(), ToolManager.call_tool() et MCPServer.call_tool() afin de retracer la chaîne de retour de l’outil et le flag convert_result. Examinez ensuite Prompt.fn, PromptResult et ResourceTemplate.matches() pour détecter les incohérences d’annotations indiquées. Le travail est terminé lorsque le pipeline de handlers possède des types publics exacts, que les chemins de typage obsolètes ou incorrects sont traités et que la gestion des valeurs de retour destinée aux utilisateurs est documentée.