OpenAPI to MCP

# openapi-mcp-ts Universal bridge between REST APIs and AI assistants via Model Context Protocol. ## What It Does Takes an OpenAPI spec or Postman Collection and exposes every endpoint as an MCP tool. Claude (or any MCP client) can then call your API directly — no custom code, no manual tool definitions. ## Why It Exists - **Zero friction** — Point at a spec, get MCP tools - **Format agnostic** — OpenAPI 3.0/3.1, Postman v2.0/v2.1, auto-detected - **Production ready** — Auth, filtering, rate limiting awareness, structured logging - **Safe defaults** — DELETE disabled, tool count warnings, smart error messages ## Tech Stack | Component | Technology | |-----------|------------| | Runtime | Node.js 20+ (ESM) | | Language | TypeScript (strict mode) | | HTTP Server | Hono | | MCP Protocol | @modelcontextprotocol/sdk | | CLI | Commander | | Validation | Zod | | OpenAPI Parsing | @apidevtools/swagger-parser | | Postman Parsing | postman-collection | | Logging | Pino | ## Architecture ``` ┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐ │ OpenAPI/Postman │ ──▶ │ Converter │ ──▶ │ MCP Tools │ │ Spec │ │ (parser.ts) │ │ (definitions) │ └─────────────────┘ └──────────────┘ └────────┬────────┘ │ ┌─────────────────┐ ┌──────────────┐ │ │ MCP Client │ ◀── │ MCP Handler │ ◀────────────┘ │ (Claude, etc) │ │ (Hono SSE) │ └─────────────────┘ └──────┬───────┘ │ ┌──────▼───────┐ ┌─────────────────┐ │ Upstream │ ──▶ │ Target API │ │ Proxy │ │ │ └──────────────┘ └─────────────────┘ ``` ## Project Structure ``` src/ ├── index.ts # Entry point, server startup ├── cli.ts # CLI argument parsing (Commander) ├── config/ │ └── loader.ts # Config from CLI/env/file, Zod validation ├── converter/ │ ├── parser.ts # OpenAPI/Postman → internal format │ ├── postman-parser.ts # Postman Collection v2.x support │ └── tool-filter.ts # Include/exclude patterns, warnings ├── mcp/ │ ├── handler.ts # MCP protocol, tool execution │ └── types.ts # MCP tool definitions ├── server/ │ ├── routes.ts # /health, /tools, /mcp endpoints │ └── upstream.ts # Proxy requests to target API └── utils/ └── logger.ts # Pino logger setup ``` ## Commands ```bash npm run dev # Development with tsx watch npm run build # Compile to dist/ npm run start # Run compiled code npm run typecheck # Type check only npm run lint # ESLint ``` ## Release Workflow Automatic Docker Hub builds via GitHub Actions on push to master. **Create new version:** ```bash # 1. Update version in package.json npm version 1.0.1 --no-git-tag-version # 2. Commit the change git add package.json git commit -m "Bump version to 1.0.1" # 3. Create and push tag git tag v1.0.1 git push origin master --tags ``` Creates Docker tags: `1.0.1`, `1.0`, `latest` ### Keep versions in sync - Git tag `v1.0.1` = package.json `1.0.1` - `--version` reads from package.json - Docker tags derived from git tags ## Testing ```bash # OpenAPI npm run dev -- --spec-url https://petstore3.swagger.io/api/v3/openapi.json \ --upstream-url https://petstore3.swagger.io/api/v3 # Postman npm run dev -- --spec-file ./collection.json --format postman \ --upstream-url https://api.example.com # Verify curl http://localhost:8080/health curl http://localhost:8080/tools | jq ``` ## Tool Count Thresholds | Count | Behavior | |-------|----------| | ≤10 | Normal | | 11-40 | Warning | | 41-100 | Strong warning | | >100 | Error, refuses to start | Use `--include-tools "get_*"` or `--exclude-tools "*_admin_*"` to filter. ## Links - Docker Hub: https://hub.docker.com/r/procoders/openapi-mcp-ts - GitHub: https://github.com/procoders/openapi-mcp-ts - MCPize (hosted): https://mcpize.com