AI导哈

AI产品目录API

使用FastAPI和MCP构建支持AI调用的产品目录服务，提供RESTful API和AI工具集成功能。

  • by sihembarghouda
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 sihembarghouda/Lab2_Building-an-AI-Ready-Product-Catalog-with-FastAPI-and-MCP

使用说明

实验室：使用FastAPI和MCP构建AI就绪产品目录

📋 目录

🎯 目标

在这个实验室中，您将使用FastAPI创建一个产品目录API，并使用FastMCP的模型上下文协议（MCP）将其转换为可访问的人工智能服务。实验室演示了如何：

  1. 第1部分：使用PostgreSQL数据库构建并测试基于FastAPI的产品目录API
  2. 第2部分：创建一个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
  1. 设置虚拟环境:
python -m venv venv

# On Windows
venv\Scripts\activate

# On macOS/Linux  
source venv/bin/activate
  1. 安装所需的软件包:
pip install -r requirements.txt

紫外线替代品:

uv add fastapi[all] uvicorn fastmcp sqlalchemy psycopg2-binary

步骤2：数据库设置

  1. 使用Docker启动PostgreSQL:
docker-compose up -d db
  1. 初始化数据库表:
python create_tables.py

🏗️ 第1部分：FastAPI产品目录API

特性

  • RESTful API 使用FastAPI框架
  • PostgreSQL数据库 与SQLAlchemy ORM的集成
  • Pydantic模型 用于数据验证
  • API自动文档 使用Swagger用户界面
  • CRUD操作 用于产品管理

可用端点

方法 端点 描述
得到 /products 列出所有产品
得到 /products/{id} 按ID获取产品
职位 /products 创建新产品

运行FastAPI服务器

uvicorn main:app --host localhost --port 8000 --reload

接入点:

  • APIhttp://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"}'

🤖 第2部分：MCP服务器集成

什么是MCP？

模型上下文协议（MCP）使AI助手能够安全地连接到外部数据源和工具。FastMCP会自动将您的FastAPI端点转换为AI可调用工具。

运行MCP服务器

  1. 保持FastAPI服务器运行 在8000端口
  2. 启动MCP服务器 在新终端中：
python mcp_server.py

MCP服务器运行在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用户界面:

  1. 打开http://localhost:8000/docs
  2. 以交互方式测试两个端点
  3. 查看请求/响应模式

测试数据库集成

# 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 Desktop的集成

设置克劳德桌面

  1. 安装克劳德桌面 （如果未安装）
  2. 配置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"]
    }
  }
}
  1. 重新启动克劳德桌面
  2. 启用工具 在新聊天中：搜索和工具>选择“产品目录”

AI交互示例

查询：“列出目录中的所有产品” 预期：克劳德打来电话 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/产品:

[
  {
    "id": 1,
    "name": "Laptop",
    "price": 999.99,
    "description": "High-end gaming laptop"
  },
  {
    "id": 2,
    "name": "Wireless Mouse",
    "price": 29.99,
    "description": "Ergonomic wireless mouse"
  }
]

GET/产品/｛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 db

MCP服务器中的导入错误:

# 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 <PID> /F

调试提示

  1. 检查日志：FastAPI和MCP服务器都提供详细的控制台输出
  2. 验证数据库：使用pgAdmin或psql检查数据库内容
  3. 测试终点：在以下位置使用Swagger UIhttp://localhost:8000/docs
  4. 验证MCP：检查Claude Desktop开发人员控制台是否存在MCP错误

🚀 扩展和下一步

即时增强功能

  1. 添加身份验证：实现JWT或API密钥身份验证
  2. 添加更多端点：PUT、DELETE操作以完成CRUD操作
  3. 数据验证：具有约束的增强Pydantic模型
  4. 错误处理：自定义异常处理程序和详细的错误响应

高级功能

  1. 数据库迁移：使用Alembic进行架构版本控制
  2. 缓存：实现Redis以提高性能
  3. 测试套件：添加带有夹具和模拟的pytest
  4. API版本控制：支持多个API版本
  5. 速率限制：实现请求限制
  6. 监控：添加日志记录、指标和健康检查

生产部署

  1. 环境变量：外部化配置
  2. 安全强化：HTTPS、CORS、安全标头
  3. 容器编排：Kubernetes部署
  4. CI/CD管道：自动化测试和部署
  5. 负载均衡：多实例部署

AI集成扩展

  1. 自然语言查询：添加语义搜索功能
  2. 批量操作：人工智能驱动的批量产品管理
  3. 推荐引擎：基于人工智能的产品建议
  4. 库存管理：库存水平监测和警报

📝 提交要求

提交以下带有截图的文件：

所需文件:

  • main.py -FastAPI应用程序
  • mcp_server.py -MCP服务器实现
  • models.py -数据库模型
  • database.py -数据库配置

截图:

  1. Swagger UI显示所有FastAPI端点
  2. Claude Desktop工具调用输出 list_products_tool
  3. Claude Desktop工具调用输出 get_product_tool
  4. 显示已创建产品的数据库内容

👤 作者

瓦希德·哈姆迪

🤔 反思问题

  1. Pydantic如何确保API响应中的数据验证？
  2. 当您发送无效的product_id（例如，字符串而不是整数）时会发生什么？
  3. FastMCP如何使用您的FastAPI应用程序的OpenAPI模式来创建工具？
  4. @mcp.tool装饰器为AI交互提供了哪些好处？
  5. 您将如何保护MCP服务器以供生产使用？

编码愉快！ 🚀

相关 MCP