FastMCP OpenAPI 자동 생성 데모
이 프로젝트는 FastMCP를 사용하여 OpenAPI 스펙에서 자동으로 MCP(Model Context Protocol) 서버를 생성하고 Swagger UI를 제공하는 데모입니다.
🌟 주요 기능
- OpenAPI 스펙 자동 변환: OpenAPI 3.0 스펙을 MCP 서버로 자동 변환
- FastAPI 통합: FastAPI 앱을 MCP 서버로 자동 변환
- Swagger UI 제공: 웹 브라우저에서 API 문서 확인 가능
- 자동 테스트: 생성된 MCP 서버의 기능을 자동으로 테스트
- 현대적인 도구: uv, pyproject.toml 사용
🚀 빠른 시작
1. uv 설치 (권장)
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# 또는 pip로 설치
pip install uv
2. 프로젝트 설정
# 프로젝트 클론 및 디렉토리 이동
git clone <repository-url>
cd fastmcp-openapi-demo
# uv로 가상환경 생성 및 의존성 설치
uv sync
# 또는 개발 의존성까지 포함해서 설치
uv sync --dev
3. 데모 실행
# 방법 1: uv run으로 직접 실행
uv run python run_demo.py
# 방법 2: 스크립트 명령어 사용
uv run fastmcp-demo
# 방법 3: 가상환경 활성화 후 실행
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
python run_demo.py
🛠️ 개발 환경 설정
코드 품질 도구
# 코드 포맷팅
uv run black .
# 린팅
uv run ruff check .
uv run ruff check . --fix # 자동 수정
# 타입 체킹
uv run mypy .
# 테스트 실행
uv run pytest
새로운 의존성 추가
# 런타임 의존성 추가
uv add package-name
# 개발 의존성 추가
uv add --dev package-name
# 특정 버전 지정
uv add "fastapi>=0.104.0"
📋 해결된 문제들
❌ 기존 문제점들
- 테스트 오류:
'list' object has no attribute 'tools' - asyncio 충돌:
Already running asyncio in this thread - MCP 엔드포인트 404:
/mcp 경로 접근 불가 - 패키지 관리: 느린 pip, 복잡한 가상환경 관리
✅ 해결 방안
- API 호환성 개선: tools/resources 객체 타입 검사 추가
- 독립 서버 생성:
standalone_mcp_server.py로 asyncio 충돌 해결 - FastAPI 통합 개선: MCP 정보 엔드포인트 추가
- 현대적인 도구: uv 사용으로 빠른 의존성 관리
🌐 웹 인터페이스
FastAPI 서버 실행 후 브라우저에서 다음 URL 접속:
- 메인 페이지: http://localhost:8000
- FastAPI Swagger UI: http://localhost:8000/docs ⭐ 권장
- 커스텀 Swagger UI: http://localhost:8000/swagger
- MCP 정보: http://localhost:8000/mcp/info
- OpenAPI 스펙: http://localhost:8000/openapi.json
📋 파일 구조
.
├── pyproject.toml # 프로젝트 설정 및 의존성
├── .python-version # Python 버전 지정
├── uv.lock # 의존성 잠금 파일 (자동 생성)
├── openapi_mcp_server.py # 메인 MCP 서버 구현
├── standalone_mcp_server.py # 독립 STDIO MCP 서버
├── test_mcp_client.py # MCP 클라이언트 테스트
├── run_demo.py # 데모 실행 스크립트
└── README.md # 이 문서
🔧 구현 방법
1. OpenAPI 스펙에서 MCP 서버 생성
from fastmcp import FastMCP
from fastmcp.server.openapi import RouteMap, MCPType
import httpx
# HTTP 클라이언트 생성
client = httpx.AsyncClient(base_url="https://api.example.com")
# OpenAPI 스펙 로드
openapi_spec = {...} # OpenAPI 3.0 스펙
# MCP 서버 생성
mcp = FastMCP.from_openapi(
openapi_spec=openapi_spec,
client=client,
name="My API Server"
)
# 서버 실행
await mcp.run()
2. FastAPI 앱에서 MCP 서버 생성
from fastapi import FastAPI
from fastmcp import FastMCP
# FastAPI 앱 생성
app = FastAPI()
@app.get("/items")
def get_items():
return [{"id": 1, "name": "Item 1"}]
# FastAPI를 MCP 서버로 변환
mcp = FastMCP.from_fastapi(app=app)
# 서버 실행
await mcp.run()
🧪 테스트
# 모든 테스트 실행
uv run pytest
# 특정 테스트 파일 실행
uv run pytest test_mcp_client.py
# 커버리지 포함 테스트
uv run pytest --cov=. --cov-report=html
🆚 uv vs pip 비교
| 기능 | uv | pip |
|---|
| 속도 | 🚀 10-100배 빠름 | 🐌 느림 |
| 의존성 해결 | ✅ 고급 알고리즘 | ⚠️ 기본적 |
| 가상환경 | ✅ 통합 관리 | ❌ 별도 도구 필요 |
| 잠금 파일 | ✅ uv.lock | ❌ 없음 |
| 크로스 플랫폼 | ✅ 일관된 경험 | ⚠️ 플랫폼별 차이 |
💡 uv 사용 팁
# 프로젝트 초기화
uv init my-project
cd my-project
# Python 버전 설정
uv python pin 3.12
# 의존성 설치 (pyproject.toml 기반)
uv sync
# 스크립트 실행
uv run python script.py
# 패키지 추가/제거
uv add requests
uv remove requests
# 개발 서버 실행
uv run uvicorn app:app --reload
🤝 기여하기
- 저장소를 포크합니다
- 기능 브랜치를 만듭니다:
git checkout -b feature/amazing-feature - uv를 사용해 개발 환경을 설정합니다:
uv sync --dev - 코드 품질 도구를 실행합니다:
uv run black . && uv run ruff check . - 테스트를 실행합니다:
uv run pytest - 변경사항을 커밋합니다:
git commit -m 'Add amazing feature' - 브랜치에 푸시합니다:
git push origin feature/amazing-feature - Pull Request를 엽니다
📄 라이센스
이 프로젝트는 MIT 라이센스 하에 배포됩니다.
📞 지원
문제가 있거나 질문이 있으시면 이슈를 생성해 주세요.