Jackyun

---
name: jackyun
display_name: 吉客云ERP数据查询
display_name_en: JackYun ERP Data Query
description: 通过吉客云MCP服务查询订单、货品、采购、库存、仓库等ERP业务数据。当用户提到吉客云、销售单、网店订单、发货单、退换补发单、出库单、入库单、调拨单、采购订单、采购结算单、采购退货单、货品档案、货品价目、仓库信息时触发本技能。
description_zh: 通过吉客云MCP服务查询订单、货品、采购、库存、仓库等ERP业务数据，全部为只读查询，不产生业务变更。
description_en: Query JackYun ERP business data (orders, goods, purchases, inventory, warehouses) through the JackYun MCP service. All tools are read-only.
category: business-productivity
version: 2.0.0
author: 吉客云技术团队
---

# 吉客云 MCP 使用说明

本连接器提供吉客云开放平台的查询能力，覆盖订单、货品、采购、库存、仓库等业务数据。所有工具均为**只读查询**，不产生业务变更。

## 一、认证与前置条件

- 使用前需完成 MCP 授权，并在吉客云开放平台的「MCP 服务工具列表」中**订阅对应工具**。
- 认证方式为请求头 `Authorization: <平台Token>`，由用户配置，AI 不接触 Token 本身。
- Token 默认有效期一年，失效时会返回 401。

## 二、通用约定

- **时间参数**：按工具要求传入创建时间 / 完成时间等，注意区分"单据创建时间"与"单据完成时间"，二者含义不同。
- **单号来源**：订单号、发货单号、采购单号等必须由用户提供，**不要臆造或推测单号**。用户未提供时先询问。
- **按货品反查**：部分单据类工具支持传入货品信息反向查询关联单据，用户只给了货品时要留意这一用法。
- **结果为空**：先确认单号/时间是否正确，再提示用户核对查询条件，不要直接断言"数据不存在"。

## 三、按业务域选择工具

### 订单类

| 用户意图 | 选用工具 |
|---|---|
| 按订单号查销售明细（店铺、货品金额、货品名称） | 销售单查询 `oms.trade.fullinfoget` |
| 按创建时间或渠道 ID 查网店订单 | 网店订单查询 `omsapi-business.order.get` |
| 按完成时间查发货单信息 | 发货单查询 `wms.order.query-info.page` |
| 按退换补发单号 / 网店订单号 / 售后单号查询 | 退换补发单查询 `ass-business.returnchange.fullinfoget` |

区分要点：**销售单**偏销售明细，**网店订单**偏渠道订单本身，**发货单**关注履约完成，**退换补发单**是售后场景。

### 库存类

| 用户意图 | 选用工具 |
|---|---|
| 查货品在各仓库的即时库存数量 | 库存查询 `erp.stockquantity.get` |
| 按出库单号或创建时间查出库单据 | 出库单查询 `erp.storage.goodsdocout.v2` |
| 按入库单号或创建时间查入库单据 | 入库单查询 `erp.storage.goodsdocin.v2` |
| 按调拨单号、创建时间、调入/调出仓库查询 | 调拨查询 `erp.allocate.get` |

区分要点：**库存查询**返回即时数量，**出入库/调拨**是单据维度，二者不可混用。

### 采购类

| 用户意图 | 选用工具 |
|---|---|
| 查采购订单的仓库、供应商、到货状态及入库明细 | 采购订单查询 `erp.purch.get` |
| 按结算单号或结算日期查采购结算单 | 采购结算单查询 `erp.purchordersett.get` |
| 按退货单号或创建时间查采购退货 | 采购退货单查询 `erp.purchreturn.get` |

区分要点：三者是采购流程的不同阶段——**订单**是采购发起，**结算单**是财务结算，**退货单**是逆向流程。

### 基础档案

| 用户意图 | 选用工具 |
|---|---|
| 按货品编码查名称、条码、单位、分类、品牌、默认仓库 | 货品查询 `erp.storage.goodslist` |
| 按货品名称 / 编号 / 规格 / 条码查价目 | 货品价目查询 `erp-goods.pricelist.get` |
| 按仓库编号查名称、地址、所属销售渠道 | 仓库查询 `erp.warehouse.get` |

## 四、典型示例

1. 用户："帮我查一下订单 XXX 的销售情况"
   → 调用销售单查询 `oms.trade.fullinfoget`，传入订单编号。

2. 用户："这个货品在各个仓库还有多少库存？"
   → 调用库存查询 `erp.stockquantity.get`，传入货品信息。

3. 用户："上周创建的采购订单到货了吗？"
   → 调用采购订单查询 `erp.purch.get`，传入采购订单创建时间范围，返回中关注到货状态与入库数量。

4. 用户："出库单 XXX 上都发了哪些货？"
   → 调用出库单查询 `erp.storage.goodsdocout.v2`，传入出库单号。

5. 用户："查一下仓库 A 的地址和所属渠道"
   → 调用仓库查询 `erp.warehouse.get`，传入仓库编号。

## 五、错误恢复

- **401 Unauthorized**：Token 过期或错误。**不要重试**，提示用户重新生成 Token 并更新配置，同时检查 AppKey 是否与应用匹配。
- **订阅后 AI 看不到新工具**：需重载 MCP 客户端——Dify 刷新页面，Cursor / Claude 需重启应用。
- **调用提示工具不可用**：用户可能未订阅该工具，引导其到「MCP 服务工具列表」订阅。
- **参数校验失败**：核对必填参数（尤其是单号和时间），补齐后重试。

## 六、边界说明

- 本连接器**仅支持查询**，不支持创建、修改、删除等写操作。用户提出写需求时，说明当前能力范围。
- 当前仅支持官方预置工具，不支持自定义；如有私有 API 需求，建议联系吉客云客户成功团队。