spec2openapi 0.1.0__tar.gz → 0.2.0__tar.gz

{spec2openapi-0.1.0/src/spec2openapi.egg-info → spec2openapi-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spec2openapi
-Version: 0.1.0
+Version: 0.2.0
 Summary: Convert legacy API specs (SOAP/WSDL, Swagger 2.0) into FastMCP-ready OpenAPI 3.x documents
 Author-email: Seoyul Yoon <devops.reso@gmail.com>
 License: Apache-2.0
@@ -61,7 +61,14 @@ WSDL ─────────┐
 Swagger 2.0 ──┘
 ```
 
-The output is a single, ordinary OpenAPI document. It is designed for a **fixed-runtime deployment model**: build one FastMCP-based container image, then swap the spec (e.g. a Kubernetes ConfigMap) to mass-produce MCP servers without rebuilding anything.
+The two inputs produce two kinds of output — this distinction matters:
+
+- **Swagger 2.0 → a plain, standard OpenAPI 3.x document.** The paths are the real REST endpoints. Any OpenAPI-driven runtime (FastMCP, or your own httpx-based server) serves it with **zero runtime changes** — just point it at the converted spec.
+- **WSDL → OpenAPI 3.x + an `x-soap` contract.** The generated `/operations/...` paths are **not real REST endpoints**; each tool call must be serialized to a SOAP envelope, sent to the SOAP endpoint, and the XML response parsed back to JSON. That logic is **not** part of a standard OpenAPI runtime — it lives in the **SOAP bridge shipped in the `[mcp]` extra**. Serving a SOAP-converted spec with a plain OpenAPI/httpx runtime will POST JSON to the SOAP endpoint and fail every call.
+
+So `spec2openapi` is a **converter for Swagger 2.0**, and a **converter + runtime contract (with a reference bridge) for SOAP**. See [How SOAP calls work](#how-soap-calls-work-the-x-soap-contract) below.
+
+The fixed-runtime deployment model — build one image, swap the spec via a Kubernetes ConfigMap to mass-produce MCP servers — applies to both, as long as the image includes the `[mcp]` extra when serving SOAP specs.
 
 ## Features
 
@@ -70,15 +77,17 @@ The output is a single, ordinary OpenAPI document. It is designed for a **fixed-
 - **`x-soap` contract** — SOAPAction, SOAP version, endpoint, wrapper element QNames, `soap:header` parts and declared faults are embedded as vendor extensions; OpenAPI `xml` annotations carry everything a call layer needs to serialize JSON ↔ literal XML.
 - **Swagger 2.0 → OpenAPI 3.x upgrade** — full mechanical mapping (servers, requestBody, formData/multipart, parameter schema wrapping, `collectionFormat` → `style`/`explode`, `$ref` rewriting, security schemes, `type: file`, `x-nullable`, discriminator). Every assumption made for missing information is recorded in `x-s2o.assumptions`; untranslatable constructs are preserved as `x-` extensions and listed in `x-s2o.lossy`.
 - **FastMCP compatibility, guaranteed and verifiable** — operationIds are generated in FastMCP's tool-name alphabet (`[A-Za-z0-9_]`, unique, ≤64 chars) so *tool name == operationId*. `spec2openapi validate` proves it: static checks, `openapi-spec-validator`, and a real `FastMCP.from_openapi()` round-trip listing the resulting tools.
-- **Reference MCP runtime (optional)** — `pip install "spec2openapi[mcp]"` adds a verified SOAP bridge (custom httpx transport) + FastMCP glue, a fixed Dockerfile, and Kubernetes examples. SOAP faults map to MCP tool errors; plain REST specs are served by the same runtime.
+- **SOAP bridge — required to *serve* SOAP specs** — `pip install "spec2openapi[mcp]"` adds the bridge (custom httpx transport) that implements the `x-soap` contract, plus FastMCP glue, a fixed Dockerfile, and Kubernetes examples. SOAP faults map to MCP tool errors. **Swagger-converted (pure REST) specs do not need this** — any OpenAPI runtime serves them. Only SOAP-converted specs require the bridge at runtime.
 
 ## Installation
 
 ```bash
-pip install spec2openapi          # converter only (zeep, lxml, PyYAML)
-pip install "spec2openapi[mcp]"   # + reference MCP runtime (fastmcp, httpx)
+pip install spec2openapi          # converter + CLI (zeep, lxml, PyYAML)
+pip install "spec2openapi[mcp]"   # + SOAP bridge & runtime — required to serve SOAP specs
 ```
 
+> The core install is enough to **convert** any spec and to serve **Swagger-converted (REST)** specs from your own runtime. The `[mcp]` extra is required only to **serve SOAP-converted** specs (it provides the bridge that turns JSON tool calls into SOAP envelopes).
+
 ## Quick start
 
 ### CLI
@@ -146,7 +155,9 @@ The generated paths (`/operations/...`) are *not* real REST endpoints — a SOAP
 
 Serialization rules (schema `xml` annotations): `xml.name`/`xml.namespace` (absent namespace = unqualified), `xml.attribute: true`, `xml.x-text: true` (simpleContent text), arrays repeat the element, and **property order = XSD sequence order** (do not alphabetize the document). `x-soap-choice` lists mutually exclusive property groups.
 
-The `[mcp]` extra contains a verified implementation of this contract (`src/spec2openapi/bridge.py`) — use it directly or as the reference for your own runtime.
+The `[mcp]` extra contains a verified implementation of this contract (`src/spec2openapi/bridge.py`) — use it directly (via `spec2openapi serve`) or as the reference for your own runtime. **There is no way to serve a SOAP-converted spec without an implementation of this contract**; a standard OpenAPI runtime cannot do it.
+
+> **Mixed SOAP + REST specs.** The reference runtime routes *all* traffic through the SOAP bridge if *any* path carries `x-soap`, so REST operations in a mixed spec are not served correctly today. Keep SOAP and REST specs separate until this is addressed ([tracking issue](https://github.com/Seo-yul/spec2openapi/issues)).
 
 ## Handling missing information (Swagger 2.0)
 
@@ -159,7 +170,7 @@ Upgrading is favorable: OpenAPI 3.x is a superset of Swagger 2.0, so almost noth
 ## Kubernetes: one image, many MCP servers
 
 ```bash
-docker build -t spec2openapi:0.1.0 .
+docker build -t spec2openapi:0.2.0 .
 spec2openapi convert <wsdl> -o openapi.yaml
 kubectl create configmap my-mcp-spec --from-file=openapi.yaml
 kubectl apply -f k8s/example.yaml    # Deployment mounts /config/openapi.yaml
@@ -184,7 +195,7 @@ pip install -e ".[dev]"
 python -m pytest tests/
 ```
 
-The suite (70 tests) covers conversion units, the Swagger upgrader, envelope (de)serialization, end-to-end MCP-tool-call → mock-SOAP-server round-trips (rpc, simpleContent, choice, recursive trees, unqualified forms), FastMCP round-trips for every fixture × OpenAPI 3.0/3.1, and stress patterns (circular `$ref`s, deep nesting, large enums, cross-namespace name collisions, duplicate operation names across services, odd path characters, deep `allOf` chains). Generated samples live in [`examples/`](examples/).
+The suite (103 tests) covers conversion units, the Swagger upgrader, envelope (de)serialization, end-to-end MCP-tool-call → mock-SOAP-server round-trips (rpc, simpleContent, choice, recursive trees, unqualified forms), FastMCP round-trips for every fixture × OpenAPI 3.0/3.1, and stress patterns (circular `$ref`s, deep nesting, large enums, cross-namespace name collisions, duplicate operation names across services, odd path characters, deep `allOf` chains). Generated samples live in [`examples/`](examples/).
 
 ## Project layout
 

{spec2openapi-0.1.0 → spec2openapi-0.2.0}/README.md

@@ -20,7 +20,14 @@ WSDL ─────────┐
 Swagger 2.0 ──┘
 ```
 
-The output is a single, ordinary OpenAPI document. It is designed for a **fixed-runtime deployment model**: build one FastMCP-based container image, then swap the spec (e.g. a Kubernetes ConfigMap) to mass-produce MCP servers without rebuilding anything.
+The two inputs produce two kinds of output — this distinction matters:
+
+- **Swagger 2.0 → a plain, standard OpenAPI 3.x document.** The paths are the real REST endpoints. Any OpenAPI-driven runtime (FastMCP, or your own httpx-based server) serves it with **zero runtime changes** — just point it at the converted spec.
+- **WSDL → OpenAPI 3.x + an `x-soap` contract.** The generated `/operations/...` paths are **not real REST endpoints**; each tool call must be serialized to a SOAP envelope, sent to the SOAP endpoint, and the XML response parsed back to JSON. That logic is **not** part of a standard OpenAPI runtime — it lives in the **SOAP bridge shipped in the `[mcp]` extra**. Serving a SOAP-converted spec with a plain OpenAPI/httpx runtime will POST JSON to the SOAP endpoint and fail every call.
+
+So `spec2openapi` is a **converter for Swagger 2.0**, and a **converter + runtime contract (with a reference bridge) for SOAP**. See [How SOAP calls work](#how-soap-calls-work-the-x-soap-contract) below.
+
+The fixed-runtime deployment model — build one image, swap the spec via a Kubernetes ConfigMap to mass-produce MCP servers — applies to both, as long as the image includes the `[mcp]` extra when serving SOAP specs.
 
 ## Features
 
@@ -29,15 +36,17 @@ The output is a single, ordinary OpenAPI document. It is designed for a **fixed-
 - **`x-soap` contract** — SOAPAction, SOAP version, endpoint, wrapper element QNames, `soap:header` parts and declared faults are embedded as vendor extensions; OpenAPI `xml` annotations carry everything a call layer needs to serialize JSON ↔ literal XML.
 - **Swagger 2.0 → OpenAPI 3.x upgrade** — full mechanical mapping (servers, requestBody, formData/multipart, parameter schema wrapping, `collectionFormat` → `style`/`explode`, `$ref` rewriting, security schemes, `type: file`, `x-nullable`, discriminator). Every assumption made for missing information is recorded in `x-s2o.assumptions`; untranslatable constructs are preserved as `x-` extensions and listed in `x-s2o.lossy`.
 - **FastMCP compatibility, guaranteed and verifiable** — operationIds are generated in FastMCP's tool-name alphabet (`[A-Za-z0-9_]`, unique, ≤64 chars) so *tool name == operationId*. `spec2openapi validate` proves it: static checks, `openapi-spec-validator`, and a real `FastMCP.from_openapi()` round-trip listing the resulting tools.
-- **Reference MCP runtime (optional)** — `pip install "spec2openapi[mcp]"` adds a verified SOAP bridge (custom httpx transport) + FastMCP glue, a fixed Dockerfile, and Kubernetes examples. SOAP faults map to MCP tool errors; plain REST specs are served by the same runtime.
+- **SOAP bridge — required to *serve* SOAP specs** — `pip install "spec2openapi[mcp]"` adds the bridge (custom httpx transport) that implements the `x-soap` contract, plus FastMCP glue, a fixed Dockerfile, and Kubernetes examples. SOAP faults map to MCP tool errors. **Swagger-converted (pure REST) specs do not need this** — any OpenAPI runtime serves them. Only SOAP-converted specs require the bridge at runtime.
 
 ## Installation
 
 ```bash
-pip install spec2openapi          # converter only (zeep, lxml, PyYAML)
-pip install "spec2openapi[mcp]"   # + reference MCP runtime (fastmcp, httpx)
+pip install spec2openapi          # converter + CLI (zeep, lxml, PyYAML)
+pip install "spec2openapi[mcp]"   # + SOAP bridge & runtime — required to serve SOAP specs
 ```
 
+> The core install is enough to **convert** any spec and to serve **Swagger-converted (REST)** specs from your own runtime. The `[mcp]` extra is required only to **serve SOAP-converted** specs (it provides the bridge that turns JSON tool calls into SOAP envelopes).
+
 ## Quick start
 
 ### CLI
@@ -105,7 +114,9 @@ The generated paths (`/operations/...`) are *not* real REST endpoints — a SOAP
 
 Serialization rules (schema `xml` annotations): `xml.name`/`xml.namespace` (absent namespace = unqualified), `xml.attribute: true`, `xml.x-text: true` (simpleContent text), arrays repeat the element, and **property order = XSD sequence order** (do not alphabetize the document). `x-soap-choice` lists mutually exclusive property groups.
 
-The `[mcp]` extra contains a verified implementation of this contract (`src/spec2openapi/bridge.py`) — use it directly or as the reference for your own runtime.
+The `[mcp]` extra contains a verified implementation of this contract (`src/spec2openapi/bridge.py`) — use it directly (via `spec2openapi serve`) or as the reference for your own runtime. **There is no way to serve a SOAP-converted spec without an implementation of this contract**; a standard OpenAPI runtime cannot do it.
+
+> **Mixed SOAP + REST specs.** The reference runtime routes *all* traffic through the SOAP bridge if *any* path carries `x-soap`, so REST operations in a mixed spec are not served correctly today. Keep SOAP and REST specs separate until this is addressed ([tracking issue](https://github.com/Seo-yul/spec2openapi/issues)).
 
 ## Handling missing information (Swagger 2.0)
 
@@ -118,7 +129,7 @@ Upgrading is favorable: OpenAPI 3.x is a superset of Swagger 2.0, so almost noth
 ## Kubernetes: one image, many MCP servers
 
 ```bash
-docker build -t spec2openapi:0.1.0 .
+docker build -t spec2openapi:0.2.0 .
 spec2openapi convert <wsdl> -o openapi.yaml
 kubectl create configmap my-mcp-spec --from-file=openapi.yaml
 kubectl apply -f k8s/example.yaml    # Deployment mounts /config/openapi.yaml
@@ -143,7 +154,7 @@ pip install -e ".[dev]"
 python -m pytest tests/
 ```
 
-The suite (70 tests) covers conversion units, the Swagger upgrader, envelope (de)serialization, end-to-end MCP-tool-call → mock-SOAP-server round-trips (rpc, simpleContent, choice, recursive trees, unqualified forms), FastMCP round-trips for every fixture × OpenAPI 3.0/3.1, and stress patterns (circular `$ref`s, deep nesting, large enums, cross-namespace name collisions, duplicate operation names across services, odd path characters, deep `allOf` chains). Generated samples live in [`examples/`](examples/).
+The suite (103 tests) covers conversion units, the Swagger upgrader, envelope (de)serialization, end-to-end MCP-tool-call → mock-SOAP-server round-trips (rpc, simpleContent, choice, recursive trees, unqualified forms), FastMCP round-trips for every fixture × OpenAPI 3.0/3.1, and stress patterns (circular `$ref`s, deep nesting, large enums, cross-namespace name collisions, duplicate operation names across services, odd path characters, deep `allOf` chains). Generated samples live in [`examples/`](examples/).
 
 ## Project layout
 

{spec2openapi-0.1.0 → spec2openapi-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spec2openapi"
-version = "0.1.0"
+version = "0.2.0"
 description = "Convert legacy API specs (SOAP/WSDL, Swagger 2.0) into FastMCP-ready OpenAPI 3.x documents"
 readme = "README.md"
 requires-python = ">=3.10"

{spec2openapi-0.1.0 → spec2openapi-0.2.0}/src/spec2openapi/__init__.py

@@ -7,7 +7,7 @@ Optional MCP runtime (pip install 'spec2openapi[mcp]'): from_openapi_spec,
 from_wsdl, BridgeOptions, SoapBridgeTransport.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.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

{spec2openapi-0.1.0 → spec2openapi-0.2.0}/src/spec2openapi/bridge.py

@@ -37,6 +37,36 @@ PASSWORD_TEXT = (
 )
 
 
+_FALSEY = {"0", "false", "no", "off", ""}
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    v = raw.strip().lower()
+    if v in _FALSEY:
+        return False
+    if v in _TRUTHY:
+        return True
+    logger.warning("env %s=%r not recognized as boolean; using %s",
+                   name, raw, default)
+    return default
+
+
+def _env_float(name: str, default: float) -> float:
+    raw = os.getenv(name)
+    if raw is None or not raw.strip():
+        return default
+    try:
+        return float(raw)
+    except ValueError:
+        logger.warning("env %s=%r is not a number; using %s",
+                       name, raw, default)
+        return default
+
+
 @dataclasses.dataclass
 class BridgeOptions:
     """Runtime options, typically injected via env vars in the container."""
@@ -57,10 +87,9 @@ class BridgeOptions:
             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"),
+            timeout=_env_float("SPEC2OPENAPI_TIMEOUT", 30.0),
+            verify=_env_bool("SPEC2OPENAPI_VERIFY", True),
+            trust_env=_env_bool("SPEC2OPENAPI_TRUST_ENV", True),
         )
 
 
@@ -188,6 +217,24 @@ def _write_object(parent: etree._Element, schema: dict, data: Any,
             logger.debug("payload key %r not in schema; ignored", name)
 
 
+def _choice_violations(schema: dict[str, Any], data: Any) -> list[str]:
+    """Enforce x-soap-choice on the payload: at most one member per group,
+    and exactly one when the group is required."""
+    if not isinstance(data, dict):
+        return []
+    errors: list[str] = []
+    for group in schema.get("x-soap-choice", []) or []:
+        members = group.get("members", [])
+        present = [m for m in members if data.get(m) is not None]
+        if len(present) > 1:
+            errors.append(
+                f"at most one of {members} may be set (got {present})"
+            )
+        elif group.get("required") and not present:
+            errors.append(f"exactly one of {members} is required")
+    return errors
+
+
 def build_envelope(op: dict[str, Any], payload: dict[str, Any],
                    index: _SpecIndex, options: BridgeOptions) -> bytes:
     xsoap = op["x-soap"]
@@ -246,7 +293,12 @@ def _coerce(text: str | None, schema: dict[str, Any]) -> Any:
         if t == "number":
             return float(s)
         if t == "boolean":
-            return s in ("true", "1")
+            low = s.lower()
+            if low in ("true", "1"):
+                return True
+            if low in ("false", "0"):
+                return False
+            return text  # non-canonical: don't silently coerce to False
     except ValueError:
         return text
     return text if t == "string" else (text if s == "" else s)
@@ -328,17 +380,43 @@ def parse_fault(body: etree._Element, env_ns: str) -> dict[str, Any] | None:
     return {"faultcode": code, "faultstring": reason, "detail": detail}
 
 
+def _http_error(http_status: int, content: bytes) -> tuple[int, dict[str, Any]]:
+    return 502, {
+        "faultcode": "spec2openapi.HTTPError",
+        "faultstring": f"endpoint returned HTTP {http_status}",
+        "detail": content[:2000].decode("utf-8", "replace"),
+    }
+
+
 def parse_response(content: bytes, op: dict[str, Any],
-                   index: _SpecIndex) -> tuple[int, dict[str, Any]]:
-    """Returns (http_status, json_payload)."""
+                   index: _SpecIndex,
+                   http_status: int = 200) -> tuple[int, dict[str, Any]]:
+    """Returns (mapped_status, json_payload). http_status is the transport
+    status code, used to give sensible errors for empty/non-XML bodies."""
     xsoap = op["x-soap"]
+    is_one_way = not xsoap.get("output")
     env_ns = SOAP_ENV_NS.get(xsoap.get("soapVersion", "1.1"), SOAP_ENV_NS["1.1"])
+
+    if not content or not content.strip():
+        # empty body: a one-way call with a 2xx succeeded; otherwise the
+        # HTTP status carries the real story
+        if http_status >= 400:
+            return _http_error(http_status, content)
+        if is_one_way:
+            return 200, {}
+        return 502, {
+            "faultcode": "spec2openapi.EmptyResponse",
+            "faultstring": f"endpoint returned an empty body (HTTP {http_status})",
+            "detail": "",
+        }
     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:
+        if http_status >= 400:
+            return _http_error(http_status, content)
         return 502, {
             "faultcode": "spec2openapi.InvalidXML",
             "faultstring": f"endpoint returned non-XML response: {exc}",
@@ -353,6 +431,8 @@ def parse_response(content: bytes, op: dict[str, Any],
                 env_ns = alt
                 break
     if body is None:
+        if http_status >= 400:
+            return _http_error(http_status, content)
         return 502, {
             "faultcode": "spec2openapi.NoBody",
             "faultstring": "no SOAP Body found in response",
@@ -444,6 +524,16 @@ class SoapBridgeTransport(httpx.AsyncBaseTransport):
                  "detail": ""},
             )
 
+        violations = _choice_violations(
+            self.index.deref(op.get("input", {})), payload
+        )
+        if violations:
+            return self._json_response(
+                request, 400,
+                {"faultcode": "spec2openapi.ChoiceViolation",
+                 "faultstring": "; ".join(violations), "detail": ""},
+            )
+
         envelope = build_envelope(op, payload, self.index, self.options)
         action = xsoap.get("soapAction", "")
         if xsoap.get("soapVersion") == "1.2":
@@ -468,11 +558,7 @@ class SoapBridgeTransport(httpx.AsyncBaseTransport):
                  "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]}
+        status, data = parse_response(
+            soap_resp.content, op, self.index, soap_resp.status_code
+        )
         return self._json_response(request, status, data)

{spec2openapi-0.1.0 → spec2openapi-0.2.0}/src/spec2openapi/cli.py

@@ -17,6 +17,10 @@ from . import __version__
 
 _MCP_HINT = "install the MCP runtime extras first: pip install 'spec2openapi[mcp]'"
 
+_HTTP_METHODS = frozenset(
+    ("get", "put", "post", "delete", "options", "head", "patch", "trace")
+)
+
 
 def _is_wsdl_source(src: str) -> bool:
     low = src.lower()
@@ -28,8 +32,12 @@ def _is_wsdl_source(src: str) -> bool:
         return True
     p = Path(src)
     if p.exists():
-        head = p.read_text(encoding="utf-8", errors="replace")[:512].lstrip()
+        head = p.read_text(encoding="utf-8-sig", errors="replace")[:512].lstrip()
         return head.startswith("<")
+    # a remote URL without a spec extension: zeep can fetch WSDLs, and
+    # load_spec cannot read a URL, so treat it as WSDL
+    if low.startswith(("http://", "https://")):
+        return True
     return False
 
 
@@ -89,7 +97,7 @@ def cmd_convert(args) -> int:
         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")
+    fmt = args.format or ("json" if (args.output or "").lower().endswith(".json") else "yaml")
     text = dump_spec(spec, fmt)
     if args.output:
         Path(args.output).write_text(text, encoding="utf-8")
@@ -139,7 +147,7 @@ def cmd_upgrade(args) -> int:
             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")
+    fmt = args.format or ("json" if (args.output or "").lower().endswith(".json") else "yaml")
     text = dump_spec(upgraded, fmt)
     if args.output:
         Path(args.output).write_text(text, encoding="utf-8")
@@ -164,8 +172,11 @@ def cmd_validate(args) -> int:
         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):
+        if not isinstance(item, dict):
+            continue
+        for method, op in item.items():
+            # only HTTP methods are operations; skip parameters/$ref/x- keys
+            if method.lower() not in _HTTP_METHODS or not isinstance(op, dict):
                 continue
             oid = op.get("operationId")
             if not oid:
@@ -174,7 +185,8 @@ def cmd_validate(args) -> int:
             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"):
+            xsoap = op.get("x-soap")
+            if isinstance(xsoap, dict) and not xsoap.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:
@@ -195,9 +207,15 @@ def cmd_validate(args) -> int:
 
     try:  # FastMCP round-trip: the compatibility this project guarantees
         import anyio
+        import httpx
         from fastmcp import Client, FastMCP
 
-        mcp = FastMCP.from_openapi(openapi_spec=spec, name="validate")
+        # supply a dummy client so specs without a `servers` entry still
+        # convert — validate measures tool convertibility, not deployment
+        dummy = httpx.AsyncClient(base_url="http://spec2openapi.invalid")
+        mcp = FastMCP.from_openapi(
+            openapi_spec=spec, name="validate", client=dummy
+        )
 
         async def _tools():
             async with Client(mcp) as client:
@@ -238,17 +256,19 @@ def cmd_validate(args) -> int:
 
 
 def cmd_serve(args) -> int:
+    spec = _load_or_convert(args.source)
     try:
+        # everything [mcp]-flavored lives inside the guard: server, the
+        # bridge import in _bridge_options, and fastmcp's lazy imports
         from .server import from_openapi_spec
+
+        mcp = from_openapi_spec(
+            spec, options=_bridge_options(args),
+            validate_output=args.validate_output,
+        )
     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)
@@ -323,7 +343,12 @@ def main(argv: list[str] | None = None) -> int:
     s.set_defaults(fn=cmd_serve)
 
     args = ap.parse_args(argv)
-    return args.fn(args)
+    try:
+        return args.fn(args)
+    except (FileNotFoundError, ValueError, OSError) as exc:
+        # expected user-input errors: one-line message, not a traceback
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
 
 
 if __name__ == "__main__":

{spec2openapi-0.1.0 → spec2openapi-0.2.0}/src/spec2openapi/convert.py

@@ -44,14 +44,21 @@ def convert_wsdl(
 
 
 def load_spec(path: str | Path) -> dict[str, Any]:
-    """Load an OpenAPI spec from a .yaml/.yml/.json file."""
+    """Load an OpenAPI/Swagger spec from a .yaml/.yml/.json file."""
     p = Path(path)
-    text = p.read_text(encoding="utf-8")
+    text = p.read_text(encoding="utf-8-sig")
     if p.suffix.lower() == ".json" or text.lstrip().startswith("{"):
-        return json.loads(text)
-    import yaml
+        spec = json.loads(text)
+    else:
+        import yaml
 
-    return yaml.safe_load(text)
+        spec = yaml.safe_load(text)
+    if not isinstance(spec, dict):
+        raise ValueError(
+            f"{p}: not a valid OpenAPI/Swagger document "
+            f"(parsed as {type(spec).__name__}, expected a mapping)"
+        )
+    return spec
 
 
 def spec_has_soap(spec: dict[str, Any]) -> bool:

{spec2openapi-0.1.0 → spec2openapi-0.2.0}/src/spec2openapi/openapi.py

@@ -25,6 +25,28 @@ import re
 from .schema import SchemaConverter, sanitize_name
 
 _TOOL_ID_RE = re.compile(r"[^A-Za-z0-9_]+")
+_MAX_ID_LEN = 64
+
+
+def _tool_id(raw: str) -> str:
+    """Normalize to FastMCP's tool-name alphabet, bounded to 64 chars."""
+    tid = _TOOL_ID_RE.sub("_", sanitize_name(raw)).strip("_")
+    return tid[:_MAX_ID_LEN] if tid else "op"
+
+
+def _unique_id(base: str, used: set[str]) -> str:
+    """Make base unique within `used`, keeping the result <= 64 chars."""
+    if base not in used:
+        used.add(base)
+        return base
+    n = 2
+    while True:
+        suffix = f"_{n}"
+        candidate = base[: _MAX_ID_LEN - len(suffix)] + suffix
+        if candidate not in used:
+            used.add(candidate)
+            return candidate
+        n += 1
 
 SOAP_FAULT_SCHEMA = {
     "type": "object",
@@ -64,11 +86,20 @@ def build_spec(
 ) -> dict[str, Any]:
     conv = SchemaConverter(parsed.xsd_meta)
     paths: dict[str, Any] = {}
+    used_ids: set[str] = set()
+
+    # reserve the built-in fault schema name up front so a WSDL type also
+    # named "SoapFault" is deduped to another name instead of clobbering it
+    fault_ref_name = "SoapFault"
+    conv.components[fault_ref_name] = SOAP_FAULT_SCHEMA
+    fault_ref = f"#/components/schemas/{fault_ref_name}"
 
     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 that alphabet, bounded to 64 chars, and re-checked for
+        # uniqueness *after* normalization/truncation so two operations
+        # never collide onto the same path (which would drop one).
+        op_id = _unique_id(_tool_id(op.op_id), used_ids)
         in_q = _element_qname(op.input_element)
         in_schema = conv.element_type_to_object_schema(
             op.input_element.type,
@@ -163,7 +194,7 @@ def build_spec(
                     ),
                     "content": {
                         "application/json": {
-                            "schema": {"$ref": "#/components/schemas/SoapFault"}
+                            "schema": {"$ref": fault_ref}
                         }
                     },
                 },
@@ -172,8 +203,7 @@ def build_spec(
         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
+    components = dict(conv.components)  # already includes the fault schema
 
     spec: dict[str, Any] = {
         "openapi": "3.0.3",
@@ -203,20 +233,31 @@ def build_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."""
 
+    # keywords whose values are data, not sub-schemas — don't descend
+    data_kw = ("example", "examples", "default", "enum")
+
     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()}
+        node = {k: (v if k in data_kw else 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")
+        # 3.0 uses boolean exclusiveMinimum/Maximum alongside minimum/maximum;
+        # 2020-12 requires a number. Convert true+bound, and drop the boolean
+        # otherwise (false = inclusive default; true without a bound is
+        # malformed and cannot be represented).
+        for kw, bound in (("exclusiveMinimum", "minimum"),
+                          ("exclusiveMaximum", "maximum")):
+            val = node.get(kw)
+            if isinstance(val, bool):
+                if val and bound in node:
+                    node[kw] = node.pop(bound)
+                else:
+                    node.pop(kw, None)
         return node
 
     out = walk(dict(spec))

{spec2openapi-0.1.0 → spec2openapi-0.2.0}/src/spec2openapi/parser.py

@@ -303,7 +303,12 @@ def parse_wsdl(
         forbid_dtd=True, forbid_entities=True,
         forbid_external=forbid_external,
     )
-    client = Client(source, settings=settings)
+    try:
+        client = Client(source, settings=settings)
+    except FileNotFoundError:
+        raise
+    except Exception as exc:  # malformed/unfetchable WSDL -> clean error
+        raise ValueError(f"could not parse WSDL '{source}': {exc}") from exc
 
     svc_doc, op_docs = _extract_wsdl_docs(source)
     xsd_meta = _collect_xsd_meta(client, source, forbid_external=forbid_external)