oas2mcp.agent.summarizer.context

Deterministic context builders for the catalog summarizer agent.

Purpose:

Build compact, structured context objects for the catalog-level summarizer agent using normalized catalogs and optional MCP candidate bundles.

Design:

• Keep context building deterministic and side-effect free.

• Emphasize the API’s purpose, conceptual structure, domains, data model, and request/response patterns.

• Preserve lightweight operational and MCP-oriented signals without letting them dominate the summarizer’s input.

• Support summarization with or without a classified MCP bundle.

Examples

context = build_catalog_summary_context(catalog, bundle=bundle)
print(context.catalog_name)
print(context.primary_schema_refs[0].schema_ref)

Classes

CandidateExample	Compact MCP candidate example for summarizer input.
CatalogSecuritySchemeContext	Compact security scheme context for summarizer input.
CatalogSummaryContext	Compact agent-facing context for catalog-level summarization.
CatalogTagContext	Deterministic tag/domain context for summarizer input.
SchemaRefSummary	Compact rollup for frequently referenced schema refs.

Functions

build_catalog_summary_context(→ CatalogSummaryContext)

Build deterministic summarizer context for an API catalog.

Module Contents

class oas2mcp.agent.summarizer.context.CandidateExample(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Compact MCP candidate example for summarizer input.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

candidate = CandidateExample(
    operation_key="GET /pets/{id}",
    operation_slug="get-pet-by-id",
    kind="resource",
    title="Get pet by ID",
    safety_level="safe_read",
)

kind: str

operation_key: str

operation_slug: str

resource_uri: str | None = None

safety_level: str

title: str

tool_name: str | None = None

class oas2mcp.agent.summarizer.context.CatalogSecuritySchemeContext(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Compact security scheme context for summarizer input.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

scheme = CatalogSecuritySchemeContext(
    name="api_key",
    type="apiKey",
    location="header",
    parameter_name="X-API-Key",
)

bearer_format: str | None = None

flow_names: list[str] = None

location: str | None = None

name: str

parameter_name: str | None = None

scheme: str | None = None

type: str

class oas2mcp.agent.summarizer.context.CatalogSummaryContext(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Compact agent-facing context for catalog-level summarization.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

context = CatalogSummaryContext(
    catalog_name="Petstore",
    catalog_slug="petstore",
    source_uri="https://example.com/openapi.json",
)

candidate_count: int = 0

candidate_kind_counts: dict[str, int] = None

candidate_safety_counts: dict[str, int] = None

catalog_name: str

catalog_slug: str

component_counts: dict[str, int] = None

deprecated_operation_count: int = 0

destructive_operation_count: int = 0

info_description: str | None = None

info_summary: str | None = None

info_title: str | None = None

info_version: str | None = None

mutating_operation_count: int = 0

notable_mutating_operations: list[str] = None

notable_operations: list[str] = None

notable_read_operations: list[str] = None

openapi_version: str | None = None

operation_count: int = 0

primary_schema_refs: list[SchemaRefSummary] = None

read_operation_count: int = 0

request_schema_refs: list[SchemaRefSummary] = None

response_schema_refs: list[SchemaRefSummary] = None

sample_resource_candidates: list[CandidateExample] = None

sample_tool_candidates: list[CandidateExample] = None

security_schemes: list[CatalogSecuritySchemeContext] = None

server_urls: list[str] = None

source_uri: str

tag_summaries: list[CatalogTagContext] = None

class oas2mcp.agent.summarizer.context.CatalogTagContext(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Deterministic tag/domain context for summarizer input.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

tag_context = CatalogTagContext(
    tag_name="pet",
    description="Everything about your Pets",
    operation_count=8,
)

description: str

mutating_operation_count: int = 0

notable_operations: list[str] = None

operation_count: int = 0

operation_ids: list[str] = None

operation_keys: list[str] = None

read_operation_count: int = 0

tag_name: str

class oas2mcp.agent.summarizer.context.SchemaRefSummary(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Compact rollup for frequently referenced schema refs.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

summary = SchemaRefSummary(
    schema_ref="#/components/schemas/Pet",
    count=4,
)

count: int

schema_ref: str

oas2mcp.agent.summarizer.context.build_catalog_summary_context(catalog: oas2mcp.models.normalized.ApiCatalog, bundle: oas2mcp.models.mcp.McpBundle | None = None) → CatalogSummaryContext

Build deterministic summarizer context for an API catalog.

Parameters:

• catalog – The normalized API catalog.

• bundle – Optional MCP bundle produced by deterministic classification.

Returns:

A compact CatalogSummaryContext suitable for a summarizer agent.

Raises:

None. –

Examples

context = build_catalog_summary_context(catalog, bundle=bundle)