spec2openapi 0.1.0__py3-none-any.whl

spec2openapi/__init__.py

@@ -0,0 +1,55 @@
+"""spec2openapi: SOAP/WSDL -> FastMCP-ready OpenAPI specs.
+
+Core API (no MCP dependencies): convert_wsdl, load_spec, dump_spec,
+spec_has_soap, parse_wsdl, build_spec.
+
+Optional MCP runtime (pip install 'spec2openapi[mcp]'): from_openapi_spec,
+from_wsdl, BridgeOptions, SoapBridgeTransport.
+"""
+
+__version__ = "0.1.0"
+
+from .convert import convert_wsdl, load_spec, spec_has_soap  # noqa: E402,F401
+from .openapi import build_spec, dump_spec, to_openapi_31  # noqa: E402,F401
+from .parser import parse_wsdl  # noqa: E402,F401
+from .swagger import convert_swagger, is_swagger2  # noqa: E402,F401
+
+_MCP_ATTRS = {
+    "from_openapi_spec": "server",
+    "from_wsdl": "server",
+    "BridgeOptions": "bridge",
+    "SoapBridgeTransport": "bridge",
+}
+
+__all__ = [
+    "__version__",
+    "convert_wsdl",
+    "load_spec",
+    "dump_spec",
+    "spec_has_soap",
+    "parse_wsdl",
+    "build_spec",
+    "to_openapi_31",
+    "convert_swagger",
+    "is_swagger2",
+    # lazily loaded, require the [mcp] extra:
+    "from_openapi_spec",
+    "from_wsdl",
+    "BridgeOptions",
+    "SoapBridgeTransport",
+]
+
+
+def __getattr__(name: str):
+    if name in _MCP_ATTRS:
+        import importlib
+
+        try:
+            module = importlib.import_module(f".{_MCP_ATTRS[name]}", __name__)
+        except ImportError as exc:
+            raise ImportError(
+                f"spec2openapi.{name} requires optional dependencies; "
+                "install them with: pip install 'spec2openapi[mcp]'"
+            ) from exc
+        return getattr(module, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

spec2openapi/bridge.py

@@ -0,0 +1,478 @@
+"""SOAP bridge: an httpx transport that turns REST/JSON calls generated by
+FastMCP's OpenAPI integration into literal SOAP calls.
+
+FastMCP tool call -> POST {base}/operations/{op} (JSON)
+    -> [this transport] JSON -> SOAP envelope (metadata from x-soap + xml
+       annotations in the spec) -> real SOAP endpoint -> XML response ->
+       JSON (shaped by the response schema) -> httpx.Response(200, json)
+
+The container image stays fixed: swapping the OpenAPI spec (ConfigMap) is
+enough to expose a different SOAP service as MCP.
+"""
+from __future__ import annotations
+
+import dataclasses
+import json
+import logging
+import os
+from typing import Any
+
+import httpx
+from lxml import etree
+
+logger = logging.getLogger("spec2openapi")
+
+SOAP_ENV_NS = {
+    "1.1": "http://schemas.xmlsoap.org/soap/envelope/",
+    "1.2": "http://www.w3.org/2003/05/soap-envelope",
+}
+XSI_NS = "http://www.w3.org/2001/XMLSchema-instance"
+WSSE_NS = (
+    "http://docs.oasis-open.org/wss/2004/01/"
+    "oasis-200401-wss-wssecurity-secext-1.0.xsd"
+)
+PASSWORD_TEXT = (
+    "http://docs.oasis-open.org/wss/2004/01/"
+    "oasis-200401-wss-username-token-profile-1.0#PasswordText"
+)
+
+
+@dataclasses.dataclass
+class BridgeOptions:
+    """Runtime options, typically injected via env vars in the container."""
+
+    endpoint: str | None = None  # override the WSDL-declared endpoint
+    username: str | None = None
+    password: str | None = None
+    auth: str | None = None  # None | "basic" | "wsse"
+    timeout: float = 30.0
+    verify: bool = True
+    headers: dict[str, str] | None = None
+    trust_env: bool = True  # honor HTTP(S)_PROXY / NO_PROXY env vars
+
+    @classmethod
+    def from_env(cls) -> "BridgeOptions":
+        return cls(
+            endpoint=os.getenv("SPEC2OPENAPI_ENDPOINT") or None,
+            username=os.getenv("SPEC2OPENAPI_USERNAME") or None,
+            password=os.getenv("SPEC2OPENAPI_PASSWORD") or None,
+            auth=os.getenv("SPEC2OPENAPI_AUTH") or None,
+            timeout=float(os.getenv("SPEC2OPENAPI_TIMEOUT", "30")),
+            verify=os.getenv("SPEC2OPENAPI_VERIFY", "1") not in ("0", "false", "False"),
+            trust_env=os.getenv("SPEC2OPENAPI_TRUST_ENV", "1")
+            not in ("0", "false", "False"),
+        )
+
+
+# --------------------------------------------------------------------------
+# spec indexing helpers
+# --------------------------------------------------------------------------
+
+
+class _SpecIndex:
+    def __init__(self, spec: dict[str, Any]):
+        self.spec = spec
+        self.components: dict[str, Any] = spec.get("components", {}).get("schemas", {})
+        self.ops: dict[str, dict[str, Any]] = {}
+        for path, item in spec.get("paths", {}).items():
+            post = (item or {}).get("post") or {}
+            xsoap = post.get("x-soap")
+            if not xsoap:
+                continue
+            req = (
+                post.get("requestBody", {})
+                .get("content", {})
+                .get("application/json", {})
+                .get("schema", {})
+            )
+            out = (
+                post.get("responses", {})
+                .get("200", {})
+                .get("content", {})
+                .get("application/json", {})
+                .get("schema", {})
+            )
+            self.ops[path] = {"x-soap": xsoap, "input": req, "output": out}
+
+    def deref(self, schema: dict[str, Any] | None) -> dict[str, Any]:
+        """Resolve $ref / single-allOf wrappers, keeping xml annotations."""
+        if not schema:
+            return {}
+        seen = 0
+        xml = schema.get("xml")
+        while seen < 32:
+            if "$ref" in schema:
+                name = schema["$ref"].rsplit("/", 1)[-1]
+                schema = self.components.get(name, {})
+            elif "allOf" in schema and len(schema["allOf"]) == 1:
+                inner = schema["allOf"][0]
+                merged = dict(inner)
+                for k, v in schema.items():
+                    if k != "allOf":
+                        merged.setdefault(k, v)
+                schema = merged
+            else:
+                break
+            seen += 1
+        if xml and "xml" not in schema:
+            schema = dict(schema)
+            schema["xml"] = xml
+        return schema
+
+
+# --------------------------------------------------------------------------
+# JSON -> SOAP envelope
+# --------------------------------------------------------------------------
+
+
+def _to_text(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _write_value(parent: etree._Element, tag: etree.QName | str, schema: dict,
+                 value: Any, index: _SpecIndex) -> None:
+    el = etree.SubElement(parent, tag)
+    if value is None:
+        el.set(etree.QName(XSI_NS, "nil"), "true")
+        return
+    schema = index.deref(schema)
+    if schema.get("type") == "object" or "properties" in schema:
+        _write_object(el, schema, value, index)
+    elif isinstance(value, (dict,)):
+        _write_object(el, schema, value, index)
+    else:
+        el.text = _to_text(value)
+
+
+def _write_object(parent: etree._Element, schema: dict, data: Any,
+                  index: _SpecIndex) -> None:
+    schema = index.deref(schema)
+    props: dict[str, Any] = schema.get("properties", {})
+    if not isinstance(data, dict):
+        parent.text = _to_text(data)
+        return
+
+    # attributes first
+    for name, pschema in props.items():
+        pd = index.deref(pschema)
+        xml = pd.get("xml") or pschema.get("xml") or {}
+        if xml.get("attribute") and name in data and data[name] is not None:
+            parent.set(xml.get("name", name), _to_text(data[name]))
+
+    # elements in schema (=XSD sequence) order
+    for name, pschema in props.items():
+        pd = index.deref(pschema)
+        xml = pd.get("xml") or pschema.get("xml") or {}
+        if xml.get("attribute"):
+            continue
+        if name not in data:
+            continue
+        value = data[name]
+        if xml.get("x-text"):  # xsd:simpleContent text value
+            parent.text = _to_text(value) if value is not None else None
+            continue
+        local = xml.get("name", name)
+        ns = xml.get("namespace")
+        tag = etree.QName(ns, local) if ns else local
+        if pd.get("type") == "array":
+            items_schema = pd.get("items", {})
+            for item in value if isinstance(value, list) else [value]:
+                _write_value(parent, tag, items_schema, item, index)
+        else:
+            _write_value(parent, tag, pd, value, index)
+
+    for name in data:
+        if name not in props:
+            logger.debug("payload key %r not in schema; ignored", name)
+
+
+def build_envelope(op: dict[str, Any], payload: dict[str, Any],
+                   index: _SpecIndex, options: BridgeOptions) -> bytes:
+    xsoap = op["x-soap"]
+    env_ns = SOAP_ENV_NS.get(xsoap.get("soapVersion", "1.1"), SOAP_ENV_NS["1.1"])
+    nsmap = {"soapenv": env_ns}
+    envelope = etree.Element(etree.QName(env_ns, "Envelope"), nsmap=nsmap)
+
+    if options.auth == "wsse" and options.username is not None:
+        header = etree.SubElement(envelope, etree.QName(env_ns, "Header"))
+        security = etree.SubElement(
+            header, etree.QName(WSSE_NS, "Security"), nsmap={"wsse": WSSE_NS}
+        )
+        security.set(etree.QName(env_ns, "mustUnderstand"), "1")
+        token = etree.SubElement(security, etree.QName(WSSE_NS, "UsernameToken"))
+        user = etree.SubElement(token, etree.QName(WSSE_NS, "Username"))
+        user.text = options.username
+        pwd = etree.SubElement(token, etree.QName(WSSE_NS, "Password"))
+        pwd.set("Type", PASSWORD_TEXT)
+        pwd.text = options.password or ""
+
+    body = etree.SubElement(envelope, etree.QName(env_ns, "Body"))
+    in_meta = xsoap.get("input", {})
+    ns = in_meta.get("namespace")
+    local = in_meta.get("element", xsoap.get("operation", "Request"))
+    # use a *prefixed* namespace: unqualified children (rpc parts,
+    # elementFormDefault="unqualified") must not inherit a default ns
+    root_nsmap = {"tns": ns} if ns else None
+    root = etree.SubElement(
+        body, etree.QName(ns, local) if ns else local, nsmap=root_nsmap
+    )
+    _write_object(root, index.deref(op.get("input", {})), payload or {}, index)
+
+    return etree.tostring(envelope, xml_declaration=True, encoding="utf-8")
+
+
+# --------------------------------------------------------------------------
+# SOAP response -> JSON
+# --------------------------------------------------------------------------
+
+
+def _localname(el: etree._Element) -> str:
+    try:
+        return etree.QName(el).localname
+    except Exception:
+        return str(el.tag)
+
+
+def _coerce(text: str | None, schema: dict[str, Any]) -> Any:
+    if text is None:
+        return None
+    t = schema.get("type")
+    s = text.strip()
+    try:
+        if t == "integer":
+            return int(s)
+        if t == "number":
+            return float(s)
+        if t == "boolean":
+            return s in ("true", "1")
+    except ValueError:
+        return text
+    return text if t == "string" else (text if s == "" else s)
+
+
+def _read_object(el: etree._Element, schema: dict[str, Any],
+                 index: _SpecIndex) -> Any:
+    schema = index.deref(schema)
+    props: dict[str, Any] = schema.get("properties", {})
+    if not props:
+        # no schema knowledge: return text or shallow dict of children
+        children = [c for c in el if isinstance(c.tag, str)]
+        if not children:
+            return el.text
+        out: dict[str, Any] = {}
+        for c in children:
+            name = _localname(c)
+            val = _read_object(c, {}, index)
+            if name in out:
+                if not isinstance(out[name], list):
+                    out[name] = [out[name]]
+                out[name].append(val)
+            else:
+                out[name] = val
+        return out
+
+    result: dict[str, Any] = {}
+    children = [c for c in el if isinstance(c.tag, str)]
+    by_name: dict[str, list[etree._Element]] = {}
+    for c in children:
+        by_name.setdefault(_localname(c), []).append(c)
+
+    for name, pschema in props.items():
+        pd = index.deref(pschema)
+        xml = pd.get("xml") or (pschema.get("xml") if isinstance(pschema, dict) else None) or {}
+        local = xml.get("name", name)
+        if xml.get("attribute"):
+            v = el.get(local)
+            if v is not None:
+                result[name] = _coerce(v, pd)
+            continue
+        if xml.get("x-text"):  # xsd:simpleContent text value
+            result[name] = _coerce(el.text, pd)
+            continue
+        nodes = by_name.get(local, [])
+        if pd.get("type") == "array":
+            items_schema = index.deref(pd.get("items", {}))
+            result[name] = [_read_node(n, items_schema, index) for n in nodes]
+        elif nodes:
+            result[name] = _read_node(nodes[0], pd, index)
+    return result
+
+
+def _read_node(node: etree._Element, schema: dict[str, Any],
+               index: _SpecIndex) -> Any:
+    if node.get(etree.QName(XSI_NS, "nil")) in ("true", "1"):
+        return None
+    schema = index.deref(schema)
+    if schema.get("type") == "object" or "properties" in schema:
+        return _read_object(node, schema, index)
+    return _coerce(node.text, schema)
+
+
+def parse_fault(body: etree._Element, env_ns: str) -> dict[str, Any] | None:
+    fault = body.find(f"{{{env_ns}}}Fault")
+    if fault is None:
+        return None
+    if env_ns == SOAP_ENV_NS["1.2"]:
+        code = fault.findtext(f"{{{env_ns}}}Code/{{{env_ns}}}Value") or ""
+        reason = fault.findtext(f"{{{env_ns}}}Reason/{{{env_ns}}}Text") or ""
+        detail_el = fault.find(f"{{{env_ns}}}Detail")
+    else:
+        code = fault.findtext("faultcode") or ""
+        reason = fault.findtext("faultstring") or ""
+        detail_el = fault.find("detail")
+    detail = ""
+    if detail_el is not None:
+        detail = etree.tostring(detail_el, encoding="unicode")
+    return {"faultcode": code, "faultstring": reason, "detail": detail}
+
+
+def parse_response(content: bytes, op: dict[str, Any],
+                   index: _SpecIndex) -> tuple[int, dict[str, Any]]:
+    """Returns (http_status, json_payload)."""
+    xsoap = op["x-soap"]
+    env_ns = SOAP_ENV_NS.get(xsoap.get("soapVersion", "1.1"), SOAP_ENV_NS["1.1"])
+    try:
+        # endpoint responses are untrusted: no entities, DTDs, or network
+        parser = etree.XMLParser(resolve_entities=False, load_dtd=False,
+                                 no_network=True, huge_tree=False)
+        tree = etree.fromstring(content, parser=parser)
+    except Exception as exc:
+        return 502, {
+            "faultcode": "spec2openapi.InvalidXML",
+            "faultstring": f"endpoint returned non-XML response: {exc}",
+            "detail": content[:2000].decode("utf-8", "replace"),
+        }
+    body = tree.find(f"{{{env_ns}}}Body")
+    if body is None:
+        # tolerate the other soap version's namespace
+        for alt in SOAP_ENV_NS.values():
+            body = tree.find(f"{{{alt}}}Body")
+            if body is not None:
+                env_ns = alt
+                break
+    if body is None:
+        return 502, {
+            "faultcode": "spec2openapi.NoBody",
+            "faultstring": "no SOAP Body found in response",
+            "detail": "",
+        }
+
+    fault = parse_fault(body, env_ns)
+    if fault is not None:
+        return 500, fault
+
+    out_meta = xsoap.get("output") or {}
+    expected = out_meta.get("element")
+    root = None
+    for c in body:
+        if not isinstance(c.tag, str):
+            continue
+        if expected is None or _localname(c) == expected:
+            root = c
+            break
+    if root is None:
+        root = next((c for c in body if isinstance(c.tag, str)), None)
+    if root is None:
+        return 200, {}
+
+    out_schema = index.deref(op.get("output", {}))
+    data = _read_object(root, out_schema, index)
+    if not isinstance(data, dict):
+        data = {"value": data}
+    return 200, data
+
+
+# --------------------------------------------------------------------------
+# the transport
+# --------------------------------------------------------------------------
+
+
+class SoapBridgeTransport(httpx.AsyncBaseTransport):
+    """httpx transport that answers FastMCP's REST calls by calling SOAP."""
+
+    def __init__(self, spec: dict[str, Any], options: BridgeOptions | None = None):
+        self.index = _SpecIndex(spec)
+        self.options = options or BridgeOptions.from_env()
+        auth = None
+        if self.options.auth == "basic" and self.options.username is not None:
+            auth = (self.options.username, self.options.password or "")
+        self._client = httpx.AsyncClient(
+            auth=auth,
+            timeout=self.options.timeout,
+            verify=self.options.verify,
+            headers=self.options.headers or {},
+            trust_env=self.options.trust_env,
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    def _json_response(self, request: httpx.Request, status: int,
+                       payload: dict[str, Any]) -> httpx.Response:
+        return httpx.Response(status, json=payload, request=request)
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        path = request.url.path
+        op = self.index.ops.get(path)
+        if op is None:
+            return self._json_response(
+                request, 404,
+                {"faultcode": "spec2openapi.UnknownOperation",
+                 "faultstring": f"no x-soap operation registered for path {path}",
+                 "detail": ""},
+            )
+        raw = request.read()
+        try:
+            payload = json.loads(raw) if raw else {}
+        except json.JSONDecodeError as exc:
+            return self._json_response(
+                request, 400,
+                {"faultcode": "spec2openapi.BadRequest",
+                 "faultstring": f"invalid JSON body: {exc}", "detail": ""},
+            )
+
+        xsoap = op["x-soap"]
+        endpoint = self.options.endpoint or xsoap.get("endpoint")
+        if not endpoint:
+            return self._json_response(
+                request, 502,
+                {"faultcode": "spec2openapi.NoEndpoint",
+                 "faultstring": "no SOAP endpoint configured "
+                                "(x-soap.endpoint / SPEC2OPENAPI_ENDPOINT)",
+                 "detail": ""},
+            )
+
+        envelope = build_envelope(op, payload, self.index, self.options)
+        action = xsoap.get("soapAction", "")
+        if xsoap.get("soapVersion") == "1.2":
+            ct = "application/soap+xml; charset=utf-8"
+            if action:
+                ct += f'; action="{action}"'
+            headers = {"Content-Type": ct}
+        else:
+            headers = {
+                "Content-Type": "text/xml; charset=utf-8",
+                "SOAPAction": f'"{action}"',
+            }
+
+        try:
+            soap_resp = await self._client.post(
+                endpoint, content=envelope, headers=headers
+            )
+        except httpx.HTTPError as exc:
+            return self._json_response(
+                request, 502,
+                {"faultcode": "spec2openapi.TransportError",
+                 "faultstring": f"SOAP endpoint unreachable: {exc}", "detail": ""},
+            )
+
+        status, data = parse_response(soap_resp.content, op, self.index)
+        # a SOAP fault usually arrives as HTTP 500; trust envelope content
+        if status == 200 and soap_resp.status_code >= 400 and not data:
+            status = 502
+            data = {"faultcode": "spec2openapi.HTTPError",
+                    "faultstring": f"endpoint returned HTTP {soap_resp.status_code}",
+                    "detail": soap_resp.text[:2000]}
+        return self._json_response(request, status, data)