item-wms-public-api-tool 2.0.4

package/HELP.md

@@ -0,0 +1,297 @@
+# WMS Item Public MCP 使用帮助
+
+## 目录
+
+- [安装](#安装)
+- [CLI 命令使用](#cli-命令使用)
+- [环境变量配置](#环境变量配置)
+- [示例命令](#示例命令)
+- [常见问题](#常见问题)
+- [API 列表](#api-列表)
+
+## 安装
+
+### 全局安装
+
+```bash
+npm install -g item-wms-public-api-tool
+```
+
+### 本地安装
+
+```bash
+npm install item-wms-public-api-tool
+```
+
+### 使用 npx 执行
+
+```bash
+npx item-wms-public-api-tool --help
+```
+
+## CLI 命令使用
+
+### 基本语法
+
+```bash
+item-wms-public-api-tool <toolName> [options]
+# 或
+item-wms-public-api-tool call <toolName> [options]
+```
+
+工具名称根据 OpenAPI 自动生成：`<method>_<path>`（非字母数字替换为 `_`），例如 `post_v1_public_user_login`。
+
+### 动态工具发现
+
+```bash
+item-wms-public-api-tool list
+item-wms-public-api-tool describe <toolName>
+```
+
+### 参数传递方式
+
+```bash
+# 单个字段（可重复）
+item-wms-public-api-tool post_v1_public_user_login --param username=test --param password=pass
+
+# 直接传 JSON
+item-wms-public-api-tool post_v1_public_user_login --json '{"username":"test","password":"pass"}'
+
+# 从文件读取 JSON
+item-wms-public-api-tool post_v1_public_user_login --file ./payload.json
+```
+
+### 全局选项
+
+| 选项 | 描述 | 示例 |
+|------|------|------|
+| `--baseUrl` | API 基础 URL（默认 `https://wms-staging.item.com/api/public`） | `--baseUrl https://wms-staging.item.com/api/public` |
+| `--token` | 认证令牌（支持原始 token 或 `Bearer ...`） | `--token YOUR_TOKEN` |
+| `--companyId` | 默认 CompanyID（请求包含该字段时自动填充，默认 `LT`） | `--companyId LT` |
+| `--facilityId` | 默认 FacilityID（请求包含该字段时自动填充，默认 `889`） | `--facilityId 889` |
+| `--customerId` | 默认 CustomerID（请求包含该字段时自动填充，默认 `FLAANT0001`） | `--customerId FLAANT0001` |
+| `--help` | 显示帮助信息 | `--help` |
+| `--version` | 显示版本信息 | `--version` |
+
+## 环境变量配置
+
+| 环境变量 | 描述 | 示例 |
+|----------|------|------|
+| `WMS_BASE_URL` | API 基础 URL（可选，覆盖默认值） | `export WMS_BASE_URL=https://wms-staging.item.com/api/public` |
+| `WMS_TOKEN` | 认证令牌 | `export WMS_TOKEN=YOUR_TOKEN` |
+| `WMS_COMPANY_ID` | 默认 CompanyID（覆盖默认 `LT`） | `export WMS_COMPANY_ID=LT` |
+| `WMS_FACILITY_ID` | 默认 FacilityID（覆盖默认 `889`） | `export WMS_FACILITY_ID=889` |
+| `WMS_CUSTOMER_ID` | 默认 CustomerID（覆盖默认 `FLAANT0001`） | `export WMS_CUSTOMER_ID=FLAANT0001` |
+
+说明：当接口包含 CompanyID/FacilityID/CustomerID 且请求未显式传递时，会自动使用配置值（未配置时使用默认值）。
+
+### 示例
+
+```bash
+# 设置环境变量
+export WMS_BASE_URL=https://wms-staging.item.com/api/public
+export WMS_TOKEN=YOUR_TOKEN
+export WMS_COMPANY_ID=LT
+export WMS_FACILITY_ID=889
+export WMS_CUSTOMER_ID=FLAANT0001
+
+# 现在可以直接执行命令，无需重复输入 baseUrl、token、CompanyID、FacilityID、CustomerID
+item-wms-public-api-tool post_v1_public_edi_outbound_order_level_search_by_paging \
+  --json '{"Paging":{"page":1,"pageSize":10}}'
+```
+
+## 示例命令
+
+以下示例中的 `--baseUrl` 可省略，默认使用 `https://wms-staging.item.com/api/public`。
+
+### 1. 列出工具
+
+```bash
+item-wms-public-api-tool list
+```
+
+### 2. 用户登录
+
+```bash
+item-wms-public-api-tool post_v1_public_user_login --param username=testuser --param password=testpass
+```
+
+### 3. 按订单维度查询订单
+
+```bash
+item-wms-public-api-tool post_v1_public_edi_outbound_order_level_search_by_paging \
+  --json '{"CompanyID":"TEST_COM","CustomerID":"TEST_CUST","FacilityID":"TEST_FAC","Paging":{"page":1,"pageSize":10}}' \
+  --token YOUR_TOKEN
+```
+
+### 4. 批量导入物品主数据
+
+```bash
+item-wms-public-api-tool post_v1_public_edi_item_master_import \
+  --json '{"items":[{"itemID":"ITEM001","itemDescription":"测试物品","companyId":"TEST_COM","customerId":"TEST_CUST"}]}' \
+  --token YOUR_TOKEN
+```
+
+## 常见问题
+
+### Q: 命令执行时提示 "command not found"
+
+A: 请确保已正确安装MCP，或使用npx方式执行：
+
+```bash
+npx item-wms-public-api-tool --help
+```
+
+### Q: 如何获取认证令牌
+
+A: 通过登录接口获取：
+
+```bash
+item-wms-public-api-tool post_v1_public_user_login --param username=YOUR_USERNAME --param password=YOUR_PASSWORD
+```
+
+提示：在 MCP stdio 模式下，登录返回 `onAuthToken` 后会自动缓存到进程内存，后续调用未显式传 `--token` 时会自动使用；CLI 每次命令仍需传 `--token` 或设置 `WMS_TOKEN`。
+
+### Q: API调用失败，提示 "Unauthorized"
+
+A: 可能的原因及解决方法：
+
+1. **用户名或密码不正确**：请检查用户名和密码是否正确。
+2. **baseUrl配置错误**：请确保使用了正确的API基础URL：`https://wms-staging.item.com/api/public`。
+3. **令牌过期或无效**：请重新获取令牌：
+
+```bash
+# 对于WMS认证
+item-wms-public-api-tool post_v1_public_user_login --param username=YOUR_USERNAME --param password=YOUR_PASSWORD
+```
+
+### Q: 如何查看特定命令的帮助
+
+A: 使用 `describe` 查看接口详情，或使用 `--help` 查看命令用法：
+
+```bash
+item-wms-public-api-tool describe post_v1_public_edi_outbound_order_level_search_by_paging
+item-wms-public-api-tool post_v1_public_edi_outbound_order_level_search_by_paging --help
+```
+
+### Q: 如何从文件读取JSON数据
+
+A: 使用命令行参数直接传递JSON字符串，或通过脚本读取文件内容后传递：
+
+```bash
+# 直接传递JSON
+item-wms-public-api-tool post_v1_public_edi_item_master_import --json '{"items":[{"itemID":"ITEM001","itemDescription":"测试物品"}]}' --token YOUR_TOKEN
+
+# 或使用文件
+item-wms-public-api-tool post_v1_public_edi_item_master_import --file items.json --token YOUR_TOKEN
+```
+
+## API 列表
+
+CLI 工具列表与 OpenAPI 保持一致，运行时自动生成。请使用以下命令查看：
+
+```bash
+item-wms-public-api-tool list
+item-wms-public-api-tool describe <toolName>
+```
+
+## 配置文件
+
+### mcp.json
+
+定义了MCP的基本信息和工具列表，包括：
+
+- 工具名称
+- 描述
+- 输入参数schema
+
+### openapi.yaml
+
+完整的API文档，包含所有接口的：
+
+- 请求参数
+- 响应格式
+- 示例
+
+## 开发相关
+
+### API 同步
+
+使用 Apifox 本地导出链接同步 OpenAPI，并把快照保存到仓库：
+
+```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`
+
+可以通过环境变量过滤导出路径前缀（默认仅包含 `/v1/public/`）：
+
+```bash
+APIFOX_PATH_PREFIX="/v1/public/" npm run sync:api
+```
+
+运行时 MCP 工具列表同样支持该前缀过滤。
+
+如果手动导出了文件，也可以用文件路径同步：
+
+```bash
+APIFOX_OPENAPI_FILE="/path/to/openapi.yaml" npm run sync:api
+```
+
+### 本地开发
+
+```bash
+# 安装依赖
+npm install
+
+# 开发模式，实时编译
+npm run dev
+
+# 构建项目
+npm run build
+
+# 类型检查
+npx tsc
+
+# 本地链接测试
+npm link
+item-wms-public-api-tool --help
+```
+
+### 添加新工具
+
+工具由 OpenAPI 自动生成，无需手动维护实体或工具定义：
+
+1. 在 Apifox 中更新接口定义
+2. 运行 `npm run sync:api` 更新 `openapi.yaml` 和 `mcp.json`
+3. MCP 工具列表自动生效（服务端会按文件变更自动刷新）
+
+## 注意事项
+
+1. 所有API调用需要有效的认证令牌
+2. 请确保配置正确的API基础URL
+3. 建议使用环境变量管理敏感信息
+4. 本项目包含查询与导入/上传等能力，调用前请确认业务权限与风险
+5. 所有命令都支持 `--help` 选项查看详细帮助
+
+## 版本历史
+
+### v0.1.0
+
+- 初始版本
+- 实现了13个WMS Public API接口
+- 支持动态CLI命令行调用
+- 完整的TypeScript类型定义
+- 支持环境变量配置
+
+## 许可证
+
+ISC

package/README.md

@@ -0,0 +1,259 @@
+# 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 item-wms-public-api-tool
+```
+
+### 本地安装
+
+```bash
+npm install item-wms-public-api-tool
+```
+
+### 使用 npx 执行
+
+```bash
+npx item-wms-public-api-tool --help
+```
+
+## 使用方法
+
+### 详细帮助文档
+
+完整的使用帮助请查看 [HELP.md](HELP.md) 文件，包含：
+
+- 动态 CLI 工具列表与用法
+- 详细的参数说明
+- 示例命令
+- 环境变量配置
+- 常见问题解答
+
+### 快速开始
+
+#### 1. 用户登录
+
+```bash
+item-wms-public-api-tool list
+item-wms-public-api-tool describe post_v1_public_user_login
+item-wms-public-api-tool 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
+export WMS_COMPANY_ID=LT
+export WMS_FACILITY_ID=889
+export WMS_CUSTOMER_ID=FLAANT0001
+
+# 当接口包含 CompanyID/FacilityID/CustomerID 且请求未显式传递时，会自动使用配置值（未配置时使用默认值）。
+
+# 现在可以直接执行命令，无需重复输入 baseUrl/token/CompanyID/FacilityID/CustomerID
+item-wms-public-api-tool post_v1_public_edi_outbound_order_level_search_by_paging \
+  --json '{"Paging":{"page":1,"pageSize":10}}'
+```
+
+#### 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 自动生成：`<method>_<path>`（非字母数字替换为 `_`），例如 `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 工具。
+
+## API 文档
+
+项目提供了完整的 OpenAPI 3.0 文档，位于 `openapi.yaml` 文件中。可以使用以下工具查看：
+
+- [Swagger UI](https://swagger.io/tools/swagger-ui/)
+- [Apifox](https://apifox.com/)
+- [Postman](https://www.postman.com/)
+
+## 开发指南
+
+### 项目结构
+
+```
+├── 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 可以直接使用：
+
+```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
+```
+
+### 开发流程
+
+1. 克隆项目
+
+```bash
+git clone <repository-url>
+cd item-wms-public-api-tool
+```
+
+2. 安装依赖
+
+```bash
+npm install
+```
+
+3. 开发模式
+
+```bash
+npm run dev
+```
+
+4. 构建项目
+
+```bash
+npm run build
+```
+
+5. 运行测试
+
+```bash
+npm test
+```
+
+6. 本地链接测试
+
+```bash
+npm link
+item-wms-public-api-tool --help
+```
+
+### 添加新工具
+
+工具由 OpenAPI 自动生成，无需手动维护实体或工具定义：
+
+1. 在 Apifox 中更新接口定义
+2. 运行 `npm run sync:api` 更新 `openapi.yaml` 和 `mcp.json`
+3. MCP 工具列表自动生效（服务端会按文件变更自动刷新）
+
+## 配置文件
+
+### mcp.json
+
+定义了 MCP 的基本信息和工具列表，包括：
+
+- 工具名称
+- 描述
+- 输入参数 schema
+
+### tsconfig.json
+
+TypeScript 编译配置，设置了目标版本、输出目录等。
+
+### package.json
+
+项目依赖和脚本配置，包括：
+
+- 生产依赖（如 commander）
+- 开发依赖（如 typescript）
+- 构建脚本
+
+## 注意事项
+
+1. 本项目包含查询与导入/上传等能力，调用前请确认业务权限与风险
+2. 所有 API 调用需要有效的认证令牌
+3. 请确保配置正确的 API 基础 URL
+4. 建议使用环境变量管理敏感信息
+
+## 版本历史
+
+### v0.1.0
+
+- 初始版本
+- 实现了物品详情获取功能
+- 实现了物品搜索功能
+- 实现了入库规则验证功能
+
+## 许可证
+
+ISC
+
+## 联系方式
+
+如有问题或建议，请联系项目维护者。

package/api/README.md

@@ -0,0 +1,9 @@
+# API Snapshot
+
+This directory stores the OpenAPI snapshot exported from Apifox.
+
+Generate or refresh the snapshot with:
+
+```bash
+npm run sync:api
+```