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"

📋 해결된 문제들

❌ 기존 문제점들

1. 테스트 오류: 'list' object has no attribute 'tools'
2. asyncio 충돌: Already running asyncio in this thread
3. MCP 엔드포인트 404: /mcp 경로 접근 불가
4. 패키지 관리: 느린 pip, 복잡한 가상환경 관리

✅ 해결 방안

1. API 호환성 개선: tools/resources 객체 타입 검사 추가
2. 독립 서버 생성: standalone_mcp_server.py로 asyncio 충돌 해결
3. FastAPI 통합 개선: MCP 정보 엔드포인트 추가
4. 현대적인 도구: 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

🤝 기여하기

1. 저장소를 포크합니다
2. 기능 브랜치를 만듭니다: git checkout -b feature/amazing-feature
3. uv를 사용해 개발 환경을 설정합니다: uv sync --dev
4. 코드 품질 도구를 실행합니다: uv run black . && uv run ruff check .
5. 테스트를 실행합니다: uv run pytest
6. 변경사항을 커밋합니다: git commit -m 'Add amazing feature'
7. 브랜치에 푸시합니다: git push origin feature/amazing-feature
8. Pull Request를 엽니다

📄 라이센스

이 프로젝트는 MIT 라이센스 하에 배포됩니다.

📞 지원

문제가 있거나 질문이 있으시면 이슈를 생성해 주세요.