MCP 服务器

Stock MCP

Unifies inventory data from four sources (Jikeyun, Supor factory, WeChat Excel, RPA) with timestamps, and exposes MCP tools for AI agents to query stock levels.

README

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 测试用例