Refactor func_metadata() into smaller components for schema & metadata generation

Description

Summary

func_metadata() in src/mcp/server/fastmcp/utilities/func_metadata.py is a large function that handles:

• signature introspection,
• parameter/return type analysis,
• JSON schema generation,
• special handling for various container and model types.

This centralizes important logic, but its size and responsibility make it difficult to understand, test, and extend.

Problems

• Complexity: Many branching code paths for different types (Pydantic, dataclasses, TypedDict, primitives, etc.).
• Maintenance: Adding new type handling or fixing edge cases requires navigating a large function.
• Testing: Hard to write targeted tests for individual behaviors without exercising the entire function.

Proposal

1. Decompose into smaller functions

   For example:

   • extract_parameters(fn) -> list[Parameter]
   • build_arg_model(params) -> PydanticModel | None
   • build_output_model(return_type) -> PydanticModel | None
   • create_converters(...) -> Callable

2. Use a strategy/registry for type handling

   • Allow registering handlers for specific type families (Pydantic, TypedDict, dataclasses, etc.).
   • This reduces the need for a long series of if isinstance(...) checks in one place.

3. Add targeted unit tests

   • Test each helper independently, covering edge cases.
   • Keep some higher-level tests that ensure the overall metadata behavior remains consistent.

Why this matters

• Extensibility: Easier to support new type patterns without making func_metadata() even larger.
• Reliability: Smaller, well-tested pieces reduce the risk of regressions when making changes.
• Readability: Contributors can understand and modify the code more easily.

Acceptance criteria

• func_metadata() is decomposed into smaller, focused helpers.
• There is a clear extension mechanism for adding support for new types.
• Unit tests cover individual behaviors; existing integration tests still pass.

References

No response

Comece em src/mcp/server/fastmcp/utilities/func_metadata.py rastreando func_metadata() e seus caminhos de introspecção de assinatura, análise de tipos, geração de schema e conversão. Use os testes unitários e de integração existentes como baseline; em seguida, adicione cobertura focada para os helpers propostos e preserve o comportamento existente dos metadados, fornecendo ao mesmo tempo um mecanismo claro de extensão para novas famílias de tipos.