openapi-mcp-generator

OpenAPI 명세(specifications)를 완전히 기능하는 Model Context Protocol (MCP) 서버로 자동 변환하는 Python 도구입니다. SSE/IO 통신 프로토콜, 인증(authentication), 그리고 포괄적인 에러 처리(error handling)를 지원하며 Docker에서 즉시 실행 가능한 구현체를 생성합니다.

• 🔄 OpenAPI를 MCP 도구(tools)/리소스(resources)로 변환
• 🐳 멀티 스테이지 빌드(multi-stage builds)를 지원하는 Docker 준비 완료
• 🔐 다양한 인증 방식 지원
• ⚡ 비동기 작업(Async operations) 및 속도 제한(rate limiting)
• 📡 SSE/IO 통신 프로토콜
• 📦 패키지 지원을 포함한 모듈형 코드 구조

이 생성기(generator)는 하위 호환성을 유지하면서 적절한 Python 패키지로 리팩터링(refactored)되었습니다:

기존 진입점(Original Entry Point): generator.py 스크립트는 이전과 동일하게 작동합니다
모듈형 구성(Modular Organization): 코드가 이제 집중된 모듈들로 분리되었습니다
패키지 설치(Package Installation): 적절한 Python 패키지로 설치할 수 있습니다
동일한 템플릿(Same Templates): /templates 디렉토리 내의 정확히 동일한 템플릿을 사용합니다
Docker 지원(Docker Support): 모든 Docker 기능을 보존합니다

원하는 방식에 따라 도구를 사용할 수 있습니다:

• generator.py를 직접 실행 (기존 방식)
• 패키지로 설치하여 mcp-generator 명령 사용
• 본인의 Python 코드에서 모듈을 프로그래밍 방식으로 사용

모듈형 코드 구조에 대한 자세한 내용은 MODULAR_REFACTORING.md를 참조하세요.

• OpenAPI 명세를 MCP 서버로 변환

• 멀티 스테이지 빌드를 포함한 Docker 준비 완료 구현체

• 다양한 인증 방식 지원

• SSE 또는 IO 통신 프로토콜 선택 가능

• 포괄적인 에러 처리 및 로깅(logging)

• 내장된 속도 제한(rate limiting) 및 보안 기능

• 최적의 성능을 위한 비동기 작업(Async operations)

• 커버리지 보고(coverage reporting)를 포함한 광범위한 테스트 스위트(test suite)

• Python 3.10+

• Docker (생성된 서버 실행용)

• pip 또는 uv (Python 패키지 관리자)

# 저장소 복제(Clone)
git clone https://github.com/abutbul/openapi-mcp-generator.git
cd openapi-mcp-generator
...

pip install openapi-mcp-generator

# 기존 스크립트 사용 (동일한 방식으로 작동함)
python generator.py openapi.yaml --output-dir ./output --api-url https://api.example.com
# 설치 후 새로운 모듈형 CLI 도구 사용
...

openapi_file
: OpenAPI YAML 파일 경로 (필수)

--output-dir
: 생성된 프로젝트의 출력 디렉토리 (기본값: '.')

--api-url
: API의 베이스 URL (Base URL)

--auth-type
: 인증 유형 (bearer, token, basic)

--api-token
: 인증을 위한 API 토큰

--api-username
: Basic 인증을 위한 사용자 이름

--api-password
: Basic 인증을 위한 비밀번호

서버를 생성한 후에는 Docker를 사용하여 빌드하고 실행할 수 있습니다:

cd output/openapi-mcp-*
./docker.sh build
./docker.sh start --transport=sse --port=8000

생성된 docker.sh 스크립트는 다음 명령어를 지원합니다:

build
: Docker 이미지 빌드

start
: 컨테이너 시작

--port=PORT
: 포트 설정 (기본값: 8000)

--transport=TYPE
: 전송 유형 (transport type) 설정: 'sse' 또는 'io' (기본값: sse)

--log-level=LEVEL
: 로깅 레벨 (logging level) 설정 (기본값: info)

stop
: 컨테이너 중지

clean
: 컨테이너 및 이미지 삭제

logs
: 컨테이너 로그 확인

모듈형 생성기 (modular generator)는 다음과 같은 구조를 가집니다:

openapi-mcp-generator/
├── generator.py # 기존 진입점 (하위 호환성을 위해 유지됨)
├── mcp_generator.py # 새로운 진입점 (모듈형 구조 사용)
...

모듈형 구조는 기존의 모든 기능을 보존하면서 코드를 더 유지보수하기 쉽게 만듭니다:

• 기존 진입점(generator.py)을 이전과 같이 여전히 사용할 수 있습니다.
• /templates에 있는 기존 템플릿들이 새로운 모듈형 코드에 의해 사용됩니다.
• 모든 Docker 관련 기능이 기존과 정확히 동일하게 보존됩니다.
• 이제 프로젝트를 정식 Python 패키지로 설치할 수 있습니다.

생성기가 실제로 작동하는 모습을 확인하려면 우리의 샘플 구현 사례를 살펴보세요:

• Trilium Notes ETAPI Server - Trilium Notes 지식 관리 시스템의 ETAPI를 위한 MCP 서버

• 저장소 포크 (Fork the repository)

• 기능 브랜치 (feature branch) 생성

• 변경 사항 적용

• 테스트 스위트 (test suite) 실행

• 풀 리퀘스트 (pull request) 제출

이 프로젝트는 MIT License 라이선스 하에 배포됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

Elasticsearch 6.1 스펙 폴더로부터 MCP 서버를 생성하려면:

# 원본 스크립트를 직접 실행
python generator.py samples/elasticsearch_6.1/api
# 또는 모듈형 엔트리 포인트 (modular entry point) 사용
...

먼저, 패키지를 설치하세요 (프로젝트 루트에서):

pip install .

그 다음 CLI 도구를 사용하여 Trilium ETAPI 스펙을 변환하세요:

mcp-generator samples/TriliumNext/etapi.openapi.yaml

또는 본인의 Python 코드에서 프로그래밍 방식으로 사용할 수 있습니다:

from openapi_mcp_generator import generator
generator.generate('samples/TriliumNext/etapi.openapi.yaml')