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

Bắt đầu trong src/mcp/server/fastmcp/utilities/func_metadata.py bằng cách lần theo func_metadata() cùng với các đường dẫn introspection chữ ký, phân tích kiểu, tạo schema và chuyển đổi của nó. Sử dụng các bài kiểm thử unit và integration hiện có làm baseline, sau đó bổ sung coverage tập trung cho các helper được đề xuất và duy trì hành vi metadata hiện có, đồng thời cung cấp một cơ chế mở rộng rõ ràng cho các họ kiểu mới.

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