stock-mcp-server

Stock MCP 后端服务（NestJS 10 + Drizzle + PostgreSQL + Redis + MCP SDK 1.0） 当前版本：v0.3.0（JKY + Supor + 微信 Excel 三数据源已接入）

快速开始

# 1. 准备 .env
cp .env.example .env
# 按需修改 PG / Redis / JKY_* 配置

# 2. 启动依赖
docker compose up -d postgres redis   # 或复用 baojia_src 实例

# 3. 安装依赖
pnpm install

# 4. 数据库迁移（首次）
pnpm db:migrate

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

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

模块结构

src/
├── main.ts                    # NestJS 启动入口（HTTP + Swagger + SSE）
├── app.module.ts              # 全局模块
├── config/                    # 配置加载与 joi 校验
├── database/
│   ├── database.module.ts     # PG Pool + Drizzle 实例
│   ├── migrate.ts             # SQL 迁移执行器
│   └── schema/                # Drizzle TS schema（inventory / audit / source 枚举）
├── redis/
│   ├── redis.module.ts        # ioredis 客户端
│   └── redis.service.ts       # 通用 getJson/setJson/限流/分布式锁
├── common/
│   ├── scheduler/              # 统一调度器（node-cron + BullMQ）
│   ├── filters/               # 全局异常过滤
│   └── interceptors/          # 统一响应包装
├── modules/
│   ├── health/                # /health/live, /health/ready
│   ├── jky/                   # 吉客云 MCP 适配（签名/限流/重试/mock）
│   ├── supor/                 # 苏泊尔工厂适配（mock/http/csv 三模式）
│   ├── wechat-xlsx/           # 微信群 Excel 监听 + 解析 + webhook
│   ├── inventory/             # 库存核心查询（多源聚合 + 缓存 + stale 判定）
│   └── mcp-tools/             # MCP 工具注册（inventory.query 等 4 个工具）
└── mcp/
    ├── bootstrap.ts           # MCP 上下文启动器
    ├── stdio.ts               # Claude Desktop 直连入口
    └── sse.controller.ts      # 远端 MCP SSE + POST message

API 速览

详见 docs/api.md。

Method	Path	说明
GET	/api/v1/inventory/query?skus=SP-X100&qty=10	主查询（与 MCP 同源）
GET	/api/v1/inventory/list-suppliers?sku=SP-X100	列出所有仓库/供应商
GET	/api/v1/health/ready	健康检查（PG + Redis）
GET	/api/v1/health/live	存活探针
GET	/api/v1/docs	Swagger UI

MCP 工具

Tool	说明	实现版本
inventory.query	主查询；多源并发 + stale 判定；强制 AI 带 asOf 字段	✅ v0.2.0
inventory.list_suppliers	列仓库/供应商	✅ v0.2.0
inventory.ask_supplier	异步 RPA 询问	🚧 v0.4.0（接口已暴露，调用会抛错）
inventory.get_ask_status	轮询 RPA 询问状态	🚧 v0.4.0

数据源（v0.3.0）

来源	接入方式	默认状态
吉客云	openapi（签名调用）	✅ mock 可用；切 JKY_MOCK_MODE=false 切真实
苏泊尔工厂	cron（每 2h）+ 按需补数	✅ mock 可用；切 `SUPOR_MODE=http
微信群 Excel	webhook 被动 + 5min 轮询兜底	✅ webhook 已就绪

测试

pnpm test          # 单元测试
pnpm test:cov      # 覆盖率

设计约束

• 不引入向量检索——库存是结构化精确匹配
• 强制三层时间戳——as_of(必填) / ingested_at / created_at；INVENTORY_REQUIRE_AS_OF=true 时缺 as_of 抛错
• 陈旧阈值 30 分钟——超阈值自动标 stale=true 并尝试 JKY 实时补数
• API + MCP 同源——所有查询都走 InventoryService，避免语义分裂
• JKY 签名兼容 baojia_src——md5(appSecret + joined(sortedParams) + appSecret)，可直接复用 baojia 的 JkyClient 测试用例