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}

Comece por FuncMetadata.convert_result(), Tool.run(), ToolManager.call_tool() e MCPServer.call_tool() para rastrear a cadeia de retorno da ferramenta e o flag convert_result. Em seguida, inspecione Prompt.fn, PromptResult e ResourceTemplate.matches() em busca das incompatibilidades de anotações mencionadas. Está concluído quando o pipeline de handlers tiver tipos públicos precisos, os caminhos de tipagem obsoletos ou incorretos tiverem sido tratados e o tratamento dos valores de retorno voltado ao usuário estiver documentado.