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

Abierto
#2,202 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
48/100
Tipo de issue
Refactorización
Claridad
Bien especificado
Estado de actividad
Estancado
Stack tecnológico
python
Área
backend-api-design, documentation

Línea de trabajo

Empieza por FuncMetadata.convert_result(), Tool.run(), ToolManager.call_tool() y MCPServer.call_tool() para seguir la cadena de retorno de la herramienta y el indicador convert_result. Después, inspecciona Prompt.fn, PromptResult y ResourceTemplate.matches() en busca de las discrepancias de anotaciones indicadas. Se considerará terminado cuando la canalización de handlers tenga tipos públicos precisos, se hayan abordado las rutas de tipado obsoletas o incorrectas y esté documentado el manejo de los valores de retorno de cara al usuario.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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

Lenguaje dominante
Python
Estrellas
24.3k
Forks
4k
Merge medio
1 d 1 h
PR fusionados (30 d)
31

Guía de contribución

Abrir la guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de modelcontextprotocol/python-sdk

Todos los issues de modelcontextprotocol/python-sdk

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.