Public APIs for auth, EDI import, queries, uploads, and item master data.
npm install 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) 调用方式
``bash`
npm install -g wms-item-public-mcp
`bash`
npm install wms-item-public-mcp
`bash`
npx wms-item-public-mcp --help
完整的使用帮助请查看 HELP.md 文件,包含:
- 动态 CLI 工具列表与用法
- 详细的参数说明
- 示例命令
- 环境变量配置
- 常见问题解答
#### 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
#### 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`定义了 MCP 的基本信息和工具列表,包括:
- 工具名称
- 描述
- 输入参数 schema
TypeScript 编译配置,设置了目标版本、输出目录等。
项目依赖和脚本配置,包括:
- 生产依赖(如 commander)
- 开发依赖(如 typescript)
- 构建脚本
1. 本项目包含查询与导入/上传等能力,调用前请确认业务权限与风险
2. 所有 API 调用需要有效的认证令牌
3. 请确保配置正确的 API 基础 URL
4. 建议使用环境变量管理敏感信息
- 初始版本
- 实现了物品详情获取功能
- 实现了物品搜索功能
- 实现了入库规则验证功能
ISC
如有问题或建议,请联系项目维护者。