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 엔드포인트 추가

1. 모델 정의 (src/core/models.py):

class NewModel(BaseEntity):
    name: str = Field(..., description="이름")
    value: int = Field(..., description="값")

2. 라우터 생성 (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")

3. 앱에 등록 (src/api/app.py):

from .routers import new_router
app.include_router(new_router.router, prefix="/api/v1", tags=["New Items"])

🔨 새 MCP 도구 추가

1. 도구 정의 (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)}

2. 리소스 추가 (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"})

🧪 테스트 작성

1. 단위 테스트:

@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

2. 통합 테스트:

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

🔧 디버깅 팁

1. DEBUG 모드 활성화:

export DEBUG=true
export LOG_LEVEL=DEBUG

2. 개발 서버에서 실행:

uvicorn src.api.app:create_app --factory --reload --log-level debug

3. MCP 서버 단독 테스트:

python -m src.mcp_server.server

🤝 기여하기

🔄 기여 워크플로우

1. Fork 저장소
2. Feature 브랜치 생성: git checkout -b feature/amazing-feature
3. 커밋: git commit -m 'Add amazing feature'
4. 푸시: git push origin feature/amazing-feature
5. 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 패키지 매니저

---

<p align="center"> <strong>🚀 이 템플릿으로 멋진 API를 만들어보세요! 🚀</strong> </p>

<p align="center"> <a href="https://github.com/your-username/fastapi-mcp-template/issues">🐛 버그 신고</a> • <a href="https://github.com/your-username/fastapi-mcp-template/discussions">💬 토론</a> • <a href="https://github.com/your-username/fastapi-mcp-template/wiki">📖 위키</a> </p>