ozon-seller-mcp 2.0.0 → 2.2.0

package/README.md

@@ -2,6 +2,8 @@
 
 Ozon 卖家 API 的标准 MCP 服务（stdio），纯 Node 实现，`npx` 即装即用，**不需要 Python**。
 
+- **广告数据**：接入 Ozon Performance API（广告后台）全部 48 个接口，`ozon_ads_stats` 一次调用出点击率/加购率/下单率/DRR 分析，见[广告数据](#广告数据performance-api)
+
 - 覆盖俄文官方 OpenAPI（2026-10-26 快照）全部 **482 个接口**，参数严格按官方 schema 校验
 - **6 个组合工具**：常见问题一次调用出结果（销量排行、商品列表、单品详情、库存、订单、经营概览）
 - **默认只读**；写操作在发送前拦截
@@ -42,10 +44,42 @@ Windows 上如果客户端找不到 `npx`，把 `command` 改为 `"cmd"`，`args
 | `OZON_MAX_RESULT_KB` | `80` | 单次结果上限；超出时截断最大的数组并提示分页 |
 | `OZON_OUTPUT_DIR` | `~/.accio/outputs/ozon` | HTML 报告目录 |
 | `OZON_ACCESS_TOKEN` | — | Ozon Delivery 分组接口的 OAuth 令牌 |
-| `HTTPS_PROXY` | — | 设置后经代理访问 |
+| `OZON_PERF_CLIENT_ID` / `OZON_PERF_CLIENT_SECRET` | — | 广告 Performance API 凭证，查广告数据才需要；和上面的 Seller API 凭证不是一组 |
+| `OZON_PROXY` | 空 | 只给 Ozon 请求用的代理，留空就直连。支持 `vless://` 节点链接（WebSocket 类型）、`http://`、`socks5://`；设置后优先于 `HTTPS_PROXY` |
+| `HTTPS_PROXY` | — | 标准代理变量，`OZON_PROXY` 为空时生效 |
 
 修改后需要重启 MCP。
 
+## 通过节点访问 Ozon
+
+国内网络直连 Ozon 经常不通。把节点链接填进 `OZON_PROXY` 即可，不用另装代理软件：
+
+```json
+"env": {
+  "OZON_CLIENT_ID": "你的 Client ID",
+  "OZON_API_KEY": "你的 API Key",
+  "OZON_PROXY": "vless://UUID@地址:443?type=ws&security=tls&host=域名&sni=域名&path=%2Fws"
+}
+```
+
+- 支持 `type=ws`、`security=tls` 或 `none` 的 VLESS 节点（常见的 Cloudflare WS 节点）；Reality、gRPC、XTLS 等类型不支持，可用本机客户端转成 `http://127.0.0.1:端口` 再填
+- 到 Ozon 的 HTTPS 在隧道内端到端加密，节点只转发字节，看不到 API Key
+- 链接里的 UUID 等同节点密码，只放在 MCP 配置里，不要提交到仓库；`ozon_status` 和报错只显示节点地址，不显示 UUID
+
+## 连不上 Ozon
+
+报错会写明底层原因、耗时和当前代理，例如 `连接 Ozon 失败（ECONNREFUSED，8 ms，代理：HTTPS_PROXY=http://127.0.0.1:7899）`。`ozon_status` 会显示 Node 版本和生效的代理。
+
+| 报错里的原因 | 处理 |
+|---|---|
+| `代理配置无效` | 代理变量缺少协议，改成 `http://127.0.0.1:端口` |
+| 带代理的 `ECONNREFUSED` / `UND_ERR_CONNECT_TIMEOUT` | 代理软件没开或端口不对；不需要代理就删掉该变量 |
+| 直连的 `UND_ERR_CONNECT_TIMEOUT` / `ECONNRESET` | 本机直连不通（软路由下 TCP 几毫秒就“连上”、TLS 握手却超时也属于这种）。在 `env` 配置 `OZON_PROXY`，见上一节；Node 不读系统代理，浏览器能打开不代表 MCP 能通 |
+| `VLESS_WS_FAILED` / 经 VLESS 节点的 `ECONNRESET` | 节点握手失败或 UUID 不对：核对链接里的 UUID、host、path，确认节点没过期 |
+| `SELF_SIGNED_CERT_IN_CHAIN` 等证书错误 | 杀毒软件或公司网关在扫描 HTTPS。关闭 HTTPS 扫描，或在 `env` 加 `"NODE_OPTIONS": "--use-system-ca"`（Node ≥ 22.15） |
+| `ENOTFOUND` | DNS 解析失败 |
+| `HTTP 401/403` | 网络已通，检查 Client ID、API Key 和权限 |
+
 ## 工具
 
 ### 组合工具（一次调用）
@@ -74,6 +108,36 @@ Windows 上如果客户端找不到 `npx`，把 `command` 改为 `"cmd"`，`args
 
 独立接口工具名为 `ozon_<官方 operationId>`，参数就是官方请求体。
 
+## 广告数据（Performance API）
+
+广告数据不在 Seller API 里，而在独立的 Performance API（`api-performance.ozon.ru`），需要另一组凭证：
+
+1. 卖家后台 **设置 → API 密钥 → Performance API**，没有服务账号就先创建
+2. 点服务账号名称 → **添加新密钥**，得到 Client ID（以 `@advertising.performance.ozon.ru` 结尾）和 Client Secret
+3. 填到 MCP 的 `env`：
+
+```json
+"env": {
+  "OZON_PERF_CLIENT_ID": "xxxx@advertising.performance.ozon.ru",
+  "OZON_PERF_CLIENT_SECRET": "你的 Client Secret"
+}
+```
+
+配置了这两项后才会出现下面 3 个广告工具（没配时工具列表与以前一样，`ozon_status` 的 `ads.setup_hint` 会提示怎么配）。只用广告功能时可以不填 `OZON_CLIENT_ID` / `OZON_API_KEY`。访问令牌由服务自动获取（30 分钟有效，提前 1 分钟换新，遇到 401 自动刷新一次），不会出现在结果里。代理设置（`OZON_PROXY` 等）与 Seller API 共用。
+
+| 工具 | 内容 |
+|---|---|
+| `ozon_ads_stats` | 【一次调用】按点击付费活动：各活动和各商品的展示、点击、点击率、加购率、下单率、花费、平均点击价、单均成本、DRR；标出点击率偏低、点击≥100 无订单、DRR 超过目标的商品。默认最近 7 天（莫斯科时间），最长 62 天。实测一个 8 个活动的店铺约 25 秒 |
+| `ozon_ads_api_catalog` | 搜索全部 48 个广告接口 + 官方说明中给出的 12 个 `/json` 报表版本，或查看单个接口的参数与响应定义 |
+| `ozon_ads_api_call` | 按路径调用任一广告接口：路径参数和查询参数放 `params`，请求体放 `body` |
+
+- `ozon_ads_stats` 的活动汇总来自 `/api/client/statistics/campaign/product/json`（同步，不消耗限额）；商品明细来自异步活动报表 `/api/client/statistics/json`（每次最多 10 个活动，同一账号同时只生成 1 个，最多等 90 秒），包含本期内已移出活动的商品。`include_products=false` 只看活动汇总
+- `/api/client/statistics/products/sku` 实测只接受今天或昨天（Ozon 返回 `date range must contain only today or yesterday`），所以不用于多天统计
+- `OZON_READ_ONLY=true` 时，改出价、启停活动、增删商品、开关“按订单付款”等 16 个写接口在发送前拦截（包括 `GET /api/client/campaign/all_sku_promo/activate` 这类用 GET 做写操作的接口）
+- 官方限制：每天总计 100 000 次；统计报表同一账号同时只能生成 1 个、一次最多 10 个活动、最长 62 天
+- 多活动统计报表是 ZIP，本服务不解压；请每次一个活动，或用 `/json` 版本
+- 活动列表按页读取（每页 100，直到读完），同时最多 4 个请求
+
 ## 限流
 
 官方文档中写明限额的接口如下。工具说明里会标出 `⚠ 限流`，调用结果附带 `rate_limit` 字段，Accio 技能要求模型把限额告诉用户。
@@ -118,7 +182,7 @@ Windows 上如果客户端找不到 `npx`，把 `command` 改为 `"cmd"`，`args
 
 ```bash
 npm install
-npm test          # 26 个单元/契约测试，不联网
+npm test          # 52 个单元/契约测试，不联网
 npm run smoke     # 启动真实进程，跑一遍 MCP stdio 握手
 ```
 
@@ -128,6 +192,7 @@ npm run smoke     # 启动真实进程，跑一遍 MCP stdio 握手
 
 - 俄文主规范：https://docs.ozon.ru/api/seller/swagger.json
 - 中文辅助规范：https://docs.ozon.ru/api/seller/zh/swagger.json
+- 广告 Performance API（2026-11-09 快照）：https://docs.ozon.ru/api/performance/swagger.json 、中文 https://docs.ozon.ru/api/performance/zh/swagger.json
 - MCP SDK：`@modelcontextprotocol/server` 2.4.0
 
 `spec/` 是版本快照，不在运行时联网更新。Accio 展示技能见 `ozon-seller-assistant.skill`（源文件在 `skills/`）。

package/bin/ozon-seller-mcp.js

@@ -18,7 +18,10 @@ if (args.includes('--version') || args.includes('-v')) {
   OZON_MAX_RESULT_KB             单次结果上限，默认 80
   OZON_OUTPUT_DIR                HTML 报告输出目录
   OZON_ACCESS_TOKEN              Ozon Delivery 接口 OAuth 令牌（可选）
-  HTTPS_PROXY                    代理（可选）
+  OZON_PERF_CLIENT_ID            广告 Performance API 的 Client ID（可选，查广告数据用）
+  OZON_PERF_CLIENT_SECRET        广告 Performance API 的 Client Secret
+  OZON_PROXY                     只给 Ozon 用的代理：vless://（WS 节点）、http://、socks5://；留空直连
+  HTTPS_PROXY                    标准代理变量，OZON_PROXY 为空时生效
 `);
 } else {
   // A stray error must not kill the server mid-conversation; log it to stderr and keep serving.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ozon-seller-mcp",
-  "version": "2.0.0",
-  "description": "Ozon Seller API MCP server: 482 official endpoints, one-call composite queries, read-only by default, strict schema validation.",
+  "version": "2.2.0",
+  "description": "Ozon Seller API + Performance (ads) API MCP server: 482 seller endpoints, 48 advertising endpoints, one-call composite queries, read-only by default, strict schema validation.",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -25,6 +25,8 @@
     "assets/",
     "spec/openapi-ru.json",
     "spec/operations.json",
+    "spec/performance-ru.json",
+    "spec/performance-zh.json",
     "skills/",
     "ozon-seller-assistant.skill"
   ],

package/skills/ozon-seller-assistant/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ozon-seller-assistant
-description: "通过 Ozon Seller MCP 查询和管理店铺商品、价格、库存、仓库、订单、退货、财务及促销，并将结果整理为清晰表格或离线 HTML 报告。用户提及 Ozon 店铺/API、库存查询、订单同步、财务对账或经营看板时使用。"
+description: "通过 Ozon Seller MCP 查询和管理店铺商品、价格、库存、仓库、订单、退货、财务、促销及广告数据（点击率、推广效果），并将结果整理为清晰表格或离线 HTML 报告。用户提及 Ozon 店铺/API、库存查询、订单同步、财务对账、广告点击率或经营看板时使用。"
 metadata:
   display_name: Ozon 店铺助手
   version: "2.0.0"
@@ -22,9 +22,17 @@ metadata:
 | 库存情况、缺货、低库存、补货清单 | `ozon_stock_overview` |
 | 最近订单/货件、发货状态、取消原因 | `ozon_orders_overview` |
 | 最近卖了多少、销量营收趋势、财务余额 | `ozon_sales_overview` |
+| 广告点击率、推广效果、哪个广告/商品亏钱（按点击付费） | `ozon_ads_stats` |
 
 组合工具结果含 `notes`（口径与缺失说明，需转告用户）和 `timing_ms`。底层接口失败时其余部分照常返回，在 notes 中说明。
 
+## 广告数据
+
+- 广告用独立的 Performance API 凭证（`OZON_PERF_CLIENT_ID` / `OZON_PERF_CLIENT_SECRET`）。`ozon_status` 的 `ads.credentials_configured=false` 时，告诉用户在卖家后台 设置 → API 密钥 → Performance API 创建服务账号和密钥，并填进 MCP env。
+- `ozon_ads_stats` 的 `flags` 是按阈值给的提示，`target_drr` 默认 30%：用户给出毛利率后用毛利率重算。展示少的商品不评判点击率，点击少的不评判转化。
+- 解读顺序：点击率低 → 主图/价格/标题；点击率正常但加购率低 → 详情页；加购正常但下单率低 → 价格与竞品；DRR 高于毛利率 → 降出价或停投。
+- 其他广告接口用 `ozon_ads_api_catalog` 搜索后 `ozon_ads_api_call` 调用；改出价、启停活动属于写操作，只读模式下会被拦截。
+
 ## 限流（必须告知用户）
 
 - 工具说明或结果中出现“⚠ 限流”/`rate_limit` 时，在回复中告诉用户该官方限制。