# Ozon API MCP сервер

MCP (Model Context Protocol) сервер для Ozon Seller API и Ozon Performance API — по образцу [Wildberries API MCP Server](https://github.com/antondrpq/Wildberries-API-MCP-Server), тот же каркас (Express + JSON-RPC 2.0 поверх Streamable HTTP), но переписан под особенности Ozon.

## Чем Ozon отличается от Wildberries (и почему код не 1:1)

| | Wildberries | Ozon |
|---|---|---|
| Авторизация Seller API | один Bearer-токен (`Authorization`) | два заголовка одновременно: `Client-Id` + `Api-Key` |
| Домены API | 7 разных поддоменов по категориям (`advert-api.`, `seller-analytics-api.`, `finance-api.` и т.д.) | один домен `api-seller.ozon.ru` на всё |
| Реклама | тот же домен и токен, что и остальное | **отдельный продукт** `api-performance.ozon.ru` со своим OAuth2 (`client_id`/`client_secret` → `access_token` по `client_credentials`, токен живёт ~30 мин) |
| Пагинация отчётов | курсор `rrdId` | где курсор `last_id`/`cursor`, где обычная постраничная (`page`/`page_size`) — зависит от эндпоинта |
| Права токена | токен создаётся с категориями доступа (Аналитика/Финансы/Продвижение и т.д.) | `Api-Key` действует на весь личный кабинет сразу, категорийного разделения нет |

Это отражено в коде: `callOzon()` — обычные вызовы Seller API с двумя заголовками, `callPerf()` — отдельный клиент с кешируемым OAuth-токеном для рекламы.

## Инструменты (31 шт.)

### Товары / остатки / цены
`ozon_product_list`, `ozon_product_info`, `ozon_product_description`, `ozon_product_attributes`, `ozon_stocks_info`, `ozon_stocks_update` (запись), `ozon_prices_info`, `ozon_prices_update` (запись), `ozon_warehouse_list`

### Заказы FBS / FBO
`ozon_fbs_postings_list`, `ozon_fbs_unfulfilled_list`, `ozon_fbs_posting_get`, `ozon_fbs_posting_cancel` (запись, деструктивно), `ozon_fbo_postings_list`, `ozon_fbo_posting_get`

### Финансы
`ozon_finance_transactions`, `ozon_finance_transaction_totals`, `ozon_finance_realization`, `ozon_finance_summary` (композитный: сам пагинирует `/v3/finance/transaction/list` и агрегирует)

### Аналитика
`ozon_analytics_data`, `ozon_analytics_stock_on_warehouses`

### Реклама (Performance API)
`ozon_perf_campaign_list`, `ozon_perf_campaign_stats_request`, `ozon_perf_campaign_stats_result` (отчёты асинхронные — запрос по UUID, потом опрос), `ozon_perf_ads_summary` (композитный: сам опрашивает отчёт с ограничением по попыткам)

### Отзывы / вопросы / чат
`ozon_reviews_list`, `ozon_review_info`, `ozon_review_comment_create` (запись, публичный текст), `ozon_chat_list`, `ozon_chat_history`, `ozon_chat_send_message` (запись, публичный текст)

**Важно:** методы отзывов (`ozon_reviews_*`) требуют подписку **Premium Plus** в личном кабинете продавца Ozon — без неё Ozon вернёт ошибку доступа.

## Установка и запуск

### Предварительные требования
- Node.js ≥ 20
- Client-Id и Api-Key из личного кабинета Ozon Seller (Настройки → Seller API)
- (опционально, для рекламы) отдельные Client-Id/Client-Secret из Performance API — создаются в личном кабинете в разделе Продвижение → Performance API

### Прямой запуск через Node.js

```bash
npm install
cp .env.example .env
# заполните OZON_CLIENT_ID / OZON_API_KEY (и опционально OZON_PERF_*) в .env
npm start
```

Сервер поднимется на порту 3000. MCP-эндпоинт: `http://localhost:3000/mcp`, health-check: `http://localhost:3000/health`.

### Docker

```bash
cp .env.example .env
docker-compose up -d
```

### Тесты и линтер

```bash
npm test
npm run lint
```

## Пример запроса

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "ozon_product_list",
      "arguments": { "limit": 50 }
    }
  }'
```

## Безопасность

- Ключи Ozon хранятся только в `.env` на сервере и никогда не уходят клиенту.
- `MCP_API_KEY` (опционально) защищает сам MCP-эндпоинт отдельным секретом — независимо от ключей Ozon.
- HTTPS в проде так же не терминируется сервером — нужен reverse-proxy.
- Контейнер запускается от непривилегированного пользователя (`appuser`).
- Инструменты с записью (`*_update`, `*_cancel`, `*_comment_create`, `*_send_message`) помечены аннотацией `readOnlyHint: false` (а `ozon_fbs_posting_cancel` — ещё и `destructiveHint: true`), чтобы клиенты MCP могли различать их и запрашивать подтверждение перед вызовом.

## Известные ограничения / что стоит проверить перед продакшном

1. **Точные пути Performance API** (`/api/client/campaign`, `/api/client/statistics`) документированы Ozon хуже, чем Seller API, и периодически меняются — перед боевым использованием сверьте с актуальной документацией на [docs.ozon.ru/api/performance](https://docs.ozon.ru/api/performance).
2. `ozon_finance_summary` и `ozon_perf_ads_summary` — композитные инструменты, написанные по аналогии с `wb_finance_summary`/`wb_ads_summary` из оригинала; они не тестировались против боевого аккаунта Ozon (нет доступа к реальным кредам), только против структуры ответов из документации — обязательно прогоните на своих данных перед доверием к цифрам.
3. Список инструментов покрывает основные разделы Ozon Seller API, но не весь API целиком (у Ozon ~460 путей); при необходимости легко добавить новый инструмент по тому же паттерну: описание в `tools[]` + ветка в `executeTool()`.