pydantic-models

Pydantic for FastMCP

Use Pydantic models for ALL tool inputs and outputs - never TypedDict, never dict[str, object]. This project has two distinct model families with different strictness, defined once in src/datadog_mcp/utils/response.py and reused everywhere. Getting the family right matters more than any single ConfigDict flag below.

The Two Model Families

Inbound: DatadogModel - tolerant, for parsing Datadog API responses

from datadog_mcp.utils.response import DatadogModel

class LogEntry(DatadogModel):
    """A single log entry, flattened from Datadog's {id, type, attributes} envelope."""
    id: str | None = None
    message: str | None = None
    timestamp: str | None = None

DatadogModel sets extra="ignore". Datadog can and does add new fields to API responses without notice; strict inbound validation would turn every such addition into a hard failure for this server. Never override this to extra="forbid" on an inbound model.

Outbound: ToolResponse / PaginatedListResponse - strict, for tool return values

from datadog_mcp.utils.response import ToolResponse, PaginatedListResponse, finalize_list_response

class GetLogDetailsResponse(ToolResponse):
    """Response for `get_log_details`."""
    log: LogEntry | None = None

class SearchLogsResponse(PaginatedListResponse):
    """Response for `search_logs`."""
    logs: list[LogEntry] = Field(default_factory=list)
    next_cursor: str | None = None
    has_more: bool = False

ToolResponse sets extra="forbid" and already declares success: bool = True and error: str | None = None. PaginatedListResponse additionally declares count, truncated, warning, total_available. This is data the server fully controls - every field must be declared up front, never injected ad-hoc at a call site (no response["extra_debug_field"] = ...).

Use PaginatedListResponse (not plain ToolResponse) for any response whose main payload is a single named list, then finalize it: