mcpify-cli 0.1.0__tar.gz

mcpify_cli-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.DS_Store

mcpify_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amanpreet Singh
+
+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_cli-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: mcpify-cli
+Version: 0.1.0
+Summary: Turn any OpenAPI/REST API into an MCP server in one command.
+Project-URL: Homepage, https://github.com/Amanbig/mcpify
+Project-URL: Issues, https://github.com/Amanbig/mcpify/issues
+Author: Amanpreet Singh
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude,mcp,model-context-protocol,openapi,rest
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# mcpify
+
+**Turn any REST API into an MCP server in one command.** Point `mcpify` at an OpenAPI
+spec and every endpoint becomes a tool your AI agent (Claude, Cursor, Windsurf, …) can
+call — no glue code, no per-endpoint wrappers.
+
+```bash
+mcpify https://api.example.com/openapi.json
+```
+
+That's it. Every operation in the spec is now a live MCP tool.
+
+---
+
+## Why
+
+[MCP](https://modelcontextprotocol.io) is how AI agents call real tools. But wiring an
+existing API into MCP means hand-writing a tool wrapper for every endpoint — tedious and
+stale the moment the API changes. Almost every API already publishes an **OpenAPI spec**.
+`mcpify` reads that spec and generates the whole MCP server at runtime, so:
+
+- **Zero per-endpoint code** — N endpoints → N tools, automatically.
+- **Always in sync** — regenerate from the spec; no wrappers to maintain.
+- **Auth-aware** — pass an API key / bearer token once, applied to every call.
+
+## Install
+
+```bash
+pipx install mcpify-cli      # or: uvx mcpify-cli ...
+```
+
+## Use
+
+Preview the tools a spec produces (no server):
+
+```bash
+mcpify --list examples/petstore-mini.yaml
+```
+
+Run it as an MCP server (stdio):
+
+```bash
+mcpify https://petstore3.swagger.io/api/v3/openapi.json
+mcpify ./openapi.yaml --base-url https://staging.internal.api
+mcpify ./openapi.yaml --auth "Authorization: Bearer $TOKEN"   # or set MCPIFY_AUTH
+```
+
+### Plug it into Claude
+
+Add to your MCP client config (Claude Desktop / Claude Code `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "petstore": {
+      "command": "mcpify",
+      "args": ["https://petstore3.swagger.io/api/v3/openapi.json"]
+    }
+  }
+}
+```
+
+Restart the client and ask: *"list the available pets"* — Claude calls the API directly.
+
+## How it works
+
+1. Load the OpenAPI 3.x document (URL or file, JSON or YAML).
+2. Walk every path/method into an `Operation` with a generated JSON input schema.
+3. Serve them over MCP; each tool call is mapped to a live HTTP request (path, query,
+   header params and JSON bodies all handled) and the response is returned to the agent.
+
+## Supported
+
+- OpenAPI 3.x, JSON or YAML, from a URL or local file
+- `GET` / `POST` / `PUT` / `PATCH` / `DELETE`
+- Path, query, and header parameters; JSON request bodies
+- A single global auth header (API key or bearer token)
+
+## Roadmap
+
+- Per-operation filtering (`--only`, `--tag`) to expose a subset of a large API
+- `$ref` resolution for fully-expanded body schemas
+- Swagger 2.0 specs
+- SSE / HTTP transport in addition to stdio
+
+PRs welcome.
+
+## License
+
+MIT

mcpify_cli-0.1.0/README.md

@@ -0,0 +1,90 @@
+# mcpify
+
+**Turn any REST API into an MCP server in one command.** Point `mcpify` at an OpenAPI
+spec and every endpoint becomes a tool your AI agent (Claude, Cursor, Windsurf, …) can
+call — no glue code, no per-endpoint wrappers.
+
+```bash
+mcpify https://api.example.com/openapi.json
+```
+
+That's it. Every operation in the spec is now a live MCP tool.
+
+---
+
+## Why
+
+[MCP](https://modelcontextprotocol.io) is how AI agents call real tools. But wiring an
+existing API into MCP means hand-writing a tool wrapper for every endpoint — tedious and
+stale the moment the API changes. Almost every API already publishes an **OpenAPI spec**.
+`mcpify` reads that spec and generates the whole MCP server at runtime, so:
+
+- **Zero per-endpoint code** — N endpoints → N tools, automatically.
+- **Always in sync** — regenerate from the spec; no wrappers to maintain.
+- **Auth-aware** — pass an API key / bearer token once, applied to every call.
+
+## Install
+
+```bash
+pipx install mcpify-cli      # or: uvx mcpify-cli ...
+```
+
+## Use
+
+Preview the tools a spec produces (no server):
+
+```bash
+mcpify --list examples/petstore-mini.yaml
+```
+
+Run it as an MCP server (stdio):
+
+```bash
+mcpify https://petstore3.swagger.io/api/v3/openapi.json
+mcpify ./openapi.yaml --base-url https://staging.internal.api
+mcpify ./openapi.yaml --auth "Authorization: Bearer $TOKEN"   # or set MCPIFY_AUTH
+```
+
+### Plug it into Claude
+
+Add to your MCP client config (Claude Desktop / Claude Code `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "petstore": {
+      "command": "mcpify",
+      "args": ["https://petstore3.swagger.io/api/v3/openapi.json"]
+    }
+  }
+}
+```
+
+Restart the client and ask: *"list the available pets"* — Claude calls the API directly.
+
+## How it works
+
+1. Load the OpenAPI 3.x document (URL or file, JSON or YAML).
+2. Walk every path/method into an `Operation` with a generated JSON input schema.
+3. Serve them over MCP; each tool call is mapped to a live HTTP request (path, query,
+   header params and JSON bodies all handled) and the response is returned to the agent.
+
+## Supported
+
+- OpenAPI 3.x, JSON or YAML, from a URL or local file
+- `GET` / `POST` / `PUT` / `PATCH` / `DELETE`
+- Path, query, and header parameters; JSON request bodies
+- A single global auth header (API key or bearer token)
+
+## Roadmap
+
+- Per-operation filtering (`--only`, `--tag`) to expose a subset of a large API
+- `$ref` resolution for fully-expanded body schemas
+- Swagger 2.0 specs
+- SSE / HTTP transport in addition to stdio
+
+PRs welcome.
+
+## License
+
+MIT

mcpify_cli-0.1.0/examples/petstore-mini.yaml

@@ -0,0 +1,39 @@
+openapi: 3.0.0
+info:
+  title: Mini Petstore
+  version: 1.0.0
+servers:
+  - url: https://petstore.example.com/v1
+paths:
+  /pets:
+    get:
+      operationId: listPets
+      summary: List all pets
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+    post:
+      operationId: createPet
+      summary: Create a pet
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name: { type: string }
+                tag: { type: string }
+  /pets/{petId}:
+    get:
+      operationId: getPet
+      summary: Get a pet by ID
+      parameters:
+        - name: petId
+          in: path
+          required: true
+          schema:
+            type: string

mcpify_cli-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "mcpify-cli"
+version = "0.1.0"
+description = "Turn any OpenAPI/REST API into an MCP server in one command."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Amanpreet Singh" }]
+keywords = ["mcp", "openapi", "rest", "claude", "ai-agents", "model-context-protocol"]
+dependencies = [
+    "mcp>=1.2.0",
+    "httpx>=0.27",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Amanbig/mcpify"
+Issues = "https://github.com/Amanbig/mcpify/issues"
+
+[project.scripts]
+mcpify = "mcpify.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcpify"]

mcpify_cli-0.1.0/src/mcpify/__init__.py

@@ -0,0 +1,7 @@
+"""mcpify — turn any OpenAPI/REST API into an MCP server in one command."""
+
+from .generator import Operation, parse_spec
+from .server import build_server, serve
+
+__version__ = "0.1.0"
+__all__ = ["Operation", "parse_spec", "build_server", "serve", "__version__"]

mcpify_cli-0.1.0/src/mcpify/cli.py

@@ -0,0 +1,59 @@
+"""mcpify command-line interface.
+
+    mcpify <openapi-spec> [--base-url URL] [--auth "Header: value"]
+    mcpify list <openapi-spec>          # preview the tools without serving
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+
+from .generator import parse_spec
+from .server import serve
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mcpify",
+        description="Turn any OpenAPI/REST API into an MCP server in one command.",
+    )
+    parser.add_argument("spec", help="URL or path to an OpenAPI 3.x JSON/YAML document")
+    parser.add_argument("--base-url", help="override the server base URL from the spec")
+    parser.add_argument(
+        "--auth",
+        help='auth header sent with every request, e.g. "Authorization: Bearer XYZ" '
+        "(or set MCPIFY_AUTH)",
+    )
+    parser.add_argument(
+        "--list",
+        action="store_true",
+        help="print the generated tools and exit (no server)",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+
+    if args.list:
+        base_url, operations = parse_spec(args.spec)
+        print(f"Base URL: {base_url}")
+        print(f"Generated {len(operations)} tools:\n")
+        for op in operations:
+            params = ", ".join(op.parameters) or "—"
+            print(f"  • {op.name}  [{op.method.upper()} {op.path}]")
+            print(f"      {op.description}")
+            print(f"      params: {params}")
+        return 0
+
+    try:
+        asyncio.run(serve(args.spec, base_url=args.base_url, auth_header=args.auth))
+    except KeyboardInterrupt:
+        return 0
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mcpify_cli-0.1.0/src/mcpify/generator.py

@@ -0,0 +1,130 @@
+"""Turn an OpenAPI spec into a list of callable MCP tools.
+
+The generator reads an OpenAPI 3.x document, walks every operation, and produces
+one :class:`Operation` per endpoint. Each Operation knows how to build its JSON
+schema (for the MCP tool definition) and how to execute itself as an HTTP request.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urljoin
+
+import httpx
+import yaml
+
+
+@dataclass
+class Operation:
+    """A single API endpoint exposed as an MCP tool."""
+
+    name: str
+    method: str
+    path: str
+    description: str
+    # parameter name -> {"in": "query"|"path"|"header", "schema": {...}, "required": bool}
+    parameters: dict[str, dict[str, Any]] = field(default_factory=dict)
+    request_body_schema: dict[str, Any] | None = None
+
+    def input_schema(self) -> dict[str, Any]:
+        """JSON schema describing this tool's arguments (MCP `inputSchema`)."""
+        properties: dict[str, Any] = {}
+        required: list[str] = []
+        for pname, meta in self.parameters.items():
+            properties[pname] = dict(meta.get("schema") or {"type": "string"})
+            properties[pname].setdefault("description", f"{meta['in']} parameter")
+            if meta.get("required"):
+                required.append(pname)
+        if self.request_body_schema is not None:
+            properties["body"] = self.request_body_schema
+            required.append("body")
+        return {"type": "object", "properties": properties, "required": required}
+
+    def build_request(self, base_url: str, args: dict[str, Any]) -> httpx.Request:
+        """Construct an httpx.Request for this operation from tool arguments."""
+        path = self.path
+        query: dict[str, Any] = {}
+        headers: dict[str, Any] = {}
+        for pname, meta in self.parameters.items():
+            if pname not in args:
+                continue
+            location = meta["in"]
+            value = args[pname]
+            if location == "path":
+                path = path.replace("{" + pname + "}", str(value))
+            elif location == "query":
+                query[pname] = value
+            elif location == "header":
+                headers[pname] = str(value)
+        url = urljoin(base_url.rstrip("/") + "/", path.lstrip("/"))
+        json_body = args.get("body") if self.request_body_schema is not None else None
+        return httpx.Request(
+            self.method.upper(), url, params=query or None, headers=headers or None,
+            json=json_body,
+        )
+
+
+def _load_document(source: str) -> dict[str, Any]:
+    """Load an OpenAPI document from a URL or a local file path."""
+    if source.startswith(("http://", "https://")):
+        text = httpx.get(source, timeout=30, follow_redirects=True).text
+    else:
+        with open(source, encoding="utf-8") as fh:
+            text = fh.read()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return yaml.safe_load(text)
+
+
+def _slug(method: str, path: str) -> str:
+    """Derive a stable, readable tool name from method + path."""
+    parts = [p for p in path.strip("/").split("/") if p]
+    cleaned = [p.strip("{}") for p in parts] or ["root"]
+    return f"{method.lower()}_{'_'.join(cleaned)}".replace("-", "_")
+
+
+def parse_spec(source: str) -> tuple[str, list[Operation]]:
+    """Parse an OpenAPI spec into (base_url, operations).
+
+    :param source: URL or file path to an OpenAPI 3.x JSON/YAML document.
+    :returns: the inferred server base URL and the list of operations.
+    """
+    doc = _load_document(source)
+    servers = doc.get("servers") or [{"url": "/"}]
+    base_url = servers[0].get("url", "/")
+
+    operations: list[Operation] = []
+    for path, path_item in (doc.get("paths") or {}).items():
+        shared_params = path_item.get("parameters", [])
+        for method, op in path_item.items():
+            if method.lower() not in {"get", "post", "put", "patch", "delete"}:
+                continue
+            op = op or {}
+            name = op.get("operationId") or _slug(method, path)
+            description = op.get("summary") or op.get("description") or f"{method.upper()} {path}"
+
+            parameters: dict[str, dict[str, Any]] = {}
+            for param in [*shared_params, *op.get("parameters", [])]:
+                if "name" not in param:
+                    continue
+                parameters[param["name"]] = {
+                    "in": param.get("in", "query"),
+                    "schema": param.get("schema", {"type": "string"}),
+                    "required": param.get("required", param.get("in") == "path"),
+                }
+
+            body_schema = None
+            content = (op.get("requestBody") or {}).get("content", {})
+            if "application/json" in content:
+                body_schema = content["application/json"].get("schema", {"type": "object"})
+
+            operations.append(
+                Operation(
+                    name=name, method=method, path=path, description=description,
+                    parameters=parameters, request_body_schema=body_schema,
+                )
+            )
+    return base_url, operations

mcpify_cli-0.1.0/src/mcpify/server.py

@@ -0,0 +1,72 @@
+"""Run the generated tools as an MCP server over stdio.
+
+Uses the low-level MCP Python SDK so we can register tools dynamically at runtime
+(one per OpenAPI operation) rather than via decorators known at import time.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+import httpx
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+from .generator import Operation, parse_spec
+
+
+def build_server(source: str, base_url: str | None = None, auth_header: str | None = None) -> Server:
+    """Create an MCP Server exposing every operation in the OpenAPI spec as a tool.
+
+    :param source: URL or path to the OpenAPI document.
+    :param base_url: override the server URL inferred from the spec.
+    :param auth_header: optional ``"Header: value"`` sent with every request
+        (defaults to the ``MCPIFY_AUTH`` env var). Useful for API keys / bearer tokens.
+    """
+    inferred_base, operations = parse_spec(source)
+    effective_base = base_url or inferred_base
+    by_name: dict[str, Operation] = {op.name: op for op in operations}
+
+    auth_header = auth_header or os.environ.get("MCPIFY_AUTH")
+    default_headers: dict[str, str] = {}
+    if auth_header and ":" in auth_header:
+        key, _, value = auth_header.partition(":")
+        default_headers[key.strip()] = value.strip()
+
+    server = Server("mcpify")
+
+    @server.list_tools()
+    async def list_tools() -> list[Tool]:
+        return [
+            Tool(name=op.name, description=op.description, inputSchema=op.input_schema())
+            for op in operations
+        ]
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+        op = by_name.get(name)
+        if op is None:
+            return [TextContent(type="text", text=f"Unknown tool: {name}")]
+        request = op.build_request(effective_base, arguments or {})
+        for header, value in default_headers.items():
+            request.headers.setdefault(header, value)
+        async with httpx.AsyncClient(timeout=30, follow_redirects=True) as client:
+            response = await client.send(request)
+        try:
+            payload = json.dumps(response.json(), indent=2)
+        except Exception:
+            payload = response.text
+        prefix = f"HTTP {response.status_code} {request.method} {request.url}\n"
+        return [TextContent(type="text", text=prefix + payload)]
+
+    return server
+
+
+async def serve(source: str, base_url: str | None = None, auth_header: str | None = None) -> None:
+    """Run the MCP server over stdio until the client disconnects."""
+    server = build_server(source, base_url=base_url, auth_header=auth_header)
+    async with stdio_server() as (read, write):
+        await server.run(read, write, server.create_initialization_options())

mcpify_cli-0.1.0/tests/test_generator.py

@@ -0,0 +1,53 @@
+"""Tests for OpenAPI parsing and request building."""
+
+import os
+
+from mcpify.generator import Operation, parse_spec
+
+SPEC = os.path.join(os.path.dirname(__file__), "..", "examples", "petstore-mini.yaml")
+
+
+def test_parse_spec_finds_all_operations():
+    base, ops = parse_spec(SPEC)
+    assert base == "https://petstore.example.com/v1"
+    names = {op.name for op in ops}
+    assert names == {"listPets", "createPet", "getPet"}
+
+
+def test_input_schema_marks_required_path_param():
+    _, ops = parse_spec(SPEC)
+    get_pet = next(op for op in ops if op.name == "getPet")
+    schema = get_pet.input_schema()
+    assert schema["properties"]["petId"]["type"] == "string"
+    assert "petId" in schema["required"]
+
+
+def test_request_body_becomes_required_body_arg():
+    _, ops = parse_spec(SPEC)
+    create = next(op for op in ops if op.name == "createPet")
+    schema = create.input_schema()
+    assert "body" in schema["properties"]
+    assert "body" in schema["required"]
+
+
+def test_build_request_substitutes_path_and_query():
+    op = Operation(
+        name="getPet", method="get", path="/pets/{petId}", description="x",
+        parameters={
+            "petId": {"in": "path", "required": True, "schema": {"type": "string"}},
+            "limit": {"in": "query", "schema": {"type": "integer"}},
+        },
+    )
+    req = op.build_request("https://api.example.com/v1", {"petId": "42", "limit": 5})
+    assert str(req.url) == "https://api.example.com/v1/pets/42?limit=5"
+    assert req.method == "GET"
+
+
+def test_build_request_sends_json_body():
+    op = Operation(
+        name="createPet", method="post", path="/pets", description="x",
+        request_body_schema={"type": "object"},
+    )
+    req = op.build_request("https://api.example.com/v1", {"body": {"name": "Rex"}})
+    assert req.method == "POST"
+    assert b"Rex" in req.content