你的业务代码 → MCP Server → AI 智能体（Cursor / Claude / 自定义应用）

FastAPI（主容器）
├── CORS 中间件
├── 生命周期管理
├── FastAPI 路由（传统 HTTP）
└── FastMCP 子应用（MCP 协议）
    └── @mcp.tool() 工具

# 克隆模板
git clone <your-repo-url> my-mcp-server
cd my-mcp-server

# 安装依赖
uv sync

# 配置环境变量
cp .env-sample .env

# 方式一：uvicorn（推荐）
uv run uvicorn app.main:app --reload

# 方式二：python
uv run python -m app.main

# 方式三：fastapi CLI
uv run fastapi dev app/main.py

# HTTP 端点
curl http://127.0.0.1:8000/example/hello
# => "Hello, World! Running mcp-server-template v0.1.0"

# MCP 协议端点（返回 MCP 端点信息，非 404 即挂载成功）
curl http://127.0.0.1:8000/example

mcp-server-template/
│
├── app/                    # 应用主目录
│   ├── routers/            # MCP 工具 + FastAPI 路由
│   │   ├── example.py      #   示例模块（供复制参考）
│   │   └── __init__.py
│   ├── utils/              # 工具函数
│   │   └── log.py          #   日志（loguru）
│   ├── __init__.py
│   ├── config.py           # 配置管理（pydantic-settings）
│   ├── dependencies.py     # 依赖注入
│   └── main.py             # 应用入口
│
├── docs/                   # 文档
├── migrations/             # Alembic 数据库迁移（可选）
├── scripts/                # 开发脚本
├── tests/                  # 测试
│
├── .env-sample             # 环境变量模板
├── .gitignore
├── .python-version
├── alembic.ini
├── docker-compose.yaml
├── Dockerfile
├── pyproject.toml
└── README.md

# app/main.py
from app.routers import your_module
from fastmcp.utilities.lifespan import combine_lifespans

your_module_app = your_module.mcp.http_app(path="/", stateless_http=True)
app.include_router(your_module.router)
app.mount("/your_module", app=your_module_app)

# 同时把 your_module_app.lifespan 合并进 FastAPI 的 lifespan：
# app = FastAPI(lifespan=combine_lifespans(lifespan, your_module_app.lifespan))

@mcp.tool()
@router.get("/search")
async def search(query: str) -> list:
    """搜索知识库（此描述会暴露给 AI）"""
    # 你的业务逻辑
    return results

uv run pytest tests/ -v

# 构建
docker build -t mcp-server:latest .

# 启动
docker compose up -d