spec2mcp 0.1.0__tar.gz

spec2mcp-0.1.0/.gitignore

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

spec2mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 api2mcp contributors
+
+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.

spec2mcp-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: spec2mcp
+Version: 0.1.0
+Summary: Turn any OpenAPI spec into a working MCP server. One command.
+Project-URL: Homepage, https://github.com/azamoviich/api2mcp
+Project-URL: Repository, https://github.com/azamoviich/api2mcp
+Author: api2mcp contributors
+License: MIT
+License-File: LICENSE
+Keywords: agent,anthropic,claude,codegen,llm,mcp,openapi,tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: serve
+Requires-Dist: mcp>=1.0; extra == 'serve'
+Description-Content-Type: text/markdown
+
+# api2mcp
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](pyproject.toml)
+
+**Turn any OpenAPI spec into a working [MCP](https://modelcontextprotocol.io) server. One command.**
+
+```bash
+api2mcp https://petstore3.swagger.io/api/v3/openapi.json
+```
+
+That's it. You now have a runnable MCP server exposing every endpoint in that API as a tool an LLM agent can call — typed arguments, docstrings, auth wiring, all generated.
+
+---
+
+## The problem
+
+Want Claude (or any MCP-compatible agent) to use Stripe, GitHub, your internal REST API, whatever? Right now that means hand-writing an MCP server: read the docs, define a tool per endpoint, map params, wire up auth, keep it in sync when the API changes.
+
+Almost every API already publishes an OpenAPI/Swagger spec describing exactly that shape. `api2mcp` reads it and generates the server for you.
+
+## Install
+
+```bash
+pip install spec2mcp
+```
+
+(The PyPI package is named `spec2mcp` — `api2mcp` was already taken. The CLI command and import name are still `api2mcp`.)
+
+## Usage
+
+```bash
+api2mcp <spec-url-or-file> [-o output-dir]
+```
+
+Works with a spec URL, a local `.json` file, or a local `.yaml`/`.yml` file.
+
+### Example
+
+```bash
+$ api2mcp https://petstore3.swagger.io/api/v3/openapi.json -o ./petstore-mcp
+Fetching spec from https://petstore3.swagger.io/api/v3/openapi.json ...
+Generated 19 tools for 'Swagger Petstore - OpenAPI 3.0'
+-> petstore-mcp/server.py
+-> petstore-mcp/README.md
+
+Run it:
+  cd petstore-mcp && pip install "mcp[cli]" requests && python server.py
+```
+
+Run the generated server, then point any MCP client at it — Claude Desktop, Claude Code, or your own agent — and every endpoint (`findPetsByStatus`, `addPet`, `deletePet`, …) is now a callable tool.
+
+### Point Claude Desktop / Claude Code at it
+
+Add to your MCP client config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "petstore": {
+      "command": "python",
+      "args": ["/absolute/path/to/petstore-mcp/server.py"],
+      "env": {
+        "API_BASE_URL": "https://petstore3.swagger.io/api/v3",
+        "API_KEY": "your-key-if-needed"
+      }
+    }
+  }
+}
+```
+
+### Auth
+
+Set env vars before running the generated server:
+
+- `API_BASE_URL` — overrides the base URL detected from the spec
+- `API_KEY` — sent as `Authorization: Bearer <API_KEY>` on every request
+
+### Use it as a library instead of the CLI
+
+```python
+from api2mcp import parse_spec, write_server
+
+spec = parse_spec("https://petstore3.swagger.io/api/v3/openapi.json")
+write_server(spec, "./out")
+```
+
+## What gets generated
+
+For every operation in the spec, one `@mcp.tool()`-decorated function:
+
+```python
+@mcp.tool()
+def findpetsbystatus(status: str = "") -> dict:
+    """Finds Pets by status."""
+    ...
+    resp = requests.request("GET", url, params=params, json=json_body, headers=_headers(), timeout=30)
+    resp.raise_for_status()
+    return resp.json()
+```
+
+- Path, query, and JSON body params become typed Python arguments (required params ordered before optional ones, so it's always valid Python)
+- The `summary`/`description` from the spec becomes the tool's docstring — that's what the LLM sees when deciding whether to call it
+- A `README.md` listing every generated tool ships alongside `server.py`
+
+The output is plain, readable code — not a black box. Generate it, read it, edit it by hand if you need something custom.
+
+## How it works
+
+1. **Parse** (`api2mcp/parser.py`) — loads the spec (JSON or YAML, URL or file), walks `paths`, flattens each operation's parameters and request body into a simple typed `Operation` model.
+2. **Generate** (`api2mcp/generator.py` + `templates/server.py.j2`) — renders a Jinja2 template into a single-file MCP server using the official `mcp` Python SDK.
+3. **Run** — the generated server is a normal Python script; `mcp.run()` speaks the MCP protocol over stdio.
+
+No LLM calls involved in generation — it's pure codegen from the spec's structure, so it's fast, free, and deterministic.
+
+## Development
+
+```bash
+git clone https://github.com/azamoviich/api2mcp
+cd api2mcp
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,serve]"
+pytest
+```
+
+## Limitations (v1)
+
+- No OAuth2 flows — only static bearer token auth via `API_KEY`
+- `$ref` resolution for request bodies is shallow (one level)
+- No pagination helpers — generated tools return raw responses as-is
+
+Contributions welcome for any of the above.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

spec2mcp-0.1.0/README.md

@@ -0,0 +1,136 @@
+# api2mcp
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](pyproject.toml)
+
+**Turn any OpenAPI spec into a working [MCP](https://modelcontextprotocol.io) server. One command.**
+
+```bash
+api2mcp https://petstore3.swagger.io/api/v3/openapi.json
+```
+
+That's it. You now have a runnable MCP server exposing every endpoint in that API as a tool an LLM agent can call — typed arguments, docstrings, auth wiring, all generated.
+
+---
+
+## The problem
+
+Want Claude (or any MCP-compatible agent) to use Stripe, GitHub, your internal REST API, whatever? Right now that means hand-writing an MCP server: read the docs, define a tool per endpoint, map params, wire up auth, keep it in sync when the API changes.
+
+Almost every API already publishes an OpenAPI/Swagger spec describing exactly that shape. `api2mcp` reads it and generates the server for you.
+
+## Install
+
+```bash
+pip install spec2mcp
+```
+
+(The PyPI package is named `spec2mcp` — `api2mcp` was already taken. The CLI command and import name are still `api2mcp`.)
+
+## Usage
+
+```bash
+api2mcp <spec-url-or-file> [-o output-dir]
+```
+
+Works with a spec URL, a local `.json` file, or a local `.yaml`/`.yml` file.
+
+### Example
+
+```bash
+$ api2mcp https://petstore3.swagger.io/api/v3/openapi.json -o ./petstore-mcp
+Fetching spec from https://petstore3.swagger.io/api/v3/openapi.json ...
+Generated 19 tools for 'Swagger Petstore - OpenAPI 3.0'
+-> petstore-mcp/server.py
+-> petstore-mcp/README.md
+
+Run it:
+  cd petstore-mcp && pip install "mcp[cli]" requests && python server.py
+```
+
+Run the generated server, then point any MCP client at it — Claude Desktop, Claude Code, or your own agent — and every endpoint (`findPetsByStatus`, `addPet`, `deletePet`, …) is now a callable tool.
+
+### Point Claude Desktop / Claude Code at it
+
+Add to your MCP client config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "petstore": {
+      "command": "python",
+      "args": ["/absolute/path/to/petstore-mcp/server.py"],
+      "env": {
+        "API_BASE_URL": "https://petstore3.swagger.io/api/v3",
+        "API_KEY": "your-key-if-needed"
+      }
+    }
+  }
+}
+```
+
+### Auth
+
+Set env vars before running the generated server:
+
+- `API_BASE_URL` — overrides the base URL detected from the spec
+- `API_KEY` — sent as `Authorization: Bearer <API_KEY>` on every request
+
+### Use it as a library instead of the CLI
+
+```python
+from api2mcp import parse_spec, write_server
+
+spec = parse_spec("https://petstore3.swagger.io/api/v3/openapi.json")
+write_server(spec, "./out")
+```
+
+## What gets generated
+
+For every operation in the spec, one `@mcp.tool()`-decorated function:
+
+```python
+@mcp.tool()
+def findpetsbystatus(status: str = "") -> dict:
+    """Finds Pets by status."""
+    ...
+    resp = requests.request("GET", url, params=params, json=json_body, headers=_headers(), timeout=30)
+    resp.raise_for_status()
+    return resp.json()
+```
+
+- Path, query, and JSON body params become typed Python arguments (required params ordered before optional ones, so it's always valid Python)
+- The `summary`/`description` from the spec becomes the tool's docstring — that's what the LLM sees when deciding whether to call it
+- A `README.md` listing every generated tool ships alongside `server.py`
+
+The output is plain, readable code — not a black box. Generate it, read it, edit it by hand if you need something custom.
+
+## How it works
+
+1. **Parse** (`api2mcp/parser.py`) — loads the spec (JSON or YAML, URL or file), walks `paths`, flattens each operation's parameters and request body into a simple typed `Operation` model.
+2. **Generate** (`api2mcp/generator.py` + `templates/server.py.j2`) — renders a Jinja2 template into a single-file MCP server using the official `mcp` Python SDK.
+3. **Run** — the generated server is a normal Python script; `mcp.run()` speaks the MCP protocol over stdio.
+
+No LLM calls involved in generation — it's pure codegen from the spec's structure, so it's fast, free, and deterministic.
+
+## Development
+
+```bash
+git clone https://github.com/azamoviich/api2mcp
+cd api2mcp
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,serve]"
+pytest
+```
+
+## Limitations (v1)
+
+- No OAuth2 flows — only static bearer token auth via `API_KEY`
+- `$ref` resolution for request bodies is shallow (one level)
+- No pagination helpers — generated tools return raw responses as-is
+
+Contributions welcome for any of the above.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

spec2mcp-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spec2mcp"
+version = "0.1.0"
+description = "Turn any OpenAPI spec into a working MCP server. One command."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "api2mcp contributors" }]
+keywords = ["mcp", "openapi", "llm", "agent", "tools", "codegen", "anthropic", "claude"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Code Generators",
+]
+dependencies = [
+  "requests>=2.28",
+  "PyYAML>=6.0",
+  "Jinja2>=3.1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+serve = ["mcp>=1.0"]  # works with both 1.x (FastMCP) and 2.x (MCPServer) APIs
+
+[project.scripts]
+api2mcp = "api2mcp.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/azamoviich/api2mcp"
+Repository = "https://github.com/azamoviich/api2mcp"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/api2mcp"]

spec2mcp-0.1.0/src/api2mcp/__init__.py

@@ -0,0 +1,5 @@
+from .parser import parse_spec, ApiSpec, Operation, Param
+from .generator import render_server, write_server
+
+__all__ = ["parse_spec", "ApiSpec", "Operation", "Param", "render_server", "write_server"]
+__version__ = "0.1.0"

spec2mcp-0.1.0/src/api2mcp/cli.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .generator import write_server
+from .parser import parse_spec
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="api2mcp",
+        description="Turn any OpenAPI spec into a working MCP server.",
+    )
+    parser.add_argument("source", help="OpenAPI spec URL or local file path (json or yaml)")
+    parser.add_argument("-o", "--out", default="./mcp_server", help="Output directory (default: ./mcp_server)")
+    args = parser.parse_args()
+
+    print(f"Fetching spec from {args.source} ...")
+    try:
+        spec = parse_spec(args.source)
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: failed to parse spec: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    if not spec.operations:
+        print("error: no operations found in spec", file=sys.stderr)
+        sys.exit(1)
+
+    out_file = write_server(spec, args.out)
+    print(f"Generated {len(spec.operations)} tools for '{spec.title}'")
+    print(f"-> {out_file}")
+    print(f"-> {out_file.parent / 'README.md'}")
+    print("\nRun it:")
+    print(f'  cd {args.out} && pip install "mcp[cli]" requests && python server.py')
+
+
+if __name__ == "__main__":
+    main()

spec2mcp-0.1.0/src/api2mcp/generator.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from .parser import ApiSpec
+
+TEMPLATE_DIR = Path(__file__).parent / "templates"
+
+_env = Environment(
+    loader=FileSystemLoader(str(TEMPLATE_DIR)),
+    autoescape=select_autoescape(disabled_extensions=("j2",)),
+    trim_blocks=True,
+    lstrip_blocks=True,
+)
+
+
+def render_server(spec: ApiSpec) -> str:
+    template = _env.get_template("server.py.j2")
+    return template.render(spec=spec)
+
+
+def write_server(spec: ApiSpec, out_dir: str) -> Path:
+    out_path = Path(out_dir)
+    out_path.mkdir(parents=True, exist_ok=True)
+
+    code = render_server(spec)
+    server_file = out_path / "server.py"
+    server_file.write_text(code)
+
+    readme = out_path / "README.md"
+    tool_lines = "\n".join(f"- `{op.func_name}` — {op.summary or (op.method.upper() + ' ' + op.path)}" for op in spec.operations)
+    readme.write_text(
+        f"""# {spec.title} — MCP Server
+
+Generated by [api2mcp](https://github.com/plagueson/api2mcp) from an OpenAPI spec.
+
+## Setup
+
+```bash
+pip install "mcp[cli]" requests
+export API_BASE_URL="{spec.base_url}"
+export API_KEY="your-key-if-needed"
+python server.py
+```
+
+## Tools ({len(spec.operations)})
+
+{tool_lines}
+"""
+    )
+    return server_file

spec2mcp-0.1.0/src/api2mcp/parser.py

@@ -0,0 +1,149 @@
+"""Loads an OpenAPI spec and flattens it into a list of Operation objects."""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from urllib.parse import urlparse
+
+import requests
+import yaml
+
+PY_TYPE_MAP = {
+    "string": "str",
+    "integer": "int",
+    "number": "float",
+    "boolean": "bool",
+    "array": "list",
+    "object": "dict",
+}
+
+
+@dataclass
+class Param:
+    name: str
+    location: str  # "path" | "query" | "header" | "body"
+    py_type: str = "str"
+    required: bool = False
+    description: str = ""
+
+
+@dataclass
+class Operation:
+    op_id: str
+    method: str
+    path: str
+    summary: str = ""
+    params: list[Param] = field(default_factory=list)
+
+    @property
+    def func_name(self) -> str:
+        name = re.sub(r"[^a-zA-Z0-9]+", "_", self.op_id).strip("_").lower()
+        return name or f"{self.method}_{self.path}".lower()
+
+
+@dataclass
+class ApiSpec:
+    title: str
+    base_url: str
+    operations: list[Operation]
+
+
+def _load_raw(source: str) -> dict:
+    parsed = urlparse(source)
+    if parsed.scheme in ("http", "https"):
+        resp = requests.get(source, timeout=15)
+        resp.raise_for_status()
+        text = resp.text
+    else:
+        text = Path(source).read_text()
+
+    text_stripped = text.lstrip()
+    if text_stripped.startswith("{"):
+        return json.loads(text)
+    return yaml.safe_load(text)
+
+
+def _resolve_type(schema: dict | None) -> str:
+    if not schema:
+        return "str"
+    return PY_TYPE_MAP.get(schema.get("type"), "str")
+
+
+def _base_url(raw: dict, source: str) -> str:
+    parsed_source = urlparse(source)
+    source_origin = (
+        f"{parsed_source.scheme}://{parsed_source.netloc}"
+        if parsed_source.scheme in ("http", "https")
+        else None
+    )
+
+    servers = raw.get("servers") or []
+    if servers and servers[0].get("url"):
+        url = servers[0]["url"]
+        if url.startswith("http"):
+            return url
+        if url.startswith("/") and source_origin:
+            return source_origin.rstrip("/") + url
+
+    return source_origin or "http://localhost:8000"
+
+
+def parse_spec(source: str) -> ApiSpec:
+    raw = _load_raw(source)
+    title = (raw.get("info") or {}).get("title", "API")
+    base_url = _base_url(raw, source)
+
+    operations: list[Operation] = []
+    paths = raw.get("paths") or {}
+    for path, methods in paths.items():
+        for method, op in methods.items():
+            if method.lower() not in ("get", "post", "put", "patch", "delete"):
+                continue
+            op_id = op.get("operationId") or f"{method}_{path}"
+            params: list[Param] = []
+
+            for p in op.get("parameters", []):
+                schema = p.get("schema") or {}
+                params.append(
+                    Param(
+                        name=p["name"],
+                        location=p.get("in", "query"),
+                        py_type=_resolve_type(schema),
+                        required=p.get("required", False),
+                        description=p.get("description", ""),
+                    )
+                )
+
+            body = op.get("requestBody")
+            if body:
+                content = body.get("content", {})
+                json_schema = (content.get("application/json") or {}).get("schema", {})
+                props = json_schema.get("properties", {})
+                required_fields = set(json_schema.get("required", []))
+                if props:
+                    for pname, pschema in props.items():
+                        params.append(
+                            Param(
+                                name=pname,
+                                location="body",
+                                py_type=_resolve_type(pschema),
+                                required=pname in required_fields,
+                                description=pschema.get("description", ""),
+                            )
+                        )
+                else:
+                    params.append(Param(name="body", location="body", py_type="dict", required=True))
+
+            operations.append(
+                Operation(
+                    op_id=op_id,
+                    method=method.lower(),
+                    path=path,
+                    summary=op.get("summary", "") or op.get("description", ""),
+                    params=params,
+                )
+            )
+
+    return ApiSpec(title=title, base_url=base_url, operations=operations)

spec2mcp-0.1.0/src/api2mcp/templates/server.py.j2

@@ -0,0 +1,79 @@
+"""
+Auto-generated MCP server for {{ spec.title }}.
+Generated by api2mcp — https://github.com/azamoviich/api2mcp
+
+Run:
+    pip install "mcp[cli]" requests
+    python server.py
+"""
+from __future__ import annotations
+
+import os
+import requests
+
+try:
+    from mcp.server.fastmcp import FastMCP  # mcp < 2.0
+except ImportError:
+    from mcp.server.mcpserver import MCPServer as FastMCP  # mcp >= 2.0
+
+BASE_URL = os.environ.get("API_BASE_URL", "{{ spec.base_url }}")
+API_KEY = os.environ.get("API_KEY", "")
+
+mcp = FastMCP("{{ spec.title }}")
+
+
+def _headers() -> dict:
+    headers = {"Accept": "application/json"}
+    if API_KEY:
+        headers["Authorization"] = f"Bearer {API_KEY}"
+    return headers
+
+{% for op in spec.operations %}
+
+@mcp.tool()
+def {{ op.func_name }}({% set ordered = (op.params | selectattr("required") | list) + (op.params | rejectattr("required") | list) %}{% for p in ordered %}{{ p.name }}: {{ p.py_type }}{% if not p.required %} = {% if p.py_type == 'str' %}""{% elif p.py_type == 'bool' %}False{% elif p.py_type in ('int', 'float') %}0{% else %}None{% endif %}{% endif %}{% if not loop.last %}, {% endif %}{% endfor %}) -> dict:
+    """{{ op.summary or (op.method.upper() ~ " " ~ op.path) }}"""
+    path = "{{ op.path }}"
+{% for p in op.params if p.location == "path" %}
+    path = path.replace("{{ '{' ~ p.name ~ '}' }}", str({{ p.name }}))
+{% endfor %}
+    url = BASE_URL.rstrip("/") + path
+{% set query_params = op.params | selectattr("location", "equalto", "query") | list %}
+{% set body_params = op.params | selectattr("location", "equalto", "body") | list %}
+{% if query_params %}
+    params = {
+{% for p in query_params %}
+        "{{ p.name }}": {{ p.name }},
+{% endfor %}
+    }
+    params = {k: v for k, v in params.items() if v not in (None, "")}
+{% else %}
+    params = None
+{% endif %}
+{% if body_params %}
+    json_body = {
+{% for p in body_params %}
+        "{{ p.name }}": {{ p.name }},
+{% endfor %}
+    }
+{% else %}
+    json_body = None
+{% endif %}
+    resp = requests.request(
+        "{{ op.method.upper() }}",
+        url,
+        params=params,
+        json=json_body,
+        headers=_headers(),
+        timeout=30,
+    )
+    resp.raise_for_status()
+    try:
+        return resp.json()
+    except ValueError:
+        return {"status_code": resp.status_code, "text": resp.text}
+{% endfor %}
+
+
+if __name__ == "__main__":
+    mcp.run()

spec2mcp-0.1.0/tests/test_generator.py

@@ -0,0 +1,54 @@
+import ast
+import json
+
+import pytest
+
+from api2mcp.generator import render_server, write_server
+from api2mcp.parser import parse_spec
+
+SPEC = {
+    "openapi": "3.0.0",
+    "info": {"title": "Order API"},
+    "servers": [{"url": "https://api.example.com"}],
+    "paths": {
+        "/orders/{orderId}": {
+            "delete": {
+                "operationId": "deleteOrder",
+                "parameters": [
+                    {"name": "apiKey", "in": "header", "required": False, "schema": {"type": "string"}},
+                    {"name": "orderId", "in": "path", "required": True, "schema": {"type": "integer"}},
+                ],
+            }
+        }
+    },
+}
+
+
+@pytest.fixture
+def spec_file(tmp_path):
+    p = tmp_path / "spec.json"
+    p.write_text(json.dumps(SPEC))
+    return str(p)
+
+
+def test_generated_code_is_valid_python(spec_file):
+    spec = parse_spec(spec_file)
+    code = render_server(spec)
+    ast.parse(code)  # raises SyntaxError if invalid
+
+
+def test_required_params_ordered_before_optional(spec_file):
+    """Regression: optional param (apiKey) appears before required (orderId) in
+    the raw OpenAPI param list, but Python needs required args first."""
+    spec = parse_spec(spec_file)
+    code = render_server(spec)
+    ast.parse(code)
+    assert "def deleteorder(orderId: int, apiKey: str = \"\")" in code
+
+
+def test_write_server_creates_files(tmp_path, spec_file):
+    spec = parse_spec(spec_file)
+    server_file = write_server(spec, str(tmp_path / "out"))
+    assert server_file.exists()
+    assert (tmp_path / "out" / "README.md").exists()
+    ast.parse(server_file.read_text())

spec2mcp-0.1.0/tests/test_parser.py

@@ -0,0 +1,93 @@
+import json
+import textwrap
+
+import pytest
+
+from api2mcp.parser import parse_spec
+
+SPEC = {
+    "openapi": "3.0.0",
+    "info": {"title": "Test API"},
+    "servers": [{"url": "/v1"}],
+    "paths": {
+        "/pets/{petId}": {
+            "get": {
+                "operationId": "getPet",
+                "summary": "Get a pet",
+                "parameters": [
+                    {"name": "petId", "in": "path", "required": True, "schema": {"type": "integer"}},
+                    {"name": "verbose", "in": "query", "required": False, "schema": {"type": "boolean"}},
+                ],
+            }
+        },
+        "/pets": {
+            "post": {
+                "operationId": "createPet",
+                "requestBody": {
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "type": "object",
+                                "required": ["name"],
+                                "properties": {
+                                    "name": {"type": "string"},
+                                    "age": {"type": "integer"},
+                                },
+                            }
+                        }
+                    }
+                },
+            }
+        },
+    },
+}
+
+
+@pytest.fixture
+def spec_file(tmp_path):
+    p = tmp_path / "spec.json"
+    p.write_text(json.dumps(SPEC))
+    return str(p)
+
+
+def test_parse_spec_basic(spec_file):
+    spec = parse_spec(spec_file)
+    assert spec.title == "Test API"
+    assert len(spec.operations) == 2
+
+
+def test_base_url_joins_relative_server_with_source_origin(monkeypatch, tmp_path):
+    """Regression: a relative `servers[].url` (e.g. "/api/v3") must be joined
+    with the spec source's origin, not silently dropped."""
+    import api2mcp.parser as parser_mod
+
+    monkeypatch.setattr(parser_mod, "_load_raw", lambda source: SPEC)
+    spec = parser_mod.parse_spec("https://example.com/openapi.json")
+    assert spec.base_url == "https://example.com/v1"
+
+
+def test_path_and_query_params(spec_file):
+    spec = parse_spec(spec_file)
+    op = next(o for o in spec.operations if o.op_id == "getPet")
+    assert op.method == "get"
+    locs = {p.name: p.location for p in op.params}
+    assert locs["petId"] == "path"
+    assert locs["verbose"] == "query"
+    required = {p.name: p.required for p in op.params}
+    assert required["petId"] is True
+    assert required["verbose"] is False
+
+
+def test_body_params_flattened(spec_file):
+    spec = parse_spec(spec_file)
+    op = next(o for o in spec.operations if o.op_id == "createPet")
+    body_params = {p.name: p for p in op.params if p.location == "body"}
+    assert body_params["name"].required is True
+    assert body_params["age"].required is False
+    assert body_params["age"].py_type == "int"
+
+
+def test_func_name_sanitized(spec_file):
+    spec = parse_spec(spec_file)
+    op = next(o for o in spec.operations if o.op_id == "getPet")
+    assert op.func_name == "getpet"