mcpify-openapi 1.0.0__py3-none-any.whl

mcpify/__init__.py

@@ -0,0 +1,17 @@
+"""mcpify — turn any OpenAPI REST API into an MCP server for AI agents."""
+
+from .spec import SpecError, load_spec, resolve_ref, resolve_schema
+from .tools import AuthConfig, RequestError, build_request, spec_to_tools
+
+__version__ = "1.0.0"
+__all__ = [
+    "SpecError",
+    "load_spec",
+    "resolve_ref",
+    "resolve_schema",
+    "AuthConfig",
+    "RequestError",
+    "build_request",
+    "spec_to_tools",
+    "__version__",
+]

mcpify/api_server.py

@@ -0,0 +1,139 @@
+"""MCP (Model Context Protocol) stdio server that exposes an OpenAPI spec.
+
+Specks newline-delimited JSON-RPC 2.0 over stdio, as used by MCP stdio
+transports. Every OpenAPI operation becomes an MCP tool that performs a
+real HTTP call against the configured base URL.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from .http_client import execute, format_result
+from .tools import AuthConfig, RequestError, build_request, spec_to_tools
+
+PROTOCOL_VERSION = "2025-06-18"
+SERVER_NAME = "mcpify"
+SERVER_VERSION = "1.0.0"
+
+
+class ApiServer:
+    """MCP handler backed by one OpenAPI specification."""
+
+    def __init__(
+        self,
+        spec: dict,
+        base_url: str,
+        server_name: str = "mcpify",
+        auth: AuthConfig | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.spec = spec
+        self.base_url = base_url
+        self.server_name = server_name
+        self.auth = auth
+        self.timeout = timeout
+        self.tools = spec_to_tools(spec)
+        self.by_name = {tool["name"]: tool for tool in self.tools}
+
+    # -- public API used by the CLI --------------------------------------
+    @property
+    def tool_count(self) -> int:
+        return len(self.tools)
+
+    def public_tools(self) -> list[dict]:
+        return [
+            {k: v for k, v in tool.items() if not k.startswith("_")}
+            for tool in self.tools
+        ]
+
+    def call_tool(self, name: str, arguments: dict) -> tuple[str, bool]:
+        tool = self.by_name.get(name)
+        if tool is None:
+            raise KeyError(name)
+        request = build_request(self.base_url, tool["_meta"], arguments, self.auth)
+        if self.auth is not None:
+            request["url"] = self.auth.apply_query(request["url"])
+        result = execute(request, timeout=self.timeout)
+        return format_result(result)
+
+    # -- MCP plumbing -----------------------------------------------------
+    def _result(self, request_id: int | str | None, payload: dict) -> dict:
+        return {"jsonrpc": "2.0", "id": request_id, "result": payload}
+
+    def _error(self, request_id: int | str | None, code: int, message: str) -> dict:
+        return {"jsonrpc": "2.0", "id": request_id, "error": {"code": code, "message": message}}
+
+    def _text(self, text: str, is_error: bool = False) -> dict:
+        payload: dict = {"content": [{"type": "text", "text": text}]}
+        if is_error:
+            payload["isError"] = True
+        return payload
+
+    def handle_message(self, message: dict) -> dict | None:
+        method = message.get("method", "")
+        request_id = message.get("id")
+        params = message.get("params") or {}
+
+        if method == "initialize":
+            requested = params.get("protocolVersion", PROTOCOL_VERSION)
+            return self._result(
+                request_id,
+                {
+                    "protocolVersion": requested,
+                    "capabilities": {"tools": {}},
+                    "serverInfo": {"name": self.server_name, "version": SERVER_VERSION},
+                },
+            )
+        if method.startswith("notifications/"):
+            return None
+        if method == "ping":
+            return self._result(request_id, {})
+        if method == "tools/list":
+            return self._result(request_id, {"tools": self.public_tools()})
+        if method == "tools/call":
+            name = params.get("name", "")
+            arguments = params.get("arguments") or {}
+            try:
+                text, is_error = self.call_tool(name, arguments)
+            except KeyError:
+                return self._error(request_id, -32601, f"unknown tool: {name}")
+            except RequestError as err:
+                return self._result(request_id, self._text(str(err), is_error=True))
+            return self._result(request_id, self._text(text, is_error=is_error))
+        return self._error(request_id, -32601, f"method not found: {method}")
+
+    def serve(self, stdin: Any = None, stdout: Any = None) -> None:
+        input_stream = stdin if stdin is not None else sys.stdin
+        output_stream = stdout if stdout is not None else sys.stdout
+        for line in input_stream:
+            line = line.strip()
+            if not line:
+                continue
+            decoded: Any
+            response: dict | None
+            try:
+                decoded = json.loads(line)
+            except json.JSONDecodeError:
+                response = self._error(None, -32700, "parse error")
+            else:
+                response = self.handle_message(decoded)
+            if response is not None:
+                output_stream.write(json.dumps(response, ensure_ascii=False) + "\n")
+                output_stream.flush()
+
+
+def serve(
+    spec_path: str,
+    base_url: str,
+    name: str = "mcpify",
+    auth: AuthConfig | None = None,
+    timeout: float = 30.0,
+) -> None:
+    """Load the spec and block on the stdio loop (the `mcpify serve` entry)."""
+    from .spec import load_spec
+
+    spec = load_spec(spec_path)
+    ApiServer(spec, base_url, server_name=name, auth=auth, timeout=timeout).serve()

mcpify/cli.py

@@ -0,0 +1,238 @@
+"""mcpify command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from typing import NoReturn
+
+from . import __version__
+from .spec import SpecError, iter_operations, load_spec, spec_servers
+from .tools import AuthConfig, spec_to_tools
+
+USE_COLOR = sys.stdout.isatty()
+
+
+def _fail(message: str, code: int = 2) -> NoReturn:
+    print(f"error: {message}", file=sys.stderr)
+    sys.exit(code)
+
+
+def filter_tools(tools: list[dict], args: argparse.Namespace) -> list[dict]:
+    """Apply --tag / --include / --exclude / --read-only / --allow / --deny filters.
+
+    Policy layering, weakest to strongest:
+      1. --read-only keeps GET operations only (a heuristic, not a guarantee).
+      2. --allow PATH_REGEX re-includes operations that --read-only dropped
+         (e.g. read-style POST endpoints).
+      3. --deny PATH_REGEX always excludes, and wins over everything.
+    """
+    include = [p.rstrip("/") for p in (args.include or [])]
+    exclude = [p.rstrip("/") for p in (args.exclude or [])]
+    allow = [re.compile(p) for p in (getattr(args, "allow", None) or [])]
+    deny = [re.compile(p) for p in (getattr(args, "deny", None) or [])]
+
+    def path_matches(path: str, patterns: list[str]) -> bool:
+        return any(path == p or path.startswith(p + "/") for p in patterns)
+
+    def regex_matches(path: str, patterns: list[re.Pattern]) -> bool:
+        return any(p.search(path) for p in patterns)
+
+    kept = []
+    for tool in tools:
+        meta = tool["_meta"]
+        read_only_dropped = args.read_only and meta["method"] != "GET"
+        if read_only_dropped and not regex_matches(meta["path"], allow):
+            continue
+        if args.tag and args.tag not in (meta.get("tags") or []):
+            continue
+        if include and not path_matches(meta["path"], include):
+            continue
+        if exclude and path_matches(meta["path"], exclude):
+            continue
+        if regex_matches(meta["path"], deny):
+            continue
+        kept.append(tool)
+    return kept
+
+
+def _base_url(spec: dict, override: str | None) -> str:
+    if override:
+        return override
+    servers = spec_servers(spec)
+    if servers:
+        return servers[0]
+    _fail(
+        "no base URL: the spec declares no servers and --base-url was not given"
+    )
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="mcpify",
+        description=(
+            "Turn any OpenAPI REST API into an MCP server so AI agents "
+            "(Claude Code, Cursor, ...) can call it — zero dependencies."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_list = sub.add_parser("list", help="preview the tools that would be generated")
+    p_list.add_argument("spec", help="path or URL of an OpenAPI document")
+    p_list.add_argument("--tag", help="only operations with this tag")
+    p_list.add_argument("--include", action="append", help="only these path prefixes (repeatable)")
+    p_list.add_argument("--exclude", action="append", help="skip these path prefixes (repeatable)")
+    p_list.add_argument("--read-only", action="store_true", help="only GET operations")
+    p_list.add_argument("--allow", action="append", metavar="REGEX",
+                        help="re-include operations dropped by --read-only (repeatable)")
+    p_list.add_argument("--deny", action="append", metavar="REGEX",
+                        help="never expose matching paths, overrides --allow (repeatable)")
+    p_list.add_argument("--json", action="store_true", help="machine-readable output")
+
+    p_serve = sub.add_parser("serve", help="start the MCP stdio server")
+    p_serve.add_argument("spec", help="path or URL of an OpenAPI document")
+    p_serve.add_argument("--base-url", help="API base URL (default: spec servers[0])")
+    p_serve.add_argument("--name", default="mcpify", help="server name reported to clients")
+    p_serve.add_argument("--auth-env", help="env variable holding the API credential")
+    p_serve.add_argument(
+        "--auth-style",
+        choices=("bearer", "header", "query"),
+        default="bearer",
+        help="how to send the credential (default: bearer)",
+    )
+    p_serve.add_argument("--auth-name", help="header or query parameter name for non-bearer auth")
+    p_serve.add_argument("--timeout", type=float, default=30.0, help="HTTP timeout seconds")
+    p_serve.add_argument("--tag", help="only operations with this tag")
+    p_serve.add_argument("--include", action="append", help="only these path prefixes (repeatable)")
+    p_serve.add_argument("--exclude", action="append", help="skip these path prefixes (repeatable)")
+    p_serve.add_argument("--read-only", action="store_true", help="expose only GET operations")
+    p_serve.add_argument("--allow", action="append", metavar="REGEX",
+                         help="re-include operations dropped by --read-only (repeatable)")
+    p_serve.add_argument("--deny", action="append", metavar="REGEX",
+                         help="never expose matching paths, overrides --allow (repeatable)")
+
+    p_doctor = sub.add_parser("doctor", help="inspect a spec and report problems")
+    p_doctor.add_argument("spec", help="path or URL of an OpenAPI document")
+
+    args = parser.parse_args(argv)
+
+    if args.command in ("list", "serve"):
+        try:
+            spec = load_spec(args.spec)
+        except SpecError as err:
+            _fail(str(err))
+        all_tools = spec_to_tools(spec)
+        tools = filter_tools(all_tools, args)
+        if not tools:
+            _fail("no operations matched (the API would expose 0 tools)")
+
+    if args.command == "list":
+        if args.json:
+            print(
+                json.dumps(
+                    [
+                        {
+                            "name": t["name"],
+                            "method": t["_meta"]["method"],
+                            "path": t["_meta"]["path"],
+                            "description": t["description"],
+                        }
+                        for t in tools
+                    ],
+                    ensure_ascii=False,
+                    indent=2,
+                )
+            )
+            return
+        def bold(s: str) -> str:
+            return f"\033[1m{s}\033[0m" if USE_COLOR else s
+        def dim(s: str) -> str:
+            return f"\033[2m{s}\033[0m" if USE_COLOR else s
+        def green(s: str) -> str:
+            return f"\033[32m{s}\033[0m" if USE_COLOR else s
+        def cyan(s: str) -> str:
+            return f"\033[36m{s}\033[0m" if USE_COLOR else s
+        print(bold(f"mcpify: {len(tools)} tools from {args.spec}"))
+        print(dim("─" * 78))
+        for tool in tools:
+            meta = tool["_meta"]
+            body = dim(" +body") if meta["has_body"] else ""
+            desc = tool["description"]
+            desc = desc[len(meta["method"]) + 3:] if desc.startswith("[") else desc
+            print(
+                f"  {cyan(tool['name']):36} {green(meta['method']):8} "
+                f"{meta['path']}{body}"
+            )
+            if desc:
+                print(f"  {'':36} {dim(desc[:90])}")
+        print(dim("─" * 78))
+        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]
+        server = ApiServer(
+            spec,
+            base,
+            server_name=args.name,
+            auth=auth,
+            timeout=args.timeout,
+        )
+        server.tools = tools
+        server.by_name = {tool["name"]: tool for tool in tools}
+        print(
+            f"mcpify: serving {len(tools)} tools from {args.spec} -> {base}",
+            file=sys.stderr,
+        )
+        server.serve()
+
+    elif args.command == "doctor":
+        try:
+            spec = load_spec(args.spec)
+        except SpecError as err:
+            _fail(str(err))
+        total = 0
+        missing_id = 0
+        no_summary = 0
+        for _method, _path, operation in iter_operations(spec):
+            total += 1
+            if not operation.get("operationId"):
+                missing_id += 1
+            if not (operation.get("summary") or operation.get("description")):
+                no_summary += 1
+        servers = spec_servers(spec)
+        variabled = [s for s in servers if "{" in s]
+        def ok(s: str) -> str:
+            return f"\033[32m{s}\033[0m" if USE_COLOR else s
+
+        def warn(s: str) -> str:
+            return f"\033[33m{s}\033[0m" if USE_COLOR else s
+
+        print(f"openapi: {spec.get('openapi') or spec.get('swagger')}")
+        print(f"title:   {spec.get('info', {}).get('title', '(untitled)')}")
+        print(f"paths:   {len(spec.get('paths', {}))}")
+        print(f"tools:   {len(spec_to_tools(spec))} operations")
+        print(f"servers: {', '.join(servers) or warn('none declared (pass --base-url)')}")
+        if missing_id:
+            print(warn(f"warning: {missing_id}/{total} operations have no operationId (names fall back to method_path)"))
+        if no_summary:
+            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 not missing_id and not no_summary:
+            print(ok("all operations carry operationId and summary — agent-friendly ✓"))
+
+
+if __name__ == "__main__":
+    main()

mcpify/http_client.py

@@ -0,0 +1,52 @@
+"""Execute built HTTP requests with urllib; never raises on HTTP >= 400."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import urllib.error
+import urllib.request
+
+
+def execute(request: dict, timeout: float = 30.0) -> dict:
+    """Perform the request and return {status, body, json}.
+
+    HTTP errors (4xx/5xx) are returned as results instead of raising, so
+    the agent can see API error payloads and react to them.
+    """
+    data = request.get("body")
+    req = urllib.request.Request(
+        request["url"],
+        data=data,
+        headers=request["headers"],
+        method=request["method"],
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as response:
+            status = response.status
+            raw = response.read().decode("utf-8", "replace")
+    except urllib.error.HTTPError as err:
+        status = err.code
+        raw = err.read().decode("utf-8", "replace")
+    except urllib.error.URLError as err:
+        return {
+            "status": 0,
+            "body": f"connection failed: {err.reason}",
+            "json": None,
+        }
+
+    parsed = None
+    with contextlib.suppress(json.JSONDecodeError, ValueError):
+        parsed = json.loads(raw)
+    return {"status": status, "body": raw, "json": parsed}
+
+
+def format_result(result: dict) -> tuple[str, bool]:
+    """Format an execute() result for an MCP tool response: (text, is_error)."""
+    body = result["body"]
+    if result["json"] is not None:
+        body = json.dumps(result["json"], ensure_ascii=False, indent=2)
+    is_error = result["status"] == 0 or result["status"] >= 400
+    if is_error:
+        return f"HTTP {result['status']}\n{body}", is_error
+    return body, is_error

mcpify/spec.py

@@ -0,0 +1,126 @@
+"""OpenAPI specification loading, $ref resolution, and operation walking.
+
+Supports JSON natively (zero dependencies). YAML specs work when PyYAML
+is installed (``pip install 'mcpify[yaml]'``).
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+HTTP_METHODS = ("get", "put", "post", "delete", "patch", "options", "head")
+
+
+class SpecError(ValueError):
+    """Raised when an OpenAPI document cannot be loaded or is invalid."""
+
+
+def load_spec(source: str) -> dict:
+    """Load an OpenAPI document from a file path or an http(s) URL.
+
+    JSON is always supported; YAML requires PyYAML.
+    """
+    text: str
+    if source.startswith(("http://", "https://")):
+        try:
+            with urllib.request.urlopen(source, timeout=15) as response:
+                text = response.read().decode("utf-8")
+        except Exception as err:
+            raise SpecError(f"could not fetch '{source}': {err}") from err
+    else:
+        path = Path(source)
+        if not path.is_file():
+            raise SpecError(f"file not found: {source}")
+        text = path.read_text(encoding="utf-8")
+
+    # Try JSON first (the common case), fall back to YAML when available.
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        try:
+            import yaml
+        except ImportError:
+            raise SpecError(
+                f"'{source}' is not valid JSON. For YAML specs install: "
+                "pip install 'mcpify[yaml]'"
+            ) from None
+        try:
+            data = yaml.safe_load(text)
+        except Exception as err:
+            raise SpecError(f"could not parse '{source}': {err}") from err
+
+    if not isinstance(data, dict):
+        raise SpecError("specification root must be an object")
+    if "openapi" not in data and "swagger" not in data:
+        raise SpecError(
+            "not an OpenAPI document (missing 'openapi' or 'swagger' version field)"
+        )
+    if not isinstance(data.get("paths"), dict):
+        raise SpecError("specification has no 'paths' object")
+    return data
+
+
+def resolve_ref(spec: dict, ref: str) -> Any:
+    """Resolve a local reference like '#/components/schemas/Pet'."""
+    if not ref.startswith("#/"):
+        raise SpecError(
+            f"only local references are supported (got '{ref}'); "
+            "inline or bundle external documents first"
+        )
+    node = spec
+    for part in ref[2:].split("/"):
+        part = part.replace("~1", "/").replace("~0", "~")
+        try:
+            node = node[part]
+        except (KeyError, TypeError):
+            raise SpecError(f"unresolvable reference: '{ref}'") from None
+    return node
+
+
+def resolve_schema(schema: Any, spec: dict, depth: int = 0) -> Any:
+    """Deeply resolve internal $ref pointers inside a schema."""
+    if depth > 20:
+        raise SpecError("circular $ref chain too deep (max 20)")
+    if isinstance(schema, list):
+        return [resolve_schema(item, spec, depth) for item in schema]
+    if not isinstance(schema, dict):
+        return schema
+
+    if "$ref" in schema:
+        target = resolve_ref(spec, schema["$ref"])
+        return resolve_schema(target, spec, depth + 1)
+
+    resolved = {}
+    for key, value in schema.items():
+        if key == "items" and isinstance(value, dict):
+            resolved[key] = resolve_schema(value, spec, depth + 1)
+        elif key == "properties" and isinstance(value, dict):
+            resolved[key] = {
+                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]
+        else:
+            resolved[key] = value
+    return resolved
+
+
+def iter_operations(spec: dict) -> Iterator[tuple[str, str, dict]]:
+    """Yield (method, path, operation) for every operation in the document."""
+    for path, path_item in spec.get("paths", {}).items():
+        if not isinstance(path_item, dict):
+            continue
+        for method in HTTP_METHODS:
+            operation = path_item.get(method)
+            if isinstance(operation, dict):
+                yield method.upper(), path, operation
+
+
+def spec_servers(spec: dict) -> list[str]:
+    """Return the declared server URLs (may be empty)."""
+    servers = spec.get("servers") or []
+    return [s.get("url", "") for s in servers if isinstance(s, dict)]

mcpify/tools.py

@@ -0,0 +1,274 @@
+"""Translate OpenAPI operations into MCP tools, and arguments into requests."""
+
+from __future__ import annotations
+
+import json
+import re
+from urllib.parse import quote
+
+from .spec import resolve_schema
+
+# Body arguments are exposed under this property name.
+BODY_ARG = "body"
+
+
+def slugify(*parts: str) -> str:
+    text = "_".join(parts).lower()
+    return re.sub(r"[^a-z0-9]+", "_", text).strip("_") or "call"
+
+
+def operation_id(method: str, path: str, operation: dict) -> str:
+    """Prefer the spec's operationId, fall back to method_path."""
+    declared = str(operation.get("operationId", "")).strip()
+    if declared:
+        return slugify(declared)
+    template = re.sub(r"[{}]", "", path)
+    return slugify(method, template)
+
+
+def build_description(method: str, path: str, operation: dict) -> str:
+    text = str(operation.get("summary") or operation.get("description") or "").strip()
+    if text:
+        return f"[{method}] {text}"
+    return f"[{method}] Call {path}"
+
+
+def extract_parameters(operation: dict, path_item: dict, spec: dict) -> list[dict]:
+    """Collect path/query/header parameters from the operation and its path item."""
+    merged: dict[tuple, dict] = {}
+
+    def add(params: list[dict]) -> None:
+        for param in params:
+            if not isinstance(param, dict):
+                continue
+            if "$ref" in param:
+                from .spec import resolve_ref
+
+                param = resolve_ref(spec, param["$ref"])
+            key = (param.get("in"), param.get("name"))
+            merged[key] = param
+
+    add(path_item.get("parameters") or [])
+    add(operation.get("parameters") or [])
+    return list(merged.values())
+
+
+def build_input_schema(
+    method: str,
+    operation: dict,
+    parameters: list[dict],
+    request_schema: dict | None,
+) -> dict:
+    """Build the JSON Schema for an MCP tool from parameters + request body."""
+    properties: dict = {}
+    required: list[str] = []
+
+    for param in parameters:
+        location = param.get("in")
+        if location not in ("path", "query", "header"):
+            continue
+        name = str(param.get("name", ""))
+        if not name:
+            continue
+        schema = resolve_schema(param.get("schema") or {}, {}) 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"]
+        # never advertise a header param for Authorization — auth is managed by flags
+        if location == "header" and name.lower() == "authorization":
+            continue
+        # path/query params are plain names; header params are namespaced
+        key = name if location in ("path", "query") else f"header:{name}"
+        properties[key] = entry
+        if param.get("required"):
+            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 {}),
+        }
+
+    return {"type": "object", "properties": properties, "required": required}
+
+
+def operation_to_tool(method: str, path: str, operation: dict, path_item: dict, spec: dict, taken: set) -> dict:
+    """Return an MCP tool descriptor for one OpenAPI operation."""
+    parameters = extract_parameters(operation, path_item, spec)
+
+    request_schema = 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)
+
+    name = operation_id(method, path, operation)
+    base = name
+    counter = 2
+    while name in taken:
+        name = f"{base}_{counter}"
+        counter += 1
+    taken.add(name)
+
+    return {
+        "name": name,
+        "description": build_description(method, path, operation),
+        "inputSchema": build_input_schema(method.upper(), operation, parameters, request_schema),
+        "_meta": {
+            "method": method.upper(),
+            "path": path,
+            "parameters": parameters,
+            "has_body": request_schema is not None,
+            "tags": list(operation.get("tags") or []),
+        },
+    }
+
+
+def spec_to_tools(spec: dict) -> list[dict]:
+    """Convert every operation in the spec into MCP tool descriptors."""
+    from .spec import iter_operations
+
+    tools: list[dict] = []
+    taken: set = set()
+    for method, path, operation in iter_operations(spec):
+        path_item = spec["paths"][path]
+        tools.append(operation_to_tool(method, path, operation, path_item, spec, taken))
+    return tools
+
+
+# ---------------------------------------------------------------------------
+# request building
+# ---------------------------------------------------------------------------
+
+class RequestError(ValueError):
+    """Raised when arguments cannot form a valid HTTP request."""
+
+
+def build_request(
+    base_url: str,
+    meta: dict,
+    arguments: dict,
+    auth: AuthConfig | None = None,
+) -> dict:
+    """Turn tool arguments into a concrete HTTP request (url/headers/body)."""
+
+    method = meta["method"]
+    path_template = meta["path"]
+    used: set = set()
+
+    # path parameters
+    def substitute(match: re.Match) -> str:
+        name = match.group(1)
+        arg = arguments.get(name)
+        if arg is None or arg == "":
+            raise RequestError(f"missing required path parameter '{name}'")
+        used.add(name)
+        return quote(str(arg), safe="")
+
+    path = re.sub(r"\{([^{}]+)\}", substitute, path_template)
+    if "{" in path or "}" in path:
+        raise RequestError(f"unfilled path parameter in '{path}'")
+
+    # query parameters
+    query_pairs: list[tuple[str, str]] = []
+    for param in meta["parameters"]:
+        if param.get("in") != "query":
+            continue
+        name = str(param.get("name", ""))
+        if name in arguments and arguments[name] not in (None, ""):
+            query_pairs.append((name, str(arguments[name])))
+            used.add(name)
+
+    # header parameters
+    headers = {"Accept": "application/json"}
+    for param in meta["parameters"]:
+        if param.get("in") != "header":
+            continue
+        name = str(param.get("name", ""))
+        key = f"header:{name}"
+        if key in arguments and arguments[key] not in (None, ""):
+            headers[name] = str(arguments[key])
+            used.add(key)
+
+    # body
+    body_bytes = None
+    if meta.get("has_body"):
+        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):
+            raise RequestError(f"'{BODY_ARG}' must be a JSON object")
+        body_bytes = json.dumps(body).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+        used.add(BODY_ARG)
+
+    unknown = sorted(set(arguments) - used)
+    if unknown:
+        raise RequestError(f"unknown argument(s): {', '.join(unknown)}")
+
+    url = base_url.rstrip("/") + path
+    if query_pairs:
+        from urllib.parse import urlencode
+
+        url += "?" + urlencode(query_pairs)
+
+    if auth is not None:
+        headers.update(auth.headers())
+
+    return {"method": method, "url": url, "headers": headers, "body": body_bytes}
+
+
+class AuthConfig:
+    """Authentication injected into outgoing requests from an env variable."""
+
+    def __init__(self, env_var: str, style: str = "bearer", name: str | None = None):
+        self.env_var = env_var
+        self.style = style
+        self.name = name
+
+    def headers(self) -> dict:
+        import os
+
+        value = os.environ.get(self.env_var)
+        if not value:
+            raise RequestError(
+                f"environment variable '{self.env_var}' is not set "
+                "(required for API authentication)"
+            )
+        if self.style == "bearer":
+            return {"Authorization": f"Bearer {value}"}
+        if self.style == "header":
+            return {(self.name or "X-API-Key"): value}
+        return {}  # query style is applied at URL build time
+
+    def apply_query(self, url: str) -> str:
+        if self.style != "query":
+            return url
+        import os
+
+        value = os.environ.get(self.env_var)
+        if not value:
+            raise RequestError(f"environment variable '{self.env_var}' is not set")
+        separator = "&" if "?" in url else "?"
+        return f"{url}{separator}{self.name or 'api_key'}={quote(value)}"
+
+
+def describe_tools(tools: list[dict]) -> str:
+    """One-line-per-tool summary used by `mcpify list`."""
+    lines = []
+    for tool in tools:
+        meta = tool["_meta"]
+        body = " +body" if meta["has_body"] else ""
+        lines.append(
+            f"{tool['name']:34} {meta['method']:7} {meta['path']}{body}  {tool['description'][len(meta['method']) + 3:]}"
+        )
+    return "\n".join(lines)
+
+
+def input_schema_json(schema: dict) -> str:
+    """Compact, stable JSON dump for schemas (without private keys)."""
+    return json.dumps({k: v for k, v in schema.items() if not k.startswith("_")}, ensure_ascii=False)

mcpify_openapi-1.0.0.dist-info/METADATA

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: mcpify-openapi
+Version: 1.0.0
+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
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0.3; extra == "yaml"
+Provides-Extra: dev
+Requires-Dist: pytest>=9.1.1; extra == "dev"
+Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
+Requires-Dist: ruff>=0.16.4; extra == "dev"
+Requires-Dist: mypy>=2.3.1; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: pyyaml>=6.0.3; extra == "dev"
+Dynamic: license-file
+
+# 🔌 mcpify
+
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+🌐 English | [Türkçe](README.tr.md)
+
+<p align="center">
+  <img src="docs/demo.gif" alt="mcpify in action — listing and serving OpenAPI endpoints as MCP tools" width="720">
+</p>
+![Tests](https://img.shields.io/badge/tests-53%20passed-brightgreen)
+[![CI](https://github.com/furkan708/mcpify/actions/workflows/ci.yml/badge.svg)](https://github.com/furkan708/mcpify/actions/workflows/ci.yml) ![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-261230.svg) ![Types: mypy](https://img.shields.io/badge/types-mypy-blue)
+![Dependencies](https://img.shields.io/badge/dependencies-zero-success)
+
+**Turn any OpenAPI REST API into an [MCP](https://modelcontextprotocol.io) server** — so Claude Code, Cursor, and every other MCP client can call your API directly. One command. Zero dependencies.
+
+![mcpify terminal demo](docs/screenshot.png)
+
+Your company has a REST API. Your AI agent needs to call it. Until now that
+meant hand-writing a custom MCP server for every API. With mcpify:
+
+```bash
+mcpify serve https://your-company.com/openapi.json
+```
+
+That's it — every endpoint just became a tool your AI agent can discover, understand, and call.
+
+📖 **Deep docs:** [Usage guide](docs/USAGE.md) — auth patterns, scoping, Docker, troubleshooting · [Architecture](docs/ARCHITECTURE.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md)
+
+## ✨ Why you'll like it
+
+- ⚡ **60 seconds to working** — point it at any OpenAPI 3.x spec (file or URL)
+- 🔐 **Credentials never touch the spec or the model** — pulled from your
+  environment at call time (`--auth-env`), sent as `Authorization: Bearer`,
+  a custom header, or a query parameter
+- 🧰 **Every operation becomes a first-class MCP tool** — input schemas are
+  generated from `parameters` + `requestBody`, internal `$ref`s are resolved
+- 🎚️ **Scope it down** — `--read-only` (GET only), `--tag payments`,
+  `--include /v1/orders`, `--exclude /admin`, plus a policy layer for real-world
+  APIs: `--deny REGEX` hides mutating GETs, `--allow REGEX` re-includes
+  read-style POST endpoints. Deny always wins.
+- 🩺 **`mcpify doctor`** — tells you if your spec is agent-friendly before you ship
+- 🪶 **Zero dependencies** — one pure-Python file tree; YAML specs need an
+  optional `pip install 'mcpify[yaml]'`
+- 🧪 **53 tests** including a full end-to-end suite against a real local HTTP API
+
+## 🚀 Quick start
+
+```bash
+git clone https://github.com/furkan708/mcpify.git
+cd mcpify && pip install .
+
+# 1. preview the tools that will be generated
+mcpify list examples/petstore.json
+
+# 2. validate the spec is agent-friendly
+mcpify doctor examples/petstore.json
+
+# 3. serve it over MCP
+mcpify serve examples/petstore.json --base-url https://petstore.example.com/v1
+```
+
+### With authentication
+
+```bash
+# Bearer token read from the environment (never hardcoded)
+export PETSTORE_KEY="sk-..."
+mcpify serve petstore.json \
+  --base-url https://petstore.example.com/v1 \
+  --auth-env PETSTORE_KEY \
+  --auth-style bearer \
+  --read-only
+```
+
+| Flag | Meaning |
+| ---- | ------- |
+| `--auth-env VAR` | environment variable holding the credential |
+| `--auth-style bearer\|header\|query` | how it is sent |
+| `--auth-name NAME` | header / query name for non-bearer styles (e.g. `X-API-Key`) |
+
+## 🤖 Plug it into your agent
+
+**Claude Code:**
+
+```bash
+claude mcp add my-api -- mcpify serve openapi.json --read-only
+```
+
+**Claude Desktop / Cursor / any MCP client** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "petstore": {
+      "command": "mcpify",
+      "args": ["serve", "~/specs/petstore.json", "--auth-env", "PETSTORE_KEY"]
+    }
+  }
+}
+```
+
+Now ask your agent: *"list the pets, then create one named Milo"* — it discovers `list_pets` and `create_pet`, fills the arguments, and performs real HTTP calls.
+
+## 🔍 How operations become tools
+
+| OpenAPI | mcpify |
+| ------- | ------ |
+| `operationId` | tool name (sanitized; falls back to `method_path`) |
+| `summary` / `description` | tool description the agent reads |
+| `parameters` (path/query/header) | individual typed arguments with enums |
+| `requestBody` (JSON) | a `body` object argument |
+| `$ref` pointers | resolved inline (components → real schemas) |
+| `servers[0].url` | default base URL (override: `--base-url`) |
+
+The agent only ever sees the tool list and your API's JSON responses —
+mcpify adds no middleware, caches nothing, and sends credentials nowhere
+except your API.
+
+## 🩺 Doctor
+
+```bash
+$ mcpify doctor my-api.json
+openapi: 3.0.3
+title:   Acme API
+paths:   23
+tools:   41 operations
+servers: https://api.acme.com
+warning: 12/41 operations have no operationId (names fall back to method_path)
+warning: 30/41 operations have no summary (agents see no description)
+```
+
+## 📖 CLI reference
+
+```
+mcpify list <spec> [--tag T] [--include P] [--exclude P] [--read-only] [--json]
+mcpify serve <spec> [--base-url URL] [--name N] [--auth-env VAR]
+                    [--auth-style bearer|header|query] [--auth-name NAME]
+                    [--timeout S] [--read-only] [--tag T] [--include P] [--exclude P]
+mcpify doctor <spec>
+```
+
+### Notes & limitations
+
+- JSON specs work out of the box; YAML specs need `pip install 'mcpify[yaml]'`
+- Only local `$ref` pointers are resolved (bundle external docs first — most tools do anyway)
+- Request bodies are exposed as a single `body` object argument — predictable over clever
+- Spec versions: OpenAPI 3.x and Swagger 2.x roots are accepted; 3.x is the happy path
+
+## 🧪 Tests
+
+```bash
+pip install pytest pyyaml
+pytest -v
+```
+
+The e2e suite boots a real local HTTP API and drives the full MCP protocol
+over stdio — initialize → tools/list → tools/call — and asserts on the HTTP
+requests that hit the wire.
+
+## 🗂️ Project Structure
+
+```
+mcpify/
+├── mcpify/
+│   ├── spec.py        # OpenAPI loading, $ref resolution, operation walking
+│   ├── tools.py       # operation -> MCP tool, argument -> HTTP request
+│   ├── http_client.py # execution (urllib, HTTP errors become tool results)
+│   ├── api_server.py  # MCP stdio server (JSON-RPC 2.0)
+│   └── cli.py         # list / serve / doctor
+├── examples/petstore.json
+└── tests/
+```
+
+## 🗺️ Roadmap
+
+- [ ] `--output-server FILE` — generate a standalone, shareable server script
+- [ ] Per-operation rate limiting
+- [ ] OAuth2 client-credentials flow
+
+## 📄 License
+
+MIT — see the [LICENSE](LICENSE) file for details.

mcpify_openapi-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+mcpify/__init__.py,sha256=ekCwGO_MK9P57-XSxWwS5P57tvptBNcY-tBZw5WEmuA,431
+mcpify/api_server.py,sha256=ArOdSzAcIVQuS1yo5qx4x2kulaHEVGSW2c5ZFkLYF4Y,5122
+mcpify/cli.py,sha256=vDxXbpqmeBtKr699c4KpmPqy83yRYg47ZcdKf8VS10w,9917
+mcpify/http_client.py,sha256=bP0c4fGoP6j-NTy1m13WdGjM-xmtkDQJHl-0fVFPxlo,1716
+mcpify/spec.py,sha256=aYk5nD0qOm_PiTOWuVpyxbVWBcZ9nVe22OTE_ulLLXE,4512
+mcpify/tools.py,sha256=6E5zPTdp84Kz1ThhWX6Npjv5rlnXXpoNp3_BXO58RoM,9492
+mcpify_openapi-1.0.0.dist-info/licenses/LICENSE,sha256=5cHYZ8MoekInkshb56FPflB05NtsdsbuR-794zZZtpg,1071
+mcpify_openapi-1.0.0.dist-info/METADATA,sha256=L6hI-irZhF6HwrzTVw57Vyjd58TdcgAk3hYUs6hfAQw,7637
+mcpify_openapi-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mcpify_openapi-1.0.0.dist-info/entry_points.txt,sha256=0Fwp_BJIUQ83w1fvqzN7tq9IC-AQoy5fNa4xIE2jyaI,43
+mcpify_openapi-1.0.0.dist-info/top_level.txt,sha256=Ef4ndUJjautEfRkIgRJPfhDvrvjDZRwGXNuzaaQ7fL4,7
+mcpify_openapi-1.0.0.dist-info/RECORD,,

mcpify_openapi-1.0.0.dist-info/WHEEL

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

mcpify_openapi-1.0.0.dist-info/entry_points.txt

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

mcpify_openapi-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Furkan Göktan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcpify_openapi-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcpify