用途
mcp-yandex-merchants 是一个 MCP（Model Context Protocol）服务器，用于把 AI 应用连接到 Yandex 商品（Яндекс Товары）的合作伙伴 API。它解决的核心问题是：在不重新编辑、重新生成或重新上传整个 YML 商品源的前提下，用自然语言对已上传商品源中的商品进行点对点修改，例如改价、设置折扣、隐藏或恢复商品显示。
主要能力
服务器提供 13 个预置操作，覆盖以下场景：
- 连接与检查：从对话中直接连接 Yandex 账号、检查访问权限（check_access）、列出可用商品源（list_feeds）。
- 价格与折扣：修改单个商品价格（set_offer_price）、批量更新最多 2000 个商品的价格（update_offer_prices）、设置带新价与划线价的折扣（set_offer_discount），以及为 Yandex Pay、SBP 或 Ozon 卡设置特殊价格。
- 商品可见性：隐藏单个商品（hide_offer）、一次隐藏最多 500 个商品（hide_offers）、恢复最多 500 个商品显示（show_offers）。商品可被永久隐藏，或隐藏最长 720 小时。
- 直接调用 API：raw_request 支持 GET、POST、DELETE，可调用没有预置操作的合作伙伴 API 方法，接受 API 原始格式的数据。
服务器在发送请求前会校验必填字段、列表大小、ID 长度、价格为正数以及折扣范围；并检查响应体中的 status 字段，因为 HTTP 200 并不代表写入成功。它不会在服务器错误或连接中断后自动重试写入，也不允许 raw_request 将 OAuth 令牌发送到外部地址。
使用方式
需要 Node.js 20 或更高版本、已上传到 Yandex 商品的 YML 商品源，以及上传该商品源所用的 Yandex 登录账号。服务器通过 npx 启动，无需单独安装包。
在 AI 应用中添加服务器后，在对话中请求“连接 Yandex 商品”，助手会给出 Yandex 登录链接并请求确认码。确认码一次性有效，10 分钟内有效。服务器使用 PKCE，令牌仅保存在本地 ~/.config/mcp-yandex-merchants/credentials.json，权限仅限所有者，并会自动续期。若已在配置中设置 YANDEX_MERCHANTS_OAUTH_TOKEN，则可跳过此步骤。
连接后可通过“检查与 Yandex 商品的连接并显示可用商品源”验证，返回商品源列表后即可进行价格与可见性操作。
不同 AI 应用的配置方式不同：Codex 可通过 Settings → MCP servers 添加 STDIO 服务器，命令为 npx -y mcp-yandex-merchants@latest；Claude Code、Claude Desktop、Cursor、VS Code 等也有各自的配置路径。该服务器是本地 MCP 服务器，ChatGPT 和 Claude 的网页版本身无法启动此类进程，需使用桌面应用、CLI 或支持本地 MCP 服务器的编辑器。
适用场景
适合需要快速修正一个或多个价格、设置折扣、隐藏已售罄商品或恢复商品显示的场景。YML 商品源本身仍通过 Yandex 商品后台或 Webmaster 管理。
限制
- 无法读取商品当前状态：API 不返回当前价格、隐藏商品列表、商品源内容或状态，需自行保存变更日志。
- 无法管理商品源本身：创建、删除或重新加载 YML 商品源只能在后台或 Webmaster 中完成。
- 仅支持卢布，API 不接受其他货币。
- 商品 ID 最长 50 个字符。
- 单次请求最多 2000 个价格；隐藏和恢复每次最多 500 个商品。
- 每分钟最多 50000 次操作，价格变更与隐藏/恢复分别计数。
- 没有自动回滚：连接中断后写入结果可能未知，且无法通过该 API 读取状态，不应自动重试此类操作。
- 没有持续监控：服务器仅在 AI 应用调用时运行。
默认情况下，服务器会向 usage.gistrec.cloud 发送匿名技术遥测数据，包括随机安装标识、事件或工具名称、包版本、Node.js 版本、操作系统以及连接的 AI 客户端信息，不包含 OAuth 令牌、账号数据、商品源与商品 ID、价格、工具参数或请求文本。可通过环境变量禁用遥测。
