oas2mcp.agent.summarizer.models

Structured output models for the catalog summarizer agent.

Purpose:

Define agent-facing structured output models for summarizing an API catalog as a whole before introducing per-operation enhancement agents.

Design:

• Use concise, typed structures that an agent can reliably fill.

• Emphasize purpose, conceptual structure, domains, and data model before operational concerns like authentication or MCP surface design.

• Keep these models specific to the summarizer workflow.

Examples

summary = CatalogSummary(
    catalog_name="Petstore",
    api_purpose="Manage pets, store orders, and users.",
    conceptual_overview="A demo REST API organized around pets, store operations, and users.",
    data_model_summary="The core schemas are Pet, User, Order, and ApiResponse.",
    data_flow_summary="The API supports both reads and mutations across core domains.",
    authentication_summary="OAuth2 and API key auth are present.",
    recommended_mcp_surface="Mostly tools with a few read-oriented resources.",
)

Classes

CatalogSummary	Structured overall summary of a normalized API catalog.
CatalogTagSummary	Structured summary for one API tag or domain.

Module Contents

class oas2mcp.agent.summarizer.models.CatalogSummary(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Structured overall summary of a normalized API catalog.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

summary = CatalogSummary(
    catalog_name="Petstore",
    api_purpose="Manage pets, orders, and users.",
    conceptual_overview="A demo REST API organized around three domains.",
    data_model_summary="The main schemas are Pet, User, Order, and ApiResponse.",
    data_flow_summary="Supports both reads and mutations across core domains.",
    authentication_summary="OAuth2 and API key auth are present.",
    recommended_mcp_surface="Use tools for actions and selected resources for reads.",
)

api_purpose: str

authentication_summary: str

catalog_name: str

conceptual_overview: str

data_flow_summary: str

data_model_summary: str

notes: list[str] = None

operational_notes: list[str] = None

primary_domains: list[CatalogTagSummary] = None

recommended_mcp_surface: str

suggested_resource_domains: list[str] = None

suggested_tool_domains: list[str] = None

class oas2mcp.agent.summarizer.models.CatalogTagSummary(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Structured summary for one API tag or domain.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

tag_summary = CatalogTagSummary(
    tag_name="pet",
    description="Operations for pet records and media.",
    operation_count=8,
)

description: str

mutating_operation_count: int = 0

notable_operations: list[str] = None

operation_count: int = 0

read_operation_count: int = 0

tag_name: str