mcpify-openapi 1.0.2__tar.gz → 1.0.3__tar.gz

{mcpify_openapi-1.0.2 → mcpify_openapi-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpify-openapi
-Version: 1.0.2
+Version: 1.0.3
 Summary: Turn any OpenAPI REST API into an MCP server so AI agents can call it — zero dependencies
 License: MIT
 Keywords: mcp,model-context-protocol,openapi,swagger,ai-agents,claude,rest,api,cli

{mcpify_openapi-1.0.2 → mcpify_openapi-1.0.3}/mcpify/__init__.py

@@ -3,7 +3,7 @@
 from .spec import SpecError, load_spec, resolve_ref, resolve_schema
 from .tools import AuthConfig, RequestError, build_request, spec_to_tools
 
-__version__ = "1.0.2"
+__version__ = "1.0.3"
 __all__ = [
     "SpecError",
     "load_spec",

{mcpify_openapi-1.0.2 → mcpify_openapi-1.0.3}/mcpify/cli.py

@@ -61,10 +61,31 @@ def filter_tools(tools: list[dict], args: argparse.Namespace) -> list[dict]:
 def _base_url(spec: dict, override: str | None) -> str:
     if override:
         return override
-    servers = spec_servers(spec)
+    servers = spec.get("servers") or []
     if servers:
-        return servers[0]
-    _fail(
+        entry = servers[0] if isinstance(servers[0], dict) else {"url": str(servers[0])}
+        url = str(entry.get("url", ""))
+        # substitute server variables from their declared defaults
+        variables = entry.get("variables")
+        if isinstance(variables, dict):
+            for name, var in variables.items():
+                default = var.get("default") if isinstance(var, dict) else None
+                if default is not None:
+                    url = url.replace("{" + name + "}", str(default))
+        if "{" in url:
+            kalan = re.findall(r"\{([^{}]+)\}", url)
+            raise SpecError(
+                f"server URL variable(s) {kalan} have no default; "
+                "pass --base-url to set the target explicitly"
+            )
+        if url and not url.startswith(("http://", "https://")):
+            raise SpecError(
+                f"server URL '{url}' is relative and cannot be called; "
+                "pass --base-url with the absolute URL"
+            )
+        if url:
+            return url
+    raise SpecError(
         "no base URL: the spec declares no servers and --base-url was not given"
     )
 
@@ -172,16 +193,15 @@ def main(argv: list[str] | None = None) -> None:
         print(dim(f"serve it: mcpify serve {args.spec}"))
 
     elif args.command == "serve":
-        if not args.base_url and not spec_servers(spec):
-            _fail(
-                "no base URL: the spec declares no servers and --base-url was not given"
-            )
         auth = None
         if args.auth_env:
             auth = AuthConfig(args.auth_env, args.auth_style, args.auth_name)
         from .api_server import ApiServer
 
-        base = args.base_url or spec_servers(spec)[0]
+        try:
+            base = _base_url(spec, args.base_url)
+        except SpecError as err:
+            _fail(str(err))
         server = ApiServer(
             spec,
             base,
@@ -230,6 +250,13 @@ def main(argv: list[str] | None = None) -> None:
             print(warn(f"warning: {no_summary}/{total} operations have no summary (agents see no description)"))
         if variabled:
             print(warn(f"warning: server URL(s) contain variables: {', '.join(variabled)} — pass --base-url"))
+        if servers and not servers[0].startswith(("http://", "https://")):
+            print(warn(f"warning: server URL '{servers[0]}' is relative — pass --base-url with the absolute URL"))
+        deprecated = sum(1 for _m, _p, op in iter_operations(spec) if op.get("deprecated"))
+        if deprecated:
+            print(warn(f"warning: {deprecated} deprecated operation(s) will be exposed (filter with --tag/--exclude if unintended)"))
+        if total > 50:
+            print(warn(f"warning: {total} operations is a large tool surface — consider --tag/--include/--exclude to protect the model's context"))
         if not missing_id and not no_summary:
             print(ok("all operations carry operationId and summary — agent-friendly ✓"))
 

{mcpify_openapi-1.0.2 → mcpify_openapi-1.0.3}/mcpify/http_client.py

@@ -41,11 +41,21 @@ def execute(request: dict, timeout: float = 30.0) -> dict:
     return {"status": status, "body": raw, "json": parsed}
 
 
+MAX_RESULT_CHARS = 40_000
+
+
 def format_result(result: dict) -> tuple[str, bool]:
-    """Format an execute() result for an MCP tool response: (text, is_error)."""
+    """Format an execute() result for an MCP tool response: (text, is_error).
+
+    Oversized bodies are truncated so a single tool call cannot blow the
+    client's context window.
+    """
     body = result["body"]
     if result["json"] is not None:
         body = json.dumps(result["json"], ensure_ascii=False, indent=2)
+    if len(body) > MAX_RESULT_CHARS:
+        kesilen = len(body) - MAX_RESULT_CHARS
+        body = body[:MAX_RESULT_CHARS] + f"\n… [truncated {kesilen:,} more characters]"
     is_error = result["status"] == 0 or result["status"] >= 400
     if is_error:
         return f"HTTP {result['status']}\n{body}", is_error

{mcpify_openapi-1.0.2 → mcpify_openapi-1.0.3}/mcpify/spec.py

@@ -103,7 +103,25 @@ def resolve_schema(schema: Any, spec: dict, depth: int = 0) -> Any:
                 name: resolve_schema(sub, spec, depth + 1) for name, sub in value.items()
             }
         elif key in ("anyOf", "oneOf", "allOf") and isinstance(value, list):
-            resolved[key] = [resolve_schema(sub, spec, depth + 1) for sub in value]
+            resolved_subs = [resolve_schema(sub, spec, depth + 1) for sub in value]
+            if key == "allOf":
+                # allOf intersection: merge member properties/required upward
+                merged_props = dict(resolved.get("properties") or {})
+                merged_req = list(resolved.get("required") or [])
+                for sub in resolved_subs:
+                    if isinstance(sub, dict):
+                        merged_props.update(sub.get("properties") or {})
+                        for req in sub.get("required") or []:
+                            if req not in merged_req:
+                                merged_req.append(req)
+                if merged_props:
+                    resolved["properties"] = merged_props
+                if merged_req:
+                    resolved["required"] = merged_req
+                # merged members are flattened into the parent; the allOf key
+                # itself is intentionally dropped
+            else:
+                resolved[key] = resolved_subs
         else:
             resolved[key] = value
     return resolved

{mcpify_openapi-1.0.2 → mcpify_openapi-1.0.3}/mcpify/tools.py

@@ -59,6 +59,7 @@ def build_input_schema(
     parameters: list[dict],
     request_schema: dict | None,
     spec: dict | None = None,
+    raw_body_content_type: str | None = None,
 ) -> dict:
     """Build the JSON Schema for an MCP tool from parameters + request body.
 
@@ -85,10 +86,7 @@ def build_input_schema(
         name = str(param.get("name", ""))
         if not name:
             continue
-        if param.get("schema"):
-            schema = safe_resolve(param["schema"])
-        else:
-            schema = {"type": "string"}
+        schema = safe_resolve(param["schema"]) if param.get("schema") else {"type": "string"}
         entry = {"type": schema.get("type", "string"), "description": str(param.get("description", ""))}
         if schema.get("enum"):
             entry["enum"] = schema["enum"]
@@ -102,12 +100,22 @@ def build_input_schema(
             required.append(key)
 
     if request_schema is not None and method not in ("GET", "HEAD", "DELETE"):
-        properties[BODY_ARG] = {
-            "type": "object",
-            "description": "JSON request body",
-            **({"properties": request_schema.get("properties", {})} if request_schema.get("properties") else {}),
-            **({"required": request_schema["required"]} if request_schema.get("required") else {}),
-        }
+        if raw_body_content_type:
+            properties[BODY_ARG] = {
+                "type": "string",
+                "description": (f"raw request body, sent as-is "
+                                f"(content type: {raw_body_content_type})"),
+            }
+        else:
+            note = ""
+            if not request_schema.get("properties") and request_schema.get("x-unresolved"):
+                note = " (schema could not be fully resolved from the spec)"
+            properties[BODY_ARG] = {
+                "type": "object",
+                "description": "JSON request body" + note,
+                **({"properties": request_schema.get("properties", {})} if request_schema.get("properties") else {}),
+                **({"required": request_schema["required"]} if request_schema.get("required") else {}),
+            }
 
     return {"type": "object", "properties": properties, "required": required}
 
@@ -117,12 +125,22 @@ def operation_to_tool(method: str, path: str, operation: dict, path_item: dict,
     parameters = extract_parameters(operation, path_item, spec)
 
     request_schema = None
+    raw_body_content_type = None
     body = operation.get("requestBody")
     if isinstance(body, dict):
         content = body.get("content") or {}
         json_media = content.get("application/json")
         if isinstance(json_media, dict) and json_media.get("schema"):
-            request_schema = resolve_schema(json_media["schema"], spec)
+            try:
+                request_schema = resolve_schema(json_media["schema"], spec)
+            except SpecError:
+                # circular / unresolvable body schema must not kill the tool
+                request_schema = {"type": "object", "x-unresolved": True}
+        elif content:
+            # non-JSON bodies (multipart uploads, form posts): expose a raw
+            # string body instead of silently dropping the operation's payload
+            raw_body_content_type = next(iter(content))
+            request_schema = {"type": "string"}
 
     name = operation_id(method, path, operation)
     base = name
@@ -135,12 +153,13 @@ def operation_to_tool(method: str, path: str, operation: dict, path_item: dict,
     return {
         "name": name,
         "description": build_description(method, path, operation),
-        "inputSchema": build_input_schema(method.upper(), operation, parameters, request_schema, spec),
+        "inputSchema": build_input_schema(method.upper(), operation, parameters, request_schema, spec, raw_body_content_type),
         "_meta": {
             "method": method.upper(),
             "path": path,
             "parameters": parameters,
             "has_body": request_schema is not None,
+            "raw_body_content_type": raw_body_content_type,
             "tags": list(operation.get("tags") or []),
         },
     }
@@ -153,6 +172,8 @@ def spec_to_tools(spec: dict) -> list[dict]:
     tools: list[dict] = []
     taken: set = set()
     for method, path, operation in iter_operations(spec):
+        if method.lower() in ("head", "options", "trace"):
+            continue  # no agent value; they carry no request semantics
         path_item = spec["paths"][path]
         tools.append(operation_to_tool(method, path, operation, path_item, spec, taken))
     return tools
@@ -218,10 +239,17 @@ def build_request(
         body = arguments.get(BODY_ARG)
         if body is None:
             raise RequestError(f"missing required argument '{BODY_ARG}' (JSON request body)")
-        if not isinstance(body, dict):
+        raw_ct = meta.get("raw_body_content_type")
+        if raw_ct:
+            if not isinstance(body, str):
+                raise RequestError(f"'{BODY_ARG}' must be a string for {raw_ct} bodies")
+            body_bytes = body.encode("utf-8")
+            headers["Content-Type"] = raw_ct
+        elif not isinstance(body, dict):
             raise RequestError(f"'{BODY_ARG}' must be a JSON object")
-        body_bytes = json.dumps(body).encode("utf-8")
-        headers["Content-Type"] = "application/json"
+        else:
+            body_bytes = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
         used.add(BODY_ARG)
 
     unknown = sorted(set(arguments) - used)

{mcpify_openapi-1.0.2 → mcpify_openapi-1.0.3}/mcpify_openapi.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpify-openapi
-Version: 1.0.2
+Version: 1.0.3
 Summary: Turn any OpenAPI REST API into an MCP server so AI agents can call it — zero dependencies
 License: MIT
 Keywords: mcp,model-context-protocol,openapi,swagger,ai-agents,claude,rest,api,cli

{mcpify_openapi-1.0.2 → mcpify_openapi-1.0.3}/mcpify_openapi.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ mcpify_openapi.egg-info/requires.txt
 mcpify_openapi.egg-info/top_level.txt
 tests/test_cli.py
 tests/test_e2e.py
+tests/test_hostile_specs.py
 tests/test_policy.py
 tests/test_ref_params.py
 tests/test_spec.py

{mcpify_openapi-1.0.2 → mcpify_openapi-1.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mcpify-openapi"  # "mcpify" on PyPI is an unrelated package; CLI command stays `mcpify`
-version = "1.0.2"
+version = "1.0.3"
 description = "Turn any OpenAPI REST API into an MCP server so AI agents can call it — zero dependencies"
 readme = "README.md"
 requires-python = ">=3.10"

mcpify_openapi-1.0.3/tests/test_hostile_specs.py

@@ -0,0 +1,168 @@
+"""Hostile-spec regression suite.
+
+Every case here maps to a documented real-world MCP/OpenAPI pain point
+(sources: arXiv 2507.16044 REST->MCP study; truefoundry & digitalapi
+conversion guides). These scenarios crashed or misbehaved in v1.0.2 and
+are locked in so they stay fixed.
+"""
+
+
+import pytest
+
+from mcpify.cli import _base_url
+from mcpify.http_client import format_result
+from mcpify.spec import SpecError
+from mcpify.tools import build_request, spec_to_tools
+
+
+def spec_with(paths, components=None, servers=None, openapi="3.0.0"):
+    return {
+        "openapi": openapi,
+        "info": {"title": "hostile", "version": "1"},
+        "servers": servers or [{"url": "https://api.example.com"}],
+        "paths": paths,
+        **({"components": components} if components else {}),
+    }
+
+
+# ---------- A) spec structure ----------
+
+def test_request_body_ref_resolves_into_tool_schema():
+    spec = spec_with(
+        {"/pets": {"post": {
+            "operationId": "createPet", "summary": "Create",
+            "requestBody": {"content": {"application/json": {
+                "schema": {"$ref": "#/components/schemas/Pet"}}}},
+            "responses": {"200": {"description": "ok"}}}}},
+        {"schemas": {"Pet": {"type": "object", "properties": {
+            "name": {"type": "string"}}}}},
+    )
+    body = spec_to_tools(spec)[0]["inputSchema"]["properties"]["body"]
+    assert list(body["properties"]) == ["name"]
+
+
+def test_circular_body_ref_degrades_instead_of_crashing():
+    spec = spec_with(
+        {"/node": {"post": {
+            "operationId": "makeNode", "summary": "Make",
+            "requestBody": {"content": {"application/json": {
+                "schema": {"$ref": "#/components/schemas/Node"}}}},
+            "responses": {"200": {"description": "ok"}}}}},
+        {"schemas": {"Node": {"type": "object", "properties": {
+            "child": {"$ref": "#/components/schemas/Node"}}}}},
+    )
+    body = spec_to_tools(spec)[0]["inputSchema"]["properties"]["body"]
+    assert body["type"] == "object"
+    assert "could not be fully resolved" in body["description"]
+
+
+def test_multipart_only_body_becomes_raw_string_arg():
+    spec = spec_with(
+        {"/upload": {"post": {
+            "operationId": "uploadFile", "summary": "Upload",
+            "requestBody": {"content": {"multipart/form-data": {
+                "schema": {"type": "object", "properties": {
+                    "file": {"type": "string", "format": "binary"}}}}}},
+            "responses": {"200": {"description": "ok"}}}}},
+    )
+    tool = spec_to_tools(spec)[0]
+    body = tool["inputSchema"]["properties"]["body"]
+    assert body["type"] == "string"
+    assert "multipart/form-data" in body["description"]
+    # and build_request sends it raw with the right content type
+    req = build_request("https://api.example.com", tool["_meta"],
+                        {"body": "RAW"})
+    assert req["body"] == b"RAW"
+    assert req["headers"]["Content-Type"] == "multipart/form-data"
+
+
+def test_allof_members_merge_into_body_schema():
+    spec = spec_with(
+        {"/pets": {"post": {
+            "operationId": "createPet", "summary": "Create",
+            "requestBody": {"content": {"application/json": {"schema": {"allOf": [
+                {"$ref": "#/components/schemas/Base"},
+                {"type": "object", "properties": {"extra": {"type": "string"}}}]}}}},
+            "responses": {"200": {"description": "ok"}}}}},
+        {"schemas": {"Base": {"type": "object", "required": ["name"],
+                              "properties": {"name": {"type": "string"}}}}},
+    )
+    body = spec_to_tools(spec)[0]["inputSchema"]["properties"]["body"]
+    assert set(body["properties"]) == {"name", "extra"}
+    assert body["required"] == ["name"]
+
+
+def test_oas31_type_arrays_do_not_crash():
+    spec = spec_with(
+        {"/x": {"get": {"operationId": "getX", "summary": "Get",
+                        "parameters": [{"name": "q", "in": "query",
+                                        "schema": {"type": ["string", "null"]}}],
+                        "responses": {"200": {"description": "ok"}}}}},
+        openapi="3.1.0",
+    )
+    props = spec_to_tools(spec)[0]["inputSchema"]["properties"]
+    assert props["q"]["type"] == ["string", "null"]
+
+
+# ---------- B) server URL (arXiv failure category B) ----------
+
+def test_server_variable_defaults_are_substituted():
+    spec = spec_with(
+        {"/x": {"get": {"operationId": "x", "responses": {"200": {"description": "ok"}}}}},
+        servers=[{"url": "https://{host}/v2",
+                  "variables": {"host": {"default": "api.example.com"}}}],
+    )
+    assert _base_url(spec, None) == "https://api.example.com/v2"
+
+
+def test_server_variable_without_default_fails_cleanly():
+    spec = spec_with(
+        {"/x": {"get": {"operationId": "x", "responses": {"200": {"description": "ok"}}}}},
+        servers=[{"url": "https://{region}.api.io",
+                  "variables": {"region": {"enum": ["eu", "us"]}}}],
+    )
+    with pytest.raises(SpecError, match="--base-url"):
+        _base_url(spec, None)
+
+
+def test_relative_server_url_fails_cleanly():
+    spec = spec_with(
+        {"/x": {"get": {"operationId": "x", "responses": {"200": {"description": "ok"}}}}},
+        servers=[{"url": "/api/v3"}],
+    )
+    with pytest.raises(SpecError, match="relative"):
+        _base_url(spec, None)
+
+
+# ---------- C) tool surface ----------
+
+def test_useless_methods_are_not_exposed():
+    spec = spec_with({"/x": {
+        "get": {"operationId": "getX", "summary": "g", "responses": {"200": {"description": "ok"}}},
+        "head": {"operationId": "headX", "summary": "h", "responses": {"200": {"description": "ok"}}},
+        "options": {"operationId": "optionsX", "summary": "o", "responses": {"200": {"description": "ok"}}},
+        "trace": {"operationId": "traceX", "summary": "t", "responses": {"200": {"description": "ok"}}},
+        "patch": {"operationId": "patchX", "summary": "p", "responses": {"200": {"description": "ok"}}},
+    }})
+    names = {t["name"] for t in spec_to_tools(spec)}
+    assert {"getx", "patchx"} <= names
+    assert not (names & {"headx", "optionsx", "tracex"})
+
+
+# ---------- D) runtime ----------
+
+def test_500_operations_convert_fast():
+    spec = spec_with({f"/res{i}": {"get": {"operationId": f"get{i}", "summary": f"s{i}",
+                                           "responses": {"200": {"description": "ok"}}}}
+                      for i in range(500)})
+    tools = spec_to_tools(spec)
+    assert len(tools) == 500
+
+
+def test_oversized_response_is_truncated():
+    big = "x" * 300_000
+    text, is_error = format_result({"status": 200, "body": big, "json": None})
+    assert not is_error
+    assert len(text) < 60_000
+    assert "truncated" in text
+    assert "260,000 more characters" in text  # mentions the cut size

{mcpify_openapi-1.0.2 → mcpify_openapi-1.0.3}/tests/test_ref_params.py

@@ -10,7 +10,7 @@ import argparse
 import pytest
 
 from mcpify.cli import filter_tools
-from mcpify.spec import SpecError, load_spec
+from mcpify.spec import load_spec
 from mcpify.tools import spec_to_tools
 
 SPEC = {

{mcpify_openapi-1.0.2 → mcpify_openapi-1.0.3}/tests/test_tools.py

@@ -4,7 +4,7 @@ import json
 
 import pytest
 
-from mcpify.spec import SpecError, load_spec
+from mcpify.spec import load_spec
 from mcpify.tools import (
     BODY_ARG,
     AuthConfig,
@@ -198,7 +198,7 @@ def test_missing_env_var_is_request_error(monkeypatch):
         auth.headers()
 
 
-def test_unresolvable_ref_raises_during_conversion():
+def test_unresolvable_body_ref_degrades_during_conversion():
     spec = {
         "openapi": "3.0.0",
         "paths": {
@@ -212,5 +212,11 @@ def test_unresolvable_ref_raises_during_conversion():
             }
         },
     }
-    with pytest.raises(SpecError):
+    tools = spec_to_tools(spec)
+    body = tools[0]["inputSchema"]["properties"]["body"]
+    assert body["type"] == "object"
+    assert "could not be fully resolved" in body["description"]
+
+
+def _old_raises_block_removed():
         spec_to_tools(spec)