oas2mcp.agent.enhancer.models

Structured models for the operation enhancer agent.

Purpose:

Define deterministic input and structured output models for refining one normalized API operation into a more MCP-friendly representation.

Design:

• Keep these models specific to the enhancer workflow.

• Separate deterministic context objects from LLM-produced enhancement outputs.

• Treat deterministic MCP classification data as hints rather than final truth.

• Preserve enough detail for naming, auth, confirmation, and later export.

Examples

enhancement = OperationEnhancement(
    operation_key="POST /pet",
    operation_slug="addpet",
    final_kind="tool",
    title="Create pet",
    description="Create a new pet record.",
    requires_confirmation=False,
)

Classes

EnhancementPromptCandidate	Suggested prompt template for an enhanced operation.
OperationEnhancement	Structured enhancement result for one operation.
OperationEnhancementContext	Deterministic agent-facing context for one operation.
ResolvedSchemaContext	Resolved schema context for one schema reference.
SecuritySchemeContext	Compact security scheme details used by the enhancer.

Module Contents

class oas2mcp.agent.enhancer.models.EnhancementPromptCandidate(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Suggested prompt template for an enhanced operation.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

prompt = EnhancementPromptCandidate(
    name="create-pet",
    title="Create pet",
    description="Create a new pet safely.",
)

arguments: list[str] = None

description: str

meta: dict[str, Any] = None

name: str

tags: list[str] = None

template: str | None = None

title: str

version: str | None = None

class oas2mcp.agent.enhancer.models.OperationEnhancement(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Structured enhancement result for one operation.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

enhancement = OperationEnhancement(
    operation_key="POST /pet",
    operation_slug="addpet",
    final_kind="tool",
    title="Create pet",
    description="Create a new pet record.",
)

auth_notes: str | None = None

component_annotations: dict[str, Any] = None

component_meta: dict[str, Any] = None

component_name: str | None = None

component_tags: list[str] = None

component_version: str | None = None

description: str

final_kind: oas2mcp.models.mcp.McpCandidateKind

namespace: str | None = None

notes: list[str] = None

operation_id: str | None = None

operation_key: str

operation_slug: str

prompt_templates: list[EnhancementPromptCandidate] = None

requires_confirmation: bool = False

resource_uri: str | None = None

title: str

tool_name: str | None = None

class oas2mcp.agent.enhancer.models.OperationEnhancementContext(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Deterministic agent-facing context for one operation.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

context = OperationEnhancementContext(
    catalog_name="Petstore",
    catalog_slug="petstore",
    source_uri="https://example.com/openapi.json",
    catalog_summary_purpose="Manage pets and orders.",
    catalog_domains=["pet", "store", "user"],
    operation_key="POST /pet",
    operation_slug="addpet",
    method="POST",
    path="/pet",
    candidate_kind_hint="tool",
)

candidate_kind_hint: str

candidate_prompt_templates: list[EnhancementPromptCandidate] = None

candidate_requires_confirmation_hint: bool = False

candidate_resource_uri_hint: str | None = None

candidate_tool_name_hint: str | None = None

catalog_domains: list[str] = None

catalog_name: str

catalog_slug: str

catalog_summary_purpose: str

description: str | None = None

method: str

operation_id: str | None = None

operation_key: str

operation_slug: str

path: str

path_parameter_names: list[str] = None

query_parameter_names: list[str] = None

request_schema_refs: list[str] = None

resolved_schemas: list[ResolvedSchemaContext] = None

response_schema_refs: list[str] = None

security_schemes: list[SecuritySchemeContext] = None

server_urls: list[str] = None

source_uri: str

summary: str | None = None

tags: list[str] = None

class oas2mcp.agent.enhancer.models.ResolvedSchemaContext(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Resolved schema context for one schema reference.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

schema_context = ResolvedSchemaContext(
    schema_ref="#/components/schemas/Pet",
    schema_object={"type": "object"},
)

schema_object: dict = None

schema_ref: str

class oas2mcp.agent.enhancer.models.SecuritySchemeContext(/, **data: Any)

Bases: oas2mcp.models.normalized.NormalizedBaseModel

Compact security scheme details used by the enhancer.

Parameters:

None.

Returns:

None.

Raises:

None. –

Examples

scheme = SecuritySchemeContext(
    name="petstore_auth",
    type="oauth2",
    flow_names=["implicit"],
)

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