内容
# Logiwa MCP 服务器
一个适用于 **Logiwa IO (WMS)** API 的 [MCP](https://modelcontextprotocol.io) 服务器。它允许 MCP 客户端（Claude Desktop、Claude Code 等）通过描述良好的工具与您的 Logiwa 仓库数据一起工作：产品、库存、发货/采购/退货订单、仓库和地点、客户/供应商/零售商、关键报告和参考查找。
- **语言/传输方式：** TypeScript · stdio
- **API 基址：** `https://myapi.logiwa.com` （可通过 `LOGIWA_BASE_URL` 重写）
- **身份验证：** JWT bearer — 通过电子邮件/密码或预先颁发的令牌获取
- **工具：** 32 个（参见 [工具](#工具)）
使用 [`mcp-builder`](https://github.com/anthropics/skills/tree/main/skills/mcp-builder) 技能构建。
---
## 先决条件
- **Node.js ≥ 18**
- 一个 **Logiwa IO 账户。** 每个用户都使用自己的凭证（电子邮件/密码或预先颁发的 JWT）进行身份验证。服务器代表配置的凭证用户调用 Logiwa API — **此仓库中不包含凭证**，因此每个用户必须提供自己的凭证。
## 设置
```bash
git clone https://github.com/cgtykctn/Logiwa-IO-WMS--MCP-.git
cd Logiwa-IO-WMS--MCP-
npm install
npm run build
```
然后在不需要凭证的情况下验证构建：
```bash
node dist/index.js --list-tools # 打印 32 个已注册的工具
```
## 身份验证
服务器通过 JWT bearer 令牌进行身份验证。通过环境变量提供凭证（参见 [`.env.example`](./.env.example)）：
| 变量 | 描述 |
|---|---|
| `LOGIWA_EMAIL` + `LOGIWA_PASSWORD` | **推荐。** 服务器将这些信息发送到 `/v3.1/Authorize/token`，缓存返回的 JWT，并在 401 时自动重新身份验证。 |
| `LOGIWA_API_TOKEN` | 预先颁发的 JWT。如果设置，它将优先使用，不会进行登录调用。 |
| `LOGIWA_BASE_URL` | 可选。API 基址 URL（默认为 `https://myapi.logiwa.com`）。 |
| `LOGIWA_TIMEOUT_MS` | 可选。每个请求的超时时间（毫秒）（默认为 `30000`）。 |
凭证仅从进程环境中读取 — 不会写入磁盘或记录。
## 在 MCP 客户端中注册
> 将 `/absolute/path/to/Logiwa-IO-WMS--MCP-` 替换为克隆仓库的实际路径，并使用您自己的 Logiwa 电子邮件/密码。服务器在本地（stdio）与 MCP 客户端一起运行 — 每个用户都在自己的机器上安装和配置。
### Claude Code（CLI）
```bash
claude mcp add logiwa \
--env LOGIWA_EMAIL=you@example.com \
--env LOGIWA_PASSWORD=your-password \
-- node "/absolute/path/to/Logiwa-IO-WMS--MCP-/dist/index.js"
```
### Claude Desktop
添加到 `claude_desktop_config.json`（设置 → 开发人员 → 编辑配置）：
```json
{
"mcpServers": {
"logiwa": {
"command": "node",
"args": ["/absolute/path/to/Logiwa-IO-WMS--MCP-/dist/index.js"],
"env": {
"LOGIWA_EMAIL": "you@example.com",
"LOGIWA_PASSWORD": "your-password"
}
}
}
}
```
编辑后重启客户端。然后，工具将出现在 `logiwa` 服务器下。
## 工具
所有列表/报告工具均使用 `page`（1 为基准）和 `page_size`（≤200）进行分页，并接受 `response_format`（默认为 `markdown`，或使用 `json` 获取完整的结构化数据）。Logiwa 的列表端点仅按页面索引分页（无服务器端文本筛选），因此请遍历结果或使用 `get`/`lookup` 工具，当您已经知道标识符时。使用工具公开 API 所需的字段，以及一个 `additional_fields` 出口，用于 Logiwa 正文中的任何其他字段。
**产品** — `logiwa_list_products`、`logiwa_get_product`、`logiwa_create_product`、`logiwa_update_product`
**库存** — `logiwa_list_inventory`、`logiwa_add_inventory`、`logiwa_adjust_inventory`、`logiwa_remove_inventory`、`logiwa_transfer_inventory`
**发货订单** — `logiwa_list_shipment_orders`、`logiwa_get_shipment_order`、`logiwa_create_shipment_order`、`logiwa_update_shipment_order`、`logiwa_cancel_shipment_order`、`logiwa_ship_shipment_orders`
**采购订单** — `logiwa_list_purchase_orders`、`logiwa_get_purchase_order`、`logiwa_create_purchase_order`、`logiwa_receive_purchase_order`
**退货订单** — `logiwa_list_return_orders`、`logiwa_create_return_order`、`logiwa_cancel_return_order`
**仓库** — `logiwa_list_warehouses`、`logiwa_list_warehouse_locations`
**合作伙伴** — `logiwa_list_customers`、`logiwa_list_vendors`、`logiwa_list_retailers`
**报告** — `logiwa_report_total_inventory`、`logiwa_report_shipment_history`、`logiwa_report_receiving_history`、`logiwa_report_available_to_promise`
**查找** — `logiwa_lookup`（客户端、仓库、类型、原因、承运商等）
> 提示：首先使用 `logiwa_lookup` 解析 `clientIdentifier`、类型名称和货币 ID，这些是创建/更新工具所需的。
## 开发
```bash
npm run dev # tsx 监视（自动重新加载）
npm run build # tsc -> dist/
npm start # node dist/index.js
npx @modelcontextprotocol/inspector node dist/index.js # 交互式测试
```
## 项目结构
```
src/
├── index.ts # 入口点：连接工具、stdio 传输、--list-tools
├── constants.ts # 基址 URL、限制、默认值
├── types.ts # 响应信封类型
├── registry.ts # 注册工具包装器，记录工具名称
├── services/
│ ├── client.ts # 身份验证（令牌获取 + 缓存 + 401 重试）和 HTTP
│ └── format.ts # 列表/对象格式化、分页、截断、错误消息
├── schemas/
│ └── common.ts # 共享 Zod 片段（分页、行项目、包装）
└── tools/ # 每个域一个文件
├── products.ts inventory.ts shipmentOrders.ts purchaseOrders.ts
├── returnOrders.ts warehouses.ts partners.ts reports.ts helpers.ts
└── simpleList.ts # 简单只读列表工具工厂
```
## 范围和备注
- 涵盖 **核心** Logiwa 域（API 有 200+ 端点）。特定领域 — 机器人、计费、计数计划、仓库任务、Webhook、数据设置 CRUD、用户/角色管理 — 在此第一个版本中故意省略，可以通过相同的方式添加。
- 破坏性操作（`*_cancel_*`、`*_remove_*`、`*_adjust_*`）使用 `destructiveHint` 标记。
- 有关 Logiwa 字段引用，请参阅 <https://mydeveloper.logiwa.com/> 中的开发人员文档和 <https://myapi.logiwa.com/swagger/index.html> 中的 Swagger UI。
## 许可证
根据 [Apache License 2.0](./LICENSE) 许可。
