docs: rewrite README with a value-first structure

Lead with what the server does (full API coverage via raw_request, writes gated
by confirmWrite, money in account currency, autoPaginate, get_quota, retries и
sandbox), trim the example prompts to non-trivial ones, shorten the campaign
audit to a table + concise takeaways (incl. ad extensions), add Требования and
Ограничения sections, and flag that the token grants full account access and is
stored in plaintext.

Author: gistrec

README.md

@@ -4,19 +4,65 @@
 [![CI](https://github.com/gistrec/mcp-yandex-direct/actions/workflows/ci.yml/badge.svg)](https://github.com/gistrec/mcp-yandex-direct/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-MCP-сервер для **Yandex Direct API v5**. Управляйте контекстной рекламой прямо из Claude (и других MCP-клиентов): кампании, группы, объявления, ключевые фразы, ставки, корректировки, расширения и статистика — на естественном языке.
+MCP-сервер для **Yandex Direct API v5**: управляйте контекстной рекламой из Claude, Cursor, Codex и других AI-клиентов на естественном языке.
 
-Покрыт весь API v5: частые операции — через удобные инструменты, всё остальное — через универсальный `raw_request`.
+Ассистент сам собирает данные из статистики, ключей, ставок и расширений, находит закономерности и вносит правки — то, что в веб-кабинете Директа приходится делать вручную и по одному экрану.
+
+## Что умеет
+
+- **Полное покрытие API v5** — частые объекты как удобные инструменты, всё остальное — через универсальный `raw_request`.
+- **Запись только по подтверждению** — изменения ставок, бюджетов, минус-слов и статусов требуют явного `confirmWrite`.
+- **Деньги в валюте аккаунта** — бюджеты и ставки на вход и на выход в той же валюте, что и кабинет (например, в рублях), без ручного пересчёта микроединиц.
+- **`autoPaginate`** — проход всех страниц по курсору `LimitedBy`, без молчаливой обрезки на больших аккаунтах.
+- **`get_quota`** — остаток дневной квоты API в Units (потрачено / осталось / лимит).
+- **Устойчивость** — ретраи на лимитах и 5xx с бэкоффом плюс режим песочницы (`YANDEX_DIRECT_SANDBOX`) для безопасных тестов.
+
+## Примеры запросов
+
+Попросите ассистента на русском — например:
+
+- «Какие ключевые фразы тратят бюджет, но не приносят кликов?»
+- «Подними ставки до 3 ₽ на фразы с CTR выше 15%»
+- «Найди id региона Москва и создай группу с таргетингом на Москву»
+- «Поставь корректировку −20% на мобильные в кампании 708589088»
+
+## Пример: аудит кампании
+
+> **Вы:** Проанализируй кампанию ClearTranscriptBot за последнюю неделю и предложи, что улучшить.
+
+> **Claude** *(вызывает `get_statistics`, `list_keywords`, `get_callouts`, `get_sitelinks`)*:
+>
+> Кампания «EPK/Поиск — бот в Max и Telegram» за 7 дней:
+>
+> | Дата | Показы | Клики | CTR | Расход, ₽ | Ср. клик, ₽ |
+> |------|-------:|------:|----:|----------:|------------:|
+> | 08.06 | 544 | 90 | 16.5% | 782.50 | 8.69 |
+> | 09.06 | 456 | 70 | 15.4% | 528.93 | 7.56 |
+> | 10.06 | 206 | 39 | 18.9% | 254.48 | 6.53 |
+> | 11.06 | 198 | 36 | 18.2% | 205.87 | 5.72 |
+> | 12.06 | 275 | 37 | 13.5% | 178.95 | 4.84 |
+> | 13.06 | 332 | 45 | 13.6% | 214.62 | 4.77 |
+> | 14.06 | 419 | 82 | 19.6% | 481.55 | 5.87 |
+> | **Итого** | **2 430** | **399** | **16.4%** | **2 646.90** | **6.63** |
+>
+> **Что улучшить:**
+> 1. **Автотаргетинг забирает почти весь трафик.** Условие `---autotargeting` собирает основную долю показов и кликов, а ключи («расшифровка интервью», «транскрибация записи» …) получают по 1–22 показа и почти 0 кликов — стоит усилить ставки на фразы или точнее настроить автотаргетинг.
+> 2. **Ставки на минимуме (0.30 ₽), а CTR высокий (16–20%).** На поиске при таком CTR имеет смысл поднять ставки на топ-фразы — заберёте больше недорогих показов.
+> 3. **Объявление 17674525479 отстаёт** (CTR 2–10% против 17–20% у основного) — кандидат на переработку заголовка/текста или отключение.
+> 4. **Расширения в порядке** — 9 уточнений и 3 быстрые ссылки; можно добавить ещё пару быстрых ссылок (лимит — 8).
 
 ## Быстрая установка
 
-**Claude Code** — одной командой:
+Разверните своего клиента:
+
+<details>
+<summary><b>Claude Code</b></summary>
 
 ```bash
 claude mcp add yandex-direct -e YANDEX_DIRECT_TOKEN=ваш_токен -- npx -y mcp-yandex-direct
 ```
 
-Другие клиенты — добавьте сервер в конфиг (разверните свой):
+</details>
 
 <details>
 <summary><b>Claude Desktop</b></summary>
@@ -100,59 +146,30 @@ YANDEX_DIRECT_TOKEN = "ваш_токен"
 
 [**→ Получить токен**](https://oauth.yandex.ru/authorize?response_type=token&client_id=7659d6ec6b044aafa6b5e3a00e8e35bb)
 
-Скопируйте токен в `YANDEX_DIRECT_TOKEN`. Токен персональный (привязан к вашему кабинету) и действует около года; при утере его можно получить заново по той же ссылке. Для агентских аккаунтов добавьте `YANDEX_DIRECT_LOGIN` — логин клиента.
+Скопируйте токен в `YANDEX_DIRECT_TOKEN`. Токен персональный (привязан к вашему кабинету) и действует около года; при утере его можно получить заново по той же ссылке.
 
-## Примеры запросов
-
-Просто пишите Claude на русском:
-
-- «Покажи все кампании и их статус»
-- «Сколько я потратил за последние 7 дней? Разбей по дням»
-- «Какие ключевые фразы тратят бюджет, но не приносят кликов?»
-- «Добавь минус-слова "бесплатно" и "онлайн" в кампанию 708589088»
-- «Подними ставки до 3 ₽ на фразы с CTR выше 15%»
-- «Найди id региона Москва и создай группу с таргетингом на Москву»
-- «Поставь корректировку −20% на мобильные в кампании X»
-- «Покажи мои уточнения и быстрые ссылки»
-
-## Пример: аудит кампании
-
-> **Вы:** Проанализируй кампанию ClearTranscriptBot за последнюю неделю и предложи, что улучшить.
-
-> **Claude** *(вызывает `get_statistics`, `list_keywords`, `get_bid_modifiers`, `get_callouts`)*:
->
-> Кампания «EPK/Поиск — бот в Max и Telegram» за 7 дней:
->
-> | Дата | Показы | Клики | CTR | Расход, ₽ | Ср. клик, ₽ |
-> |------|-------:|------:|----:|----------:|------------:|
-> | 08.06 | 544 | 90 | 16.5% | 782.50 | 8.69 |
-> | 09.06 | 456 | 70 | 15.4% | 528.93 | 7.56 |
-> | 10.06 | 206 | 39 | 18.9% | 254.48 | 6.53 |
-> | 11.06 | 198 | 36 | 18.2% | 205.87 | 5.72 |
-> | 12.06 | 275 | 37 | 13.5% | 178.95 | 4.84 |
-> | 13.06 | 332 | 45 | 13.6% | 214.62 | 4.77 |
-> | 14.06 | 419 | 82 | 19.6% | 481.55 | 5.87 |
-> | **Итого** | **2 430** | **399** | **16.4%** | **2 646.90** | **6.63** |
->
-> **Что улучшить:**
-> 1. **Автотаргетинг забирает почти весь трафик.** Условие `---autotargeting` собирает основную долю показов и кликов, а ваши ключи («расшифровка интервью», «транскрибация записи» …) получают по 1–22 показа и почти 0 кликов. Стоит проверить, не каннибализирует ли автотаргетинг фразы, и либо усилить ставки на ключи, либо точнее настроить автотаргетинг.
-> 2. **Ставки на минимуме (0.30 ₽), а CTR высокий (16–20%).** На поиске при таком CTR имеет смысл протестировать повышение ставок на топ-фразы — заберёте больше недорогих показов.
-> 3. **Объявление 17674525479 отстаёт** (CTR 2–10% против 17–20% у основного). Кандидат на переработку заголовка/текста или отключение.
-> 4. **Возрастные корректировки 0–17 и 18–24 обнулены.** Если ваша ЦА — взрослые, всё ок; иначе проверьте, не режете ли платёжеспособную аудиторию.
-> 5. **Расширения настроены хорошо:** 9 уточнений + 3 быстрые ссылки. Можно добавить ещё пару быстрых ссылок (лимит — 8).
->
-> Хотите, подниму ставки на топ-фразы и отключу слабое объявление? *(перед записью спрошу подтверждение)*
-
-Все операции записи (изменение ставок, бюджетов, минус-слов, статусов) сервер выполняет только по вашему явному запросу.
+⚠️ Токен даёт **полный доступ** к рекламному кабинету (включая трату бюджета) и хранится **открытым текстом** в конфиге клиента — относитесь к нему как к паролю.
 
 ## Настройка
 
 | Переменная | Обяз. | Описание |
 |---|---|---|
 | `YANDEX_DIRECT_TOKEN` | да | OAuth-токен Яндекс Директа. |
 | `YANDEX_DIRECT_LOGIN` | нет | Логин клиента (для агентских аккаунтов). |
+| `YANDEX_DIRECT_SANDBOX` | нет | `true` — работать в песочнице API. |
+
+Полный список переменных (язык ответов, таймауты, повторы) и инструментов — в [docs/TOOLS.md](https://github.com/gistrec/mcp-yandex-direct/blob/main/docs/TOOLS.md).
+
+## Требования
+
+- Node.js 18+ (запускается через `npx`, отдельная установка не нужна).
+- OAuth-токен Яндекс Директа — см. [Получение токена](#получение-токена).
+
+## Ограничения
 
-Остальные переменные (язык ответов, таймауты, повторы, песочница) и полный список инструментов — в [документации](https://github.com/gistrec/mcp-yandex-direct/blob/main/docs/TOOLS.md).
+- `get_statistics` использует асинхронный сервис Reports: отчёт генерируется на стороне Яндекса (сервер опрашивает готовность) и имеет собственные лимиты на объём и число отчётов в сутки.
+- Токен живёт около года — потом нужно получить заново.
+- Для агентских аккаунтов укажите клиента через `YANDEX_DIRECT_LOGIN`.
 
 ## Документация