openapi-to-mcp-cli 0.9.1__py3-none-any.whl

openapi_to_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""OpenAPI to MCP
+This module provides functionality to convert OpenAPI specifications to MCP (Model Context Protocol) format.
+"""

openapi_to_mcp/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapter components for interfacing with external systems."""

openapi_to_mcp/adapters/generator.py

@@ -0,0 +1,206 @@
+"""Adapter for generating MCP server files from templates."""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import jinja2
+
+from openapi_to_mcp.common.exceptions import GenerationError
+
+logger = logging.getLogger(__name__)
+
+RUNTIME_TEMPLATE_NAMES = (
+    "audit",
+    "request_context",
+    "auth",
+    "cache",
+    "circuit_breaker",
+    "config",
+    "errors",
+    "executor",
+    "executor_support",
+    "generated",
+    "http_transport",
+    "limiter",
+    "observability",
+    "performance_preset",
+    "rate_limit",
+    "resilience",
+    "retry",
+    "request",
+    "redaction",
+    "response",
+    "serialization",
+    "tool_access",
+    "validation",
+)
+CUSTOM_TEMPLATE_NAMES = ("tools",)
+
+
+class Generator:
+    """Handles rendering templates and writing MCP server files."""
+
+    def __init__(self, output_dir: str, context: dict[str, Any]) -> None:
+        """
+        Initialize the generator.
+
+        Args:
+            output_dir: The target directory for generated files.
+            context: Data for template rendering (server_name, tools, etc.).
+        """
+        self.output_path = Path(output_dir)
+        self.context = context
+        # Template directory is relative to this file's parent's parent
+        # This ensures it works with the new directory structure
+        self.template_dir = Path(__file__).parent.parent / "templates"
+        self.env: jinja2.Environment | None = None
+
+    def generate_files(self) -> None:
+        """
+        Generate all necessary MCP server files from templates.
+
+        Raises:
+            GenerationError: If template rendering or file writing fails.
+        """
+        self._setup_environment()
+        if not self.env:
+            err_msg = "Internal error: Jinja2 environment not initialized."
+            raise GenerationError(err_msg)
+
+        self._ensure_output_directories()
+        self._generate_static_files()
+        self._generate_transport_file()
+
+    def _setup_environment(self) -> None:
+        """
+        Initialize the Jinja2 template environment.
+
+        Raises:
+            GenerationError: If the template directory is not found.
+        """
+        if not self.template_dir.is_dir():
+            err_msg = f"Template directory not found at {self.template_dir}"
+            raise GenerationError(err_msg)
+
+        self.env = jinja2.Environment(
+            loader=jinja2.FileSystemLoader(self.template_dir),
+            autoescape=jinja2.select_autoescape(["html", "xml", "j2"]),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+    def _ensure_output_directories(self) -> None:
+        """
+        Create the output directory and src subdirectory.
+
+        Raises:
+            GenerationError: If directory creation fails.
+        """
+        try:
+            self.output_path.mkdir(parents=True, exist_ok=True)
+            src_path = self.output_path / "src"
+            src_path.mkdir(exist_ok=True)
+            runtime_path = src_path / "runtime"
+            runtime_path.mkdir(exist_ok=True)
+            custom_path = src_path / "custom"
+            custom_path.mkdir(exist_ok=True)
+        except OSError as e:
+            err_msg = (
+                f"Failed to create output directories in '{self.output_path}': {e}"
+            )
+            raise GenerationError(err_msg) from e
+
+    def _generate_static_files(self) -> None:
+        """
+        Generate overwriteable templates and preserved customization templates.
+
+        Raises:
+            GenerationError: If template rendering or file writing fails.
+        """
+        generated_templates = {
+            "package.json.j2": self.output_path / "package.json",
+            "tsconfig.json.j2": self.output_path / "tsconfig.json",
+            "src/server.ts.j2": self.output_path / "src" / "server.ts",
+            "README.md.j2": self.output_path / "README.md",
+            ".env.example.j2": self.output_path / ".env.example",
+            "src/index.ts.j2": self.output_path / "src" / "index.ts",
+        }
+        generated_templates.update(self._runtime_templates())
+
+        for template_name, output_file in generated_templates.items():
+            self._render_and_write(template_name, output_file)
+        for template_name, output_file in self._custom_templates().items():
+            self._render_if_missing(template_name, output_file)
+
+    def _runtime_templates(self) -> dict[str, Path]:
+        runtime_output = self.output_path / "src" / "runtime"
+        return {
+            f"src/runtime/{name}.ts.j2": runtime_output / f"{name}.ts"
+            for name in RUNTIME_TEMPLATE_NAMES
+        }
+
+    def _custom_templates(self) -> dict[str, Path]:
+        custom_output = self.output_path / "src" / "custom"
+        return {
+            f"src/custom/{name}.ts.j2": custom_output / f"{name}.ts"
+            for name in CUSTOM_TEMPLATE_NAMES
+        }
+
+    def _generate_transport_file(self) -> None:
+        """
+        Generate the appropriate transport file based on context.
+
+        Raises:
+            GenerationError: If template rendering or file writing fails.
+        """
+        transport_output_file = self.output_path / "src" / "transport.ts"
+
+        if self.context.get("transport") == "streamable-http":
+            transport_template_name = "src/transport_streamable_http.ts.j2"
+            logger.info(
+                "Rendering streamable-http transport template to src/transport.ts"
+            )
+        else:
+            transport_template_name = "src/transport_stdio.ts.j2"
+            logger.info("Rendering STDIO transport template to src/transport.ts")
+
+        self._render_and_write(transport_template_name, transport_output_file)
+
+    def _render_and_write(self, template_name: str, output_file: Path) -> None:
+        """
+        Render a single template and write it to the output file.
+
+        Args:
+            template_name: The name of the template file.
+            output_file: The output file path.
+
+        Raises:
+            GenerationError: If template rendering or file writing fails.
+        """
+        if not self.env:
+            err_msg = "Internal error: Jinja2 environment not initialized."
+            raise GenerationError(err_msg)
+
+        try:
+            template = self.env.get_template(template_name)
+            rendered_content = template.render(self.context)
+
+            with output_file.open("w", encoding="utf-8") as f:
+                f.write(rendered_content)
+
+        except jinja2.TemplateNotFound as e:
+            err_msg = (
+                f"Required template '{template_name}' not found in {self.template_dir}."
+            )
+            raise GenerationError(err_msg) from e
+        except Exception as e:
+            err_msg = f"Error rendering or writing template '{template_name}' to '{output_file}': {e}"
+            raise GenerationError(err_msg) from e
+
+    def _render_if_missing(self, template_name: str, output_file: Path) -> None:
+        """Render a template only when the target file does not already exist."""
+        if output_file.exists():
+            logger.info("Preserving existing customization file: %s", output_file)
+            return
+        self._render_and_write(template_name, output_file)

openapi_to_mcp/adapters/spec_loader.py

@@ -0,0 +1,135 @@
+import logging
+from pathlib import Path
+
+import requests
+import yaml
+from openapi_spec_validator import validate as validate_spec
+
+from openapi_to_mcp.common.exceptions import SpecLoaderError
+
+logger = logging.getLogger(__name__)
+
+
+class SpecLoader:
+    """Handles loading and validation of OpenAPI specifications from files or URLs."""
+
+    def __init__(self, source: str) -> None:
+        """
+        Initialize the spec loader with a source.
+
+        Args:
+            source: Path or URL to the OpenAPI specification
+        """
+        self.source = source
+        self.spec = None
+        self._content = None
+
+    def load_and_validate(self) -> dict:
+        """
+        Load the OpenAPI spec from the source and validate it.
+
+        Returns:
+            The loaded and validated specification dictionary.
+
+        Raises:
+            SpecLoaderError: If loading or validation fails.
+        """
+        logger.info("Loading OpenAPI spec from: %s", self.source)
+        self._load_content()
+        self._parse_and_validate()
+        logger.info("OpenAPI spec loaded and validated successfully.")
+        return self.spec
+
+    def _load_content(self) -> None:
+        """
+        Load the raw content from file or URL.
+
+        Raises:
+            SpecLoaderError: If loading fails.
+        """
+        if self.source.startswith(("http://", "https://")):
+            self._load_from_url()
+        else:
+            self._load_from_file()
+
+    def _load_from_url(self) -> None:
+        """
+        Load content from a URL.
+
+        Raises:
+            SpecLoaderError: If the URL request fails.
+        """
+        try:
+            logger.debug("Fetching spec from URL: %s", self.source)
+            response = requests.get(self.source, timeout=10)
+            response.raise_for_status()
+            self._content = response.text
+            logger.debug("Successfully fetched spec from URL.")
+        except requests.exceptions.Timeout as e:
+            logger.exception(
+                "Timeout occurred while fetching spec from URL: %s", self.source
+            )
+            err_msg = f"Timeout fetching OpenAPI spec from URL '{self.source}'"
+            raise SpecLoaderError(err_msg) from e
+        except requests.exceptions.RequestException as e:
+            logger.exception("Error fetching spec from URL '%s'", self.source)
+            err_msg = f"Error fetching OpenAPI spec from URL '{self.source}': {e}"
+            raise SpecLoaderError(err_msg) from e
+
+    def _load_from_file(self) -> None:
+        """
+        Load content from a file.
+
+        Raises:
+            SpecLoaderError: If the file cannot be read.
+        """
+        try:
+            source_path = Path(self.source)
+            logger.debug("Reading spec from file: %s", source_path)
+            if not source_path.is_file():
+                raise FileNotFoundError(f"File not found: {source_path}")  # noqa: TRY301
+            with source_path.open("r", encoding="utf-8") as f:
+                self._content = f.read()
+            logger.debug("Successfully read spec from file.")
+        except FileNotFoundError as e:
+            logger.exception("OpenAPI spec file not found at '%s'", self.source)
+            err_msg = f"OpenAPI spec file not found at '{self.source}'"
+            raise SpecLoaderError(err_msg) from e
+        except Exception as e:
+            logger.exception("Error reading OpenAPI spec file '%s'", self.source)
+            err_msg = f"Error reading OpenAPI spec file '{self.source}': {e}"
+            raise SpecLoaderError(err_msg) from e
+
+    def _parse_and_validate(self) -> None:
+        """
+        Parse the loaded content and validate the spec.
+
+        Raises:
+            SpecLoaderError: If parsing or validation fails.
+        """
+        if self._content is None:
+            logger.error("Internal error: Spec content not loaded before parsing.")
+            err_msg = "Internal error: Spec content not loaded before parsing."
+            raise SpecLoaderError(err_msg)
+
+        try:
+            logger.debug("Parsing spec content (YAML/JSON).")
+            self.spec = yaml.safe_load(self._content)
+            if not isinstance(self.spec, dict):
+                err_msg = "Parsed specification is not a valid dictionary structure."
+                exception = SpecLoaderError(err_msg)
+                logger.error(err_msg, exc_info=exception)
+                raise exception  # noqa: TRY301
+
+            logger.debug("Validating OpenAPI spec structure.")
+            validate_spec(self.spec)
+            logger.debug("OpenAPI spec structure validation successful.")
+
+        except yaml.YAMLError as e:
+            logger.exception("Error parsing OpenAPI spec content (YAML/JSON)")
+            err_msg = f"Error parsing OpenAPI spec content (YAML/JSON): {e}"
+            raise SpecLoaderError(err_msg) from e
+        except Exception as e:
+            logger.exception("OpenAPI spec validation failed")
+            err_msg = f"OpenAPI spec validation failed: {e}"
+            raise SpecLoaderError(err_msg) from e

openapi_to_mcp/adapters/testing/__init__.py

@@ -0,0 +1,21 @@
+"""Testing components for MCP servers."""
+
+from openapi_to_mcp.adapters.testing.models import (
+    ConnectionSettings,
+    ServerTestRequest,
+)
+from openapi_to_mcp.adapters.testing.response_formatting import (
+    McpResult,
+    format_mcp_error,
+    format_mcp_response,
+)
+from openapi_to_mcp.adapters.testing.server_tester import execute_mcp_server
+
+__all__ = [
+    "ConnectionSettings",
+    "McpResult",
+    "ServerTestRequest",
+    "execute_mcp_server",
+    "format_mcp_error",
+    "format_mcp_response",
+]

openapi_to_mcp/adapters/testing/models.py

@@ -0,0 +1,46 @@
+"""Models and contracts for MCP server testing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from openapi_to_mcp.common import OpenApiMcpError
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectionSettings:
+    """Connection details for an MCP server test."""
+
+    server_cmd: str | None = None
+    endpoint_url: str | None = None
+    env: dict[str, str] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ServerTestRequest:
+    """Describe one MCP request and its connection settings."""
+
+    transport: str
+    method: str
+    params: dict[str, Any] | None = None
+    req_id: int = 1
+    connection: ConnectionSettings = field(default_factory=ConnectionSettings)
+
+
+class UnsupportedMethodError(OpenApiMcpError):
+    """Raised when an unsupported MCP method is requested."""
+
+
+class ServerConnectionError(OpenApiMcpError):
+    """Raised when an MCP server connection fails."""
+
+
+class TransportStrategy:
+    """Base contract for MCP testing transports."""
+
+    async def connect_and_execute(
+        self, method: str, params: dict[str, Any] | None, req_id: int
+    ) -> dict[str, Any]:
+        """Connect to the server and execute the requested method."""
+        raise NotImplementedError("Subclasses must implement this method")

openapi_to_mcp/adapters/testing/response_formatting.py

@@ -0,0 +1,94 @@
+"""JSON-RPC response formatting for MCP server tests."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Protocol, TypeGuard, cast
+
+from mcp.types import CallToolResult, ListToolsResult
+
+if TYPE_CHECKING:
+    from mcp import MCPError
+
+McpResult = ListToolsResult | CallToolResult | Mapping[str, Any]
+
+
+class _ModelLike(Protocol):
+    def model_dump(self, *, mode: str, by_alias: bool) -> dict[str, Any]:
+        """Serialize model fields with their declared aliases."""
+        ...
+
+
+def _is_model_like(value: object) -> TypeGuard[_ModelLike]:
+    fields = getattr(type(value), "model_fields", None)
+    return callable(getattr(value, "model_dump", None)) and isinstance(fields, Mapping)
+
+
+def _model_fields(value: _ModelLike) -> Mapping[str, object]:
+    return cast(
+        "Mapping[str, object]",
+        type(value).model_fields,
+    )
+
+
+def _field_alias(field_name: str, field: object) -> str:
+    serialization_alias = getattr(field, "serialization_alias", None)
+    if isinstance(serialization_alias, str):
+        return serialization_alias
+    alias = getattr(field, "alias", None)
+    return alias if isinstance(alias, str) else field_name
+
+
+def _serialize_model_member(value: object, dumped: object) -> object:
+    if _is_model_like(value):
+        return _serialize_model(value)
+    if isinstance(value, list) and isinstance(dumped, list):
+        return [
+            _serialize_model_member(item, serialized)
+            for item, serialized in zip(value, dumped, strict=True)
+        ]
+    return dumped
+
+
+def _serialize_model(value: _ModelLike) -> dict[str, Any]:
+    payload = cast(
+        "dict[str, Any]",
+        value.model_dump(mode="json", by_alias=True),
+    )
+    for field_name, field in _model_fields(value).items():
+        alias = _field_alias(field_name, field)
+        if alias not in payload:
+            continue
+        output_key = "meta" if alias == "_meta" else alias
+        serialized = _serialize_model_member(
+            getattr(value, field_name),
+            payload[alias],
+        )
+        if output_key != alias:
+            del payload[alias]
+        payload[output_key] = serialized
+    return payload
+
+
+def format_mcp_response(value: McpResult | None, req_id: int) -> dict[str, Any]:
+    """Serialize an MCP result into a JSON-RPC response dictionary."""
+    if value is None:
+        return {
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "error": {
+                "code": -32603,
+                "message": "Internal error: No response data received from server.",
+            },
+        }
+    response = dict(value) if isinstance(value, Mapping) else _serialize_model(value)
+    response.setdefault("jsonrpc", "2.0")
+    response.setdefault("id", req_id)
+    return response
+
+
+def format_mcp_error(error: MCPError, req_id: int) -> dict[str, Any]:
+    """Serialize an MCP protocol error into a JSON-RPC error response."""
+    payload: dict[str, Any] = {"code": error.code, "message": error.message}
+    payload["data"] = error.data
+    return {"jsonrpc": "2.0", "id": req_id, "error": payload}

openapi_to_mcp/adapters/testing/server_tester.py

@@ -0,0 +1,85 @@
+"""Orchestrate requests across MCP server testing transports."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from mcp import MCPError
+
+from openapi_to_mcp.adapters.testing.models import (
+    ConnectionSettings,
+    ServerConnectionError,
+    ServerTestRequest,
+    TransportStrategy,
+    UnsupportedMethodError,
+)
+from openapi_to_mcp.adapters.testing.response_formatting import (
+    format_mcp_error,
+)
+from openapi_to_mcp.adapters.testing.stdio_transport import (
+    StdioTransport,
+)
+from openapi_to_mcp.adapters.testing.streamable_http_transport import (
+    DEFAULT_PROTOCOL_VERSION,
+    StreamableHttpTransport,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _create_transport_strategy(request: ServerTestRequest) -> TransportStrategy:
+    """Create the transport strategy selected by a server test request."""
+    connection = request.connection
+    if request.transport == "stdio":
+        if not connection.server_cmd:
+            raise ValueError("server_cmd is required for stdio transport")
+        return StdioTransport(connection.server_cmd, connection.env)
+    if request.transport == "streamable-http":
+        if not connection.endpoint_url:
+            raise ValueError("endpoint_url is required for streamable-http transport")
+        return StreamableHttpTransport(connection.endpoint_url)
+    raise ValueError(f"Unsupported transport type: {request.transport}")
+
+
+async def execute_mcp_server(request: ServerTestRequest) -> dict[str, Any]:
+    """Execute one MCP server test request using its configured transport."""
+    logger.info(
+        "Testing MCP server via %s transport. Method: %s",
+        request.transport,
+        request.method,
+    )
+    try:
+        strategy = _create_transport_strategy(request)
+        return await strategy.connect_and_execute(
+            request.method,
+            request.params,
+            request.req_id,
+        )
+    except MCPError as error:
+        logger.exception(
+            "MCP error during %s test for method '%s'",
+            request.transport,
+            request.method,
+        )
+        return format_mcp_error(error, request.req_id)
+    except Exception:
+        logger.exception(
+            "Unexpected error during %s MCP test for method '%s'",
+            request.transport,
+            request.method,
+        )
+        raise
+
+
+__all__ = [
+    "DEFAULT_PROTOCOL_VERSION",
+    "ConnectionSettings",
+    "ServerConnectionError",
+    "ServerTestRequest",
+    "StdioTransport",
+    "StreamableHttpTransport",
+    "TransportStrategy",
+    "UnsupportedMethodError",
+    "execute_mcp_server",
+]

openapi_to_mcp/adapters/testing/stdio_transport.py

@@ -0,0 +1,83 @@
+"""Stdio transport for MCP server tests."""
+
+from __future__ import annotations
+
+import logging
+import shlex
+from typing import TYPE_CHECKING, Any
+
+from mcp import ClientSession, MCPError, StdioServerParameters, stdio_client
+
+from openapi_to_mcp.adapters.testing.models import (
+    ServerConnectionError,
+    TransportStrategy,
+    UnsupportedMethodError,
+)
+from openapi_to_mcp.adapters.testing.response_formatting import (
+    format_mcp_error,
+    format_mcp_response,
+)
+
+if TYPE_CHECKING:
+    from mcp.types import CallToolResult, ListToolsResult
+
+logger = logging.getLogger(__name__)
+
+
+async def perform_mcp_request(
+    session: ClientSession, method: str, params: dict[str, Any] | None
+) -> ListToolsResult | CallToolResult:
+    """Perform one tools/list or tools/call request through a client session."""
+    if method == "list":
+        logger.info("Sending ListTools request")
+        return await session.list_tools()
+    if method == "call":
+        if params is None or "tool_name" not in params:
+            raise ValueError("Missing 'tool_name' in params for tool call method.")
+        tool_name = params["tool_name"]
+        logger.info("Sending CallTool request for tool: %s", tool_name)
+        return await session.call_tool(
+            name=tool_name,
+            arguments=params.get("tool_arguments"),
+        )
+    raise UnsupportedMethodError(f"Unsupported method for testing: {method}")
+
+
+class StdioTransport(TransportStrategy):
+    """Execute MCP requests through a managed stdio client session."""
+
+    def __init__(self, server_cmd: str, env: dict[str, str] | None = None) -> None:
+        if not server_cmd:
+            raise ValueError("server_cmd is required for stdio transport")
+        self.server_cmd = server_cmd
+        self.env = env
+
+    async def connect_and_execute(
+        self, method: str, params: dict[str, Any] | None, req_id: int
+    ) -> dict[str, Any]:
+        """Connect over stdio and return a JSON-RPC response dictionary."""
+        command = shlex.split(self.server_cmd)
+        stdio_params = StdioServerParameters(
+            command=command[0],
+            args=command[1:],
+            env=self.env,
+        )
+        try:
+            async with (
+                stdio_client(stdio_params) as (read, write),
+                ClientSession(read, write) as session,
+            ):
+                await session.initialize()
+                result = await perform_mcp_request(session, method, params)
+                return format_mcp_response(result, req_id)
+        except MCPError as error:
+            logger.info(
+                "Received MCP error response over stdio: %s",
+                error.message,
+            )
+            return format_mcp_error(error, req_id)
+        except Exception as error:
+            logger.exception("Error during stdio connection")
+            raise ServerConnectionError(
+                f"Failed to connect via stdio: {error}"
+            ) from error