stock-mcp-server

库存查询 MCP 后端服务，定位为 paxaq/baojia_src 的延伸项目。

本项目把吉客云库存、苏泊尔工厂库存、微信群供应商 Excel、供应商人工/RPA 询问统一到一套 REST API 与 MCP 工具中。上游 AI 或业务系统只需要调用统一库存入口，不直接理解每个数据源的差异。

当前主线版本：v0.6.0

文档入口

Related MCP server: Inventory Management AI MCP

快速开始

# 1. 准备环境变量
cp .env.example .env

# 2. 准备 PostgreSQL / Redis
# 推荐复用 baojia_src 的实例，但使用独立 PG_SCHEMA 与 Redis DB。

# 3. 安装依赖
pnpm install

# 4. 执行数据库迁移
pnpm db:migrate

# 5. 启动 API + SSE MCP
pnpm start:dev

# 6. 单独启动 stdio MCP（Claude Desktop 等本地客户端）
pnpm mcp:stdio

默认服务地址：

• REST API：http://localhost:7300/api/v1

• Swagger：http://localhost:7300/api/docs

• MCP SSE：由 MCP_SSE_PATH 控制，默认 /mcp/sse

容器部署

podman build -t stock-mcp:latest .
podman run -d --name stock-mcp --env-file stock-mcp.env -p 7300:7300 stock-mcp:latest

当前生产容器启用健康检查、供应商库存文件监听、每天 9:30 供应商群提醒、DeepSeek 表头映射兜底、库存查询 REST API 和 MCP 查询工具。管理端、RPA 问供应商闭环、苏泊尔/吉客云实时库存仍未进入生产主链路。

核心能力

重要设计约束

• 库存是结构化精确匹配，不引入向量检索。

• API 与 MCP 必须同源，统一走库存服务，避免同一问题在不同入口语义不一致。

• 所有客户可见库存回复必须带 asOf 或 customerReply 中的“数据截至”信息。

• 供应商库存按供应商/仓库展示，不跨供应商简单求和。

• 陈旧库存默认阈值 30 分钟，超阈值标记 stale=true。

• 与 baojia_src 共用基础设施时，要用独立 schema、Redis DB 和 key prefix 隔离。

测试

pnpm test
pnpm test:cov

只读联调诊断

验证 baojia_src 供应商群 Excel 文件链路时，先运行只读诊断脚本：

pnpm diagnose:wechat-files

该脚本只查询 baojia_src 的微信消息和媒体文件，检查文件路径可读性并 dry-run 解析 Excel，不写任何业务表。

当前测试主要覆盖：

• 吉客云签名

• 苏泊尔适配器 mock 模式，不能代表真实苏泊尔库存链路已打通

• 微信 Excel 解析基础逻辑，不能代表真实微信群文件环境已验收

• 库存聚合基础逻辑