Acmezone Data MCP

Acmezone Data MCP 是一个面向公司内部 Amazon 经营数据的只读 MCP 服务。它把销量、库存、库存金额和财务数据封装成 19 个 Tool，供 WorkBuddy、MCP Inspector 及其他兼容 MCP 的客户端调用。

两阶段模块化重构已经完成：Tool 接口层与 Repository 数据访问层均已落地，并通过重构前后完整回归。实施记录请参阅 重构计划。

当前状态

• Python 3.12
• MCP Streamable HTTP
• 容器监听：0.0.0.0:8000
• 无环境变量配置，数据路径、工作表名和端口目前写在 settings.py 中
• 19 个 Tool 已按业务领域拆分到 8 个模块，既有接口保持兼容
• Excel 和 SQLite 的直接读取已集中到 Repository 层
• 19 个 Tool 均发布结构化输出 Schema、参数枚举/范围和只读标记
• Excel Snapshot 按文件大小和纳秒级修改时间缓存，源文件变化后自动失效
• Excel 以 read_only=True、data_only=True 打开
• SQLite 财务库通过 mode=ro 只读连接

当前目录：

mcp/
├─ mcp_server.py
├─ settings.py
├─ core/
├─ tools/
├─ repositories/              # Excel、销售、库存和财务数据访问
├─ tests/
├─ scripts/
├─ docs/
├─ requirements.txt
└─ Dockerfile

数据源

业务数据	容器路径	工作表/数据表	容器权限
历史销量与预测	/storage/sales_data.xlsx	data	只读
当前销售	/storage/sales.xlsx	Sheet1	只读
当前库存	/storage/inventory.xlsx	Sheet1	只读
库存数量与金额	/storage/inventory_value.xlsx	库存情况	只读
历史财务	/finance/finance_profit.db	SQLite	只读

源文件修改时间只用于判断数据新鲜度，不再用于划分实际与预测。实际/预测分界统一使用公司时区 Asia/Shanghai 的当前月份。财务数据另外使用数据库中的报表月份和上传时间表示数据截止期。

Docker 部署方式

当前 NAS 容器使用以下存储挂载：

NAS 目录或文件	容器位置	权限	用途
共享文件夹/docker1/AcmezoneWeb/mcp	/app	读写	MCP 源代码
共享文件夹/docker1/AcmezoneWeb/backend/app/finance_profit.db	/finance/finance_profit.db	只读	财务数据库
共享文件夹/docker1/AcmezoneWeb/data	/storage	只读	Excel 数据文件

容器执行：

python /app/mcp_server.py

当前 Dockerfile 只安装依赖，不复制源代码，这是因为运行时会把整个 MCP 项目目录挂载到 /app。因此该镜像如果脱离 /app 挂载单独运行，将找不到 mcp_server.py；这是当前部署方式的已知前提。

容器内服务监听 8000 端口。NAS 对外端口以容器管理界面的“端口映射”配置为准。

Tool 概览

产品

• search_product
• get_product_catalog_summary
• get_parent_children
• get_product_overview
• compare_product_overviews

销售

• get_sales_history
• get_current_sales
• get_sales_ranking
• get_sales_trend_ranking

库存

• get_inventory
• get_inventory_value
• get_inventory_ranking

财务、预测和系统

• get_finance_history
• get_finance_ranking
• get_replenishment_forecast
• get_product_batch
• filter_products
• get_data_source_status
• get_data_quality_report

各 Tool 的参数和用途参阅 Tool 接口参考。

安装依赖

pip install -r requirements.txt

当前依赖：

• mcp[cli]==2.0.0
• openpyxl==3.1.5
• pydantic==2.13.4

核心运行依赖已锁定版本。升级依赖或重建镜像前，仍应先运行完整回归。

启动

在具备 /storage 和 /finance 数据挂载的容器内执行：

python /app/mcp_server.py

本地直接运行虽然可以启动服务，但如果不存在对应的绝对数据路径，数据查询 Tool 会返回数据文件不存在或不可访问。

维护原则

• 不修改原始 Excel 或财务数据库。
• Tool 只读取和整理真实业务数据，不替代 AI 进行经营判断。
• 修改 Tool 时应保持名称、参数和返回结构的向后兼容。
• 重构过程中每迁移一个模块，都应重新检查 Tool 注册数量和代表性响应。
• 修改 Tool 时必须同步更新接口参考、架构说明和员工使用文档。

文档一致性检查：

python scripts/check_documentation_consistency.py

项目文档

• Tool 接口参考
• 模块化重构计划
• 当前架构说明
• 员工快速使用指南
• 员工使用手册—完整参考
• 文档同步维护规则