Yango Tech Retail MCP

Yango Tech Retail MCP

English | Русский

A1 Yango Tech Retail MCP 可将 AI 应用连接到 Yango Tech Retail 中的零售商账户。使用日常语言即可查询门店、订单、商品、价格和库存，也可以按需创建订单和更新账户数据。

此服务通过面向零售商的 B2B API，为食品杂货零售和暗店提供服务。它不是电商平台卖家门户、出租车服务或 Yango Delivery。

• 16 个工具。 9 个只读工具、5 个写入工具和 2 个可能造成破坏的工具，涵盖门店、目录、定价、库存、订单和收据。
• 从安全的只读操作开始。 在更改账户内容之前，先检查已连接的数据。
• 明确的写入边界。 订单创建和取消、商品新增或更新、价格变更、折扣创建和库存更新均与读取操作分开。
• 更广泛的 API 覆盖范围。 技术用户可以通过 raw_request 调用没有专用工具的方法。

可以从以下请求开始：

列出我们的门店，并显示每家门店中商品 [product ID] 的库存。

连接服务 · 探索使用场景 · 查看技术文档

一分钟了解其工作方式

你： 列出我们的门店，并显示每家门店中商品 [product ID] 的库存。

助手： 我会返回门店及其 ID，以及每家门店中该商品的当前库存。

你： 显示所有价目表中该商品的价格。

助手： 我会返回价目表以及每份价目表中该商品的当前价格。不会更改任何账户数据。

你： 将价目表 [price-list ID] 中的价格改为 99.90。

助手： 这会更改一个面向真实客户的价格。在请求确认之前，我会显示商品、价目表、当前价格和新价格。

你： 确认。

助手： 价格已更新。我会重新读取价目表并返回当前价格。

门店、商品、价格、库存和订单状态始终取自已连接的零售商账户和当前 API 响应。

目录

• 快速开始
• 你可以让它做什么
• 零售数据如何连接
• 账户会发生哪些更改
• 获取访问权限
• 配置
• 数据和遥测
• 限制和后台工作
• 技术文档
• 支持

快速开始

你需要 Node.js 20+、Yango Tech Retail 账户和零售商 Bearer 令牌。

1. 从 Yango Tech 集成经理处获取令牌。

2. 按照以下任一说明将服务添加到你的 AI 应用。

3. 先尝试只读请求：

   列出我们的门店，并显示每家门店中产品 [product ID] 的库存。

codex mcp add yango-retail \
  --env YANGO_RETAIL_TOKEN=your_token \
  -- npx -y mcp-yango-retail@latest

codex mcp list

claude mcp add \
  --env YANGO_RETAIL_TOKEN=your_token \
  --transport stdio \
  --scope user \
  yango-retail \
  -- npx -y mcp-yango-retail@latest

claude mcp list

{
  "mcpServers": {
    "yango-retail": {
      "command": "npx",
      "args": ["-y", "mcp-yango-retail@latest"],
      "env": {
        "YANGO_RETAIL_TOKEN": "your_token"
      }
    }
  }
}

{
  "mcpServers": {
    "yango-retail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yango-retail@latest"],
      "env": {
        "YANGO_RETAIL_TOKEN": "your_token"
      }
    }
  }
}

{
  "servers": {
    "yango-retail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yango-retail@latest"],
      "env": {
        "YANGO_RETAIL_TOKEN": "${input:yango_retail_token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "yango_retail_token",
      "description": "Yango Tech Retail Bearer token",
      "password": true
    }
  ]
}

你可以让它做什么

查看门店和产品目录

• 列出门店，并显示其 ID、状态、位置、地址以及可用时的名称。
• 按游标浏览产品，并查看其状态、类别、本地化名称、条形码和自定义属性。
• 在一次请求中创建或更新最多 100 个产品。产品记录会执行插入或更新，而不会作为重复项添加。

查看和更新价格

• 列出价格表，并读取一个或多个价格表中的产品价格。
• 比较同一产品在不同价格表中的价格。
• 在一次请求中设置最多 100 个价格，使用 "150.00" 这样的十进制字符串。
• 与 Yango Tech 确认预期字段结构后，创建最多 100 个门店专属折扣。

查看和更新库存

• 查看各门店的库存，包括产品、数量和货架类型。
• 更新一家门店最多 1,000 条库存明细。
• 首次导入库存时使用 initialize，日常更新时使用 modify。

处理订单和收据

• 收集门店、产品、数量、价格、配送详情和付款类型后创建订单。
• 读取订单详情，并一次检查多个订单的当前状态。
• 关注订单事件流，了解新订单、状态变更和已开具的收据。
• 按订单 ID 或收据 ID 读取财政收据。
• 检查订单当前状态和取消原因后取消订单。

使用其他 API 方法

raw_request 涵盖没有专用工具的 /b2b/v1/* 方法，包括订单更新、VAT 数据、价目表链接、拣货、物流和 3PL 配送操作。它可能会更改真实账户数据，适用于了解上游 API 的技术用户。

完整的架构、响应字段和 API 缺口请参阅工具参考。

零售数据如何关联

数据流使用游标分页。若一页中的项目少于请求的上限，则表示当前商品、价目表或库存数据流已全部读取。订单事件数据流会持续更新：保留其最后一个游标，稍后请求下一页。

账户会发生哪些变化

服务会为只读、写入和破坏性操作提供 MCP 注释。AI 客户端决定何时以及如何请求确认。

写入前，请让助手显示目标门店、商品 ID、价目表、数量、当前值和拟设值。上游没有完整记录写入响应，因此成功更新价格或库存后，服务可以重新读取相应数据并显示当前值。

获取访问权限

Yango Tech 集成经理会为零售商账户签发 Bearer 令牌。本仓库未提供自助式令牌门户的说明。

1. 联系 Yango Tech 集成经理并申请零售商 Bearer 令牌。
2. 将其添加到 AI 客户端，变量名为 YANGO_RETAIL_TOKEN。
3. 请勿将令牌提交到 Git，并且只能通过 AI 客户端的机密或环境变量配置进行共享。

生产环境 API 主机为 https://api.retailtech.yango.com。每次 API 调用都是在 /b2b/v1/* 下发送带 JSON 请求体的 POST 请求，包括读取操作。

令牌存储在 AI 客户端的本地配置中。请像对待密码一样妥善保管，切勿提交包含真实令牌的配置。

配置

数据与遥测

向 Yango Tech Retail 发送请求

服务在你的机器上运行，并将零售商数据直接发送到配置的 Yango Tech Retail API 主机。Bearer 令牌仅会附加到解析到该主机的请求中。即使是 raw_request，也只接受相对路径，并会拒绝解析到其他源的路径。

匿名遥测

默认情况下，服务会向 usage.gistrec.cloud 发送技术事件：服务启动、被调用的工具名称，以及启动失败时的固定原因代码。

事件包含随机安装 ID、软件包版本、AI 客户端名称和版本、Node.js 版本及操作系统。**不会读取或发送 Bearer 令牌、零售商数据、工具参数和提示词。**遥测超时时间为 2 秒，且不会阻塞工具调用。

如要停用遥测，请添加：

ASKADS_TELEMETRY=0

实现位于 src/telemetry.ts。

限制与后台工作

• **公开 API 配额没有文档说明。**官方 Python 客户端对单个令牌和端点的请求速率限制为每秒 5 次；请将其作为操作指南，而非已公布的 API 限制。此服务不会主动限制每次调用的速率。
• **429 响应会触发重试。**如果存在 Retry-After，服务会遵循该值，且重试次数不会超过 YANGO_RETAIL_MAX_RETRIES 所允许的上限。
• **不确定失败后不会重放写入操作。**网络错误和 5xx 错误的重试仅适用于无副作用的读取操作。写入操作结果不确定时，请先读取当前订单、价格或库存，再尝试操作。
• **批量操作有限制。**每个请求最多接受 100 条商品、价格和折扣记录；库存更新最多接受 1,000 行。
• **没有后台监控。**只有从 AI 应用调用时，服务才会运行。如果应用支持计划任务，可以定期检查订单状态或库存。
• **不会自动回滚。**更新成功后会立即更改零售商账户。
• **删除操作受上游 API 限制。**商品和价格采用插入或更新方式；已知 API 中没有删除商品、价格或折扣的方法。
• **上游对折扣的支持不完整。**活动期限和折扣值的确切键名未记录，且已知没有列出或删除折扣的方法。使用前请与 Yango Tech 确认请求负载。

技术文档

• MCP 能力目录 — 面向任务的工具文档，涵盖每个工具。
• 所有工具 — 输入架构、响应、分页、API 缺口和批量限制。
• 开发 — 本地设置和项目检查。
• 发布 — 软件包发布和 MCP 目录收录。
• npm 软件包 — 已发布的 mcp-yango-retail 软件包。
• Yango Tech 官方 Python 客户端 — 此 API 现有的上游规范。

支持

发现了 Bug 或缺少某项使用场景？创建 Issue 或在 Telegram 上联系我们。

你已读到最后！