用 AI Agent 管理仓库：闪仓 WMS 的 MCP 协议实战指南
闪仓 WMS 是国内首个支持 MCP 协议的仓库管理系统。通过 fwh 命令行工具，Claude Code、Cursor、Windsurf 等 AI Agent 可以直接用自然语言查询库存、创建单据、审批流程，同时通过登录前置、租户锁定、写操作opt-in三重安全模型保障数据安全。
当 AI Agent 遇上仓库管理
传统仓库管理系统的操作路径是固定的：打开浏览器，登录后台，逐个菜单点击，填写表单，提交。对于日常高频操作——查库存、建采购单、审批入库——这个流程重复且耗时。
如果仓库管理员可以直接对 AI 说"帮我查一下可口可乐的库存"，AI 就能立刻返回精确的库存数据，这将从根本上改变仓库管理的工作方式。
闪仓 WMS 通过实现 Model Context Protocol (MCP) 协议，让这个场景成为现实。据我们了解，闪仓是国内首个支持 MCP 的仓库管理系统。
什么是 MCP 协议
MCP (Model Context Protocol) 是 Anthropic 于 2024 年发布的开放协议，定义了 AI 模型与外部工具之间的标准化通信方式。简单来说，MCP 让 AI Agent 能够像调用函数一样操作外部系统——读取数据、执行写入、触发流程。
MCP 协议的核心设计包括：
- 工具注册：服务端向 AI 声明自己有哪些能力（工具），每个工具有名称、参数定义和描述
- 标准化调用：AI 通过 JSON-RPC 消息调用这些工具，获取结构化返回值
- stdio 传输：通过标准输入/输出通信，天然适合命令行工具集成
目前支持 MCP 的 AI 客户端包括 Claude Code (Anthropic 官方 CLI)、Cursor、Windsurf 等主流 AI 编程工具。
fwh：闪仓的 CLI 与 MCP 服务端
闪仓的 MCP 能力由命令行工具 fwh (Flash Warehouse CLI) 提供。fwh 是一个用 Go 编写的静态二进制文件，无运行时依赖，支持 macOS、Linux 和 Windows。
fwh 同时具备两个身份：
- 传统 CLI 工具：23 个顶级命令，人工在终端直接操作仓库系统
- MCP 服务端：通过
fwh mcp启动，向 AI Agent 暴露 44 个只读工具和 106 个（含写入）工具
在 Claude Code 中配置
在 ~/.claude/mcp.json 中添加以下配置：
{
"mcpServers": {
"flash-warehouse": {
"command": "/absolute/path/to/fwh",
"args": ["mcp"]
}
}
}
如果需要允许写操作（创建单据、审批等），将 args 改为：
"args": ["mcp", "--enable-writes"]
Cursor 和 Windsurf 的配置格式完全相同。
实际使用场景
配置完成后，你可以在 AI 对话中直接用自然语言操作仓库：
- "查一下可口可乐的库存" -- AI 调用
goods_list工具，按名称模糊搜索，返回匹配商品的库存数量和仓库位置 - "今天的销售额是多少" -- AI 调用
bi_today_sales_revenue，返回当日营收和订单数 - "帮我建一张采购入库单" -- AI 调用
purchase_input_create，按你提供的商品和数量生成单据 - "审批这张单据" -- AI 调用
bill_audit，完成单据审批流程 - "哪些商品库存低于警戒线" -- AI 调用
alert_overview，返回库存预警汇总
每个工具都返回结构化的 JSON 数据，AI 可以直接解析并以自然语言呈现结果。
三重安全模型
让 AI Agent 操作生产数据，安全性是第一要务。fwh 围绕三条硬性规则设计了安全模型：
第一层：登录前置 (Login-first)
MCP 服务端在启动时强制要求已有登录会话。必须先在终端执行 fwh login，服务端才能启动。这意味着 AI Agent 永远无法自行登录——登录凭据不会出现在对话历史中。
fwh login --user 13800138000
# Password: ********
# logged in as 13800138000 (user_id=1)
第二层：租户锁定 (Tenant-locked)
binding_user_id 是闪仓 WMS 隔离多租户数据的核心字段。在 fwh 中，这个值在登录时从服务端响应中获取，存储在 Go 结构体的未导出字段中，只有 getter 没有 setter。没有任何 CLI 参数、环境变量或 MCP 工具参数可以覆盖它。
源码级审计测试 TestTenantLock_UserIDChokepoints 在每次构建时验证：session.UserID() 只在 api/client.go 的 3 个固定位置被读取。任何新的读取点都会触发测试失败。
第三层：写操作 opt-in
fwh mcp 默认只注册只读工具（44 个）。写入工具（创建、修改、删除、审批）只在显式传入 --enable-writes 时才注册。未注册的工具在 MCP 协议层面根本不存在——AI 不可能调用一个不存在的工具。
此外，每个写入工具的描述都以 WARNING: 开头，确保 AI 在推理阶段就意识到操作的破坏性。例如：
WARNING: APPROVE a bill. Commits inventory changes, cannot be undone.
工具覆盖范围
fwh 的 MCP 工具覆盖了闪仓 PC 端的全部核心功能：
| 业务域 | 只读工具 | 写入工具 |
|---|---|---|
| 商品管理 | goods_list, goods_get, goods_search_barcode, goods_amount | goods_create, goods_modify, goods_delete |
| 仓库管理 | warehouse_list | warehouse_create, warehouse_modify, warehouse_delete |
| 单据（16种类型） | bill_list, bill_search, bill_info_by_type | 采购/销售/调拨创建、审批、驳回、转换（共 23 个工具） |
| BI 看板 | bi_total_value, bi_today_sales_revenue 等 8 个 | -- |
| 库存预警 | alert_overview, alert_list, alert_count | alert_set_config, alert_refresh |
| 盘点 | check_task_list, check_task_items 等 5 个 | check_task_create, check_task_finish 等 4 个 |
| 收银 POS | -- | pos_sell |
| 员工与权限 | staff_list, role_list, power_list 等 8 个 | staff_create, role_bind 等 12 个 |
与传统操作方式的对比
以"查询并补货"这个日常操作为例：
传统方式：打开浏览器 -> 登录系统 -> 进入库存预警页面 -> 找到低库存商品 -> 切换到采购模块 -> 填写采购单 -> 提交。耗时约 5-10 分钟。
MCP 方式：在 Claude Code 中说"帮我检查库存预警，对低于警戒线的商品自动生成采购入库单"。AI 按顺序调用 alert_overview -> alert_list -> purchase_input_create，全程约 30 秒。
快速开始
# 1. 构建 fwh（需要 Go 1.22+）
cd flash_warehouse_cli
go build -o ./bin/fwh ./cmd/fwh
# 2. 登录
./bin/fwh login --user 你的手机号
# 3. 验证身份
./bin/fwh whoami
# 4. 配置 Claude Code（编辑 ~/.claude/mcp.json）
# 5. 重启 Claude Code，开始用自然语言管理仓库
总结
MCP 协议为仓库管理带来了全新的交互范式。闪仓 WMS 通过 fwh 工具的 44 个只读和 106 个全量 MCP 工具，实现了 PC 端功能的完整覆盖，同时通过登录前置、租户锁定、写操作 opt-in 三重安全模型，确保 AI Agent 在生产环境中的操作安全可控。
闪仓 WMS 完全免费，访问 flashwarehouse.cn 了解更多。
