FastMCP OpenAPI Demo

# 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 라이센스 하에 배포됩니다. ## 📞 지원 문제가 있거나 질문이 있으시면 이슈를 생성해 주세요.