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

openapi_to_mcp/adapters/testing/streamable_http_transport.py

@@ -0,0 +1,163 @@
+"""Streamable HTTP transport for MCP server tests."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any
+
+import requests
+from mcp.types import CallToolResult, ListToolsResult
+
+from openapi_to_mcp.adapters.testing.models import (
+    ServerConnectionError,
+    TransportStrategy,
+    UnsupportedMethodError,
+)
+from openapi_to_mcp.adapters.testing.response_formatting import format_mcp_response
+
+logger = logging.getLogger(__name__)
+DEFAULT_PROTOCOL_VERSION = "2025-11-25"
+
+
+def _normalize_result(
+    response: dict[str, Any], method: str, req_id: int
+) -> dict[str, Any]:
+    if "error" in response or not isinstance(response.get("result"), dict):
+        return response
+    model_type = ListToolsResult if method == "list" else CallToolResult
+    model = model_type.model_validate(response["result"])
+    formatted = format_mcp_response(model, req_id)
+    normalized = dict(response)
+    normalized["result"] = {
+        key: value for key, value in formatted.items() if key not in {"jsonrpc", "id"}
+    }
+    return normalized
+
+
+class StreamableHttpTransport(TransportStrategy):
+    """Execute MCP JSON-RPC requests through streamable HTTP."""
+
+    def __init__(self, endpoint_url: str) -> None:
+        if not endpoint_url:
+            raise ValueError("endpoint_url is required for streamable-http transport")
+        self.endpoint_url = endpoint_url
+        self._session_id: str | None = None
+        self._protocol_version = DEFAULT_PROTOCOL_VERSION
+
+    def _build_jsonrpc_payload(
+        self, method: str, params: dict[str, Any] | None, req_id: int
+    ) -> dict[str, Any]:
+        if method == "list":
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "method": "tools/list",
+                "params": {},
+            }
+        if method == "call":
+            if params is None or "tool_name" not in params:
+                raise ValueError("Missing 'tool_name' in params for tool call method.")
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "method": "tools/call",
+                "params": {
+                    "name": params["tool_name"],
+                    "arguments": params.get("tool_arguments", {}),
+                },
+            }
+        raise UnsupportedMethodError(f"Unsupported method for testing: {method}")
+
+    def _build_headers(self) -> dict[str, str]:
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+            "MCP-Protocol-Version": self._protocol_version,
+        }
+        if self._session_id:
+            headers["Mcp-Session-Id"] = self._session_id
+        return headers
+
+    def _parse_json_response(self, response: requests.Response) -> dict[str, Any]:
+        try:
+            response_data = response.json()
+        except json.JSONDecodeError as error:
+            raise ServerConnectionError(
+                f"Invalid JSON response from streamable-http endpoint: {error}"
+            ) from error
+        if not isinstance(response_data, dict):
+            raise ServerConnectionError(
+                "Unexpected non-object JSON response from streamable-http endpoint"
+            )
+        return response_data
+
+    def _initialize(self, req_id: int) -> None:
+        payload = {
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "method": "initialize",
+            "params": {
+                "protocolVersion": self._protocol_version,
+                "capabilities": {},
+                "clientInfo": {
+                    "name": "openapi-to-mcp-tester",
+                    "version": "0.1.0",
+                },
+            },
+        }
+        response = requests.post(
+            self.endpoint_url,
+            json=payload,
+            timeout=30,
+            headers=self._build_headers(),
+        )
+        response.raise_for_status()
+        self._session_id = response.headers.get("Mcp-Session-Id")
+        response_data = self._parse_json_response(response)
+        if "error" in response_data:
+            raise ServerConnectionError(
+                f"Initialize request failed: {response_data['error']}"
+            )
+        self._send_initialized_notification()
+
+    def _send_initialized_notification(self) -> None:
+        response = requests.post(
+            self.endpoint_url,
+            json={
+                "jsonrpc": "2.0",
+                "method": "notifications/initialized",
+                "params": {},
+            },
+            timeout=30,
+            headers=self._build_headers(),
+        )
+        response.raise_for_status()
+
+    def _post_jsonrpc(
+        self, method: str, params: dict[str, Any] | None, req_id: int
+    ) -> dict[str, Any]:
+        self._initialize(req_id=req_id * 1000 + 1)
+        response = requests.post(
+            self.endpoint_url,
+            json=self._build_jsonrpc_payload(method, params, req_id),
+            timeout=30,
+            headers=self._build_headers(),
+        )
+        response.raise_for_status()
+        response_data = self._parse_json_response(response)
+        return _normalize_result(response_data, method, req_id)
+
+    async def connect_and_execute(
+        self, method: str, params: dict[str, Any] | None, req_id: int
+    ) -> dict[str, Any]:
+        """Connect over streamable HTTP and return the JSON-RPC response."""
+        logger.info("Connecting to streamable-http endpoint at %s", self.endpoint_url)
+        try:
+            return await asyncio.to_thread(self._post_jsonrpc, method, params, req_id)
+        except Exception as error:
+            logger.exception("Error during streamable-http connection")
+            raise ServerConnectionError(
+                f"Failed to connect via streamable-http: {error}"
+            ) from error

openapi_to_mcp/cli.py

@@ -0,0 +1,45 @@
+import rich_click as click
+
+from openapi_to_mcp.commands import diff, doctor, generate, run, test_server
+from openapi_to_mcp.common import configure_logger
+
+
+def _configure_rich_click() -> None:
+    click.rich_click.TEXT_MARKUP = "rich"
+    click.rich_click.SHOW_ARGUMENTS = True
+    click.rich_click.GROUP_ARGUMENTS_OPTIONS = True
+    click.rich_click.OPTIONS_TABLE_HELP_SECTIONS = [
+        "help",
+        "metavar",
+        "envvar",
+        "default",
+        "required",
+    ]
+    click.rich_click.STYLE_COMMAND = "bold yellow"
+    click.rich_click.STYLE_OPTION = "bold cyan"
+    click.rich_click.STYLE_SWITCH = "bold cyan"
+    click.rich_click.STYLE_METAVAR = "bold white"
+    click.rich_click.STYLE_OPTION_HELP = "white"
+    click.rich_click.STYLE_HEADER_TEXT = "bold white"
+    click.rich_click.STYLE_USAGE = "bold green"
+    click.rich_click.STYLE_ERRORS_SUGGESTION = "bold red"
+
+
+_configure_rich_click()
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+def cli() -> None:
+    """A CLI tool to diagnose, diff, generate, run, and test MCP servers from OpenAPI specs."""
+    configure_logger()
+
+
+cli.add_command(generate)
+cli.add_command(run)
+cli.add_command(test_server)
+cli.add_command(doctor)
+cli.add_command(diff)
+
+
+if __name__ == "__main__":
+    cli()

openapi_to_mcp/commands/__init__.py

@@ -0,0 +1,15 @@
+"""Commands component for the openapi-to-mcp package."""
+
+from openapi_to_mcp.commands.diff import diff
+from openapi_to_mcp.commands.doctor import doctor
+from openapi_to_mcp.commands.generate import generate
+from openapi_to_mcp.commands.run import run_server as run
+from openapi_to_mcp.commands.test_server import run_test_server as test_server
+
+__all__ = [
+    "diff",
+    "doctor",
+    "generate",
+    "run",
+    "test_server",
+]

openapi_to_mcp/commands/diff.py

@@ -0,0 +1,138 @@
+"""CLI command for diffing MCP-surface changes between two specs."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Literal
+
+import rich_click as click
+
+from openapi_to_mcp.adapters.spec_loader import SpecLoader
+from openapi_to_mcp.common import MappingError
+from openapi_to_mcp.common.exceptions import SpecLoaderError
+from openapi_to_mcp.common.terminal import (
+    print_error_panel,
+    print_section,
+    print_success_panel,
+    print_warning_panel,
+)
+from openapi_to_mcp.diff import DiffAnalyzer, DiffReport
+
+OutputFormat = Literal["json", "text"]
+
+if TYPE_CHECKING:
+    from openapi_to_mcp.diff.models import FailMode
+
+
+@click.command()
+@click.option(
+    "--before-openapi-json",
+    "-b",
+    required=True,
+    help="Old OpenAPI specification JSON or YAML path or URL.",
+)
+@click.option(
+    "--after-openapi-json",
+    "-a",
+    required=True,
+    help="New OpenAPI specification JSON or YAML path or URL.",
+)
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["text", "json"], case_sensitive=False),
+    default="text",
+    show_default=True,
+    help="Output format for the diff report.",
+)
+@click.option(
+    "--fail-on",
+    type=click.Choice(["none", "breaking"], case_sensitive=False),
+    default="none",
+    show_default=True,
+    help="Exit non-zero when the selected change class is present.",
+)
+def diff(
+    before_openapi_json: str,
+    after_openapi_json: str,
+    output_format: OutputFormat,
+    fail_on: FailMode,
+) -> None:
+    """Compare two OpenAPI specs as generated MCP tool surfaces."""
+    report = _build_report(before_openapi_json, after_openapi_json)
+    _render_report(report, output_format, fail_on)
+    raise click.exceptions.Exit(report.exit_code(fail_on))
+
+
+def _build_report(before_source: str, after_source: str) -> DiffReport:
+    before_spec = _load_spec(before_source)
+    after_spec = _load_spec(after_source)
+    try:
+        return DiffAnalyzer(before_spec, after_spec).analyze(
+            before_source, after_source
+        )
+    except MappingError as exc:
+        err_msg = (
+            f"Unable to diff MCP surface: {exc}. "
+            "Run `openapi-to-mcp doctor` on both specs first."
+        )
+        raise click.ClickException(err_msg) from exc
+
+
+def _load_spec(source: str) -> dict:
+    try:
+        return SpecLoader(source=source).load_and_validate()
+    except SpecLoaderError as exc:
+        raise click.ClickException(f"Failed to load spec `{source}`: {exc}") from exc
+
+
+def _render_report(
+    report: DiffReport, output_format: OutputFormat, fail_on: FailMode
+) -> None:
+    if output_format == "json":
+        click.echo(json.dumps(report.to_dict(fail_on), indent=2))
+        return
+    if not report.changes:
+        print_success_panel(
+            "Diff Report",
+            [
+                f"Before: {report.before_source}",
+                f"After: {report.after_source}",
+                "No MCP-surface changes detected.",
+                f"Exit code: {report.exit_code(fail_on)}",
+            ],
+        )
+        return
+    _print_summary(report, fail_on)
+    for change in report.changes:
+        _render_change(change.to_dict())
+
+
+def _print_summary(report: DiffReport, fail_on: FailMode) -> None:
+    lines = [
+        f"Before: {report.before_source}",
+        f"After: {report.after_source}",
+        f"Breaking: {report.breaking_count()}",
+        f"Non-breaking: {report.non_breaking_count()}",
+        f"Exit code: {report.exit_code(fail_on)}",
+    ]
+    if report.breaking_count() > 0:
+        print_error_panel("Diff Summary", lines)
+        return
+    print_warning_panel("Diff Summary", lines)
+
+
+def _render_change(change: dict[str, object]) -> None:
+    print_section(f"{_format_impact(change['impact'])}: {change['code']}")
+    click.echo(f"Location: {change['location']}")
+    click.echo(f"Issue: {change['message']}")
+    details = change.get("details")
+    if isinstance(details, dict) and details:
+        click.echo(f"Details: {json.dumps(details, sort_keys=True)}")
+    click.echo(f"Hint: {change['hint']}")
+    click.echo()
+
+
+def _format_impact(impact: object) -> str:
+    value = str(impact).replace("_", "-")
+    return value.upper()

openapi_to_mcp/commands/doctor.py

@@ -0,0 +1,97 @@
+"""Doctor command for spec-readiness diagnostics."""
+
+from __future__ import annotations
+
+import json
+from typing import Literal
+
+import rich_click as click
+
+from openapi_to_mcp.adapters.spec_loader import SpecLoader
+from openapi_to_mcp.common.exceptions import SpecLoaderError
+from openapi_to_mcp.common.terminal import (
+    print_error_panel,
+    print_section,
+    print_success_panel,
+    print_warning_panel,
+)
+from openapi_to_mcp.doctor import DoctorAnalyzer, DoctorReport
+
+OutputFormat = Literal["json", "text"]
+
+
+@click.command()
+@click.option(
+    "--openapi-json",
+    "-o",
+    required=True,
+    help="Path or URL to OpenAPI specification JSON or YAML file.",
+)
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["text", "json"], case_sensitive=False),
+    default="text",
+    show_default=True,
+    help="Output format for diagnostics.",
+)
+def doctor(openapi_json: str, output_format: OutputFormat) -> None:
+    """Inspect an OpenAPI spec for MCP-generation readiness."""
+    report = _build_report(openapi_json)
+    _render_report(report, output_format)
+    raise click.exceptions.Exit(report.exit_code())
+
+
+def _build_report(source: str) -> DoctorReport:
+    try:
+        spec = SpecLoader(source=source).load_and_validate()
+    except SpecLoaderError as exc:
+        report = DoctorReport(source=source)
+        report.add_error(
+            "spec_load_failed",
+            str(exc),
+            source,
+            "Fix the spec source or validation error before generating an MCP server.",
+        )
+        return report
+    return DoctorAnalyzer(spec).analyze(source)
+
+
+def _render_report(report: DoctorReport, output_format: OutputFormat) -> None:
+    if output_format == "json":
+        click.echo(json.dumps(report.to_dict(), indent=2))
+        return
+    if not report.issues:
+        print_success_panel(
+            "Doctor Report",
+            [
+                f"Source: {report.source}",
+                "No readiness issues found.",
+                "Exit code: 0",
+            ],
+        )
+        return
+    _print_summary_panel(report)
+    for issue in report.issues:
+        _render_issue(issue.to_dict())
+
+
+def _render_issue(issue: dict[str, str]) -> None:
+    print_section(f"{issue['severity'].upper()}: {issue['code']}")
+    click.echo(f"Location: {issue['location']}")
+    click.echo(f"Issue: {issue['message']}")
+    click.echo(f"Hint: {issue['hint']}")
+    click.echo()
+
+
+def _print_summary_panel(report: DoctorReport) -> None:
+    lines = [
+        f"Source: {report.source}",
+        f"Errors: {report.error_count()}",
+        f"Warnings: {report.warning_count()}",
+        f"Exit code: {report.exit_code()}",
+    ]
+    if report.error_count() > 0:
+        print_error_panel("Doctor Summary", lines)
+        return
+    print_warning_panel("Doctor Summary", lines)

openapi_to_mcp/commands/generate.py

@@ -0,0 +1,78 @@
+"""CLI adapter for MCP project generation."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Unpack
+
+import rich_click as click
+
+from openapi_to_mcp.commands.generation_models import (
+    GenerateClickOptions,
+    GenerationRequest,
+    compose_generation_request,
+    generation_cli_values,
+)
+from openapi_to_mcp.commands.generation_service import generate_project
+from openapi_to_mcp.commands.options import add_options, generate_options
+from openapi_to_mcp.commands.policy_support import load_policy_and_settings
+from openapi_to_mcp.common.exceptions import (
+    GenerationError,
+    MappingError,
+    NoToolsMappedError,
+    PolicyConfigError,
+    SchemaError,
+    SpecLoaderError,
+)
+from openapi_to_mcp.common.terminal import print_success_panel
+
+logger = logging.getLogger(__name__)
+
+
+def _generation_request(options: GenerateClickOptions) -> GenerationRequest:
+    policy, values = load_policy_and_settings(
+        generation_cli_values(options), options["config"]
+    )
+    return compose_generation_request(
+        options["openapi_json"], options["output_dir"], values, policy
+    )
+
+
+def _print_success(output_dir: str) -> None:
+    print_success_panel(
+        "MCP Server Generation Successful",
+        [
+            f"Files generated in: {output_dir}",
+            "Check the generated README for build and runtime instructions.",
+        ],
+    )
+
+
+@click.command()
+@add_options(generate_options)
+def generate(**options: Unpack[GenerateClickOptions]) -> None:
+    """Generate a Node.js/TypeScript MCP server from an OpenAPI specification."""
+    try:
+        generate_project(request=_generation_request(options))
+        logger.info("MCP server generation successful.")
+        _print_success(options["output_dir"])
+    except NoToolsMappedError as error:
+        if error.is_error:
+            raise click.ClickException(str(error)) from error
+        click.echo(str(error))
+    except click.ClickException:
+        raise
+    except (
+        SpecLoaderError,
+        MappingError,
+        GenerationError,
+        PolicyConfigError,
+        SchemaError,
+    ) as error:
+        raise click.ClickException(str(error)) from error
+    except Exception as error:
+        logger.critical(
+            "An unexpected critical error occurred: %s", error, exc_info=True
+        )
+        sys.exit(1)

openapi_to_mcp/commands/generation_context.py

@@ -0,0 +1,109 @@
+"""Build template context values for generated MCP servers."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from openapi_to_mcp.common.performance_presets import performance_preset_context
+
+if TYPE_CHECKING:
+    from openapi_to_mcp.commands.generation_models import GenerationSettings
+
+logger = logging.getLogger(__name__)
+
+
+def _server_name(provided: str | None, spec_info: dict[str, Any]) -> str:
+    if provided:
+        return provided
+    title = spec_info.get("title")
+    if title:
+        logger.info("Using server name from OpenAPI spec info.title: %s", title)
+        return str(title)
+    default = "openapi-mcp-server"
+    logger.warning(
+        "Server name not provided and not found in spec title. Using default: %s",
+        default,
+    )
+    return default
+
+
+def _server_version(provided: str | None, spec_info: dict[str, Any]) -> str:
+    if provided:
+        return provided
+    version = spec_info.get("version")
+    if version:
+        logger.info("Using server version from OpenAPI spec info.version: %s", version)
+        return str(version)
+    default = "1.0.0"
+    logger.warning(
+        "Server version not provided and not found in spec version. Using default: %s",
+        default,
+    )
+    return default
+
+
+def _swagger_base_url(spec: dict[str, Any]) -> str | None:
+    host = spec.get("host")
+    if not isinstance(host, str) or not host:
+        return None
+    base_path = spec.get("basePath", "")
+    schemes = spec.get("schemes", [])
+    scheme = schemes[0] if isinstance(schemes, list) and schemes else "https"
+    if not isinstance(base_path, str):
+        base_path = ""
+    if not isinstance(scheme, str) or not scheme:
+        return None
+    url = f"{scheme}://{host}{base_path}"
+    logger.info("Using base URL from Swagger 2 host/basePath: %s", url)
+    return url
+
+
+def _base_url(spec: dict[str, Any]) -> str:
+    servers = spec.get("servers", [])
+    if isinstance(servers, list) and servers:
+        first_server = servers[0]
+        if isinstance(first_server, dict) and isinstance(first_server.get("url"), str):
+            url = first_server["url"]
+            logger.info("Using base URL from spec servers[0].url: %s", url)
+            return url
+        logger.warning(
+            "First server object in spec lacks a valid 'url' string. Using placeholder for .env."
+        )
+    swagger_url = _swagger_base_url(spec)
+    if swagger_url is not None:
+        return swagger_url
+    logger.warning(
+        "No 'servers' array found and no Swagger 2 host/basePath detected. Using placeholder for .env."
+    )
+    return "YOUR_API_BASE_URL_HERE"
+
+
+def build_template_context(
+    spec: dict[str, Any],
+    settings: GenerationSettings,
+    public_tools: list[dict[str, Any]],
+    runtime_tools: dict[str, dict[str, Any]],
+    auth_env_vars: list[str],
+) -> dict[str, Any]:
+    """Build the Jinja context consumed by the project generator."""
+    spec_info = spec.get("info", {})
+    identity = settings.identity
+    transport = settings.transport
+    behavior = settings.behavior
+    return {
+        "server_name": _server_name(identity.name, spec_info),
+        "server_version": _server_version(identity.version, spec_info),
+        "server_description": spec_info.get("description", ""),
+        "transport": transport.kind,
+        "host": transport.host,
+        "port": transport.port,
+        "mcp_endpoint": transport.endpoint,
+        "strict": behavior.strict,
+        "runtime_validation": behavior.runtime_validation,
+        "tools": public_tools,
+        "runtime_tools": runtime_tools,
+        "auth_env_vars": auth_env_vars,
+        "api_base_url_comment": _base_url(spec),
+        "performance_presets": performance_preset_context(),
+    }