kjaylee/openapi-tool-scaffold

OpenAPI Tool Scaffold

Research → Audit → Rewrite 패턴으로 재작성한 Python 3.10+ 기반 OpenAPI→MCP 생성 스킬.

• 입력: OpenAPI 3.x spec (URL 또는 로컬 JSON/YAML)
• 출력: 실행 가능한 MCP stdio 서버 Python 파일
• 핵심: 각 REST endpoint를 MCP tool로 자동 노출

외부 툴을 blind install 하지 않고, 공개 패턴을 흡수해 내부 재구현.

왜 필요한가?

1. 실제 필요성: 외부 API 통합 시간을 크게 절약
2. 기존 것으로 충분한가?: 기존 mcporter류는 있어도 OpenAPI→MCP 자동 코드 생성은 공백 존재
3. 비용 대비 효과: 추가 SaaS 비용 없이 개발 시간 절감
4. 과대포장 방지: 기존 구현을 그대로 가져오지 않고 패턴만 흡수

포함 파일

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

빠른 시작

# 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 사용법

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

옵션:

• --server-name : MCP 서버 이름 오버라이드
• --base-url : OpenAPI servers보다 우선하는 API base URL
• --template : 서버 템플릿 경로 변경
• --include-deprecated : deprecated operation 포함
• --max-tools N : 생성 tool 수 제한 (0=무제한)

인증 패턴 (생성 서버)

생성된 서버는 OpenAPI components.securitySchemes + operation/global security를 해석해 다음 환경변수를 자동 사용한다.

1) Bearer

• BEARER_TOKEN_<SCHEME_NAME>
• fallback: BEARER_TOKEN

2) API Key

• API_KEY_<SCHEME_NAME>
• fallback: API_KEY
• OpenAPI 정의(in: header/query/cookie, name)에 맞게 자동 주입

3) OAuth (stub)

• OAUTH_ACCESS_TOKEN_<SCHEME_NAME>
• fallback: OAUTH_ACCESS_TOKEN
• 토큰 자동 발급 플로우는 구현하지 않고, 토큰 주입 스텁으로 처리

(추가) Basic auth도 지원:

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

생성되는 MCP 메서드

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

stdio 입력은 newline JSON-RPC를 기본으로 처리하며, Content-Length 프레이밍 입력도 수용한다. 출력은 newline JSON-RPC(기본)이며 MCP_USE_CONTENT_LENGTH=1로 Content-Length 출력 가능.

제한사항

• OpenAPI 3.x만 지원
• 외부 $ref URL dereference는 자동 fetch하지 않음 (로컬 #/... 중심)
• complex serialization(style/explode deepObject)은 기본 매핑 수준으로 처리
• OAuth 자동 리프레시/코드교환은 범위 밖 (stub)

운영 팁

• 민감 endpoint는 OpenAPI 단계에서 별도 spec 분리 권장
• --max-tools로 초기 노출 범위를 좁히고 점진 확장
• 반드시 읽기/쓰기/삭제 endpoint 구분 후 클라이언트 측 승인 정책 추가

Research/Audit 결과

세부 조사 결과는 references/research-audit.md 참고.

핵심 결론:

• 오픈소스는 대부분 TS/Node 또는 특정 플랫폼 편향
• Python 경량/무의존(또는 최소의존) 생성기 수요 존재
• 라이선스는 주로 MIT/Apache-2.0으로 패턴 참조에 적합
• 따라서 내부 Python 재작성 전략이 타당