Yango Tech Retail MCP（mcp-yango-retail）是一个 MCP 服务器，用于把 AI 应用连接到 Yango Tech Retail 中的零售商账户。通过自然语言，用户可以检查门店、订单、商品、价格和库存，也可以在需要时创建订单并更新账户数据。
【用途】 该服务器面向杂货零售和暗店的零售商 B2B API，不是市场卖家门户、出租车服务或 Yango Delivery。它让 AI 客户端能够以近似对话的方式操作零售数据，并在执行写入前明确区分只读、写入和可能具有破坏性的操作。
【主要能力】 服务器共提供 16 个工具：9 个只读工具、5 个写入工具和 2 个可能具有破坏性的工具，覆盖门店、目录、定价、库存、订单和收据。
- 门店与商品目录：列出门店及其 id、状态、位置、地址和名称（如可用）；按游标浏览商品，查看状态、分类、本地化名称、条形码和自定义属性；单次请求最多创建或更新 100 个商品，商品记录为 upsert 而非重复添加。
- 价格与折扣：列出价目表并读取一个或多个价目表中的商品价格；比较同一商品在不同价目表中的价格；单次请求最多设置 100 个价格，使用如 "150.00" 的十进制字符串；在确认预期字段结构后，可创建最多 100 个门店专属折扣。
- 库存：读取各门店库存，包括商品、数量和货架类型；单次最多更新一个门店的 1,000 条库存行；首次库存加载使用 initialize，日常更新使用 modify。
- 订单与收据：在收集门店、商品、数量、价格、配送详情和付款类型后创建订单；读取订单详情并同时检查多个订单的当前状态；跟随订单事件流获取新订单、状态变化和已开具收据；按订单 id 或收据 id 读取财政收据；在检查当前状态和取消原因后取消订单。
- 扩展 API：raw_request 覆盖未提供专用工具的 /b2b/v1/* 方法，包括订单更新、增值税数据、价目表链接、拣货、物流和 3PL 配送操作。它可以修改真实账户数据，面向理解上游 API 的技术用户。
【使用方式】 需要 Node.js 20+、一个 Yango Tech Retail 账户和零售商 Bearer token。token 需从 Yango Tech 集成经理处获取。将服务器添加到 AI 应用后，建议先用只读请求，例如“列出我们的门店，并显示每个门店中商品 [product ID] 的库存”。 不同客户端的配置方式：
- 通用命令行启动：npx -y mcp-yango-retail@latest
- 在某类 AI 应用中：打开 Settings → MCP servers，选择 Add server，选择 STDIO，输入启动命令 npx -y mcp-yango-retail@latest 和 YANGO_RETAIL_TOKEN 环境变量，保存后重启。
- 在 Claude Desktop 中：当前官方路径为 Settings → Extensions；对于仍支持本地配置的构建，可使用 JSON stdio 配置作为回退，macOS 保存到 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 保存到 %APPDATA%\Claude\claude_desktop_config.json。
- 在 Cursor 中：macOS/Linux 添加到 ~/.cursor/mcp.json，Windows 添加到 %USERPROFILE%.cursor\mcp.json。
- 在 VS Code 中：运行 MCP: Open User Configuration 并添加配置，然后通过 MCP: List Servers 检查服务器。 连接检查方式、Codex 和 Claude Code 的 MCP 文档也提供了参考路径。
【数据与安全】 服务器在本机运行，将零售商数据直接发送到配置的 Yango Tech Retail API 主机。生产 API 主机为 https://api.retailtech.yango.com。每个 API 调用都是 POST，JSON 请求体位于 /b2b/v1/* 下，读操作也如此。Bearer token 仅附加到针对该主机的请求，raw_request 只接受相对路径并拒绝解析到其他来源的路径。 默认情况下，服务器向 usage.gistrec.cloud 发送匿名技术事件，包括服务器启动、被调用的工具名称和启动失败时的固定原因码；事件包含随机安装 id、包版本、AI 客户端名称和版本、Node.js 版本和操作系统。不会读取或发送 Bearer token、零售商数据、工具参数和提示词。遥测有两秒超时，不会阻塞工具调用。可通过配置禁用遥测，实现位于 src/telemetry.ts。
【限制与后台工作】 公共 API 配额未文档化。官方 Python 客户端对一个 token 和一个端点保持每秒 5 次请求，可作为操作参考，但并非公布的 API 限制；本服务器不会主动限制每个调用。429 响应会重试，遵循 Retry-After，并且重试次数不超过 YANGO_RETAIL_MAX_RETRIES 允许的值。不确定失败后的写入不会被重放；网络和 5xx 重试仅适用于无副作用的读取。不确定写入后，应先读取当前订单、价格或库存再重试。批量限制：商品、价格和折扣每次请求最多 100 条，库存更新最多 1,000 行。没有后台监控，服务器仅在 AI 应用调用时工作；如果应用支持计划任务，可定期检查订单状态或库存。没有自动回滚，成功更新会立即更改零售商账户。删除受上游 API 限制，商品和价格是 upsert，没有已知的商品、价格或折扣删除方法。折扣支持在上游不完整，活动周期和折扣值的具体键未文档化，也没有已知的列出或删除折扣的方法，使用前需与 Yango Tech 确认载荷。
【适用场景】 适合零售商运营人员或技术用户通过 AI 应用查询门店、商品、价格和库存，以及按需创建订单、更新价格和库存、取消订单并读取收据。技术用户还可通过 raw_request 访问更广泛的 API 方法。需要 Yango Tech Retail 账户和 Bearer token，且应先进行只读操作，写入前确认目标数据，写入后重新读取当前值。
