Handling Pydantic Models and YAML Redundancy in MXCP

[bgaidioz]

In MXCP, type conversion is implemented in both directions between MCP and Python functions. When Python functions use Pydantic models for typing, the .yml content often feels redundant: models already define descriptions, examples, and default values directly in Python.

Current Behavior

MXCP currently ignores Pydantic models declared in the Python code. Instead, it advertises types to FastMCP using Pydantic models generated from the .yml content. This approach fails in both directions today.

def process_user(user: UserModel) -> ResponseModel:
    # user is expected to be an instance of UserModel

The function above expects a UserModel input and returns a ResponseModel, but MXCP disregards these. It forges models from the YAML specification and passes them to FastMCP. When the tool is called, FastMCP converts JSON into this forged input model, which does not match the Python model. Similarly, when the Python function returns its own model, it doesn’t match the YAML-forged output model either.

A PR attempts to fix this.

However, the redundancy issue and the fact that MXCP discards Python-declared models still remain.

The Redundancy Problem

When Python code uses type annotations with Pydantic models (including descriptions, examples, and default parameter values), specifying the same information again in .yml is redundant and error-prone. Any change to the Python code must also be manually reflected in .yml.

That said, there are valid reasons why the YAML specification might diverge from the Pydantic model:

• Different descriptions. The description shown to an LLM (MCP tool) may differ from the one suitable for code documentation.
  • Pydantic: minDate: "minimum date for search"
  • MCP tool: minDate: "minimum date for search. Note that no items were registered after 2024-11-30."
• Pagination parameters. YAML might include richer usage guidance.
  • Pydantic: cursor: "cursor to start from"
  • MCP tool: cursor: "cursor to start from, as returned by tool query(..). Call 'query' to prepare results."
• Top-level examples. MCP (via JSON Schema) supports full example calls and results, which Pydantic does not natively support.
• Type differences. The MCP-facing type may be more LLM-friendly.
  • Pydantic: minTime: datetime.datetime
  • MCP tool: minTime: string-format-datetime or "now" or "today" or "yesterday" → These values could be converted to real datetimes by MXCP before calling the Python function.
• Different defaults. The tool might have an MCP-level default distinct from the developer’s model default.
• Alternate input formats. For example, the tool might accept a comma-separated list or a list, while the Python model expects a strict List[str].
• Output redaction. The MCP tool output might intentionally differ from the Python model’s output.

Proposed Behavior

As a user, I wouldn’t expect Python models to be ignored. A reasonable approach could be that MXCP takes Python type annotations into account first, and then allows the .yml to override selectively, e.g. rewriting description, type, or default only where explicitly specified.

That way, .yml could complement, not duplicate, the information already defined in Python.

DuckDB tools do not support annotations.