Source code for oas2mcp.models.mcp

"""MCP preparation models.

Purpose:
    Define structured intermediate models used to classify normalized OpenAPI
    operations into MCP-oriented candidates before any agent enhancement step.

Design:
    - Keep the first pass deterministic and lightweight.
    - Represent only the metadata needed before runtime/server generation.
    - Make these models suitable as structured output targets for later agents.

Examples:
    .. code-block:: python

        candidate = McpCandidate(
            operation_key="GET /pets/{petId}",
            kind="tool",
            title="Get pet by ID",
        )
"""

from __future__ import annotations

from typing import Any, Literal

from pydantic import Field

from oas2mcp.models.normalized import NormalizedBaseModel


[docs]
McpCandidateKind = Literal[
    "tool",
    "resource",
    "resource_template",
    "prompt",
    "exclude",
]


[docs]
McpSafetyLevel = Literal["safe_read", "mutating", "destructive"]




[docs]
class McpPromptTemplate(NormalizedBaseModel):
    """A suggested prompt template derived from an API operation.

    Args:
        None.

    Returns:
        None.

    Raises:
        None.

    Examples:
        .. code-block:: python

            prompt = McpPromptTemplate(
                name="explain-get-pet-by-id",
                title="Explain get pet by ID",
                description="Summarize how to use this endpoint.",
            )
    """


[docs]
    name: str


[docs]
    title: str


[docs]
    description: str


[docs]
    arguments: list[str] = Field(default_factory=list)


[docs]
    template: str | None = None


[docs]
    version: str | None = None


[docs]
    tags: list[str] = Field(default_factory=list)


[docs]
    meta: dict[str, Any] = Field(default_factory=dict)





[docs]
class McpCandidate(NormalizedBaseModel):
    """A deterministic MCP candidate derived from one operation.

    Args:
        None.

    Returns:
        None.

    Raises:
        None.

    Examples:
        .. code-block:: python

            candidate = McpCandidate(
                operation_key="GET /pets/{petId}",
                kind="tool",
                title="Get pet by ID",
                description="Retrieve a pet by its ID.",
            )
    """


[docs]
    operation_key: str


[docs]
    operation_slug: str


[docs]
    kind: McpCandidateKind


[docs]
    title: str


[docs]
    description: str


[docs]
    safety_level: McpSafetyLevel


[docs]
    requires_confirmation: bool = False


[docs]
    tool_name: str | None = None


[docs]
    resource_uri: str | None = None


[docs]
    auth_scheme_names: list[str] = Field(default_factory=list)


[docs]
    auth_notes: str | None = None


[docs]
    prompt_templates: list[McpPromptTemplate] = Field(default_factory=list)


[docs]
    notes: list[str] = Field(default_factory=list)





[docs]
class McpBundle(NormalizedBaseModel):
    """A collection of MCP candidates for one catalog.

    Args:
        None.

    Returns:
        None.

    Raises:
        None.

    Examples:
        .. code-block:: python

            bundle = McpBundle(
                catalog_name="Petstore",
                candidates=[],
            )
    """


[docs]
    catalog_name: str


[docs]
    catalog_slug: str


[docs]
    candidates: list[McpCandidate] = Field(default_factory=list)