mcpify-openapi 1.0.0__tar.gz

mcpify_openapi-1.0.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,182 @@
+# 🔌 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/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_openapi-1.0.0/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()