# 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 설치 (권장)
```bash
# 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. 프로젝트 설정
```bash
# 프로젝트 클론 및 디렉토리 이동
git clone <repository-url>
cd fastmcp-openapi-demo
# uv로 가상환경 생성 및 의존성 설치
uv sync
# 또는 개발 의존성까지 포함해서 설치
uv sync --dev
```
### 3. 데모 실행
```bash
# 방법 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
```
## 🛠️ 개발 환경 설정
### 코드 품질 도구
```bash
# 코드 포맷팅
uv run black .
# 린팅
uv run ruff check .
uv run ruff check . --fix # 자동 수정
# 타입 체킹
uv run mypy .
# 테스트 실행
uv run pytest
```
### 새로운 의존성 추가
```bash
# 런타임 의존성 추가
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 서버 생성
```python
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 서버 생성
```python
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()
```
## 🧪 테스트
```bash
# 모든 테스트 실행
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 사용 팁
```bash
# 프로젝트 초기화
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 라이센스 하에 배포됩니다.
## 📞 지원
문제가 있거나 질문이 있으시면 이슈를 생성해 주세요.
