实验室：使用FastAPI和MCP构建一个AI就绪的产品目录
  
📋 目录
🎯 目标
在这个实验中，你将使用FastAPI创建一个产品目录API，并使用FastMCP和模型上下文协议（MCP）将其转换为AI可访问的服务。本实验演示了如何：
- 第一部分基于FastAPI和PostgreSQL数据库构建并测试产品目录API
- 第二部分创建一个MCP服务器，以将您的API作为可被AI调用的工具暴露出来
持续时间大约90分钟
📚 先决条件
- Python 3.10及以上版本 已安装
- 对Python、REST API和JSON有基本了解
- 熟悉终端命令和虚拟环境
- 所需软件包:
fastapi[all]，fastmcp，uvicorn，sqlalchemy，psycopg2-binary - 可选用于测试AI工具调用的Claude Desktop（免费层级已足够）
- 代码编辑器（例如，VS Code）
- Docker 和 Docker Compose（用于容器化部署）
📁 项目结构
product-catalog-lab/
├── README.md # This file
├── main.py # FastAPI application
├── mcp_server.py # MCP server implementation
├── models.py # SQLAlchemy models
├── database.py # Database configuration
├── create_tables.py # Database initialization script
├── requirements.txt # Python dependencies
├── Dockerfile # Docker configuration
├── docker-compose.yml # Multi-container setup
├── openapi.json # Generated OpenAPI schema
├── step1.txt # Part 1 instructions
├── step2.txt # Part 2 instructions
└── __pycache__/ # Python cache files🚀 安装
步骤1：设置您的环境
- 创建并导航到项目目录:
mkdir product-catalog-lab
cd product-catalog-lab- 设置虚拟环境：
python -m venv venv
# On Windows
venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate- 安装所需的软件包：
pip install -r requirements.txt带有紫外线的替代方案：
uv add fastapi[all] uvicorn fastmcp sqlalchemy psycopg2-binary步骤2：数据库设置
- 使用 Docker 启动 PostgreSQL:
docker-compose up -d db- 初始化数据库表：
python create_tables.py🏗️ 第一部分：FastAPI 产品目录 API
特点/功能
- RESTful API（Representational State Transfer Application Programming Interface，即表现层状态转移应用程序编程接口） 使用 FastAPI 框架
- PostgreSQL 数据库 与SQLAlchemy ORM的集成
- Pydantic 模型 用于数据验证
- 自动API文档 使用Swagger UI
- CRUD操作 对于产品管理
可用的终端节点
| 方法 | 终点 | 描述 | ||
|---|---|---|---|---|
| GET | /products | 列出所有产品 | ||
| GET | （可译为） | 获取 | /products/{id} | 通过ID获取产品 |
| 帖子 | /products | 创建新产品 |
运行 FastAPI 服务器
uvicorn main:app --host localhost --port 8000 --reload接入点：
- API：http://localhost:8000
- 交互式文档：http://localhost:8000/docs
- OpenAPI 模式：http://localhost:8000/openapi.json
测试API
列出所有产品:
curl http://localhost:8000/products获取特定产品：
curl http://localhost:8000/products/1开发新产品:
curl -X POST "http://localhost:8000/products" \
-H "Content-Type: application/json" \
-d '{"id": 4, "name": "Monitor", "price": 299.99, "description": "4K Display"}'🤖 第二部分：MCP服务器集成
什么是MCP？
模型上下文协议（MCP）使人工智能助手能够安全地连接到外部数据源和工具。FastMCP自动将您的FastAPI端点转换为可被AI调用的工具。
运行MCP服务器
- 保持FastAPI服务器运行 在8000端口上
- 启动MCP服务器 在新终端中：
python mcp_server.pyMCP服务器运行在8001端口，并将您的API端点作为AI工具暴露出来。
可用的MCP工具
list_products()从目录中获取所有产品get_product(product_id)检索特定产品详情
🧪 测试
手动API测试
使用curl:
# Test products endpoint
curl http://localhost:8000/products
# Test specific product
curl http://localhost:8000/products/1
# Test non-existent product (should return 404)
curl http://localhost:8000/products/999使用Swagger UI：
- 打开 http://localhost:8000/docs
- 交互式地测试两个端点
- 查看请求/响应模式
测试数据库集成
# Check if tables were created
python -c "from database import engine; from sqlalchemy import inspect; print(inspect(engine).get_table_names())"🐳 Docker 部署
选项1：Docker Compose（推荐）
启动所有服务:
docker-compose up -d所包含的服务：
- PostgreSQL 数据库（端口 5432）
- FastAPI 应用程序（端口 8000）
选项2：手动Docker构建
构建并运行：
docker build -t product-catalog .
docker run -p 8000:8000 product-catalog🎯 AI与Claude桌面端的集成
设置Claude桌面版
- 安装Claude桌面版 （如果尚未安装）
- 配置MCP服务器 在
claude-desktop-config.json:
{
"mcpServers": {
"product-catalog": {
"command": "C:\\Users\\zeine\\product-catalog-lab\\venv\\Scripts\\python.exe",
"args": ["C:\\Users\\zeine\\product-catalog-lab\\mcp_server.py"]
}
}
}- 重启Claude桌面版
- 启用工具 在新聊天中：搜索和工具 > 选择“产品目录”
人工智能交互示例
查询“列出目录中的所有产品” 预期克劳德打电话来 list_products_tool 并显示格式化的产品列表
查询“ID为2的产品是什么？” 预期的克劳德打电话来 get_product_tool 带有ID 2并显示产品详情
API 文档
产品型号
class Product(BaseModel):
id: int # Unique identifier
name: str # Product name
price: float # Product price
description: Optional[str] # Optional description响应示例
GET /products 翻译为中文是：“获取/产品列表”：
[
{
"id": 1,
"name": "Laptop",
"price": 999.99,
"description": "High-end gaming laptop"
},
{
"id": 2,
"name": "Wireless Mouse",
"price": 29.99,
"description": "Ergonomic wireless mouse"
}
]获取 /products/{id}（注：这里的“获取”是根据HTTP GET方法的语义翻译，实际在编程或API调用中，我们通常说“发送GET请求到/products/{id}”或“访问/products/{id}资源”）：
{
"id": 1,
"name": "Laptop",
"price": 999.99,
"description": "High-end gaming laptop"
}🔧 故障排除
常见问题
数据库连接错误：
# Check if PostgreSQL is running
docker ps
# Restart database
docker-compose restart dbMCP服务器中的导入错误：
# Ensure FastAPI server is running first
# Check Python path configuration in mcp_server.py端口已被占用：
# Kill process on port 8000
netstat -ano | findstr :8000
taskkill /PID
/F调试技巧
- 检查日志FastAPI和MCP服务器都提供了详细的控制台输出
- 验证数据库使用 pgAdmin 或 psql 查看数据库内容
- 测试端点在 http://localhost:8000/docs 上使用 Swagger UI
- 验证MCP检查Claude Desktop开发者控制台中的MCP错误
🚀 扩展与下一步计划
即时提升
- 添加认证实现JWT或API密钥认证
- 添加更多终端节点用于完整CRUD操作的PUT、DELETE方法
- 数据验证带有约束条件的增强型 Pydantic 模型
- 错误处理自定义异常处理器和详细的错误响应
高级功能
- 数据库迁移使用 Alembic 进行模式版本控制
- 缓存实施 Redis 以提升性能
- 测试套件添加带有固定装置和模拟的 pytest
- API版本控制支持多个API版本
- 速率限制实现请求限流
- 监测添加日志记录、指标和健康检查
生产部署
- 环境变量外部化配置
- 安全加固HTTPS，CORS，安全头部
- 容器编排Kubernetes 部署
- 持续集成/持续交付（CI/CD）流水线自动化测试与部署
- 负载均衡多实例部署
AI集成扩展
- 自然语言查询添加语义搜索功能
- 批处理操作基于人工智能的大宗产品管理
- 推荐引擎基于人工智能的产品推荐
- 库存管理库存水平监控与提醒
📝 提交要求
提交以下文件，并附上截图：
所需文件：
main.py- FastAPI 应用程序mcp_server.py- MCP服务器实现models.py- 数据库模型database.py- 数据库配置
屏幕截图：
- Swagger UI 显示所有 FastAPI 端点
- Claude桌面工具调用输出结果为
list_products_tool - Claude桌面工具调用输出结果为
get_product_tool - 数据库内容显示已创建的产品
👤 作者
由瓦希德·哈姆迪（Wahid Hamdi）所著/所述
______________________________________________________________________
🤔 思考题
- Pydantic是如何确保API响应中的数据验证的？
- 当你发送一个无效的产品ID（例如，字符串而不是整数）时会发生什么？
- FastMCP 是如何利用您的 FastAPI 应用的 OpenAPI 规格来创建工具的？
- @mcp.tool 装饰器为人工智能交互提供了哪些好处？
- 您将如何确保MCP服务器适合生产环境使用？
______________________________________________________________________
编码愉快！ 🚀