WMS Item Public MCP

面向开发者、可被 AI Agent / Atlas / CLI 调用的 WMS API 能力封装。

项目概述

本项目是一个 WMS（仓库管理系统）的 MCP（Model Control Plane）实现，参考 Apifox MCP 模式，提供认证、EDI 导入、查询、文件上传、商品主数据等公共 API 能力封装。

功能特性

- ✅ 支持 npx 方式执行
- ✅ 面向接口开发 / 二次开发
- ✅ 未来可供 Atlas 或其他 AI Agent 接入
- ✅ 完整的 TypeScript 类型定义
- ✅ 支持动态 CLI 命令行调用
- ✅ 支持环境变量配置
- ✅ 标准MCP (stdio/JSON-RPC) 调用方式

安装

$3

``bash
npm install -g wms-item-public-mcp
`

$3

`bash
npm install wms-item-public-mcp
`

$3

`bash
npx wms-item-public-mcp --help
`

使用方法

$3

完整的使用帮助请查看 HELP.md 文件，包含：

- 动态 CLI 工具列表与用法
- 详细的参数说明
- 示例命令
- 环境变量配置
- 常见问题解答

$3

#### 1. 用户登录

`bash
wms-item-public-mcp list
wms-item-public-mcp describe post_v1_public_user_login
wms-item-public-mcp post_v1_public_user_login --param username=USERNAME --param password=PASSWORD
`

默认 baseUrl 为 https://wms-staging.item.com/api/public，也可以通过 --baseUrl 传入覆盖。

#### 2. 环境变量配置

可以通过环境变量配置全局参数，避免每次命令都输入（baseUrl 为空时会使用默认值）：

`bash
export WMS_BASE_URL=https://wms-staging.item.com/api/public
export WMS_TOKEN=YOUR_TOKEN

现在可以直接执行命令，无需重复输入 baseUrl 和 token


wms-item-public-mcp post_v1_public_edi_outbound_order_level_search_by_paging \
--param CompanyID=TEST_COM \
--param CustomerID=TEST_CUST \
--param FacilityID=TEST_FAC
`

#### 3. 标准MCP (stdio) 调用

当进程运行在非TTY模式时，服务进入标准MCP JSON-RPC模式，支持 initialize、tools/list、tools/call 等方法：

`json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"agent","version":"1.0.0"}}}
`

`json
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
`

`json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"post_v1_public_user_login","arguments":{"username":"USERNAME","password":"PASSWORD"},"options":{"baseUrl":"https://wms-staging.item.com/api/public"}}}
`

工具名称根据 OpenAPI 自动生成：_（非字母数字替换为 _），例如 post_v1_public_user_login。完整列表请见 mcp.json。
运行时工具列表同样支持 APIFOX_PATH_PREFIX 过滤（未设置时默认 /v1/public/）。
同一 MCP 进程内，若登录返回 onAuthToken，服务会自动缓存并用于后续调用（未显式传 token 时）。

`json
{"jsonrpc":"2.0","id":4,"method":"prompts/list"}
`

`json
{"jsonrpc":"2.0","id":5,"method":"prompts/get","params":{"name":"wms_call_flow","arguments":{"language":"zh","include_examples":"true"}}}
`

提示内容会指导模型基于接口定义生成真实可用的 HTTP 接口实现，而不是调用 MCP 工具。

如需强制“只提供接口定义、不允许调用工具”，可设置：

`bash
MCP_MODE=docs
`

该模式下 tools/list 仅保留文档工具，tools/call 只允许 openapi_doc，其余工具将返回禁用提示。
openapi_doc 可按 name/path/query 返回对应接口文档，并附带提示词（强调不要调用 MCP），用于让 AI 直接生成项目级 HTTP 调用代码。

API 文档

项目提供了完整的 OpenAPI 3.0 文档，位于 openapi.yaml 文件中。可以使用以下工具查看：

- Swagger UI
- Apifox
- Postman

开发指南

$3

`
├── src/
│ ├── client.ts # HTTP 客户端
│ ├── index.ts # CLI 入口
│ ├── cli.ts # 基于 OpenAPI 的动态 CLI
│ ├── openapi-tools.ts # OpenAPI -> MCP 工具映射
│ └── server.ts # MCP stdio 服务
├── dist/ # 编译输出目录
├── mcp.json # MCP 配置文件
├── openapi.yaml # OpenAPI 文档
├── package.json # 项目配置
└── tsconfig.json # TypeScript 配置
`

$3

使用 Apifox 本地导出链接同步 OpenAPI，并把快照保存到仓库，保证其他开发者/CI 可以直接使用：

`bash


默认使用本地导出链接

npm run sync:api

或显式指定导出链接

APIFOX_OPENAPI_URL="http://127.0.0.1:4523/export/openapi/2?version=3.0" npm run sync:api
`

同步脚本会：
- 保存快照到 api/openapi.apifox.yaml
- 覆盖 openapi.yaml
- 重新生成 mcp.json
建议将 api/openapi.apifox.yaml、openapi.yaml、mcp.json 一并提交，方便团队与CI保持一致。

可以通过环境变量过滤导出路径前缀（默认仅包含 /v1/public/）：

`bash
APIFOX_PATH_PREFIX="/v1/public/" npm run sync:api
`

如果手动导出了文件，也可以用文件路径同步：

`bash
APIFOX_OPENAPI_FILE="/path/to/openapi.yaml" npm run sync:api
`

$3

1. 克隆项目

`bash
git clone
cd wms-item-public-mcp
`

2. 安装依赖

`bash
npm install
`

3. 开发模式

`bash
npm run dev
`

4. 构建项目

`bash
npm run build
`

5. 运行测试

`bash
npm test
`

6. 本地链接测试

`bash
npm link
wms-item-public-mcp --help
`

$3

工具由 OpenAPI 自动生成，无需手动维护实体或工具定义：

1. 在 Apifox 中更新接口定义
2. 运行 npm run sync:api 更新 openapi.yaml 和 mcp.json`
3. MCP 工具列表自动生效（服务端会按文件变更自动刷新）

配置文件

$3

定义了 MCP 的基本信息和工具列表，包括：

- 工具名称
- 描述
- 输入参数 schema

$3

TypeScript 编译配置，设置了目标版本、输出目录等。

$3

项目依赖和脚本配置，包括：

- 生产依赖（如 commander）
- 开发依赖（如 typescript）
- 构建脚本

注意事项

1. 本项目包含查询与导入/上传等能力，调用前请确认业务权限与风险
2. 所有 API 调用需要有效的认证令牌
3. 请确保配置正确的 API 基础 URL
4. 建议使用环境变量管理敏感信息

版本历史

$3

- 初始版本
- 实现了物品详情获取功能
- 实现了物品搜索功能
- 实现了入库规则验证功能

许可证

ISC

联系方式

如有问题或建议，请联系项目维护者。