内容
# 电子商务分析MCP服务器
一个基于PostgreSQL的**模型上下文协议（MCP）**服务器，提供一套精选的**分析工具**、**操作工具**、**模式**和**安全SQL**工具，用于与电子商务数据库合作。这样，AI代理（IDE助手、聊天应用等）可以探索数据、生成报告和制作仪表盘，而无需临时编写SQL。
使用**FastMCP**、**SQLAlchemy**和**psycopg**构建，并具有模式反射功能，以适应现实世界中常见的电子商务模式变化。
---
## 为什么存在
如果你曾经希望AI助手可靠地回答以下问题：
- “本周发生了什么变化？”
- “哪些产品推动了收入增长？”
- “我们是否正在积压订单？”
- “我们现在应该重新订购什么？”
……使用你的**实际数据库**（而非猜测），该项目提供了一个干净、受控的MCP接口，适用于Postgres。
---
## 主要功能
- **分析工具**：按日统计的收入和订单、热门产品、热门客户、重复购买率、毛利率和销售关键绩效指标。
- **操作和报告工具**：Markdown格式的一页销售和操作报告、表格计数、低库存洞察和操作健康检查。
- **可视化仪表盘**：2x2的综合**销售仪表盘PNG**（收入趋势、订单趋势、热门产品、关键绩效指标瓷砖）。
- **模式工具**：模式概览、表格列表、表格描述和模式缓存刷新。
- **安全SQL访问**：一个加固的、只读的SQL工具，仅允许`SELECT`/`WITH`/`SHOW`/`EXPLAIN`。
- **演示数据种子**：用于本地实验的现实合成电子商务数据生成器。
- **提示助手**：针对执行简报、销售深度分析、操作分类、库存规划和数据质量烟雾测试的意见提示模板。
---
## 架构概述
- **MCP服务器**：使用`fastmcp`实现，并通过`ecom-mcp`控制台脚本启动。
- **配置**：集中在`Settings`（Pydantic `BaseSettings`），从环境变量和可选的`.env`文件加载。
- **数据库访问**：使用具有连接池的`Engine`和小型工作单元抽象的SQLAlchemy。
- **模式反射**：自动检查`public`模式中的表格和列，以适用于常见的电子商务模式（即使列名略有不同）。
- **服务**：
- **AnalyticsService**：高级报告查询（收入、客户、产品、利润率等）。
- **OpsService**：销售和操作的Markdown报告。
- **SchemaService**：表格和列的内省助手。
- **SqlService**：具有安全检查和超时的只读SQL执行。
- **SeedService**：具有安全防护栏的演示数据写入器。
---
## 要求
- **Python**：`>= 3.13`
- **PostgreSQL**：任何合理的PostgreSQL版本
- **网络访问**：MCP主机必须能够连接到DSN中提供的数据库
---
## 快速入门（推荐使用`uv`）
```bash
git clone https://github.com/<your-org>/<your-repo>.git
cd <your-repo>
# 安装依赖
uv sync
# 运行MCP服务器（stdio）
uv run ecom-mcp
```
或者：
```bash
uv run python -m app.main
```
---
## 安装（pip）
```bash
git clone https://github.com/<your-org>/<your-repo>.git
cd <your-repo>
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install .
```
安装后，`ecom-mcp`控制台脚本将在您的`PATH`上可用。
---
## 配置
配置由`app.config.settings.Settings`处理，从以下来源读取：
- 环境变量
- 项目根目录中的可选`.env`文件
### 主要设置
- **`POSTGRES_DSN`**（必填）：PostgreSQL连接字符串
- 接受`postgresql+psycopg://...`、`postgresql://...`或`postgres://...`。
- **`ALLOW_WRITES`**（可选，默认：`true`）：启用可写工具（尤其是演示数据种子）。
- 在生产环境中，您通常希望**禁用**此功能。
- **`LOG_LEVEL`**（可选，默认：`INFO`）：Python日志级别（`DEBUG`、`INFO`、`WARNING`等）
示例`.env`：
```bash
POSTGRES_DSN=postgresql://user:password@localhost:5432/ecom_db
ALLOW_WRITES=false
LOG_LEVEL=INFO
```
> 注意：`ALLOW_WRITES=false`（或`0`）将阻止修改数据的工具，例如`seed_demo_data`。
---
## 运行MCP服务器
通过控制台脚本启动服务器：
```bash
ecom-mcp
```
这启动了一个名为 **`ecom-postgres`** 的FastMCP服务器，该服务器通过 **stdio** 进行通信，这是大多数MCP主机所期望的传输方式。
或者直接运行模块：
```bash
python -m app.main
```
---
## 连接到MCP主机
该项目默认情况下通过 **stdio** 运行。
### Claude Desktop / Cursor / Trae（带有`mcpServers`的JSON）
```json
{
"mcpServers": {
"ecom_postgres": {
"command": "uv",
"args": ["--directory", "E:\\projects\\ecom-mcp", "run", "ecom-mcp"]
}
}
}
```
### VS Code（创建 `.vscode/mcp.json`）
VS Code使用不同的顶级键（`servers`）并要求 `type: "stdio"`：
```json
{
"servers": {
"ecomPostgres": {
"type": "stdio",
"command": "uv",
"args": ["--directory", "${workspaceFolder}", "run", "ecom-mcp"],
"envFile": "${workspaceFolder}\\.env"
}
}
}
```
---
## MCP工具
工具标识通常与Python函数名称匹配。
### 健康状况
- **`db_ping`**（`health`）：
连接性检查，返回当前数据库、用户、模式和服务器时间。
### 模式和元数据
- **`refresh_schema_cache`**（`schema`）：
清除缓存的模式元数据。在迁移或模式更改后使用。
- **`schema_overview`**（`schema`）：
返回`public`中表格和列的Markdown概述，以及结构化JSON。
- **`list_tables`**（`schema`）：
列出`public`模式中的所有表格。
- **`describe_table`**（`schema`）：
返回给定表格的列、类型、空性和默认值。
- **`table_counts`**（`schema`，`debug`）：
常见电子商务表格（仅存在表格）的行计数。
### 分析
- **`revenue_by_day(days=30)`**（`analytics`，`sales`）：
过去`N`天的每日订单和收入（如果存在`status`列，则排除已取消的订单）。
- **`top_products_last_days(days=30, limit=10)`**（`analytics`，`sales`，`catalog`）：
过去`N`天收入最高的商品。
- **`top_customers_last_days(days=90, limit=10)`**（`analytics`，`sales`，`customer`）：
过去`N`或90天收入最高的客户。
- **`repeat_purchase_rate(days=180)`**（`analytics`，`customer`）：
在选择的时间窗口内，拥有2+订单的客户比例。
- **`gross_margin_last_days(days=30)`**（`analytics`，`finance`）：
过去`N`天的收入、成本、毛利率和利润率。
### 操作和报告
- **`low_stock(threshold=10, limit=50)`**（`ops`，`inventory`）：
列出低库存商品（需要`v_inventory_on_hand`视图或`inventory`表格）。
- **`ops_health_report(days=14, low_stock_threshold=10)`**（`ops`，`report`）：
总结订单状态混合、积压和库存风险的Markdown报告。
- **`sales_report(days=30, top_n=10)`**（`analytics`，`report`，`sales`）：
具有关键绩效指标、日常趋势和热门商品的一页Markdown销售报告。
### 仪表盘
- **`sales_dashboard(days=30, top_n=10)`**（`analytics`，`report`，`charts`）：
生成2x2的PNG仪表盘（收入趋势、订单趋势、热门商品、关键绩效指标瓷砖）。
返回Markdown描述和PNG图像字节。
> 注意：工具返回的图像的渲染依赖于MCP主机。一些客户端显示内联图像；其他客户端显示base64。
### SQL（只读）
- **`sql_readonly(query, max_rows=200, timeout_ms=5000)`**（`sql`）：
执行单个只读SQL语句（仅限`SELECT`/`WITH`/`SHOW`/`EXPLAIN`）。
强制执行：
- 规范化SQL，去除末尾分号
- 无内部分号（仅限单个语句）
- 服务器端语句超时（`timeout_ms`）
- 行限制（`max_rows`）
### 种子和演示数据
- **`seed_demo_data(size="small|medium|large", reset_first=True, seed=42)`**（`seed`，`demo`）：
插入现实的演示电子商务数据，可选地首先截断现有数据。
- 需要 `ALLOW_WRITES=true`（或 `1`）——否则引发权限错误。
- 尺寸：
- **small**：~50个客户，150个产品，600个订单
- **medium**：~300个客户，900个产品，7,000个订单
- **large**：~1,500个客户，4,000个产品，40,000个订单
---
## 提示助手
服务器注册了多个**MCP提示**，引导AI代理有效使用工具：
- **`weekly_exec_brief(days=7)`**：一页执行简报（关键绩效指标、变化、风险、后续行动）。
- **`sales_deep_dive(days=30, top_n=15)`**：详细销售分析（趋势、驱动因素、盈利能力、建议）。
- **`investigate_revenue_drop(days=14, compare_days=14)`**：比较两个时间窗口的根因手册。
- **`ops_triage(days=14)`**：关注积压、状态混合和库存风险的操作分类。
- **`inventory_reorder_plan(days=30, low_stock_threshold=10)`**：使用低库存 + 销售速度的库存计划。
- **`data_quality_smoke_test()`**：种子或模式更改后的快速健全检查。
提示优先使用内置分析工具，仅在需要时使用`sql_readonly`。
---
## 预期模式（高级别）
服务器设计为通过反射适应常见的电子商务模式，但如果`public`模式中存在以下表格（或等效表格），则效果最佳：
- **`customers`**
- 推荐列：`customer_id`、`email`、`full_name`
- **`categories`**（可选，但由种子使用）
- 推荐列：`category_id`、`name`、`slug`
- **`products`**
- 推荐列：`product_id`、`sku`、`name`、`category_id`、`price`
- 推荐额外列：`cost`、`currency_code`、`attributes`、`is_active`
- **`orders`**
- 时间戳：`placed_at`、`ordered_at`、`created_at`、`order_date`之一
- 总计：`total_amount`、`grand_total`、`total`之一
- 可选：`status`、`order_number`、`currency_code`、
`subtotal_amount`、`discount_amount`、`tax_amount`、`shipping_amount`
- **`order_items`**
- 数量：`quantity`或`qty`
- 种子必填：`unit_price`、`sku_snapshot`、`name_snapshot`
- 可选：`unit_cost`、`line_subtotal`、`line_total`、`item_discount`、`item_tax`
- **库存**
- `v_inventory_on_hand`视图或具有`on_hand`或`quantity_on_hand`的`inventory`表格，
以及与`products`的关系
- **库存变动**（可选）
- `stock_movements`表格，当存在时由种子使用
代码尝试动态选择正确的列，如果缺少必需的表格或列，则会引发明确的运行时错误。
---
## 安全性和最佳实践
- 优先使用分析/报告工具而不是原始SQL（`revenue_by_day`、`sales_report`、`ops_health_report`等）。
- 在生产环境中锁定写入：设置`ALLOW_WRITES=false`。
- 在迁移后刷新模式缓存：调用`refresh_schema_cache`。
---
## 开发
- **代码风格**：`ruff`（参见`pyproject.toml`中的 `[tool.ruff]`）
- **可编辑安装**：
```bash
uv pip install -e .
```
然后，您可以在代码迭代时从环境中运行`ecom-mcp`。
---
## 许可证
MIT 许可证
版权 (c) 2025 Masoud Ahangary
特此授予任何人免费使用、复制、修改、合并、发布、分发、再授权和/或出售该软件的副本，以及允许任何人依照上述条件使用该软件。
上述版权声明和此许可声明应包含在所有副本或软件的重要部分中。
除非适用法律要求，否则软件不提供任何形式的保证，包括但不限于适销性、特定用途适用性和非侵权性。 在任何情况下，作者或版权持有人均不承担因软件或使用或其他交易而产生的任何索赔、损害或其他责任，无论是合同、侵权或其他原因。
---
## 贡献
欢迎提出问题和拉取请求。如果您添加了新工具，请包括：
- 预期模式假设
- 示例输出
- 安全注意事项（读写权限、超时、限制）
