ozon-seller-mcp 2.1.0 → 2.3.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 个组合工具**：常见问题一次调用出结果（销量排行、商品列表、单品详情、库存、订单、经营概览）
 - **默认只读**；写操作在发送前拦截
@@ -35,18 +37,46 @@ Windows 上如果客户端找不到 `npx`，把 `command` 改为 `"cmd"`，`args
 
 | 变量 | 默认 | 说明 |
 |---|---|---|
-| `OZON_CLIENT_ID` / `OZON_API_KEY` | — | 店铺凭证，必填 |
+| `OZON_CLIENT_ID` / `OZON_API_KEY` | — | 单店凭证；只有一家店时用 |
+| `OZON_SHOPS` | — | 多店铺：JSON 数组，见下方「多店铺」；填了它就不再读单店的 4 个凭证变量 |
 | `OZON_READ_ONLY` | `true` | `false` 才允许写操作；其他值启动报错，拼写错误不会开放写入 |
 | `OZON_TOOLSET` | `core` | `core` 常用工具；`minimal` 只要组合工具和通用工具；`all` 全部接口；可追加接口路径或工具名，逗号分隔，如 `core,/v1/returns/list` |
 | `OZON_COMPACT` | `true` | 结果省略 null、空字符串、空数组、空对象 |
 | `OZON_MAX_RESULT_KB` | `80` | 单次结果上限；超出时截断最大的数组并提示分页 |
 | `OZON_OUTPUT_DIR` | `~/.accio/outputs/ozon` | HTML 报告目录 |
 | `OZON_ACCESS_TOKEN` | — | Ozon Delivery 分组接口的 OAuth 令牌 |
+| `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。
 
+## 多店铺
+
+一个 MCP 连多家店：`OZON_SHOPS` 填一个 JSON 数组，每家店一项。
+
+```json
+"env": {
+  "OZON_SHOPS": "[{\"name\":\"shop-a\",\"client_id\":\"…\",\"api_key\":\"…\",\"perf_client_id\":\"…@advertising.performance.ozon.ru\",\"perf_client_secret\":\"…\",\"market\":true,\"default\":true},{\"name\":\"shop-b\",\"client_id\":\"…\",\"api_key\":\"…\",\"perf_client_id\":\"…\",\"perf_client_secret\":\"…\"}]",
+  "OZON_READ_ONLY": "true"
+}
+```
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `name` | 是 | 店铺名，1～32 个字母、数字、汉字、`_`、`-`，不能重复；调用时用它选店 |
+| `client_id` / `api_key` | 二选一 | 该店的 Seller API 凭证，两项要么都填要么都不填 |
+| `perf_client_id` / `perf_client_secret` | 二选一 | 该店的广告凭证，两项要么都填要么都不填；每家店至少填一组凭证（只做广告的店可以不填 Seller API） |
+| `access_token` | 否 | 该店的 Ozon Delivery OAuth 令牌 |
+| `default` | 否 | `true` = 调用不指定店铺时用它；不标就用第一项 |
+| `market` | 否 | `true` = 市场数据店，最多一家；没有店标它时，市场数据接口就用调用时选的那家店 |
+
+- 访问 Ozon 的工具（含组合工具、广告工具）都多一个可选参数 `shop`（店铺名），不填用默认店。结果里的 `shop` 字段写明实际用哪家店的凭证查的。只在本地运行的工具（`ozon_status`、目录、说明、校验、报告）没有这个参数。
+- **市场数据固定走 `market` 店**：类目大盘 `/v1/analytics/category/comparison`、全站热搜词 `/v1/search-queries/top`、`/v1/search-queries/text` 要 Premium Pro 订阅，结果和查询的店铺无关，所以不论 `shop` 填哪家，都用市场数据店的凭证查。本店相关的数据（销量、商品搜索词、价格指数、广告）一律用各自店的凭证。
+- 限流和 5 分钟读缓存按店铺（Client-Id）分开计；广告令牌每家店各一个。
+- 配置有错（JSON 不合法、缺凭证、重名、未知字段、两家店填了同一个 `client_id` / `perf_client_id`、两家都标 `market`）启动时直接报错，报错只说第几项哪个字段，不回显密钥。所有店的密钥都会从结果和报错里隐藏。
+- `ozon_status` 列出每家店的名称、Client-Id、是否默认 / 市场店、是否配了 Seller API / 广告凭证，不含密钥。
+
 ## 通过节点访问 Ozon
 
 国内网络直连 Ozon 经常不通。把节点链接填进 `OZON_PROXY` 即可，不用另装代理软件：
@@ -105,6 +135,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 技能要求模型把限额告诉用户。
@@ -149,7 +209,7 @@ Windows 上如果客户端找不到 `npx`，把 `command` 改为 `"cmd"`，`args
 
 ```bash
 npm install
-npm test          # 26 个单元/契约测试，不联网
+npm test          # 52 个单元/契约测试，不联网
 npm run smoke     # 启动真实进程，跑一遍 MCP stdio 握手
 ```
 
@@ -159,6 +219,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

@@ -11,13 +11,19 @@ if (args.includes('--version') || args.includes('-v')) {
 用法：npx -y ozon-seller-mcp
 
 环境变量：
-  OZON_CLIENT_ID, OZON_API_KEY   店铺凭证（必填）
+  OZON_CLIENT_ID, OZON_API_KEY   单店凭证（只有一家店时用）
+  OZON_SHOPS                     多店铺：JSON 数组，每项 {"name","client_id","api_key",
+                                 "perf_client_id"?,"perf_client_secret"?,"access_token"?,"market"?,"default"?}；
+                                 填了它就不再读上面的单店变量。"market": true 的店负责
+                                 类目大盘、全站热搜词（需 Premium Pro）；工具多一个 shop 参数
   OZON_READ_ONLY                 true（默认，只读）/ false（允许写入）
   OZON_TOOLSET                   core（默认）/ all / minimal / 追加接口路径，逗号分隔
   OZON_COMPACT                   true（默认，省略空值字段）/ false
   OZON_MAX_RESULT_KB             单次结果上限，默认 80
   OZON_OUTPUT_DIR                HTML 报告输出目录
   OZON_ACCESS_TOKEN              Ozon Delivery 接口 OAuth 令牌（可选）
+  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 为空时生效
 `);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ozon-seller-mcp",
-  "version": "2.1.0",
-  "description": "Ozon Seller API MCP server: 482 official endpoints, one-call composite queries, read-only by default, strict schema validation.",
+  "version": "2.3.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` 时，在回复中告诉用户该官方限制。