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

Aberta
#2,202 0 comentários 0 reações 0 responsáveis Ver no GitHub

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
48/100
Tipo de issue
Refatoração
Clareza
Claramente especificada
Status de atividade
Estagnada
Stack de tecnologia
python
Domínio
backend-api-design, documentation

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

enhancement v2

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:

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:

Prompt / Resource

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

Linguagem predominante
Python
Estrelas
24.3k
Forks
4k
Merge médio
1d 1h
PRs com merge (30d)
31

Guia de contribuição

Abrir o guia de contribuição

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de modelcontextprotocol/python-sdk

Todas as issues de modelcontextprotocol/python-sdk

Issues semelhantes

Mais issues de Python

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.