闪

闪仓进销存MCP

JuhuoTechnology/FlashwarehouseMCP

0 Stars 2 次浏览更新于 2026-08-23

其他

该服务暂未提供标准配置，请参考 README 手动接入

服务介绍

flash_warehouse_cli (`fwh`)

一个跨平台的命令行工具和模型上下文协议服务器，用于闪仓 WMS（Flash Warehouse Management System）。单个静态二进制文件。无运行时依赖。支持 macOS、Linux 和 Windows。

fwh 允许 AI 代理（Claude Code, Cursor, Windsurf）查询和操作您的 WMS，同时人类用户也可以将其作为传统的 shell CLI 使用。

完整的 PC 功能对等。 认证、商品、仓库、警报、库存盘点、库存审批、账单（16 种类型 + 审核/拒绝 + 转换）、合作伙伴、员工+角色+权限、BI 仪表板、POS、设置、打印模板、AI、分类以及文件操作均已实现。23 个 CLI 顶级命令，44 个只读 MCP 工具，106 个带有 --enable-writes 的 MCP 工具。请参阅 MANUAL.md 获取完整操作手册。

安全模型（首先阅读）

fwh 围绕两个硬性规则设计：

先登录。 除了 login / logout / version / help 命令外，所有命令在没有会话文件存在的情况下都会快速失败。这在 CLI 根目录（PersistentPreRunE）中强制执行。
租户锁定。 WMS 后端使用的 binding_user_id 仅在登录时从服务器的登录响应中设置一次，并存储在一个未导出的 Go 结构字段中，该字段有 getter 但没有 setter。没有任何 CLI 标志、环境变量或 MCP 工具参数可以覆盖它。API 客户端是代码库中唯一读取它的位置（通过两个审核过的瓶颈点），并且单元测试断言了这一不变量。

WMS 后端没有 JWT、会话和服务器端租户——它信任客户端发送的任何 binding_user_id。fwh 是后端缺乏的安全边界。 如果它接受 binding_user_id 作为输入，代理可以通过猜测 ID 轻松读取或写入其他租户的数据。

您应该了解当前部署的其他属性：

默认后端是 http://8.155.11.178/flash_warehouse —— 纯 HTTP。第一次通过 HTTP 登录时，fwh login 会在 stderr 上打印一条警告。这是现有部署的一个属性，而不是 fwh 引入的。
密码以明文形式传输。服务器在比较之前使用 SHA-256 对其进行哈希处理。这与 PC 和移动客户端一致。
会话文件位于 ~/.config/fwh/session.json（macOS: ~/Library/Application Support/fwh/session.json; Windows: %AppData%\fwh\session.json），模式为 0600。

安装

从源代码安装（第一阶段开发）


cd flash_warehouse_cli

go build -o ./bin/fwh ./cmd/fwh

./bin/fwh version

需要 Go 1.22+。

一行命令安装（第四阶段 — 尚未发布）


# macOS / Linux

curl -fsSL https://.../install.sh | sh



# Windows (PowerShell)

irm https://.../install.ps1 | iex

快速开始


# 1. Log in (prompts for password if you omit --password)

fwh login --user 13800138000

# Password: ********

# logged in as 13800138000 (user_id=1) @ http://8.155.11.178/flash_warehouse



# 2. Verify the active session

fwh whoami

# user_id:   1

# username:  13800138000

# base_url:  http://8.155.11.178/flash_warehouse

# logged_at: 2026-04-11 15:53:57 CST



# 3. Query the data scoped to your account

fwh warehouse list

fwh goods list --page-size 10

fwh goods get 6954767410388

fwh goods search --barcode 6954767410388



# 4. Log out — deletes ~/.config/fwh/session.json

fwh logout

输出格式

每个数据命令都接受 --output table|json。默认值自动选择：终端上为 table，当 stdout 被管道传递时为 json —— 因此 fwh goods list | jq '.items[].goodsName' 可以正常工作。

用作 MCP 服务器

fwh mcp 在 stdio 上启动一个模型上下文协议服务器。LLM 代理（Claude Code, Cursor, Windsurf）可以调用以下工具。

前提条件

首先在 shell 中执行 fwh login。如果没有活动会话，MCP 服务器将拒绝启动——代理不能通过工具登录（对话历史记录将包含您的明文密码）。
将 fwh 添加到您的代理的 MCP 配置中。

Claude Code (`~/.claude/mcp.json`)


{

  "mcpServers": {

    "flash-warehouse": {

      "command": "/absolute/path/to/fwh",

      "args": ["mcp"]

    }

  }

}

要允许写操作：


{

  "mcpServers": {

    "flash-warehouse": {

      "command": "/absolute/path/to/fwh",

      "args": ["mcp", "--enable-writes"]

    }

  }

}

写操作是可选的。 代理对生产库存进行幻觉性的 bill_audit 调用是一个真实的运营事件。每个写操作工具描述都以 WARNING: 开头，因此模型的预飞行推理会揭示其破坏性。

工具清单摘要

44 个只读工具 始终可用（商品/仓库/警报/库存/账单/合作伙伴/员工/角色/BI/配置/账户/AI + whoami）
总共 106 个工具 当设置了 --enable-writes 时（添加创建/修改/删除/审核/拒绝/批准工具）请参阅 MANUAL.md §5 以获取按领域分组的完整工具清单。

会话撤销

如果您在 MCP 服务器仍在运行时执行 fwh logout，则服务器会在下一次工具调用时（它会重新统计会话文件）注意到这一点，并返回 session_revoked 错误。重新登录后，请重启 MCP 服务器。

项目布局


flash_warehouse_cli/

├── cmd/fwh/                   # tiny main.go entrypoint

├── internal/

│   ├── version/               # build-time metadata

│   ├── config/                # Session (tenant-lock), Config, paths

│   ├── api/                   # HTTP client — the ONLY package that reads session.UserID()

│   ├── service/               # shared business layer — CLI + MCP both call into this

│   ├── cli/                   # Cobra commands + auth gate

│   │   └── output/            # table/JSON rendering

│   └── mcp/                   # MCP tool handlers

└── go.mod

运行审计：


go test ./internal/api/ -v -run TestTenantLock

有两个测试强制执行租户锁定：

TestTenantLock_UserIDChokepoints — session.UserID() 在 api/client.go 中恰好被读取了三次（attachBinding / bindingPathSegment / bindingUserIDInt）。
TestTenantLock_NoForbiddenInputFields — 在 internal/{cli,mcp,service} 中任何地方都不存在结构标签 json:"binding_user_id"。

第三层 —— internal/mcp/schema.go 中的 validateInputShape —— 在程序启动时运行，并且如果任何已注册的工具输入类型包含禁止字段，则会引发 panic。

配置文件（可选）

如果您需要指向不同的后端（开发、预发布），请在 ~/.config/fwh/config.toml 处放置一个 TOML 文件：


base_url = "http://localhost:10086/flash_warehouse"

default_output = "table"

insecure = true   # suppress the plain-HTTP warning

所有字段都是可选的。fwh login --base-url ... 也可以在每次调用时覆盖。

路线图

v0.2 ✅ (当前) — 完整的 PC 功能对等：23 个 CLI 命令，44 个只读 + 106 个写入启用的 MCP 工具。完整的操作手册见 MANUAL.md。已在 darwin/linux/windows × amd64/arm64 上验证交叉编译。
下一步 — 基于 GoReleaser 的发布流水线 + install.sh / install.ps1 一行安装脚本，Homebrew tap，Scoop bucket。AI 工具的 SSE 流式传输。仓库侧后端清理（goods_picture_url，不一致的包装器类型）。

开发者笔记


# Build

go build -o ./bin/fwh ./cmd/fwh



# Run tests (includes tenant-lock audit)

go test ./...



# Typecheck only

go build ./...



# Cross-compile sanity (Phase 4 covers this with goreleaser)

GOOS=linux  GOARCH=amd64 go build -o ./bin/fwh-linux-amd64  ./cmd/fwh

GOOS=darwin GOARCH=arm64 go build -o ./bin/fwh-darwin-arm64 ./cmd/fwh

GOOS=windows GOARCH=amd64 go build -o ./bin/fwh.exe         ./cmd/fwh

独立测试环境

所有配置/会话路径都尊重 FWH_CONFIG_DIR 环境变量。在手动测试期间使用它来针对一次性配置运行 fwh：


export FWH_CONFIG_DIR=/tmp/fwh-sandbox

fwh login --user ...

查看源码项目主页

服务介绍

flash_warehouse_cli (fwh)