shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 开发与工程无需 API Key

openapi-tool-scaffold

将OpenAPI 3.x (JSON/YAML) 规范自动转换为MCP stdio服务器（Python）代码的技能。用于通过MCP工具快速桥接外部REST API。支持认证（Bearer, API Key, OAuth stub），并能为每个endpoint自动生成工具。触发器：OpenAPI→MCP转换，外部API与MCP集成，REST API工具自动化，Python MCP脚手架。

person作者: jakexiaohubgithub
open_in_new仓库download下载资源包

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 재작성 전략이 타당