使用说明

FastAPI+MCP模板

现代API服务器与模型上下文协议（MCP）集成模板

利用FastAPI和MCP的生产级API服务器模板。提供LLM集成、结构化日志记录、全面的测试和最佳的开发人员体验。

主要功能

🚀 生产级API服务器

现代FastAPI：自动API记录、类型安全性、高性能
Scalar文档化：美丽的交互式API文档
结构化日志记录：颜色支持，文件轮换，请求跟踪
全面的异常处理：特定类型的自定义异常和详细错误信息
依赖注入：采用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等等。 | | 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/AAzure容器实例

# 환경변수 설정 예시
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

📋 编码样式

类型提示：对所有函数使用类型提示
文档字符串：使用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

🤝 贡献

🔄 贡献工作流

分叉存储库
Feature分支 创建： git checkout -b feature/amazing-feature
提交: git commit -m 'Add amazing feature'
推送: git push origin feature/amazing-feature
拉取请求 创建

📋 贡献准则

代码样式：使用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许可证以下分发。

🙏 感谢的话

快速 API -现代化的Python Web框架
FastMCP -模型上下文协议구현
派丹蒂克 -数据验证和设置管理
紫外线的 -快速的Python包管理器

🚀 이 템플릿으로 멋진 API를 만들어보세요! 🚀

🐛 버그 신고 • 💬 토론 • 📖 위키