|
| 1 | +# openapi-mcp-ts |
| 2 | + |
| 3 | +Universal bridge between REST APIs and AI assistants via Model Context Protocol. |
| 4 | + |
| 5 | +## What It Does |
| 6 | +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. |
| 7 | + |
| 8 | +## Why It Exists |
| 9 | +- **Zero friction** — Point at a spec, get MCP tools |
| 10 | +- **Format agnostic** — OpenAPI 3.0/3.1, Postman v2.0/v2.1, auto-detected |
| 11 | +- **Production ready** — Auth, filtering, rate limiting awareness, structured logging |
| 12 | +- **Safe defaults** — DELETE disabled, tool count warnings, smart error messages |
| 13 | + |
| 14 | +## Tech Stack |
| 15 | +| Component | Technology | |
| 16 | +|-----------|------------| |
| 17 | +| Runtime | Node.js 20+ (ESM) | |
| 18 | +| Language | TypeScript (strict mode) | |
| 19 | +| HTTP Server | Hono | |
| 20 | +| MCP Protocol | @modelcontextprotocol/sdk | |
| 21 | +| CLI | Commander | |
| 22 | +| Validation | Zod | |
| 23 | +| OpenAPI Parsing | @apidevtools/swagger-parser | |
| 24 | +| Postman Parsing | postman-collection | |
| 25 | +| Logging | Pino | |
| 26 | + |
| 27 | +## Architecture |
| 28 | +``` |
| 29 | +┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐ |
| 30 | +│ OpenAPI/Postman │ ──▶ │ Converter │ ──▶ │ MCP Tools │ |
| 31 | +│ Spec │ │ (parser.ts) │ │ (definitions) │ |
| 32 | +└─────────────────┘ └──────────────┘ └────────┬────────┘ |
| 33 | + │ |
| 34 | +┌─────────────────┐ ┌──────────────┐ │ |
| 35 | +│ MCP Client │ ◀── │ MCP Handler │ ◀────────────┘ |
| 36 | +│ (Claude, etc) │ │ (Hono SSE) │ |
| 37 | +└─────────────────┘ └──────┬───────┘ |
| 38 | + │ |
| 39 | + ┌──────▼───────┐ ┌─────────────────┐ |
| 40 | + │ Upstream │ ──▶ │ Target API │ |
| 41 | + │ Proxy │ │ │ |
| 42 | + └──────────────┘ └─────────────────┘ |
| 43 | +``` |
| 44 | + |
| 45 | +## Project Structure |
| 46 | +``` |
| 47 | +src/ |
| 48 | +├── index.ts # Entry point, server startup |
| 49 | +├── cli.ts # CLI argument parsing (Commander) |
| 50 | +├── config/ |
| 51 | +│ └── loader.ts # Config from CLI/env/file, Zod validation |
| 52 | +├── converter/ |
| 53 | +│ ├── parser.ts # OpenAPI/Postman → internal format |
| 54 | +│ ├── postman-parser.ts # Postman Collection v2.x support |
| 55 | +│ └── tool-filter.ts # Include/exclude patterns, warnings |
| 56 | +├── mcp/ |
| 57 | +│ ├── handler.ts # MCP protocol, tool execution |
| 58 | +│ └── types.ts # MCP tool definitions |
| 59 | +├── server/ |
| 60 | +│ ├── routes.ts # /health, /tools, /mcp endpoints |
| 61 | +│ └── upstream.ts # Proxy requests to target API |
| 62 | +└── utils/ |
| 63 | + └── logger.ts # Pino logger setup |
| 64 | +``` |
| 65 | + |
| 66 | +## Commands |
| 67 | +```bash |
| 68 | +npm run dev # Development with tsx watch |
| 69 | +npm run build # Compile to dist/ |
| 70 | +npm run start # Run compiled code |
| 71 | +npm run typecheck # Type check only |
| 72 | +npm run lint # ESLint |
| 73 | +``` |
| 74 | + |
| 75 | +## Release Workflow |
| 76 | + |
| 77 | +Automatic Docker Hub builds via GitHub Actions on push to master. |
| 78 | + |
| 79 | +**Create new version:** |
| 80 | +```bash |
| 81 | +# 1. Update version in package.json |
| 82 | +npm version 1.0.1 --no-git-tag-version |
| 83 | + |
| 84 | +# 2. Commit the change |
| 85 | +git add package.json |
| 86 | +git commit -m "Bump version to 1.0.1" |
| 87 | + |
| 88 | +# 3. Create and push tag |
| 89 | +git tag v1.0.1 |
| 90 | +git push origin master --tags |
| 91 | +``` |
| 92 | + |
| 93 | +Creates Docker tags: `1.0.1`, `1.0`, `latest` |
| 94 | + |
| 95 | +### Keep versions in sync |
| 96 | +- Git tag `v1.0.1` = package.json `1.0.1` |
| 97 | +- `--version` reads from package.json |
| 98 | +- Docker tags derived from git tags |
| 99 | + |
| 100 | +## Testing |
| 101 | +```bash |
| 102 | +# OpenAPI |
| 103 | +npm run dev -- --spec-url https://petstore3.swagger.io/api/v3/openapi.json \ |
| 104 | + --upstream-url https://petstore3.swagger.io/api/v3 |
| 105 | + |
| 106 | +# Postman |
| 107 | +npm run dev -- --spec-file ./collection.json --format postman \ |
| 108 | + --upstream-url https://api.example.com |
| 109 | + |
| 110 | +# Verify |
| 111 | +curl http://localhost:8080/health |
| 112 | +curl http://localhost:8080/tools | jq |
| 113 | +``` |
| 114 | + |
| 115 | +## Tool Count Thresholds |
| 116 | +| Count | Behavior | |
| 117 | +|-------|----------| |
| 118 | +| ≤10 | Normal | |
| 119 | +| 11-40 | Warning | |
| 120 | +| 41-100 | Strong warning | |
| 121 | +| >100 | Error, refuses to start | |
| 122 | + |
| 123 | +Use `--include-tools "get_*"` or `--exclude-tools "*_admin_*"` to filter. |
| 124 | + |
| 125 | +## Links |
| 126 | +- Docker Hub: https://hub.docker.com/r/procoders/openapi-mcp-ts |
| 127 | +- GitHub: https://github.com/procoders/openapi-mcp-ts |
| 128 | +- MCPize (hosted): https://mcpize.com |
0 commit comments