FastAPI + MCP Template
현대적인 API 서버와 MCP(Model Context Protocol) 통합 템플릿
FastAPI와 MCP를 활용한 프로덕션 수준의 API 서버 템플릿입니다. LLM 통합, 구조화된 로깅, 포괄적인 테스트, 그리고 최고의 개발자 경험을 제공합니다.
✨ 주요 특징
🚀 프로덕션 수준의 API 서버
- 현대적인 FastAPI: 자동 API 문서화, 타입 안전성, 고성능
- Scalar 문서화: 아름답고 대화형 API 문서
- 구조화된 로깅: 색상 지원, 파일 로테이션, 요청 추적
- 포괄적인 예외 처리: 타입별 커스텀 예외 및 상세한 오류 정보
- Dependency Injection: FastAPI DI 패턴으로 깔끔한 코드 구조
🤖 MCP 서버 통합
- FastMCP 구현: 최신 Model Context Protocol 표준
- SSE 통신: 실시간 Server-Sent Events 연결
- 도구 및 리소스: LLM이 활용할 수 있는 다양한 도구
- 확장 가능: 새로운 MCP 기능 쉽게 추가
🛡️ 보안 및 설정
- 환경별 설정: 개발, 테스트, 프로덕션 환경 지원
- 보안 기본값: 자동 시크릿 키 생성, CORS 보안 설정
- 환경변수 관리: .env 파일 지원 및 완전한 설정 검증
🧪 완전한 테스트 커버리지
- 단위 테스트: MCP 도구 및 API 엔드포인트
- 통합 테스트: 전체 시스템 엔드투엔드 테스트
- 동시성 테스트: 멀티스레드 및 성능 테스트
📁 프로젝트 구조
coupang-partners-api/
├── 🏗️ 소스 코드
│ ├── src/
│ │ ├── core/ # 🔧 핵심 모듈
│ │ │ ├── config.py # ⚙️ 환경별 설정 관리
│ │ │ ├── logging.py # 📝 구조화된 로깅 시스템
│ │ │ ├── exceptions.py # ⚠️ 커스텀 예외 처리
│ │ │ ├── dependencies.py # 🔗 의존성 주입 패턴
│ │ │ ├── database.py # 💾 데이터베이스 추상화
│ │ │ └── models.py # 📋 Pydantic 모델
│ │ ├── api/ # 🌐 FastAPI 애플리케이션
│ │ │ ├── app.py # 🚀 메인 애플리케이션
│ │ │ └── routers/ # 🛣️ API 라우터
│ │ ├── mcp_server/ # 🤖 MCP 서버
│ │ │ ├── server.py # 🖥️ MCP 서버 구현
│ │ │ ├── tools.py # 🔨 MCP 도구
│ │ │ └── resources.py # 📦 MCP 리소스
│ │ └── templates/ # 📄 템플릿 파일
│ ├── 🧪 테스트
│ │ ├── tests/
│ │ │ ├── test_api.py # 🌐 API 테스트
│ │ │ ├── test_mcp.py # 🤖 MCP 테스트
│ │ │ └── test_integration.py # 🔄 통합 테스트
│ ├── 📚 예시 및 문서
│ │ ├── examples/ # 💡 사용 예시
│ │ └── docs/ # 📖 문서
│ └── 🐳 배포
│ ├── Dockerfile # 🐳 Docker 이미지
│ ├── docker-compose.yml # 🐙 Docker Compose
│ └── .dockerignore # 🚫 Docker 제외 파일
├── ⚡ 실행 스크립트
│ ├── run_server.py # 🚀 통합 서버 실행
│ ├── run_api_server.py # 🌐 API 서버 실행
│ ├── run_mcp_server.py # 🤖 MCP 서버 실행
│ └── run_docker.py # 🐳 Docker 실행 도구
├── 🔧 설정 파일
│ ├── .env.example # 🔑 환경변수 예시
│ ├── .gitignore # 🚫 Git 제외 파일
│ ├── pyproject.toml # 📦 프로젝트 설정
│ └── uv.lock # 🔒 의존성 락 파일
└── 📋 메타데이터
├── README.md # 📖 이 파일
└── setup_template.py # ⚙️ 템플릿 설정 도구
🚀 빠른 시작
1️⃣ 환경 설정
의존성 설치
# UV 패키지 매니저 사용 (권장)
uv sync
# 또는 pip 사용
pip install -r requirements.txt
# 개발 환경 (테스트, 린팅 도구 포함)
pip install -r requirements-dev.txt
환경변수 설정
# 환경변수 파일 복사 및 수정
cp .env.example .env
.env 파일 주요 설정:
# 애플리케이션 설정
APP_NAME="My Awesome API"
ENVIRONMENT="development" # development, production, test
# 보안 설정
SECRET_KEY="your-secure-random-key-here"
# CORS 설정 (개발용)
CORS_ORIGINS="http://localhost:3000,http://localhost:8080"
# 로깅 설정
LOG_LEVEL="INFO"
LOG_FILE="logs/app.log"
2️⃣ 서버 실행
🎯 통합 실행 (권장)
# API + MCP 서버 동시 실행
python run_server.py
🔄 개별 실행
# Terminal 1: API 서버 (포트 8000)
python run_api_server.py
# Terminal 2: MCP 서버 (포트 8001)
python run_mcp_server.py
🐳 Docker 실행
# 프로덕션 모드
docker-compose up --build
# 개발 모드 (볼륨 마운트)
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build
3️⃣ 접속 확인
| 서비스 | URL | 설명 |
|---|---|---|
| 🌐 API 서버 | http://localhost:8000 | 메인 API 엔드포인트 |
| 📚 API 문서 | http://localhost:8000/docs | 대화형 API 문서 (Scalar) |
| ❤️ 헬스체크 | http://localhost:8000/health | 서버 상태 확인 |
| 🤖 MCP 서버 | http://localhost:8001/sse | MCP SSE 엔드포인트 |
🛠️ 템플릿 커스터마이징
💡 빠른 설정
# 대화형 CLI로 프로젝트 정보 설정
python setup_template.py --customize
🆕 새 프로젝트 생성
# 새 프로젝트 생성
python setup_template.py --new my-awesome-project
# 특정 디렉토리에 생성
python setup_template.py --new my-project --target-dir /path/to/projects
🔄 백업에서 복원
# 원래 템플릿 상태로 복원
python setup_template.py --restore
📚 API 문서
🏥 헬스 체크
GET /health # 종합 헬스 체크
GET /health/simple # 간단한 상태 확인
GET /health/detailed # 상세 시스템 정보
📦 아이템 관리
GET /api/v1/items # 아이템 목록 (페이지네이션)
POST /api/v1/items # 아이템 생성
GET /api/v1/items/{id} # 특정 아이템 조회
PUT /api/v1/items/{id} # 아이템 수정
DELETE /api/v1/items/{id} # 아이템 삭제
GET /api/v1/items/search/by-name # 이름으로 검색
GET /api/v1/items/stats/summary # 통계 정보
👥 사용자 관리
GET /api/v1/users # 사용자 목록
POST /api/v1/users # 사용자 생성
GET /api/v1/users/{id} # 특정 사용자 조회
PUT /api/v1/users/{id} # 사용자 수정
DELETE /api/v1/users/{id} # 사용자 삭제
📖 API 사용 예시
아이템 생성
curl -X POST "http://localhost:8000/api/v1/items" \
-H "Content-Type: application/json" \
-d '{
"name": "노트북",
"description": "고성능 개발용 노트북",
"price": 1200000,
"category": "electronics",
"is_available": true,
"tags": ["laptop", "development"]
}'
아이템 검색
curl "http://localhost:8000/api/v1/items?category=electronics&available_only=true&limit=10"
🤖 MCP 서버 기능
🔨 사용 가능한 도구 (Tools)
| 도구명 | 설명 | 매개변수 |
|---|---|---|
get_items | 아이템 목록 조회 | skip, limit, category, available_only |
get_item_by_id | ID로 아이템 조회 | item_id |
create_item | 새 아이템 생성 | name, price, description, etc. |
update_item | 아이템 수정 | item_id, 수정할 필드들 |
delete_item | 아이템 삭제 | item_id |
search_items | 아이템 검색 | query, search_field |
get_database_stats | 데이터베이스 통계 | 없음 |
export_database | 데이터 내보내기 | 없음 |
📦 사용 가능한 리소스 (Resources)
| 리소스 URI | 설명 |
|---|---|
database://schema | 데이터베이스 스키마 정보 |
docs://api | API 문서 정보 |
data://items | 아이템 데이터 |
data://users | 사용자 데이터 |
🎯 MCP 사용 예시
MCP 클라이언트에서 도구 호출:
# 아이템 생성
result = await mcp_server.call_tool("create_item", {
"name": "새 상품",
"price": 50000,
"category": "electronics"
})
# 아이템 검색
result = await mcp_server.call_tool("search_items", {
"query": "노트북",
"search_field": "name"
})
🧪 테스트
🏃 테스트 실행
# 모든 테스트 실행
pytest
# 커버리지 포함
pytest --cov=src --cov-report=html
# 특정 테스트 모듈
pytest tests/test_api.py -v
# MCP 테스트만 실행
pytest tests/test_mcp.py -v
# 통합 테스트만 실행
pytest tests/test_integration.py -v
📊 테스트 커버리지
- API 엔드포인트: 모든 CRUD 작업 및 오류 시나리오
- MCP 도구: 모든 도구 기능 및 오류 처리
- 통합 테스트: API ↔ MCP 데이터 일관성
- 동시성 테스트: 멀티스레드 환경에서의 안정성
- 시스템 한계 테스트: 대용량 데이터 및 극한 상황
🎯 테스트 예시
# 개발용 빠른 테스트
pytest tests/ -k "not integration" --tb=short
# CI/CD용 전체 테스트
pytest tests/ --cov=src --cov-report=xml --junitxml=test-results.xml
🚀 배포
🐳 Docker 배포
프로덕션 빌드
# 이미지 빌드
docker build -t my-awesome-api .
# 컨테이너 실행
docker run -p 8000:8000 -p 8001:8001 my-awesome-api
Docker Compose
# 프로덕션 환경
docker-compose up --build -d
# 로그 확인
docker-compose logs -f
# 서비스 중지
docker-compose down
☁️ 클라우드 배포
Heroku
# Heroku CLI 로그인
heroku login
# 앱 생성
heroku create my-awesome-api
# 환경변수 설정
heroku config:set SECRET_KEY="your-secret-key"
heroku config:set ENVIRONMENT="production"
# 배포
git push heroku main
AWS ECS / Azure Container Instances
# 환경변수 설정 예시
export SECRET_KEY="your-production-secret-key"
export ENVIRONMENT="production"
export CORS_ORIGINS="https://yourdomain.com"
# 컨테이너 실행
docker run -p 8000:8000 -p 8001:8001 \
-e SECRET_KEY=$SECRET_KEY \
-e ENVIRONMENT=$ENVIRONMENT \
-e CORS_ORIGINS=$CORS_ORIGINS \
my-awesome-api
📊 프로덕션 모니터링
환경변수 설정:
# 로깅 설정
LOG_LEVEL="WARNING"
LOG_FILE="/var/log/app/app.log"
# 보안 설정
SECRET_KEY="강력한-랜덤-키-32자-이상"
CORS_ORIGINS="https://yourdomain.com,https://admin.yourdomain.com"
# 성능 설정
DATABASE_URL="postgresql://user:pass@host:5432/dbname"
🔧 개발 가이드
📝 새 API 엔드포인트 추가
- 모델 정의 (
src/core/models.py):
class NewModel(BaseEntity):
name: str = Field(..., description="이름")
value: int = Field(..., description="값")
- 라우터 생성 (
src/api/routers/new_router.py):
from fastapi import APIRouter, Depends
from ...core.dependencies import get_database
from ...core.models import NewModel
router = APIRouter()
@router.get("/items", response_model=List[NewModel])
async def get_items(db: InMemoryDatabase = Depends(get_database)):
return db.find_all("new_items")
- 앱에 등록 (
src/api/app.py):
from .routers import new_router
app.include_router(new_router.router, prefix="/api/v1", tags=["New Items"])
🔨 새 MCP 도구 추가
- 도구 정의 (
src/mcp_server/tools.py):
@mcp.tool()
def new_tool(context: Context, param1: str, param2: int = 10) -> dict:
"""새로운 MCP 도구"""
try:
# 비즈니스 로직
result = process_data(param1, param2)
return {"success": True, "result": result}
except Exception as e:
logger.error(f"Tool error: {e}")
return {"success": False, "error": str(e)}
- 리소스 추가 (
src/mcp_server/resources.py):
@mcp.resource("data://new_resource")
def get_new_resource(context: Context) -> str:
"""새로운 MCP 리소스"""
return json.dumps({"data": "new_resource_data"})
🧪 테스트 작성
- 단위 테스트:
@pytest.mark.asyncio
async def test_new_tool():
result = await mcp_server.call_tool("new_tool", {
"param1": "test",
"param2": 5
}, mock_context)
assert result["success"] == True
- 통합 테스트:
def test_new_endpoint(client):
response = client.post("/api/v1/new-items", json={
"name": "Test Item",
"value": 100
})
assert response.status_code == 201
📋 코딩 스타일
- 타입 힌트: 모든 함수에 타입 힌트 사용
- Docstring: Google 스타일 docstring 사용
- 로깅: 구조화된 로깅 (
logger.info(),logger.error()) - 예외 처리: 커스텀 예외 클래스 사용
- 의존성 주입: FastAPI Depends() 패턴 활용
🔍 문제 해결
🚨 일반적인 문제들
포트 충돌
# 포트 사용 확인
lsof -i :8000
lsof -i :8001
# 프로세스 종료
kill -9 <PID>
환경변수 설정 오류
# 환경변수 확인
python -c "from src.core.config import settings; print(settings.dict())"
# .env 파일 확인
cat .env
의존성 문제
# 의존성 재설치
uv sync --refresh
# 캐시 정리
uv cache clean
로그 확인
# 애플리케이션 로그
tail -f logs/app.log
# Docker 로그
docker-compose logs -f
🔧 디버깅 팁
- DEBUG 모드 활성화:
export DEBUG=true
export LOG_LEVEL=DEBUG
- 개발 서버에서 실행:
uvicorn src.api.app:create_app --factory --reload --log-level debug
- MCP 서버 단독 테스트:
python -m src.mcp_server.server
🤝 기여하기
🔄 기여 워크플로우
- Fork 저장소
- Feature 브랜치 생성:
git checkout -b feature/amazing-feature - 커밋:
git commit -m 'Add amazing feature' - 푸시:
git push origin feature/amazing-feature - Pull Request 생성
📋 기여 가이드라인
- 코드 스타일: Black, isort, flake8 사용
- 테스트: 새 기능에 대한 테스트 추가
- 문서화: Docstring 및 README 업데이트
- 커밋 메시지: Conventional Commits 스타일 사용
🛠️ 개발 환경 설정
# 개발 의존성 설치
uv sync --dev
# pre-commit 훅 설치
pre-commit install
# 코드 포맷팅
black src/ tests/
isort src/ tests/
# 린팅
flake8 src/ tests/
mypy src/
📄 라이선스
이 프로젝트는 MIT 라이선스 하에 배포됩니다.
🙏 감사의 말
- FastAPI - 현대적인 Python 웹 프레임워크
- FastMCP - Model Context Protocol 구현
- Pydantic - 데이터 검증 및 설정 관리
- UV - 빠른 Python 패키지 매니저
🚀 이 템플릿으로 멋진 API를 만들어보세요! 🚀