wms-item-public-mcp

v3.0.1

Published

24 days ago

Public APIs for auth, EDI import, queries, uploads, and item master data.

0High
0Medium
0Low

pickkkiy

wms mcp api cli

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) 调用方式

安装

全局安装

npm install -g wms-item-public-mcp

本地安装

npm install wms-item-public-mcp

使用 npx 执行

npx wms-item-public-mcp --help

使用方法

详细帮助文档

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

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

快速开始

1. 用户登录

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 为空时会使用默认值）：

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 等方法：

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

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

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

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

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

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

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

MCP_MODE=docs

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

API 文档

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

开发指南

项目结构

├── 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 配置

API 同步

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

# 默认使用本地导出链接
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/）：

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

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

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

开发流程

克隆项目

git clone <repository-url>
cd wms-item-public-mcp

安装依赖

npm install

开发模式

npm run dev

构建项目

npm run build

运行测试

npm test

本地链接测试

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

添加新工具

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

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

配置文件

mcp.json

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

工具名称
描述
输入参数 schema

tsconfig.json

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

package.json

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

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

注意事项

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

版本历史

v0.1.0

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

许可证

ISC

联系方式

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