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

[dgenio]

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