openapi-tool-scaffold

OpenAPI Tool Scaffold

Rewritten using the Research → Audit → Rewrite pattern: Python 3.10+-based OpenAPI→MCP generation skill.

• Input: OpenAPI 3.x spec (URL or local JSON/YAML)
• Output: executable MCP stdio server Python file
• Core: automatically expose each REST endpoint as an MCP tool

Do not blind install external tools; absorb public patterns and reimplement internally.

Why is it needed?

1. Real need: greatly saves time integrating external APIs
2. Are existing options enough?: even with existing mcporter-like tools, there is a gap for automatic OpenAPI→MCP code generation
3. Cost-effectiveness: reduces development time with no additional SaaS cost
4. Avoiding overhype: does not copy existing implementations as-is, only absorbs patterns

Included files

openapi-tool-scaffold/
├── SKILL.md
├── scripts/
│   └── openapi-to-mcp.py
├── templates/
│   └── mcp_server_stdio.py.tmpl
├── examples/
│   ├── README.md
│   ├── petstore-mcp-server.py
│   ├── todo-mini-openapi.yaml
│   └── todo-mini-mcp-server.py
└── references/
    └── research-audit.md

Quick start

# 1) Petstore OpenAPI -> MCP 서버 코드 생성
python3 skills/openapi-tool-scaffold/scripts/openapi-to-mcp.py \
  "https://petstore3.swagger.io/api/v3/openapi.json" \
  --output skills/openapi-tool-scaffold/examples/petstore-mcp-server.py \
  --server-name petstore_mcp

# 2) 생성 코드 문법 검사
python3 -m py_compile skills/openapi-tool-scaffold/examples/petstore-mcp-server.py

# 3) MCP 서버 실행 (stdio)
python3 skills/openapi-tool-scaffold/examples/petstore-mcp-server.py

CLI usage

python3 scripts/openapi-to-mcp.py INPUT --output OUTPUT.py [options]

Options:

• --server-name : override MCP server name
• --base-url : API base URL that takes precedence over OpenAPI servers
• --template : change server template path
• --include-deprecated : include deprecated operations
• --max-tools N : limit the number of generated tools (0=unlimited)

Auth patterns (generated server)

The generated server parses the OpenAPI components.securitySchemes + operation/global securityand automatically uses the following environment variables.

1) Bearer

• BEARER_TOKEN_<SCHEME_NAME>
• fallback: BEARER_TOKEN

2) API Key

• API_KEY_<SCHEME_NAME>
• fallback: API_KEY
• OpenAPI definition (in: header/query/cookie, name) automatically injected accordingly

3) OAuth (stub)

• OAUTH_ACCESS_TOKEN_<SCHEME_NAME>
• fallback: OAUTH_ACCESS_TOKEN
• The automatic token issuance flow is not implemented; handled with a token injection stubprocessed as

(Additional) Basic auth is also supported:

• BASIC_USERNAME_<SCHEME_NAME>, BASIC_PASSWORD_<SCHEME_NAME>
• fallback: BASIC_USERNAME, BASIC_PASSWORD

Generated MCP methods

• initialize
• tools/list
• tools/call
• ping

stdio input handles newline JSON-RPC by default, and also accepts Content-Length framed input. Output is newline JSON-RPC (default), and MCP_USE_CONTENT_LENGTH=1enables Content-Length output.

Limitations

• OpenAPI 3.x만 support
• External $ref URL dereference is not automatically fetched (focuses on local #/... )
• complex serialization (style/explode deepObject) is handled at the basic mapping level
• OAuth automatic refresh/code exchange is out of scope (stub)

Operational tips

• For sensitive endpoints, it is recommended to separate them into a separate spec at the OpenAPI stage
• --max-toolsto narrow the initial exposure scope and expand gradually
• Be sure to distinguish read/write/delete endpoints and then add a client-side approval policy

Research/Audit results

For detailed investigation results, see references/research-audit.md .

Key conclusions:

• Most open source is TS/Node or biased toward specific platforms
• There is demand for a lightweight/zero-dependency (or minimal-dependency) Python generator
• Licenses are mostly MIT/Apache-2.0, suitable for pattern reference
• Therefore, an internal Python rewrite strategy is valid