oas2mcp.agent.surface.models

Structured models for the catalog surface planner agent.

Purpose:

Define the deterministic input and structured output models used by the catalog-level surface planner. This workflow refines shared FastMCP-facing server instructions, prompts, and resources after per-operation enhancement.

Design:

• Keep these models specific to catalog-level surface planning.

• Separate deterministic planning context from LLM-produced surface output.

• Preserve a stable, inspectable shape for later export and bootstrapping.

• Constrain resource planning to handlers supported by the runtime layer.

Classes

CatalogSurfaceOperationContext	Compact operation summary used by the catalog surface planner.
CatalogSurfacePlan	Structured catalog-level surface plan produced by the planner agent.
CatalogSurfacePlanningContext	Deterministic context passed into the catalog surface planner agent.
CatalogSurfacePromptPlan	Catalog-level prompt definition proposed by the surface planner.
CatalogSurfaceResourcePlan	Catalog-level resource definition proposed by the surface planner.

Module Contents

class oas2mcp.agent.surface.models.CatalogSurfaceOperationContext(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Compact operation summary used by the catalog surface planner.

auth_notes: str | None = None

description: str

final_kind: oas2mcp.models.mcp.McpCandidateKind

namespace: str | None = None

operation_id: str | None = None

operation_slug: str

prompt_template_names: list[str] = None

requires_confirmation: bool = False

resource_uri: str | None = None

title: str

tool_name: str | None = None

class oas2mcp.agent.surface.models.CatalogSurfacePlan(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Structured catalog-level surface plan produced by the planner agent.

catalog_prompts: list[CatalogSurfacePromptPlan] = None

catalog_resources: list[CatalogSurfaceResourcePlan] = None

notes: list[str] = None

server_instructions: str

class oas2mcp.agent.surface.models.CatalogSurfacePlanningContext(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Deterministic context passed into the catalog surface planner agent.

api_purpose: str

authentication_summary: str

catalog_name: str

catalog_notes: list[str] = None

catalog_slug: str

catalog_version: str | None = None

conceptual_overview: str

default_catalog_prompts: list[CatalogSurfacePromptPlan] = None

default_catalog_resources: list[CatalogSurfaceResourcePlan] = None

default_server_instructions: str

operations: list[CatalogSurfaceOperationContext] = None

primary_domains: list[str] = None

recommended_mcp_surface: str

source_uri: str

suggested_resource_domains: list[str] = None

suggested_tool_domains: list[str] = None

class oas2mcp.agent.surface.models.CatalogSurfacePromptPlan(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Catalog-level prompt definition proposed by the surface planner.

arguments: list[str] = None

description: str

meta: dict[str, Any] = None

name: str

tags: list[str] = None

template: str

title: str

version: str | None = None

class oas2mcp.agent.surface.models.CatalogSurfaceResourcePlan(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Catalog-level resource definition proposed by the surface planner.

annotations: dict[str, Any] = None

arguments: list[str] = None

description: str

handler: Literal['static', 'operation_metadata', 'namespace_operations'] = 'static'

kind: Literal['resource', 'resource_template']

meta: dict[str, Any] = None

mime_type: str = 'application/json'

name: str

payload: Any | None = None

tags: list[str] = None

title: str

uri: str

version: str | None = None