openai-swagger-to-mcp (#49)

* openai-swagger-to-mcp

* openai-swagger-to-mcp

* openai-swagger-to-mcp

* openai-swagger-to-mcp

* fix

Author: barnuri

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "monthly"

.gitignore

@@ -19,3 +19,7 @@ test*
 openapiSchemaExample.json
 package-lock.json
 .gitconfig
+tasks.md
+plan.md
+code-review.md
+.playwright-mcp

ReadMe.md

@@ -1,6 +1,71 @@
 # openapi-toolkit
 openapi-toolkit is an open-source tool designed to streamline the integration of OpenAPI (formerly known as Swagger) specifications into your development workflow. By taking an OpenAPI/Swagger file as input, the OpenAPI Toolkit automatically generates server and client code, enabling seamless integration of APIs. This automation accelerates development processes, ensures consistency across different platforms, and reduces the risk of manual errors. Whether you're building a new service or integrating with existing APIs, OpenAPI Toolkit simplifies the process by providing ready-to-use code tailored to your OpenAPI specifications.
 
+# Generate MCP Server
+
+openapi-toolkit generates a fully functional [MCP SDK FastMCP](https://github.com/modelcontextprotocol/python-sdk) server from any OpenAPI/Swagger spec — one MCP tool per API endpoint, grouped by controller, with the async Pydantic v2 client bundled inline.
+
+## Generate
+
+```bash
+# no install required
+npx openapi-toolkit -i https://petstore3.swagger.io/api/v3/openapi.json -g python-mcp-server -t server -o ./my-api-mcp
+
+# or with global install
+npm i -g openapi-toolkit
+openapi-toolkit -i https://petstore3.swagger.io/api/v3/openapi.json -g python-mcp-server -t server -o ./my-api-mcp
+```
+
+Generated layout:
+```
+my-api-mcp/
+  pyproject.toml          # uv project: mcp, httpx, pydantic
+  README.md
+  src/
+    mcp_server.py         # FastMCP entry point, tool registration, transport CLI
+    client/               # generated async httpx + Pydantic v2 client (inline)
+      __init__.py
+      client.py
+      models/
+      controllers/
+    server/
+      tools/
+        <controller>.py   # one file per API controller tag
+```
+
+## Install and run
+
+```bash
+cd my-api-mcp
+uv sync
+BASE_URL=https://api.example.com uv run python src/mcp_server.py
+```
+
+## Transport options
+
+```bash
+# stdio (default — for Claude Desktop and most MCP clients)
+BASE_URL=https://api.example.com uv run python src/mcp_server.py --transport stdio
+
+# SSE
+BASE_URL=https://api.example.com uv run python src/mcp_server.py --transport sse --host 0.0.0.0 --port 8000
+
+# Streamable HTTP
+BASE_URL=https://api.example.com uv run python src/mcp_server.py --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp
+```
+
+A fully generated example (Petstore API) is available in this repo: [examples/pet-store-mcp](https://github.com/barnuri/openapi-toolkit/tree/master/examples/pet-store-mcp)
+
+![pet-store-mcp folder structure](/docs/pet-store-mcp-vscode.png?raw=true)
+
+## Environment variables
+
+| Variable | Description |
+|---|---|
+| `BASE_URL` | Base URL of the target API (required at runtime) |
+| `TOOL_FILTER_ROUTES` | Comma-separated controller names to load (e.g. `pet,store`). Loads all if unset. |
+| `TOOL_FILTER_METHODS` | Comma-separated tool function names to register (e.g. `getPetById,addPet`). Registers all if unset. |
+
 # Install
 
 [![Run Tests](https://github.com/barnuri/openapi-toolkit/actions/workflows/runTests.yaml/badge.svg)](https://github.com/barnuri/openapi-toolkit/actions/workflows/runTests.yaml) [![Create Tag And Release And Publish To NPM](https://github.com/barnuri/openapi-toolkit/actions/workflows/createTagAndReleaseAndPublish.yaml/badge.svg)](https://github.com/barnuri/openapi-toolkit/actions/workflows/createTagAndReleaseAndPublish.yaml)

ex.png docs/ex.pngex.png renamed to docs/ex.png

@@ -38,4 +38,4 @@ const ex = async () = {
 
 ### Result
 
-![Example](https://github.com/barnuri/openapi-toolkit/blob/master/ex.png?raw=true)
+![Example](https://github.com/barnuri/openapi-toolkit/blob/master/docs/ex.png?raw=true)

docs/pet-store-mcp-vscode.png

@@ -0,0 +1,48 @@
+# pet-store-mcp
+
+MCP server generated by [openapi-toolkit](https://github.com/barnuri/openapi-toolkit).
+
+## Install
+
+```bash
+uv sync
+```
+
+## Run
+
+```bash
+# stdio (default — for Claude Desktop and most MCP clients)
+BASE_URL=https://api.example.com uv run python src/mcp_server.py
+
+# SSE
+BASE_URL=https://api.example.com uv run python src/mcp_server.py --transport sse --host 0.0.0.0 --port 8000
+
+# Streamable HTTP
+BASE_URL=https://api.example.com uv run python src/mcp_server.py --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp
+```
+
+## Environment variables
+
+| Variable | Description |
+|---|---|
+| `BASE_URL` | Base URL of the target API (required) |
+| `TOOL_FILTER_ROUTES` | Comma-separated controller names to load (e.g. `pet,store`). Loads all if unset. |
+| `TOOL_FILTER_METHODS` | Comma-separated tool function names to register (e.g. `getPetById,addPet`). Registers all if unset. |
+
+## CLI options
+
+```
+--transport   stdio | sse | streamable-http  (default: stdio)
+--host        host for HTTP transports        (default: 0.0.0.0)
+--port        port for HTTP transports        (default: 8000)
+--path        path for streamable-http        (default: /mcp)
+```
+
+## Project layout
+
+```
+src/
+  mcp_server.py       # entry point — tool registration and transport CLI
+  client/             # async httpx + Pydantic v2 client (generated inline)
+  server/tools/       # one file per API controller
+```

examples/ReadMe.md

@@ -0,0 +1,19 @@
+[project]
+name = "pet-store-mcp"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=1.0",
+    "httpx>=0.27",
+    "pydantic>=2.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/client", "src/server"]
+
+[project.scripts]
+pet-store-mcp = "mcp_server:main"

examples/pet-store-mcp/README.md

@@ -0,0 +1 @@
+from .client import Client