spec2openapi 0.1.0__py3-none-any.whl

spec2openapi/cli.py

@@ -0,0 +1,330 @@
+"""spec2openapi command line interface.
+
+  spec2openapi convert service.wsdl -o service.openapi.yaml
+  spec2openapi upgrade swagger2.json -o service.openapi.yaml
+  spec2openapi inspect service.wsdl
+  spec2openapi validate service.openapi.yaml   # incl. FastMCP round-trip
+  spec2openapi serve spec.yaml --transport http   # reference MCP runtime
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from . import __version__
+
+_MCP_HINT = "install the MCP runtime extras first: pip install 'spec2openapi[mcp]'"
+
+
+def _is_wsdl_source(src: str) -> bool:
+    low = src.lower()
+    if low.endswith((".yaml", ".yml", ".json")):
+        return False
+    if low.endswith((".wsdl", "?wsdl")):
+        return True
+    if "?" in low and "wsdl" in low.split("?", 1)[1]:  # e.g. ?singleWsdl
+        return True
+    p = Path(src)
+    if p.exists():
+        head = p.read_text(encoding="utf-8", errors="replace")[:512].lstrip()
+        return head.startswith("<")
+    return False
+
+
+def _load_or_convert(source: str) -> dict:
+    from .convert import convert_wsdl, load_spec
+    from .swagger import convert_swagger, is_swagger2
+
+    if _is_wsdl_source(source):
+        return convert_wsdl(source)
+    spec = load_spec(source)
+    if is_swagger2(spec):
+        print("note: Swagger 2.0 input detected; upgrading to OpenAPI 3.0 "
+              "in memory (see `spec2openapi upgrade`)", file=sys.stderr)
+        spec = convert_swagger(spec)
+    return spec
+
+
+def _add_bridge_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--endpoint", help="override SOAP endpoint URL "
+                                      "(env SPEC2OPENAPI_ENDPOINT)")
+    p.add_argument("--auth", choices=["basic", "wsse"],
+                   help="authentication scheme (env SPEC2OPENAPI_AUTH)")
+    p.add_argument("--username", help="env SPEC2OPENAPI_USERNAME")
+    p.add_argument("--password", help="env SPEC2OPENAPI_PASSWORD")
+    p.add_argument("--timeout", type=float, default=None,
+                   help="SOAP call timeout seconds (default 30)")
+    p.add_argument("--insecure", action="store_true",
+                   help="disable TLS certificate verification")
+
+
+def _bridge_options(args):
+    from .bridge import BridgeOptions
+
+    opt = BridgeOptions.from_env()
+    if args.endpoint:
+        opt.endpoint = args.endpoint
+    if args.auth:
+        opt.auth = args.auth
+    if args.username:
+        opt.username = args.username
+    if args.password:
+        opt.password = args.password
+    if args.timeout is not None:
+        opt.timeout = args.timeout
+    if args.insecure:
+        opt.verify = False
+    return opt
+
+
+def cmd_convert(args) -> int:
+    from .convert import convert_wsdl, dump_spec
+
+    spec = convert_wsdl(
+        args.wsdl, title=args.title, version=args.spec_version,
+        base_path=args.base_path, service=args.service, port=args.port_name,
+        prefer_soap12=args.prefer_soap12, strict=args.strict,
+        openapi_version=args.openapi_version,
+        forbid_external=args.forbid_external, huge_tree=args.huge_tree,
+    )
+    fmt = args.format or ("json" if (args.output or "").endswith(".json") else "yaml")
+    text = dump_spec(spec, fmt)
+    if args.output:
+        Path(args.output).write_text(text, encoding="utf-8")
+        n = len(spec.get("paths", {}))
+        print(f"wrote {args.output} ({n} operations)", file=sys.stderr)
+    else:
+        print(text)
+    return 0
+
+
+def cmd_inspect(args) -> int:
+    from .parser import parse_wsdl
+
+    parsed = parse_wsdl(args.wsdl, forbid_external=args.forbid_external,
+                        huge_tree=args.huge_tree)
+    print(f"service : {parsed.name}")
+    if parsed.documentation:
+        print(f"doc     : {parsed.documentation}")
+    print(f"ops     : {len(parsed.operations)}")
+    for op in parsed.operations:
+        params = ", ".join(n for n, _ in op.input_element.type.elements)
+        extras = []
+        if op.headers:
+            extras.append(f"headers: {', '.join(h.part for h in op.headers)}")
+        if op.faults:
+            extras.append(f"faults: {', '.join(f.name for f in op.faults)}")
+        suffix = f"  ({'; '.join(extras)})" if extras else ""
+        print(f"  - {op.op_id}({params})  [SOAP {op.soap_version}, {op.style}]"
+              f" {op.endpoint}{suffix}")
+        if op.documentation:
+            print(f"      {op.documentation}")
+    for name, reason in parsed.skipped:
+        print(f"  ! skipped {name}: {reason}")
+    return 0
+
+
+def cmd_upgrade(args) -> int:
+    from .convert import dump_spec, load_spec
+    from .swagger import convert_swagger
+
+    spec = load_spec(args.source)
+    upgraded = convert_swagger(spec, openapi_version=args.openapi_version)
+
+    report = upgraded.get("x-s2o", {})
+    for kind in ("assumptions", "lossy"):
+        for msg in report.get(kind, []):
+            print(f"{kind[:-1] if kind.endswith('s') else kind}: {msg}",
+                  file=sys.stderr)
+
+    fmt = args.format or ("json" if (args.output or "").endswith(".json") else "yaml")
+    text = dump_spec(upgraded, fmt)
+    if args.output:
+        Path(args.output).write_text(text, encoding="utf-8")
+        n = len(upgraded.get("paths", {}))
+        print(f"wrote {args.output} ({n} paths, "
+              f"{len(report.get('assumptions', []))} assumptions, "
+              f"{len(report.get('lossy', []))} lossy)", file=sys.stderr)
+    else:
+        print(text)
+    return 0
+
+
+def cmd_validate(args) -> int:
+    """Static checks + optional FastMCP round-trip on a spec (or WSDL)."""
+    import re
+
+    spec = _load_or_convert(args.source)
+    problems: list[str] = []
+
+    paths = spec.get("paths", {})
+    if not paths:
+        problems.append("spec has no paths")
+    op_ids: list[str] = []
+    for path, item in paths.items():
+        for method, op in (item or {}).items():
+            if not isinstance(op, dict):
+                continue
+            oid = op.get("operationId")
+            if not oid:
+                problems.append(f"{method.upper()} {path}: missing operationId")
+                continue
+            op_ids.append(oid)
+            if not re.fullmatch(r"[A-Za-z0-9_.-]{1,64}", oid):
+                problems.append(f"{oid}: not a safe MCP tool name")
+            if op.get("x-soap") and not op["x-soap"].get("input", {}).get("element"):
+                problems.append(f"{oid}: x-soap.input.element missing")
+    dupes = {o for o in op_ids if op_ids.count(o) > 1}
+    if dupes:
+        problems.append(f"duplicate operationIds: {sorted(dupes)}")
+
+    print(f"operations        : {len(op_ids)}")
+    print(f"component schemas : {len(spec.get('components', {}).get('schemas', {}))}")
+
+    try:  # optional deep validation
+        from openapi_spec_validator import validate as osv_validate
+
+        osv_validate(spec)
+        print("openapi-spec-validator: OK")
+    except ImportError:
+        print("openapi-spec-validator: not installed (skipped)")
+    except Exception as exc:
+        problems.append(f"openapi-spec-validator: {exc}")
+
+    try:  # FastMCP round-trip: the compatibility this project guarantees
+        import anyio
+        from fastmcp import Client, FastMCP
+
+        mcp = FastMCP.from_openapi(openapi_spec=spec, name="validate")
+
+        async def _tools():
+            async with Client(mcp) as client:
+                return await client.list_tools()
+
+        tools = anyio.run(_tools)
+        print(f"FastMCP round-trip: OK ({len(tools)} tools)")
+        for tool in sorted(tools, key=lambda t: t.name):
+            schema = getattr(tool, "inputSchema", None) or {}
+            params = ", ".join((schema.get("properties") or {}).keys())
+            print(f"  - {tool.name}({params})")
+        tool_names = {t.name for t in tools}
+
+        def _norm(s: str) -> str:  # FastMCP tool-name normalization
+            return re.sub(r"[^A-Za-z0-9_]", "_", s)
+
+        renamed = {o for o in op_ids
+                   if o not in tool_names and _norm(o) in tool_names}
+        for o in sorted(renamed):
+            print(f"note: operationId '{o}' is exposed as tool "
+                  f"'{_norm(o)}' (FastMCP normalization)")
+        missing = {o for o in op_ids
+                   if o not in tool_names and _norm(o) not in tool_names}
+        if missing:
+            problems.append(f"operations not materialized as tools: {sorted(missing)}")
+    except ImportError:
+        print(f"FastMCP round-trip: fastmcp not installed (skipped) - {_MCP_HINT}")
+    except Exception as exc:
+        problems.append(f"FastMCP round-trip failed: {exc}")
+
+    if problems:
+        print("\nFAIL")
+        for p in problems:
+            print(f"  ! {p}")
+        return 1
+    print("\nOK: spec is FastMCP-convertible")
+    return 0
+
+
+def cmd_serve(args) -> int:
+    try:
+        from .server import from_openapi_spec
+    except ImportError:
+        print(f"error: {_MCP_HINT}", file=sys.stderr)
+        return 2
+
+    spec = _load_or_convert(args.source)
+    mcp = from_openapi_spec(
+        spec, options=_bridge_options(args),
+        validate_output=args.validate_output,
+    )
+    if args.transport == "http":
+        mcp.run(transport="http", host=args.host, port=args.port,
+                path=args.path, show_banner=False)
+    else:
+        mcp.run(show_banner=False)  # stdio
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    logging.basicConfig(level=logging.INFO, stream=sys.stderr,
+                        format="%(levelname)s %(name)s: %(message)s")
+    ap = argparse.ArgumentParser(
+        prog="spec2openapi",
+        description="Convert SOAP/WSDL services into FastMCP-ready OpenAPI "
+                    "specs (x-soap extensions carry the SOAP binding).",
+    )
+    ap.add_argument("--version", action="version",
+                    version=f"spec2openapi {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    c = sub.add_parser("convert", help="WSDL -> OpenAPI spec with x-soap extensions")
+    c.add_argument("wsdl", help="WSDL path or URL")
+    c.add_argument("-o", "--output", help="output file (default: stdout)")
+    c.add_argument("--format", choices=["yaml", "json"])
+    c.add_argument("--title", help="override info.title")
+    c.add_argument("--spec-version", default="1.0.0", help="info.version")
+    c.add_argument("--base-path", default="/operations")
+    c.add_argument("--openapi-version", choices=["3.0", "3.1"], default="3.0")
+    c.add_argument("--service", help="pick a wsdl:service by name")
+    c.add_argument("--port-name", help="pick a wsdl:port by name")
+    c.add_argument("--prefer-soap12", action="store_true")
+    c.add_argument("--strict", action="store_true",
+                   help="fail instead of skipping unsupported operations")
+    c.add_argument("--forbid-external", action="store_true",
+                   help="refuse to fetch remote wsdl:/xsd: imports "
+                        "(recommended for WSDLs from untrusted sources)")
+    c.add_argument("--huge-tree", action="store_true",
+                   help="lift libxml2 depth/size limits for very large WSDLs")
+    c.set_defaults(fn=cmd_convert)
+
+    i = sub.add_parser("inspect", help="list operations found in a WSDL")
+    i.add_argument("wsdl", help="WSDL path or URL")
+    i.add_argument("--forbid-external", action="store_true",
+                   help="refuse to fetch remote wsdl:/xsd: imports")
+    i.add_argument("--huge-tree", action="store_true",
+                   help="lift libxml2 depth/size limits for very large WSDLs")
+    i.set_defaults(fn=cmd_inspect)
+
+    u = sub.add_parser("upgrade",
+                       help="Swagger 2.0 -> OpenAPI 3.x (FastMCP needs 3.x)")
+    u.add_argument("source", help="Swagger 2.0 file (.yaml/.json)")
+    u.add_argument("-o", "--output", help="output file (default: stdout)")
+    u.add_argument("--format", choices=["yaml", "json"])
+    u.add_argument("--openapi-version", choices=["3.0", "3.1"], default="3.0")
+    u.set_defaults(fn=cmd_upgrade)
+
+    v = sub.add_parser("validate",
+                       help="check a spec (or WSDL) for FastMCP convertibility")
+    v.add_argument("source", help="OpenAPI spec (.yaml/.json) or WSDL path/URL")
+    v.set_defaults(fn=cmd_validate)
+
+    s = sub.add_parser("serve",
+                       help="reference MCP runtime (requires [mcp] extra)")
+    s.add_argument("source", help="OpenAPI spec (.yaml/.json) or WSDL path/URL")
+    s.add_argument("--transport", choices=["stdio", "http"], default="stdio")
+    s.add_argument("--host", default="0.0.0.0")
+    s.add_argument("--port", type=int, default=8000)
+    s.add_argument("--path", default="/mcp")
+    s.add_argument("--validate-output", action="store_true",
+                   help="validate tool output against the response schema")
+    _add_bridge_args(s)
+    s.set_defaults(fn=cmd_serve)
+
+    args = ap.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

spec2openapi/convert.py

@@ -0,0 +1,62 @@
+"""Core conversion API (no MCP/httpx dependencies).
+
+    spec = spec2openapi.convert_wsdl("https://host/service?wsdl")
+    spec2openapi.dump_spec(spec)          # yaml/json text
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .openapi import build_spec, dump_spec  # noqa: F401  (re-exported)
+from .parser import parse_wsdl
+
+
+def convert_wsdl(
+    source: str,
+    *,
+    title: str | None = None,
+    version: str = "1.0.0",
+    base_path: str = "/operations",
+    service: str | None = None,
+    port: str | None = None,
+    prefer_soap12: bool = False,
+    strict: bool = False,
+    openapi_version: str = "3.0",
+    forbid_external: bool = False,
+    huge_tree: bool = False,
+) -> dict[str, Any]:
+    """WSDL (path/URL) -> OpenAPI dict with x-soap extensions.
+
+    Set forbid_external=True when the WSDL comes from an untrusted source
+    (refuses to fetch remote wsdl:/xsd: imports).
+    """
+    parsed = parse_wsdl(
+        source, service=service, port=port,
+        prefer_soap12=prefer_soap12, strict=strict,
+        forbid_external=forbid_external, huge_tree=huge_tree,
+    )
+    return build_spec(
+        parsed, title=title, version=version,
+        base_path=base_path, openapi_version=openapi_version,
+    )
+
+
+def load_spec(path: str | Path) -> dict[str, Any]:
+    """Load an OpenAPI spec from a .yaml/.yml/.json file."""
+    p = Path(path)
+    text = p.read_text(encoding="utf-8")
+    if p.suffix.lower() == ".json" or text.lstrip().startswith("{"):
+        return json.loads(text)
+    import yaml
+
+    return yaml.safe_load(text)
+
+
+def spec_has_soap(spec: dict[str, Any]) -> bool:
+    for item in spec.get("paths", {}).values():
+        for method in (item or {}).values():
+            if isinstance(method, dict) and method.get("x-soap"):
+                return True
+    return False

spec2openapi/openapi.py

@@ -0,0 +1,234 @@
+"""Assemble the parsed WSDL model into an OpenAPI spec (3.0 or 3.1).
+
+The spec is a valid, ordinary OpenAPI document that FastMCP's
+`from_openapi()` can consume directly. SOAP binding metadata is embedded in
+vendor extensions:
+
+- root  `x-soap`  : wsdl source, generator info, skipped operations
+- op    `x-soap`  : soapAction, soapVersion, style, endpoint, wrapper
+                    element QNames, soap:header parts, declared faults
+- schemas carry OpenAPI `xml` annotations (name / namespace / attribute /
+  x-text) which a SOAP call layer uses to serialize JSON <-> literal XML.
+
+Property order inside `properties` mirrors the XSD sequence order and MUST
+be preserved (do not alphabetize the document).
+"""
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlparse
+
+from . import __version__ as _version
+from .parser import ParsedWsdl
+import re
+
+from .schema import SchemaConverter, sanitize_name
+
+_TOOL_ID_RE = re.compile(r"[^A-Za-z0-9_]+")
+
+SOAP_FAULT_SCHEMA = {
+    "type": "object",
+    "description": "SOAP Fault mapped to a JSON error payload.",
+    "properties": {
+        "faultcode": {"type": "string"},
+        "faultstring": {"type": "string"},
+        "detail": {"type": "string"},
+    },
+}
+
+
+def _origin(url: str) -> str:
+    try:
+        p = urlparse(url)
+        if p.scheme and p.netloc:
+            return f"{p.scheme}://{p.netloc}"
+    except Exception:
+        pass
+    return url or "http://localhost"
+
+
+def _element_qname(element: Any) -> dict[str, Any]:
+    qname = getattr(element, "qname", None)
+    if qname is None:
+        return {"element": getattr(element, "name", ""), "namespace": None}
+    return {"element": qname.localname, "namespace": qname.namespace}
+
+
+def build_spec(
+    parsed: ParsedWsdl,
+    *,
+    title: str | None = None,
+    version: str = "1.0.0",
+    base_path: str = "/operations",
+    openapi_version: str = "3.0",
+) -> dict[str, Any]:
+    conv = SchemaConverter(parsed.xsd_meta)
+    paths: dict[str, Any] = {}
+
+    for op in parsed.operations:
+        # FastMCP normalizes tool names to [A-Za-z0-9_]; emit operationIds
+        # in that alphabet so tool name == operationId after the round-trip
+        op_id = _TOOL_ID_RE.sub("_", sanitize_name(op.op_id)).strip("_")
+        in_q = _element_qname(op.input_element)
+        in_schema = conv.element_type_to_object_schema(
+            op.input_element.type,
+            hint=f"{op_id}Input",
+            qkey=(in_q["namespace"] or "", in_q["element"]),
+        )
+        has_params = bool(in_schema.get("properties"))
+
+        if op.output_element is not None:
+            out_q = _element_qname(op.output_element)
+            out_schema = conv.element_type_to_object_schema(
+                op.output_element.type,
+                hint=f"{op_id}Output",
+                qkey=(out_q["namespace"] or "", out_q["element"]),
+            )
+        else:
+            out_schema = {"type": "object"}
+
+        x_soap: dict[str, Any] = {
+            "operation": op.name,
+            "service": op.service,
+            "port": op.port,
+            "soapAction": op.soap_action,
+            "soapVersion": op.soap_version,
+            "style": op.style,
+            "endpoint": op.endpoint,
+            "input": _element_qname(op.input_element),
+        }
+        if op.output_element is not None:
+            x_soap["output"] = _element_qname(op.output_element)
+
+        doc_lines = [
+            op.documentation
+            or f"SOAP operation {op.name} of service {op.service}."
+        ]
+
+        if op.headers:
+            hmeta = []
+            for h in op.headers:
+                comp = conv.register_element_component(
+                    h.element, hint=f"{op_id}Header_{h.part}"
+                )
+                entry = _element_qname(h.element)
+                entry["part"] = h.part
+                entry["schema"] = f"#/components/schemas/{comp}"
+                hmeta.append(entry)
+            x_soap["headers"] = hmeta
+            names = ", ".join(h["element"] for h in hmeta)
+            doc_lines.append(
+                f"Requires SOAP header(s): {names} "
+                "(supplied by the runtime, not by tool arguments)."
+            )
+
+        if op.faults:
+            fmeta = []
+            fault_names = []
+            for f in op.faults:
+                entry: dict[str, Any] = {"name": f.name}
+                if f.element is not None:
+                    entry.update(_element_qname(f.element))
+                    comp = conv.register_element_component(
+                        f.element, hint=f"{op_id}Fault_{f.name}"
+                    )
+                    entry["schema"] = f"#/components/schemas/{comp}"
+                fmeta.append(entry)
+                fault_names.append(f.name)
+            x_soap["faults"] = fmeta
+            doc_lines.append(f"Declared faults: {', '.join(fault_names)}.")
+
+        description = "\n".join(doc_lines)
+        post: dict[str, Any] = {
+            "operationId": op_id,
+            "summary": doc_lines[0].splitlines()[0][:120],
+            "description": description,
+            "tags": [op.service],
+            "x-soap": x_soap,
+            "requestBody": {
+                "required": has_params,
+                "content": {"application/json": {"schema": in_schema}},
+            },
+            "responses": {
+                "200": {
+                    "description": f"Result of SOAP operation {op.name}",
+                    "content": {"application/json": {"schema": out_schema}},
+                },
+                "500": {
+                    "description": "SOAP Fault"
+                    + (
+                        f" (declared: {', '.join(f.name for f in op.faults)})"
+                        if op.faults
+                        else ""
+                    ),
+                    "content": {
+                        "application/json": {
+                            "schema": {"$ref": "#/components/schemas/SoapFault"}
+                        }
+                    },
+                },
+            },
+        }
+        paths[f"{base_path}/{op_id}"] = {"post": post}
+
+    endpoint = parsed.operations[0].endpoint if parsed.operations else ""
+    components = dict(conv.components)
+    components["SoapFault"] = SOAP_FAULT_SCHEMA
+
+    spec: dict[str, Any] = {
+        "openapi": "3.0.3",
+        "info": {
+            "title": title or parsed.name,
+            "version": version,
+            "description": parsed.documentation
+            or f"Generated from WSDL by spec2openapi {_version}. "
+            f"Each path is a SOAP operation exposed as a JSON call.",
+        },
+        "servers": [{"url": _origin(endpoint)}],
+        "paths": paths,
+        "components": {"schemas": components},
+        "x-soap": {
+            "wsdl": parsed.source,
+            "generator": f"spec2openapi/{_version}",
+            "skippedOperations": [
+                {"operation": o, "reason": r} for o, r in parsed.skipped
+            ],
+        },
+    }
+    if openapi_version.startswith("3.1"):
+        spec = to_openapi_31(spec)
+    return spec
+
+
+def to_openapi_31(spec: dict[str, Any]) -> dict[str, Any]:
+    """Convert the generated 3.0 document to OpenAPI 3.1 JSON Schema style."""
+
+    def walk(node: Any) -> Any:
+        if isinstance(node, list):
+            return [walk(v) for v in node]
+        if not isinstance(node, dict):
+            return node
+        node = {k: walk(v) for k, v in node.items()}
+        if node.pop("nullable", False):
+            t = node.get("type")
+            if isinstance(t, str):
+                node["type"] = [t, "null"]
+        if node.get("exclusiveMinimum") is True and "minimum" in node:
+            node["exclusiveMinimum"] = node.pop("minimum")
+        if node.get("exclusiveMaximum") is True and "maximum" in node:
+            node["exclusiveMaximum"] = node.pop("maximum")
+        return node
+
+    out = walk(dict(spec))
+    out["openapi"] = "3.1.0"
+    return out
+
+
+def dump_spec(spec: dict[str, Any], fmt: str = "yaml") -> str:
+    if fmt == "json":
+        import json
+
+        return json.dumps(spec, indent=2, ensure_ascii=False)
+    import yaml
+
+    return yaml.safe_dump(spec, sort_keys=False, allow_unicode=True, width=100)