spec2openapi 0.1.0__py3-none-any.whl

spec2openapi/swagger.py

@@ -0,0 +1,430 @@
+"""Swagger 2.0 -> OpenAPI 3.x upgrade (FastMCP only accepts OpenAPI 3.x).
+
+Design principles for information gaps (2.0 documents often omit things):
+
+1. Apply industry-consensus defaults deterministically and RECORD every
+   assumption under the root `x-s2o.assumptions` so the upgrade is
+   auditable (missing consumes/produces -> application/json, missing
+   operationId -> "{method}_{path}", missing host -> relative server "/").
+2. Never silently drop untranslatable constructs: preserve them as `x-`
+   extensions and record them under `x-s2o.lossy`.
+3. The final gate is `spec2openapi validate`, whose FastMCP round-trip
+   proves the upgraded spec actually materializes as MCP tools.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from . import __version__ as _version
+from .openapi import to_openapi_31
+
+_METHODS = ("get", "put", "post", "delete", "options", "head", "patch")
+
+# Swagger 2.0 parameter fields that move into `schema` in OpenAPI 3
+_SCHEMA_FIELDS = (
+    "type", "format", "items", "default", "maximum", "exclusiveMaximum",
+    "minimum", "exclusiveMinimum", "maxLength", "minLength", "pattern",
+    "maxItems", "minItems", "uniqueItems", "enum", "multipleOf",
+)
+
+# FastMCP normalizes tool names to [A-Za-z0-9_]; generate ids accordingly
+# so that tool name == operationId holds after the round-trip.
+_ID_RE = re.compile(r"[^A-Za-z0-9_]+")
+
+
+def is_swagger2(spec: dict[str, Any]) -> bool:
+    return str(spec.get("swagger", "")).startswith("2")
+
+
+def convert_swagger(
+    spec: dict[str, Any], *, openapi_version: str = "3.0"
+) -> dict[str, Any]:
+    """Upgrade a Swagger 2.0 dict to OpenAPI 3.0 (or 3.1)."""
+    if not is_swagger2(spec):
+        raise ValueError("not a Swagger 2.0 document (missing swagger: '2.0')")
+    up = _Upgrader(spec)
+    out = up.convert()
+    if openapi_version.startswith("3.1"):
+        out = to_openapi_31(out)
+    return out
+
+
+class _Upgrader:
+    def __init__(self, src: dict[str, Any]):
+        self.src = src
+        self.assumptions: list[str] = []
+        self.lossy: list[str] = []
+        # global body-parameters become requestBodies, not parameters
+        self._global_body_params: set[str] = {
+            name
+            for name, p in (src.get("parameters") or {}).items()
+            if isinstance(p, dict) and p.get("in") == "body"
+        }
+
+    # -- helpers -----------------------------------------------------------
+
+    def _fix_ref(self, ref: str) -> str:
+        if ref.startswith("#/definitions/"):
+            return ref.replace("#/definitions/", "#/components/schemas/", 1)
+        if ref.startswith("#/parameters/"):
+            name = ref.rsplit("/", 1)[-1]
+            if name in self._global_body_params:
+                return f"#/components/requestBodies/{name}"
+            return ref.replace("#/parameters/", "#/components/parameters/", 1)
+        if ref.startswith("#/responses/"):
+            return ref.replace("#/responses/", "#/components/responses/", 1)
+        return ref
+
+    def _fix_schema(self, node: Any) -> Any:
+        """Recursive schema fixups: $refs, type:file, x-nullable,
+        discriminator string -> object."""
+        if isinstance(node, list):
+            return [self._fix_schema(v) for v in node]
+        if not isinstance(node, dict):
+            return node
+        out: dict[str, Any] = {}
+        for k, v in node.items():
+            if k == "$ref" and isinstance(v, str):
+                out[k] = self._fix_ref(v)
+            elif k == "x-nullable":
+                out["nullable"] = v
+            elif k == "discriminator" and isinstance(v, str):
+                out[k] = {"propertyName": v}
+            else:
+                out[k] = self._fix_schema(v)
+        if out.get("type") == "file":
+            out["type"] = "string"
+            out["format"] = "binary"
+        return out
+
+    def _media_types(self, kind: str, op: dict, ctx: str) -> list[str]:
+        types = op.get(kind) or self.src.get(kind) or []
+        if not types:
+            self.assumptions.append(
+                f"{ctx}: no '{kind}' declared; assumed application/json"
+            )
+            return ["application/json"]
+        return list(types)
+
+    # -- parameters --------------------------------------------------------
+
+    def _convert_param(self, p: dict, ctx: str) -> dict:
+        """query/path/header (non-body, non-formData) parameter."""
+        out = {
+            k: v
+            for k, v in p.items()
+            if k in ("name", "in", "description", "required", "allowEmptyValue")
+            or k.startswith("x-")
+        }
+        schema = {k: self._fix_schema(v) for k, v in p.items()
+                  if k in _SCHEMA_FIELDS}
+        if schema.get("type") == "file":
+            schema = {"type": "string", "format": "binary"}
+        out["schema"] = schema or {"type": "string"}
+
+        cf = p.get("collectionFormat")
+        if cf:
+            loc = p.get("in")
+            if cf == "csv":
+                out["style"] = "form" if loc in ("query", "formData") else "simple"
+                out["explode"] = False
+            elif cf == "multi":
+                out["style"] = "form"
+                out["explode"] = True
+            elif cf == "ssv":
+                out["style"] = "spaceDelimited"
+                out["explode"] = False
+            elif cf == "pipes":
+                out["style"] = "pipeDelimited"
+                out["explode"] = False
+            else:  # tsv and friends have no OpenAPI 3 equivalent
+                out["x-collectionFormat"] = cf
+                self.lossy.append(
+                    f"{ctx}: collectionFormat '{cf}' has no OpenAPI 3 "
+                    "equivalent; preserved as x-collectionFormat"
+                )
+        return out
+
+    def _body_to_request_body(self, p: dict, op: dict, ctx: str) -> dict:
+        rb: dict[str, Any] = {}
+        if p.get("description"):
+            rb["description"] = p["description"]
+        if p.get("required"):
+            rb["required"] = True
+        if p.get("name"):
+            rb["x-original-body-name"] = p["name"]
+        schema = self._fix_schema(p.get("schema", {}))
+        rb["content"] = {
+            mt: {"schema": schema}
+            for mt in self._media_types("consumes", op, ctx)
+        }
+        return rb
+
+    def _form_to_request_body(self, params: list[dict], op: dict,
+                              ctx: str) -> dict:
+        has_file = any(p.get("type") == "file" for p in params)
+        media = "multipart/form-data" if has_file else (
+            "application/x-www-form-urlencoded"
+        )
+        props: dict[str, Any] = {}
+        required: list[str] = []
+        for p in params:
+            schema = {k: self._fix_schema(v) for k, v in p.items()
+                      if k in _SCHEMA_FIELDS}
+            if p.get("type") == "file":
+                schema = {"type": "string", "format": "binary"}
+            if p.get("description"):
+                schema["description"] = p["description"]
+            props[p["name"]] = schema or {"type": "string"}
+            if p.get("required"):
+                required.append(p["name"])
+        body_schema: dict[str, Any] = {"type": "object", "properties": props}
+        if required:
+            body_schema["required"] = required
+        return {
+            "required": bool(required),
+            "content": {media: {"schema": body_schema}},
+        }
+
+    def _split_params(self, raw: list, op: dict, ctx: str
+                      ) -> tuple[list, dict | None]:
+        """-> (parameters, requestBody|None)"""
+        params: list[dict] = []
+        body: dict | None = None
+        form: list[dict] = []
+        for p in raw:
+            if not isinstance(p, dict):
+                continue
+            if "$ref" in p:
+                ref = self._fix_ref(p["$ref"])
+                if "/requestBodies/" in ref:
+                    body = {"$ref": ref}
+                else:
+                    params.append({"$ref": ref})
+                continue
+            loc = p.get("in")
+            if loc == "body":
+                body = self._body_to_request_body(p, op, ctx)
+            elif loc == "formData":
+                form.append(p)
+            else:
+                params.append(self._convert_param(p, ctx))
+        if form:
+            if body is not None:
+                self.lossy.append(
+                    f"{ctx}: both body and formData parameters present; "
+                    "formData ignored"
+                )
+            else:
+                body = self._form_to_request_body(form, op, ctx)
+        return params, body
+
+    # -- responses ----------------------------------------------------------
+
+    def _convert_response(self, resp: dict, op: dict, ctx: str) -> dict:
+        if "$ref" in resp:
+            return {"$ref": self._fix_ref(resp["$ref"])}
+        out: dict[str, Any] = {
+            "description": resp.get("description", "")
+        }
+        for k, v in resp.items():
+            if k.startswith("x-"):
+                out[k] = v
+        if "schema" in resp:
+            schema = self._fix_schema(resp["schema"])
+            examples = resp.get("examples") or {}
+            content: dict[str, Any] = {}
+            for mt in self._media_types("produces", op, ctx):
+                entry: dict[str, Any] = {"schema": schema}
+                if mt in examples:
+                    entry["example"] = examples[mt]
+                content[mt] = entry
+            out["content"] = content
+        if "headers" in resp:
+            headers = {}
+            for hname, h in resp["headers"].items():
+                hh = {k: v for k, v in h.items() if k == "description"}
+                hh["schema"] = {
+                    k: self._fix_schema(v) for k, v in h.items()
+                    if k in _SCHEMA_FIELDS
+                } or {"type": "string"}
+                headers[hname] = hh
+            out["headers"] = headers
+        return out
+
+    # -- security -------------------------------------------------------------
+
+    def _convert_security_schemes(self) -> dict:
+        out: dict[str, Any] = {}
+        flow_names = {
+            "implicit": "implicit",
+            "password": "password",
+            "application": "clientCredentials",
+            "accessCode": "authorizationCode",
+        }
+        for name, sd in (self.src.get("securityDefinitions") or {}).items():
+            t = sd.get("type")
+            if t == "basic":
+                out[name] = {"type": "http", "scheme": "basic"}
+                if sd.get("description"):
+                    out[name]["description"] = sd["description"]
+            elif t == "apiKey":
+                out[name] = {k: sd[k] for k in ("type", "name", "in")
+                             if k in sd}
+                if sd.get("description"):
+                    out[name]["description"] = sd["description"]
+            elif t == "oauth2":
+                flow = flow_names.get(sd.get("flow"), sd.get("flow"))
+                flow_obj: dict[str, Any] = {
+                    "scopes": sd.get("scopes", {}),
+                }
+                if "authorizationUrl" in sd:
+                    flow_obj["authorizationUrl"] = sd["authorizationUrl"]
+                if "tokenUrl" in sd:
+                    flow_obj["tokenUrl"] = sd["tokenUrl"]
+                entry: dict[str, Any] = {
+                    "type": "oauth2", "flows": {flow: flow_obj},
+                }
+                if sd.get("description"):
+                    entry["description"] = sd["description"]
+                out[name] = entry
+            else:
+                out[name] = dict(sd)
+                self.lossy.append(
+                    f"securityDefinitions.{name}: unknown type '{t}' copied as-is"
+                )
+        return out
+
+    # -- top level -------------------------------------------------------------
+
+    def _servers(self) -> list[dict]:
+        host = self.src.get("host")
+        base = self.src.get("basePath", "")
+        schemes = self.src.get("schemes")
+        if not host:
+            self.assumptions.append(
+                "no 'host' declared; emitted relative server url "
+                f"'{base or '/'}' (override endpoint at runtime)"
+            )
+            return [{"url": base or "/"}]
+        if not schemes:
+            schemes = ["https"]
+            self.assumptions.append(
+                "no 'schemes' declared; assumed https"
+            )
+        return [{"url": f"{s}://{host}{base}"} for s in schemes]
+
+    def _gen_operation_id(self, method: str, path: str) -> str:
+        raw = f"{method}_{path.strip('/') or 'root'}"
+        raw = raw.replace("{", "").replace("}", "")
+        return _ID_RE.sub("_", raw).strip("_")[:64]
+
+    def convert(self) -> dict[str, Any]:
+        src = self.src
+        out: dict[str, Any] = {
+            "openapi": "3.0.3",
+            "info": dict(src.get("info", {"title": "API", "version": "0.0.0"})),
+            "servers": self._servers(),
+            "paths": {},
+        }
+        for k in ("tags", "externalDocs", "security"):
+            if k in src:
+                out[k] = src[k]
+
+        used_ids: set[str] = set()
+        for path, item in (src.get("paths") or {}).items():
+            if not isinstance(item, dict):
+                continue
+            new_item: dict[str, Any] = {}
+            shared_raw = item.get("parameters", [])
+            for k, v in item.items():
+                if k.startswith("x-"):
+                    new_item[k] = v
+            for method in _METHODS:
+                op = item.get(method)
+                if not isinstance(op, dict):
+                    continue
+                ctx = f"{method.upper()} {path}"
+                new_op: dict[str, Any] = {}
+                for k in ("summary", "description", "tags", "deprecated",
+                          "externalDocs", "security"):
+                    if k in op:
+                        new_op[k] = op[k]
+                for k, v in op.items():
+                    if k.startswith("x-"):
+                        new_op[k] = v
+
+                op_id = op.get("operationId")
+                if not op_id:
+                    op_id = self._gen_operation_id(method, path)
+                    self.assumptions.append(
+                        f"{ctx}: no operationId; generated '{op_id}'"
+                    )
+                else:
+                    normalized = _ID_RE.sub("_", op_id).strip("_")[:64]
+                    if normalized != op_id:
+                        self.assumptions.append(
+                            f"{ctx}: operationId '{op_id}' normalized to "
+                            f"'{normalized}' (FastMCP tool-name convention)"
+                        )
+                        op_id = normalized
+                base_id = op_id
+                n = 2
+                while op_id in used_ids:
+                    op_id = f"{base_id}_{n}"
+                    n += 1
+                used_ids.add(op_id)
+                new_op["operationId"] = op_id
+
+                raw_params = list(shared_raw) + list(op.get("parameters", []))
+                params, request_body = self._split_params(raw_params, op, ctx)
+                if params:
+                    new_op["parameters"] = params
+                if request_body is not None:
+                    new_op["requestBody"] = request_body
+
+                new_op["responses"] = {
+                    str(code): self._convert_response(resp, op, ctx)
+                    for code, resp in (op.get("responses") or {}).items()
+                } or {"200": {"description": "OK"}}
+
+                new_item[method] = new_op
+            out["paths"][path] = new_item
+
+        components: dict[str, Any] = {}
+        if src.get("definitions"):
+            components["schemas"] = {
+                name: self._fix_schema(schema)
+                for name, schema in src["definitions"].items()
+            }
+        global_params = src.get("parameters") or {}
+        conv_params = {}
+        request_bodies = {}
+        for name, p in global_params.items():
+            if name in self._global_body_params:
+                request_bodies[name] = self._body_to_request_body(p, {}, name)
+            else:
+                conv_params[name] = self._convert_param(p, f"parameters.{name}")
+        if conv_params:
+            components["parameters"] = conv_params
+        if request_bodies:
+            components["requestBodies"] = request_bodies
+        if src.get("responses"):
+            components["responses"] = {
+                name: self._convert_response(r, {}, f"responses.{name}")
+                for name, r in src["responses"].items()
+            }
+        schemes = self._convert_security_schemes()
+        if schemes:
+            components["securitySchemes"] = schemes
+        if components:
+            out["components"] = components
+
+        out["x-s2o"] = {
+            "source": "swagger-2.0",
+            "generator": f"spec2openapi/{_version}",
+            "assumptions": self.assumptions,
+            "lossy": self.lossy,
+        }
+        return out

spec2openapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: spec2openapi
+Version: 0.1.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
+Project-URL: Homepage, https://github.com/Seo-yul/spec2openapi
+Project-URL: Repository, https://github.com/Seo-yul/spec2openapi
+Project-URL: Issues, https://github.com/Seo-yul/spec2openapi/issues
+Project-URL: Changelog, https://github.com/Seo-yul/spec2openapi/blob/main/CHANGELOG.md
+Keywords: wsdl,soap,swagger,openapi,mcp,fastmcp,converter,legacy,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: zeep>=4.2
+Requires-Dist: lxml>=4.9
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=3.0; extra == "mcp"
+Requires-Dist: httpx>=0.27; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: fastmcp>=3.0; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: openapi-spec-validator>=0.7; extra == "dev"
+Dynamic: license-file
+
+# spec2openapi
+
+> Convert legacy API specifications — SOAP/WSDL and Swagger 2.0 — into **FastMCP-ready OpenAPI 3.x** documents.
+
+[![CI](https://github.com/Seo-yul/spec2openapi/actions/workflows/ci.yml/badge.svg)](https://github.com/Seo-yul/spec2openapi/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/spec2openapi)](https://pypi.org/project/spec2openapi/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
+[![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-Contributor%20Covenant-purple.svg)](CODE_OF_CONDUCT.md)
+
+[한국어 문서 (Korean README)](README.ko.md)
+
+---
+
+MCP (Model Context Protocol) tooling such as [FastMCP](https://gofastmcp.com) can turn an OpenAPI 3.x document into an MCP server automatically — but enterprises are full of services described only by WSDL or Swagger 2.0. `spec2openapi` closes that gap:
+
+```
+WSDL ─────────┐
+              ├──(spec2openapi)──> OpenAPI 3.x (+ x-soap extensions) ──> FastMCP.from_openapi() ──> MCP tools
+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.
+
+## Features
+
+- **WSDL → OpenAPI 3.0/3.1** — document/literal and rpc/literal bindings, SOAP 1.1/1.2, nested complex types, arrays, attributes, `nillable`, inheritance (flattened `complexContent` extensions), `simpleContent` (text value + attributes), `choice` (members become optional + `x-soap-choice`), default values, recursive types, multi-service/multi-port WSDLs with automatic dedup.
+- **XSD facets & docs carried into tool schemas** — enumerations, `pattern`, length and numeric bounds, `fractionDigits` (→ `multipleOf`), and `xsd:annotation` documentation are extracted (including from `xsd:import`-ed schemas) so LLMs see well-described, well-constrained tool arguments.
+- **`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.
+
+## Installation
+
+```bash
+pip install spec2openapi          # converter only (zeep, lxml, PyYAML)
+pip install "spec2openapi[mcp]"   # + reference MCP runtime (fastmcp, httpx)
+```
+
+## Quick start
+
+### CLI
+
+```bash
+# See what a WSDL contains (operations, headers, faults, style)
+spec2openapi inspect https://legacy-host/OrderService?wsdl
+
+# WSDL -> OpenAPI
+spec2openapi convert https://legacy-host/OrderService?wsdl -o orders.openapi.yaml
+
+# Swagger 2.0 -> OpenAPI 3.x (assumptions reported on stderr)
+spec2openapi upgrade swagger2.json -o service.openapi.yaml
+
+# Prove the spec converts cleanly into MCP tools
+spec2openapi validate orders.openapi.yaml
+
+# Reference MCP runtime (requires the [mcp] extra)
+spec2openapi serve orders.openapi.yaml --transport http --port 8000
+```
+
+```text
+$ spec2openapi validate orders.openapi.yaml
+operations        : 2
+component schemas : 3
+openapi-spec-validator: OK
+FastMCP round-trip: OK (2 tools)
+  - CreateOrder(customer, items, note)
+  - GetOrder(orderId)
+
+OK: spec is FastMCP-convertible
+```
+
+### Library
+
+```python
+import spec2openapi
+
+# WSDL -> OpenAPI dict
+spec = spec2openapi.convert_wsdl("https://legacy-host/OrderService?wsdl")
+
+# Swagger 2.0 -> OpenAPI dict
+legacy = spec2openapi.load_spec("swagger2.json")
+spec = spec2openapi.convert_swagger(legacy, openapi_version="3.1")
+
+print(spec2openapi.dump_spec(spec))            # YAML text
+
+# Optional [mcp] extra: run it as an MCP server right away
+mcp = spec2openapi.from_openapi_spec(spec)
+mcp.run(transport="http", host="0.0.0.0", port=8000)
+```
+
+## How SOAP calls work (the `x-soap` contract)
+
+The generated paths (`/operations/...`) are *not* real REST endpoints — a SOAP translation layer must build the actual call. Everything it needs ships inside the spec:
+
+| Field (`paths.*.post.x-soap`) | Meaning |
+|---|---|
+| `operation` / `service` / `port` | WSDL names |
+| `soapAction`, `soapVersion`, `style` | `"1.1"`/`"1.2"`, `document`/`rpc` |
+| `endpoint` | `soap:address` (override at runtime) |
+| `input` / `output` | wrapper element QNames |
+| `headers[]` | `soap:header` parts with schema refs |
+| `faults[]` | declared faults with schema refs |
+
+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.
+
+## Handling missing information (Swagger 2.0)
+
+Upgrading is favorable: OpenAPI 3.x is a superset of Swagger 2.0, so almost nothing must be invented. Where documents are genuinely underspecified, a three-tier policy applies:
+
+1. **Deterministic, documented defaults** — missing `consumes`/`produces` → `application/json`; missing `operationId` → `{method}_{path}`; missing `host` → relative server `/`; missing `schemes` → `https`. All recorded in `x-s2o.assumptions`.
+2. **Preserve, never drop** — constructs with no OpenAPI 3 equivalent (e.g. `collectionFormat: tsv`) are kept as `x-` extensions and listed in `x-s2o.lossy`.
+3. **Verify the outcome** — `spec2openapi validate` runs the actual FastMCP round-trip; assumptions never block tool generation because tools only need paths and schemas.
+
+## Kubernetes: one image, many MCP servers
+
+```bash
+docker build -t spec2openapi:0.1.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
+```
+
+Only the ConfigMap changes per service; credentials live in a Secret (`SPEC2OPENAPI_ENDPOINT`, `SPEC2OPENAPI_AUTH` = `basic`|`wsse`, `SPEC2OPENAPI_USERNAME`/`PASSWORD`, `SPEC2OPENAPI_TIMEOUT`, `SPEC2OPENAPI_VERIFY`, `SPEC2OPENAPI_TRUST_ENV`). The MCP endpoint is `http://<service>:8000/mcp` (streamable HTTP).
+
+## Limitations
+
+rpc/encoded (skipped and recorded in `x-soap.skippedOperations`), MTOM/attachments, WS-Policy/WS-Addressing, and substitution groups are not supported. WS-Security support in the reference runtime is UsernameToken (PasswordText).
+
+## Security
+
+All XML parsing disables DTD loading, entity resolution, and parser-level network access. When converting WSDLs from **untrusted sources**, add `--forbid-external` (CLI) or `forbid_external=True` (API) to refuse fetching remote `wsdl:`/`xsd:` imports (SSRF mitigation; local relative imports still work). See [SECURITY.md](SECURITY.md) for the full notes and how to report vulnerabilities.
+
+## Development
+
+```bash
+git clone https://github.com/Seo-yul/spec2openapi.git
+cd spec2openapi
+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/).
+
+## Project layout
+
+```
+src/spec2openapi/
+  parser.py    WSDL parsing (zeep) + raw XSD scraping (facets/docs)
+  schema.py    XSD -> JSON Schema (xml annotations, choice, simpleContent)
+  openapi.py   OpenAPI 3.0/3.1 assembly + x-soap extensions
+  swagger.py   Swagger 2.0 -> OpenAPI 3.x upgrader (x-s2o report)
+  convert.py   core public API
+  cli.py       convert / upgrade / inspect / validate / serve
+  bridge.py    [mcp] SOAP bridge (httpx transport)
+  server.py    [mcp] FastMCP glue
+```
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md); by participating you agree to uphold it. Security issues should be reported privately per [SECURITY.md](SECURITY.md).
+
+## License
+
+[Apache-2.0](LICENSE) © Seoyul Yoon

spec2openapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+spec2openapi/__init__.py,sha256=DoFVZfZGQ5zyPwizWASea6i4Ayw7Wcu9-P8lNUu5Jis,1602
+spec2openapi/bridge.py,sha256=dmFkkSVTMq61_Zc2fUfj68l351puN9yIhqbb2UFB-g8,17842
+spec2openapi/cli.py,sha256=5el4EsmEIeyHisv2iC6372VQzfwsy5MsKgk9qL9iNL8,12890
+spec2openapi/convert.py,sha256=-dh1enyn4nzRmMEXIu-G3tvQwfVYyiFSJT8uVOsgpqo,1860
+spec2openapi/openapi.py,sha256=WaB2VOAa0ocCrFtOT6syZ1RfDmzkojm9PTo_oeLvvHE,8202
+spec2openapi/parser.py,sha256=J5Dz6VzEnsO53q8A-dCXAfxq0DWHo2PUlRMoVBOOjuk,14422
+spec2openapi/schema.py,sha256=tEL1E19ifBt3agQc66fUWfA-spTcPMJ8_7xk2N5ErJU,14223
+spec2openapi/server.py,sha256=zm9eaYZdS55pjpWki40Gxxwu0qD-3NEwAQ9JODxHWlk,2715
+spec2openapi/swagger.py,sha256=bY-no2YnHzhfAquaFDx9yWFalG0t_MyZPJoNjafzwHc,16999
+spec2openapi-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+spec2openapi-0.1.0.dist-info/licenses/NOTICE,sha256=zAkiLCa3_3uH4MsMEbZl9rNVduuctejTEPG0KPk-tNw,40
+spec2openapi-0.1.0.dist-info/METADATA,sha256=gA5fQwZ1f2F5jKv7Fz10VPB-wTx_BNCcRuEaONGLvHc,11408
+spec2openapi-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+spec2openapi-0.1.0.dist-info/entry_points.txt,sha256=NhuUOMb8fm5PiltKu4aJF-Xl70HM8kWBLlAEvcEyWSs,55
+spec2openapi-0.1.0.dist-info/top_level.txt,sha256=CftEOgnXYLVL0K29581AP6wegrffm2aaoTVBHGCSUYc,13
+spec2openapi-0.1.0.dist-info/RECORD,,

spec2openapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

spec2openapi-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spec2openapi = spec2openapi.cli:main