代理零售 MCP 系统

一个全栈人工智能应用程序，实现了一个安全连接到 Firebase Firestore 数据库的模型上下文协议 (MCP) 服务器，通过 Streamlit 聊天界面进行控制，并由 OpenAI 的 gpt-4o 提供支持。

系统架构

本项目采用解耦的微服务模式构建：

1. MCP 后端服务器 (src/server.py)：一个 fastmcp Python 服务器，公开了零售专用工具 ['check_inventory', 'calculate_elasticity', 'get_demand_forecast']。直接连接到 Google Cloud Firestore。

2. AI Streamlit 前端 (src/client.py)：一个异步 Web UI，使用持久的 Server-Sent Events (SSE) 与后端服务器通信。解析工具输入并将其动态循环到 OpenAI 函数调用中。

Related MCP server: E-commerce MCP Server

先决条件与配置

在运行任何脚本之前，必须在项目根目录配置 .env 文件。

创建一个 .env 文件并定义以下变量：

# Your OpenAI API Key for the GPT-4o Agent
OPENAI_API_KEY="sk-proj-YOUR-KEY-HERE"

# The absolute path to your Firebase Service Account JSON key
FIREBASE_CREDENTIALS_PATH="./firebase-key.json"

（如果 FIREBASE_CREDENTIALS_PATH 留空，系统将尝试原生使用 Google Cloud 的应用程序默认凭据）。

安装

本项目使用 uv 作为闪电般的 Python 包依赖管理器。

在根目录下运行以下命令，以确保依赖项映射到 Python >= 3.11：

uv init
uv add mcp pydantic firebase-admin python-dotenv openai streamlit

数据库初始化（模拟数据）

如果您有一个全新的 Firebase Firestore 实例，可以使用内置的种子工具向数据库填充 100 个零售产品样本。

1. 生成静态 CSV 模拟数据结构：

   uv run python generate_data.py

2. 将生成的 CSV 数据直接流式传输到您的 Firebase NoSQL 数据库中：

   uv run python seed_db.py

运行应用程序

由于 Web 界面和工具服务器通过隔离的本地网络循环进行通信，您必须在两个独立的终端选项卡中并行运行这两个进程。

1. 启动后端工具服务器

这将在 8000 端口启动一个 ASGI Uvicorn 应用程序，通过 HTTP 服务器发送事件 (SSE) 原生处理所有工具执行请求。

uv run python src/server.py

2. 启动 Streamlit 客户端

在新的终端窗口中，启动 Streamlit 对话代理：

uv run streamlit run src/client.py 

Web 浏览器选项卡将自动在 http://localhost:8501 打开。现在您可以询问诸如 “产品 P1002 的库存水平是多少？” 或 “分析 P1100 的价格弹性预测” 之类的问题。

云部署 (Google Cloud Run)

如果您想将 AI 代理和后端基础设施永久迁移到云端，我已经配置了专门为 Google Cloud Run 无服务器部署设计的先进 Dockerfile。

请参阅完整的 DEPLOYMENT.md 文档指南，获取将两个容器推送到 Web 的说明。