mpstats-connector · diff
git:20260730.f7208ad to git:20260816.fb31033
7 added, 4 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: mpstats-connector
- description: Use this skill when the operator needs MPStats sales/stock analytics for a specific Ozon or Wildberries item — per-day sales graphs, current price and stock, warehouse stock split (FBS vs FBO), seller/brand identity, and a rolling orders-per-day average. Trigger on Russian queries like "продажи товара на озон", "аналитика ozon sku", "остатки на складе ozone", "mpstats по артикулу", "продажи за 30 дней", or English equivalents. Requires a paid MPStats account (MPSTATS_MP_AUTH env). Skip for raw catalog price/availability checks (use wb_/ozon_ connectors instead — they need no account).
+ description: Use this skill for MPStats sales/stock analytics on a specific Ozon or Wildberries item — per-day sales, current price and stock, FBS/FBO warehouse split, seller/brand identity, and a rolling orders-per-day average. Trigger on "продажи товара на озон", "аналитика ozon sku", "mpstats по артикулу", "продажи за 30 дней", or English equivalents. Requires a paid MPStats account (MPSTATS_MP_AUTH env). Skip raw catalog price checks — use wb_/ozon_ connectors (no account needed).
---
# MPStats Connector
Paid-account sales/stock analytics for Ozon and Wildberries items, via the
MPStats browser-plugin API (`plugin.mpstats.io/pluginapi`). Unlike the
anonymous catalog connectors in this workspace, this one is **optional**: it
needs a paid MPStats account configured as the `MPSTATS_MP_AUTH` env var (the
raw `mp_auth` JWT cookie from a logged-in browser plugin session at
mpstats.io). Without it the server boots cleanly, every tool returns
`auth_missing`, and no other connector is affected — like every source here,
it is a pleasant extra you opt into, not a requirement.
## When to use
- Per-SKU 30-day **sales analytics** — orders graph, price graph, stock graph
- **Current price and stock** for an item (today's reading off the graph tail)
- **Warehouse stock split** — FBS (seller warehouse) vs FBO (marketplace warehouse)
- Seller/brand identity and a rolling **orders-per-day** average
- Sales-trend comparison across several SKUs in one batched call
## When NOT to use
- Bare price/availability checks with no account — use `wb_card` / `ozon_card`.
- Reviews, categories, seller tax identity — MPStats does not surface those; use
the catalog connectors.
- Search by text or category browsing — MPStats analytics is keyed by SKU, not
by query.
## Prerequisites
Set `MPSTATS_MP_AUTH` to the raw JWT (no `mp_auth=` prefix, no quotes):
```
export MPSTATS_MP_AUTH='eyJ0eXAiOiJKV1Qi...' # from a logged-in mpstats.io session
```
Without it, every tool returns an `auth_missing` error (retryable: false) and
the server still boots cleanly. Treat the token as a secret: it identifies a
paid, quota-billed account. Never log it, never commit it.
## Tools available
- `mpstats_item(skus, place, oz_fbs=True)` — per-SKU 30-day analytics. Up to 100
SKUs per call. Returns, per SKU: `seller`, `seller_id`, `brand`, `stock_now`,
`price_avg_rub`, `orders_per_day`, `days_on_stocks`, `totals` (orders/sum/
sum_prev), and four per-day graphs (`orders_graph`, `prices_graph`,
`count_graph`, `rubrics_graph`).
- `mpstats_warehouses(skus, place)` — per-SKU warehouse stock split: `fbs`
count, `fbo` total (collapsed from the upstream per-warehouse list), the raw
`fbo_warehouses` list, and the upstream `last_update` timestamp.
- - `mpstats_selfcheck()` — tri-state health canary: `success`, `drift_detected`
- (reachable but unparseable — code change needed), or `inconclusive` (transport
- failure / missing auth — says nothing about the parsers).
+
+ **Not an MCP tool:** `mpstats_selfcheck()` is a tri-state health canary:
+ `success`, `drift_detected` (reachable but unparseable — code change needed), or
+ `inconclusive` (transport failure / missing auth — says nothing about the
+ parsers). It is CLI-only — `marketplace-mcp doctor` runs every connector's canary
+ at once.
## Marketplace parameter
`place` is `"ozon"` or `"wildberries"`. `oz_fbs` is an Ozon-specific
Fulfilled-by-Seller flag (default true); harmless for wildberries.
## Workflow patterns
**Sales snapshot for one Ozon item by SKU:**
1. `mpstats_item([5107857210], place="ozon")` — current price/stock + 30-day graphs
2. Read `price_avg_rub` and `stock_now` for today; sum `orders_graph` for the
window total; compare `totals.sum` vs `totals.sum_prev` for trend.
**Compare a basket of SKUs:**
1. `mpstats_item([sku1, sku2, ...], place="ozon")` — batched, request-order
preserved. A SKU MPStats has no data for surfaces as a `meta.warnings` entry,
not a silent gap.
**Stock split (where the units physically sit):**
1. `mpstats_item([...], place="ozon")` for `stock_now` (total)
2. `mpstats_warehouses([...], place="ozon")` for the FBS/FBO split and
`last_update` (when MPStats last refreshed the snapshot).
## Graph semantics (gotchas)
- Graphs are length `days` (default 30), **oldest-first**; the final cell is
"today". The current price or stock is the last **non-zero** cell.
- Price and stock diverge on an all-zero graph, deliberately. `price_avg_rub`
becomes `None`, because a false `0.0` would rank a delisted item as the
cheapest. `stock_now` becomes `0`, because "none in stock" is a real reading.
An **empty** graph gives `None` for both — that one is genuinely no data.
- A zero cell means **"no data for that day"**, not "the value was zero".
Sum the graph for a real total; do not read a single cell as the answer.
- `totals.orders` / `totals.sum` are MPStats' own aggregates over the window —
prefer them over hand-summing unless you need a custom sub-window.
- A missing value is always `None`, never `0`: a zero would rank a dead listing
as the top seller — the exact bug this connector's parsers exist to prevent.
## Error format
On failure, raises `ToolError` with a JSON body: `{"error": "<code>",
"message": "...", "retryable": <bool>}`. Codes: `auth_missing` (no/expired
token — not retryable), `bad_request` (bad SKU/place), `rate_limited`
(retryable, honours `retry_after_s`), `transport_down`, `parser_drift`
(upstream shape changed — code change needed), `not_found` (no analytics for
any SKU). Partial data (some SKUs missing) stays a success with `meta.warnings`
and `meta.healthy: false` — silence never reads as success here.