DirectAI MCP — личный сервер статистики и управления Яндекс Директом

ИИ-агент? Следуй AGENTS.md.

DirectAI MCP is a local MCP server for Yandex Direct stats and management. Runs on your Windows 11 PC for a single user. Tested on Windows 11 only; macOS/Linux not supported. Start install at §1 below.

Локальный MCP-сервер: ИИ-ассистенты (OpenCode, Codex и др.) через него читают статистику и управляют вашими аккаунтами Яндекс Директа. Только для одного пользователя, работает на вашем компьютере, в интернет ничего не выставляет.

Прежде чем устанавливать

Обязательно:

• Windows 11 (инструкции — только для PowerShell; macOS/Linux не тестировались и не поддерживаются);

• аккаунт Яндекс Директа с хотя бы одной кампанией (можно черновик); для агентств — главный логин агентства;

• своё приложение на oauth.yandex.ru (анкета на 5 минут, права Директ и Метрика) — запомните ID приложения;

• одобренный доступ к API Директа (Инструменты → API → заявка с ID приложения); одобрение занимает до нескольких дней;

• ИИ-помощник с поддержкой MCP (OpenCode, Codex, Claude Code, Claude Desktop, Hermes); сам DirectAI бесплатный, работает локально на вашем компьютере, для одного пользователя.

По ходу установки: токен получаете по ссылке, вводите сами в своём терминале, никогда не в чат.

Желательно: доступ к счётчику Метрики (иначе CRM-выручка не отличается от условной ценности целей).

Не нужно: программировать, покупать сервер, заранее ставить git или Python.

С чего начать

1. Создайте приложение и подайте заявку на API — это самое долгое, начните с этого (подробности — §1.1, шаг 5).

2. Пока ждёте одобрения — установите DirectAI (§1 или §1.1).

3. Когда заявку одобрят — получите токен и выполните проверку (set-token, затем check).

Related MCP server: MCP «Яндекс Директ»

1. Установка с нуля

Нужно: Windows 11, uv, git (оба ставятся через winget, см. §1.1), токен Яндекс Директа (как получить — см. §1.1, нужен доступ к API).

cd $env:USERPROFILE
git clone https://github.com/perejaslav/directai-mcp.git directai-mcp
cd $env:USERPROFILE\directai-mcp
uv tool install --editable .
uv tool update-shell
directai-mcp init
directai-mcp set-token --login ВАШ_ЛОГИН
directai-mcp check

Впишите свой логин в %USERPROFILE%\.directai\accounts.toml ([auth] login, замените демо-алиасы) между init и set-token; в set-token передайте тот же логин флагом --login.

Что происходит: init создаёт %USERPROFILE%\.directai\ и копирует примеры конфигов (существующие не трогает); set-token маскированно спрашивает токен и кладёт его в Credential Manager Windows (в файлах токена нет никогда); check проверяет доступ. Ожидание — строки OK по каждому аккаунту с числом кампаний и остатком баллов.

1.1. Установка через ИИ-агента — промпт для новичка

Новичок (свой аккаунт Директа, ничего общего с автором) копирует блок ниже в любого агента (OpenCode, Codex, Claude Code) — агент ставит всё с нуля.

Ты помогаешь новичку установить DirectAI MCP с нуля на Windows 11.
Человек не знает git, uv и PowerShell. Объясняй простыми словами,
одно действие за раз. Каждую команду давай отдельно, жди результата.
Правила: бюджеты и стратегию без «да» владельца не менять; guard не выключать никогда;
запись только через план с подтверждением; токен только в Credential Manager.
0. Сначала спроси, одобрен ли уже доступ к API Директа. Нет — начни
с шага 5 (создать приложение и подать заявку: это самое долгое),
затем ставь DirectAI (шаги 1–4), а токен и check — после одобрения.
Доступ уже одобрен — иди по шагам 1–4, затем токен и проверка.
1. Спроси разрешение и поставь git и uv (флаги снимают лишние вопросы):
winget install --id Git.Git -e --accept-package-agreements --accept-source-agreements
winget install --id astral-sh.uv -e --accept-package-agreements --accept-source-agreements
Проверь: git --version и uv --version. Нет команды — обнови PATH в этой сессии
(давай строку одним блоком, проверь, что вставилась одной строкой):
$env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")
Нет winget — поставь App Installer из Microsoft Store.
2. Склонируй репозиторий (три команды, по одной). Папка directai-mcp уже есть —
не клонируй, а выполни git pull внутри неё:
cd $env:USERPROFILE
git clone https://github.com/perejaslav/directai-mcp.git directai-mcp
cd $env:USERPROFILE\directai-mcp
3. Установи и инициализируй (по одной команде):
uv tool install --editable .
uv tool update-shell
$env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")
directai-mcp --version
directai-mcp init
Первая установка качает Python несколько минут — это не зависание.
4. Спроси логины кабинетов (это не секрет): главный — владелец будущего токена.
Если кабинетов несколько (агентство: главный логин видит клиентские) —
попроси все. ПОЛНОСТЬЮ замени демо-алиасы в %USERPROFILE%\.directai\accounts.toml:
[auth] login — реальный главный логин, под каждый логин свой [aliases.*].
goals.toml необязателен: названия целей Метрики, можно заполнить позже.
5. Токен. Объясни: создай приложение типа «Для доступа к API или отладки»
на https://oauth.yandex.ru/client/new с правами direct:api и metrika:read.
Redirect URI настраивать не нужно — он фиксирован. Затем открой в браузере ссылку
https://oauth.yandex.ru/authorize?response_type=token&client_id=ID_ПРИЛОЖЕНИЯ&redirect_uri=https://oauth.yandex.ru/verification_code
(подставь ID со страницы приложения) и нажми «Разрешить» — токен появится
в адресной строке. Скопируй ТОЛЬКО значение после access_token= и до &,
не весь URL (вид: access_token=y0_AgA...&token_type=...). Спроси «что видишь?»:
ошибка OAuth — проверить ID приложения и пробелы. Это штатный способ из доки:
https://yandex.ru/dev/direct/doc/ru/concepts/auth-token. Затем подай заявку
на доступ к API в интерфейсе Директа (Инструменты → API → Мои заявки),
инструкция: https://yandex.ru/dev/direct/doc/ru/concepts/register.
В описании заявки укажи «личный учёт статистики и управление своими кампаниями».
Одобрение занимает до нескольких дней — ошибка 58 до этого норма, просто ждём.
Без metrika:read типы ценностей берутся из goals.toml (по умолчанию условные).
6. Токен в чат писать ЗАПРЕЩЕНО. Пусть человек САМ выполнит в своём терминале:
directai-mcp set-token — и введёт токен в скрытое поле. Символы не отображаются —
это нормально: вставить и Enter. Если вставил в чат — останови, попроси
отозвать токен в Яндекс ID и выпустить новый.
7. Проверь: directai-mcp check. Расшифруй итог: OK — работает; 53 — неверный
токен, повторить шаг 6; 58 — нет доступа к API, вернуться к шагу 5; 513 —
у логина нет аккаунта в Директе (создай кампанию в интерфейсе); 152 —
кончились баллы API, подождать до завтра. Коды:
https://yandex.ru/dev/direct/doc/ref-v5/concepts/errors-list.html
8. Самопроверка сервера: directai-mcp probe. Ожидание — две строки OK
(версия сервера, число инструментов, stats_summary найден). Баллы API
не тратятся. Сырые stdio-пробы вручную не делать — только probe.
9. Подключи харнес: сначала спроси, какой — OpenCode, Codex или Claude Code.
Сделай копию его конфига (*.bak), потом ДОПИШИ блок directai-mcp, чужие MCP
не трогай. Готовые блоки — examples/harness-configs.md.
9. Попроси человека САМОГО перезапустить харнес (закрыть все его окна
и открыть заново). В новой сессии пусть спросит:
«Используй только directai-mcp: покажи расходы по всем аккаунтам за вчера» —
и сверит цифры с веб-интерфейсом Директа. Сошлось — готово.
10. Удали свои бэкапы (*.bak-*, *-tool-backup-*), чужие файлы не трогай.

2. Подключение к харнесам

Команда запуска везде одна — directai-mcp (без аргументов: STDIO-сервер). После настройки перезапустите харнес.

OpenCode — файл %USERPROFILE%\.config\opencode\opencode.json:

{
  "mcp": {
    "directai-mcp": {
      "type": "local",
      "command": ["directai-mcp"],
      "enabled": true
    }
  }
}

Codex — файл %USERPROFILE%\.codex\config.toml:

[mcp_servers.directai-mcp]
command = "directai-mcp"
args = []

Остальные (Claude Desktop, Claude Code) — готовые фрагменты в examples/harness-configs.md. Если харнес не видит команду, укажите полный путь к directai-mcp.exe (покажет (Get-Command directai-mcp).Source).

Проверка (задать ИИ): «Покажи расходы по всем аккаунтам за последние 7 дней» — итоги должны совпасть с веб-интерфейсом Директа.

3. Файлы в %USERPROFILE%\.directai\

Переопределить каталог: переменная DIRECTAI_HOME. Токен Директа: только Credential Manager (directai-mcp) или переменная DIRECTAI_TOKEN. Для Метрики (v1.17.1) — отдельный токен: directai-mcp set-metrika-token --login <логин> (Credential Manager directai-mcp-metrika или переменная DIRECTAI_METRIKA_TOKEN), подробности — §7.1; без него чтение идёт токеном Директа с примечанием, а запись целей недоступна. Для Яндекс.Вебмастера можно хранить отдельный токен: directai-mcp set-token --webmaster (Credential Manager directai-mcp-webmaster или переменная DIRECTAI_WEBMASTER_TOKEN); без него используется основной токен. Для Wordstat API Yandex Cloud используется отдельный API-ключ: выполните directai-mcp set-token --wordstat, введите folderId каталога AI Studio, затем ключ в скрытом поле. Ключ хранится в Credential Manager (directai-mcp-wordstat или DIRECTAI_WORDSTAT_API_KEY), а folderId — в [wordstat] folder_id в accounts.toml. Секретный ключ в этот файл не записывается. Действия Wordstat — только чтение и не используют OAuth-токен Директа. Запись в Яндекс Аудитории выключена по умолчанию ([audience] write_enabled=false); включается только явным write_enabled = true, путь тот же: plan_write → ваше согласие → apply_write, guard требует имя сегмента [TEST DirectAI]*.

4. Что умеет сервер

Порядок работы ИИ: search_actions → describe_action → run_read (чтение) или plan_write → показать вам → apply_write (запись).

describe_action без имени (или с пустой строкой) — статус сервера, вызов бесплатный (API не тратится): server_version (что декларирует установка пакета, importlib.metadata), code_version (код, реально запущенный в процессе), disk_version (исходники на диске) и строка «Метрика: …» — какой токен используется для Метрики (отдельный или токен Директа), §7.1. Если code_version ≠ disk_version — блок предупреждения «перезапустите MCP-сервер»; если server_version ≠ code_version — «переустановите пакет» (uv tool install --force --editable ., README §7): у editable-установки метаданные обновляются только переустановкой, перезапуск сервера не поможет.

Чтение (57):

Метрика: отчёты (v1.12.0, только чтение)

• metrika_traffic — визиты, пользователи, отказы, глубина, время, достижения цели и CR по источникам: group_by — source (тип источника), utm / utm_full, direct (кампании Директа), landing (страница входа), device, region. Фильтры filter_utm_source / filter_utm_campaign (точное совпадение).

• metrika_goals_report — строки = цели (достижения, CR); в разрезе group_by — опционально (те же значения).

• metrika_bytime — динамика по дням/неделям (group: day|week): визиты, отказы, выбранная цель.

• metrika_direct_cpa — связка с Директом по кампаниям одного логина: расход/клики из Директа + визиты/отказы/цели из Метрики; колонки — кампания, расход, клики, визиты, клики→визиты %, отказы %, цели, CR %, CPA = расход / цели. Расхождение кликов и визитов > 30% — флаг «проверить разметку/счётчик».

• Общее: счётчик — counter_id, иначе [metrika] counter_id, иначе счётчики кампаний; период по умолчанию — последние 14 полных дней; цели по умолчанию — основная (primary_conversion_goal_id), иначе все цели счётчика; атрибуция по умолчанию lastsign (в шапке); accuracy=full, семплирование помечается; 403 по счётчику — «нет доступа», без падения.

• Отчёты остаются только на чтение; запись целей счётчика — отдельные действия записи, см. §5.3.

• Порядок сопоставления кампаний в metrika_direct_cpa (способ — в колонке «Связь»): ID → ID+1e8 (у старых кампаний OrderID в Метрике больше CampaignId на сто миллионов; «Связь» = ID+сдвиг) → точное имя при единственном кандидате («Связь» = имя). Несопоставленные — отдельными блоками (кампании логина без расхода / визиты кампаний других логинов / «Чужие кампании»).

Режим выгрузки (dump)

Любое действие чтения принимает параметры dump_dir (папка сессии) и dump_tag (суффикс имени). В этом режиме ответ дополнительно сохраняется в файлы как есть, без преобразований:

• <NN>_<action>[_<tag>].json — конверт ответа: raw_items (объекты API: деньги в micros, enum, null, вложенность; единственное преобразование — ID-ключи *Id(s) числом → строкой), requested_field_names (по каким полям читали), pagination_complete (все ли страницы прочитаны — честно из пагинации, не дефолт), truncated (неполон ли именно raw), display_truncated (обрезан ли только показ для чата), warnings. Пример: 03_keywords_list.json, 07_ads_list_morning.json;

• manifest.json — порядок файлов и их sha256 (сборка только по манифесту, не по glob);

• describe_<action>.json — схема ответа (один раз на действие).

Пример вызова: run_read({"name": "keywords_list", "params": {"account": "client-a", "campaign_ids": [900000036], "dump_dir": "C:/work/dump-session", "dump_tag": "morning"}}). Основной потребитель — скилл yandex-direct-campaign-dump-directai: он вызывает чтения, собирает dump.json, проверяет полноту валидатором и строит Markdown/Excel. Вручную данные не пересказываются.

Связанные правила чтения:

• ads_list, параметр states: по умолчанию архивные не возвращаются; states: ["ARCHIVED"] (или вместе с ON/OFF/SUSPENDED) включает их.

• Фразы — целиком по умолчанию (включая внутрифразные минус-слова); укороченный показ — только явным short_phrases: true и только для отображения, raw не трогает.

Прогноз ставок и спроса (v1.9.0, только чтение)

• keyword_bids_forecast — по уже добавленным фразам (KeywordBids.get: AuctionBids → объём трафика/ставка/цена, Coverage для сетей): ровно один scope (campaign_id | adgroup_ids | keyword_ids), ровно один кабинет; таблица «объём → ставка → цена» + медианы цены для объёмов 100 и 15. Пример: run_read({"name": "keyword_bids_forecast", "params": {"account": "client-a", "keyword_ids": [900000011], "include_network": false}}).

• phrases_forecast — по новым фразам до добавления (Live v4 CreateNewForecast → ожидание → GetForecast → DeleteForecastReport): не более 100 фраз за отчёт, region_ids[] обязателен, currency (по умолчанию RUB). Пример: run_read({"name": "phrases_forecast", "params": {"account": "client-a", "phrases": ["окна пвх"], "region_ids": [213]}}).

• Ограничения: ставки не меняются; на автостратегиях/ЕПК данные показываются с пометкой «ставками управляет стратегия, прогноз справочный», при отсутствии — «нет данных аукциона» (не ошибка); AuctionBids=null при RARELY_SERVED, только графических объявлениях в группе и всегда для автотаргетинга (показывается отдельно); прогноз для новых фраз: не более 5 отчётов одновременно (ошибка 31), хранение 5 часов, готовность до ~60 с (таймаут — forecast_id для повтора); период API прогноза не поддерживает.

• Проверено живьём (10.2026): при поиске SERVING_OFF API всё равно отдаёт AuctionBids — показываются справочно с пометкой про отключение поиска; позиции прогноза — P11..P24, CTR — числом (знак % добавляет рендер).

Ретаргетинг и аудитории (v1.10.0)

• Чтение всегда доступно: retargeting_lists_list — условия кабинета («выполнили всё ... И НЕ выполнили ничего ...», Scope, где используются); audience_targets_list — привязки к группам (условие, состояние, ставка/приоритет). Пример: run_read({"name": "retargeting_lists_list", "params": {"account": "client-a"}}).

• Правила (A8): в ЕПК/текстово-графических группах — условия RETARGETING (цели/сегменты Метрики, сегменты Аудиторий); AUDIENCE — для медийных групп (краткосрочные интересы допустимы и в ТГО); совместимость привязки проверяется живьём по AvailableForTargetsInAdGroupTypes условия (ЕПК-группы API v5 видит как TEXT_AD_GROUP). На поиске условие сужает аудиторию (AND с фразами), в сетях — расширяет (OR). Исключить аудиторию (например, купивших) — только корректировкой ставки −100% (bid_modifiers_set, вид RETARGETING): «показы этой аудитории будут полностью отключены»; в конверсионных стратегиях это меняет целевую CPA/ДРР. Условие только из NONE-правил — только для корректировок (привязать к группе нельзя).

• Запись выключена по умолчанию: [retargeting] write_enabled = true в accounts.toml (аналог [audience]). Примеры: посетители сайта за 30 дней без заказа — retargeting_list_create (ALL-правило «цель визита», NONE-правило «цель заказа»); исключить купивших — bid_modifiers_set с kind: RETARGETING, bid_modifier: 0 на условие купивших.

• Лимиты API: 2000 условий на пользователя, 1000 за вызов; 1–50 правил, 1–250 аргументов; срок членства 1–540 дней (для целей Метрики); не более 50 привязок в ТГО-группе; ставка привязки — ручная стратегия (при авто — только приоритет, ставка игнорируется с предупреждением).

• Баллы: KeywordBids.get — 15 + 3 за каждые 2000 фраз (оценка в ответе, факт — в строке API:; при 152 — понятная ошибка с остатком); Live-прогноз — без Units (баллы не расходуются). Учёт баллов уже есть (Units из заголовков, net_summary) — переиспользован.

• Каждый ответ помечен «прогноз Яндекса, не гарантия» с датой, регионами и валютой (НДС — как отдаёт API, без пересчёта). В dump поля аукциона не добавляются. Подсказка также в описании keywords_add.

Запись (25, все — только через план, см. §5):

Запись в Аудитории (экспериментально, выключена по умолчанию [audience] write_enabled=false): audience_segment_from_file — создание сегмента uploading из локального CSV/TXT (phone/email, в API только SHA256-хеши; имя только [TEST DirectAI]*, файл с несколькими колонками без id_column отклоняется) и audience_segment_delete — удаление сегмента только [TEST DirectAI]* по живому имени из API. Путь тот же: plan_write → ваше согласие → apply_write; без включённого write_enabled оба действия отклоняются до API.

Запись ретаргетинга (v1.10.0, выключена по умолчанию [retargeting] write_enabled=false): retargeting_list_create / retargeting_list_update / retargeting_list_delete — условия (цели Метрики, сегменты; удаление — только неиспользуемых, без префикса [TEST DirectAI] нужно явное согласие) и audience_target_add / audience_target_state — привязка к группам и её состояние. Исключение аудитории — только корректировкой −100% (bid_modifiers_set, вид RETARGETING), не условием. Путь тот же: plan_write → ваше согласие → apply_write; без включённого write_enabled все пять действий отклоняются до API. Подробности — раздел «Ретаргетинг и аудитории» ниже.

5. Как работает запись

1. ИИ вызывает plan_write — сервер показывает предпросмотр «было → станет» и предупреждения (например, ставка меняется больше чем в 2 раза).

2. Вы читаете предпросмотр и явно разрешаете.

3. ИИ вызывает apply_write (с acknowledge_warnings=true, если были предупреждения) — сервер выполняет, затем повторно читает объект (read-back) и пишет всё в журнал.

4. Итог: applied (подтверждено), partial (часть строк отклонена API), failed, unverified (результат неясен — проверить вручную).

Журнал: инструмент get_operation_log (последние операции) и файл journal.sqlite. Планы живут в каталоге plans\ — общем для всех процессов сервера: план, созданный в одном процессе, применяется из любого другого ровно один раз (повтор — «уже применён», истёкший — «просрочен», неизвестный id — «не найден»). Прямых записей в обход плана не бывает. Что можно где: бюджеты и смена стратегии запрещены везде (к ключевым целям относится изменение их набора и ценностей); в боевых кампаниях разрешены фразы (добавление, пауза/запуск), объявления (создание, тексты, ссылки), ссылки/уточнения, регионы групп, минусы и площадки (добавление), ставки и корректировки; замена целиком (replace), пауза кампаний и объявлений, удаления — только в тестовых кампаниях [TEST DirectAI]*.

5.1. Создание кампаний: ЕПК по умолчанию

• campaigns_create создаёт UNIFIED_CAMPAIGN (ЕПК, запрос на json/v501). Legacy TEXT_CAMPAIGN — только явным campaign_type="TEXT_CAMPAIGN" с предупреждением «устаревший тип».

• campaigns_update: блок стратегии и версия запроса — по типу кампании (UnifiedCampaign/v501 для ЕПК).

• adgroups_create: тип группы API выводит из кампании; неизвестная кампания или тип — отказ до API.

• ads_create: для ЕПК используйте responsive_ads (RESPONSIVE_AD, запрос на v501); TEXT_AD допустим, но API конвертирует его (10251) — предупреждение требует подтверждения. Совместимость типа группы/кампании проверяется до API. DisplayUrlPath обязателен для обоих типов и сверяется в read-back.

• Цепочка создания: кампания → группа → фразы → объявление отдельными планами; модерация (ads_state moderate) в цепочку не входит и заблокирована guard по умолчанию — только отдельным шагом с явного решения пользователя.

5.2. Ключевые цели (campaigns_update: priority_goals)

Цели и их ценности (PriorityGoals) — вход оптимизации, поэтому меняются тем же планом, что и стратегия: только в тестовой кампании, а в режиме confirm — после явного «да» на конкретный план.

• Формат: список [{goal_id, value_rub, is_metrika_source_of_value=false}]. value_rub — ценность конверсии в рублях (для «Максимум прибыли» — маржа); внутрь уходит в микро-единицах (₽ × 1 000 000). Список целей — metrika_goals_list; is_metrika_source_of_value=true API принимает только для стратегий с долей расходов (AVERAGE_CRR, PAY_FOR_CONVERSION_CRR).

• Режим один — замена набора целиком (Operation=SET): не перечислили цель — она пропала. Пустой список без явного priority_goals_reset=true отклоняется до API; priority_goals_reset=true — это PriorityGoals=null (оптимизация на вовлечённые сессии). Оба параметра вместе нельзя.

• Повторяющийся goal_id, goal_id ≤ 0 и value_rub ≤ 0 — отказ до API.

• Как в API, ключевые цели нельзя передавать кампании в пакетной стратегии (и нельзя одновременно с ключом пакетной стратегии в параметрах): такую кампанию сначала отвязывают (PackageBiddingStrategy=null + новая BiddingStrategy) — DirectAI этого пока не делает.

• Предпросмотр плана показывает цели и ценности «было → станет», read-back после записи перечитывает PriorityGoals и сверяет их с запрошенными.

5.3. Цели счётчика Метрики (metrika_goal_create/update/delete)

Запись целей — через Management API POST|PUT|DELETE /management/v1/counter/{counterId}/goal(s). Нужен отдельный токен приложения Метрики с правом metrika:write (§7.1): без него запись отклоняется до обращения к API. Если права нет, API отвечает 403, и сервер объясняет, как перевыпустить токен — токен в сообщениях, логах и чате не появляется.

counter_id — точный id счётчика, без разбора кампаний.

Типы целей и параметры:

Общее для всех: name (1–255), default_price (цена по умолчанию, не отрицательная), is_favorite.

• Мультицели в Management API нет — типа multi в GoalE не существует (мультицель есть только в интерфейсе Метрики). Эквивалент «несколько условий через ИЛИ» — несколько conditions в одной цели, так и работает type=url/action; отдельная попытка создать multi отклоняется с этим текстом. Типы chat и payment_system в DirectAI не заведены.

• Проверки до записи (живое чтение, до обращения к API): право на счётчик (GET counter/{id} → permission: own/edit; view — только просмотр, запись отклоняется), лимит счётчика — до 200 целей, и точный дубль: тот же тип + те же условия → отказ с id и именем существующей цели (порядок условий и краевые пробелы не считаются различием; порядок шагов составной цели — считается).

• metrika_goal_update — частичное изменение (имя, условия, цена по умолчанию, is_favorite, depth, duration). В API PUT заменяет цель целиком, поэтому сервер читает живую цель и собирает полное тело: поля, которые вы не меняли, сохраняются. Ничего не меняется — отказ до API. Тип цели и её шаги не меняются; автоцели (e_purchase, call, form, conditional_call и др. — их нет в GoalE) не обновляются и удаляются только вручную в интерфейсе.

• metrika_goal_delete — необратимо: собранная по цели статистика пропадёт из отчётов. План всегда помечается «⚠ ОПАСНАЯ ОПЕРАЦИЯ» и применяется только с owner_confirmed=true (в любом режиме guard) и acknowledge_warnings=true.

• Read-back после каждой записи: сервер заново читает цели счётчика и сверяет тип, условия и имя (id новой цели — из ответа POST). При таймауте или обрыве связи статус unverified, запись не повторяется вслепую — решение принимает перечитанный список целей.

6. Guard (защита)

Опасные операции — строго внутри кампаний [TEST DirectAI]*. Guard это контролирует: перед каждой записью сверяет живое имя кампании через API.

Как завести тестовую кампанию: создайте в интерфейсе Директа кампанию с именем, начинающимся на [TEST DirectAI] (можно черновик); только в ней доступны replace, пауза кампаний/объявлений, удаления.

Коротко о правилах:

• бюджеты и смена стратегии — запрещены везде, даже в тестовых; к стратегии отнесены и ключевые цели с ценностями (см. §5.2);

• в боевых кампаниях можно: фразы, объявления, ссылки/уточнения, регионы, минусы и ставки (см. §5);

• только в тестовых: замены целиком, пауза кампаний/объявлений, удаления.

Блокируется: запись вне разрешённого, переименование кампаний, модерация, чужие общие объекты, неизвестные действия.

Включён по умолчанию ([guard] guard=true в accounts.toml плюс дефолт в коде). Выключение — только вашим решением: поставьте guard = false (и убедитесь, что нет переменной DIRECTAI_TEST_GUARD=1), после тестов верните true.

Режим confirm (v1.15.0): не запрет, а подтверждение владельца

[guard]
guard = true
mode = "confirm"   # по умолчанию "block"

В режиме confirm политические запреты не блокируют, а превращают план в «⚠ ОПАСНАЯ ОПЕРАЦИЯ» со списком причин: бюджет (daily_budget, strategy с WeeklySpendLimit), смена стратегии, изменение ключевых целей и их ценностей (§5.2), модерация, переименование кампании, создание кампании без префикса, пауза/запуск/архив кампаний и объявлений, правки вне [TEST DirectAI]*, замены целиком, удаление корректировок, чужие общие объекты.

Такой план применяется только apply_write(..., owner_confirmed=true) — агент ставит флаг лишь после явного «да» владельца в чате на этот конкретный план. Предупреждения по-прежнему требуют отдельно acknowledge_warnings=true. В журнал операция пишется с пометкой [ОПАСНАЯ, подтверждено владельцем].

Жёсткими остаются и в confirm: объект не найден/ошибка API, поля read_only (A1), выключенные Аудитории/ретаргетинг (write_enabled=false), неизвестные действия.

Цели Метрики (§5.3) живут вне Директа, поэтому префикс [TEST DirectAI]* к ним не относится: запись проверяет право на счётчик, отсутствие дубля и лимит 200 целей (это отказ до API), а удаление цели в любом режиме guard требует owner_confirmed=true.

campaigns_update снова принимает name (одна кампания за план) и daily_budget (₽, daily_budget_mode STANDARD|DISTRIBUTED) — в block они отклоняются до API, в confirm — опасная операция. То же и для ключевых целей (priority_goals, priority_goals_reset): класс «стратегии» (§5.2), свойств плана (plan_id, TTL 15 минут, acknowledge_warnings, owner_confirmed) сервер не ослаблял.

6.1 Правило для агентов-клиентов MCP

Текст блокировки guard — это защита, а не ошибка.

При блокировке агент:

1. останавливается и сообщает вам: какая операция, какой объект, почему заблокирована (режим confirm: план «⚠ ОПАСНАЯ ОПЕРАЦИЯ» — показывает причины дословно и применяет с owner_confirmed=true только после вашего явного «да» на этот план);

2. не ищет и не меняет конфиг guard (accounts.toml, секция [guard], переменная DIRECTAI_TEST_GUARD) и вообще ничего в safety/;

3. не предлагает обход защиты;

4. не переносит операцию на другую кампанию (в т.ч. тестовую) без вашего явного указания.

Снятие ограничения — только ваше ручное решение (см. §6). Ни один инструмент сервера конфиг guard не пишет и не читает наружу: единственный источник — accounts.toml и переменная окружения.

6.2 Сравнение периодов и выбор инструмента

1. Сравнение периодов агент выполняет только через stats_compare (A, B, Δ абс., Δ% одним вызовом). Два вызова stats_* с ручной арифметикой запрещены — они дают разную точность Δ%.

2. Если вы указали конкретный MCP-сервер или инструмент — агент использует только его и не подменяет другим.

7. Обновление

Перед обновлением: закройте все окна харнесов и остановите фоновый шлюз Hermes (он держит directai-mcp.exe даже при закрытых окнах) — команды выполняет человек в обычном PowerShell:

Get-Process directai-mcp -ErrorAction SilentlyContinue | Stop-Process -Force
hermes -p default gateway stop 2>$null
Get-CimInstance Win32_Process |
  Where-Object { $_.CommandLine -match 'hermes|openchamber|opencode' -and $_.ProcessId -ne $PID } |
  ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
Start-Sleep -Seconds 2
Get-CimInstance Win32_Process |
  Where-Object { $_.Name -eq 'directai-mcp.exe' -or $_.CommandLine -match 'hermes|openchamber|opencode' } |
  Select-Object ProcessId, Name

Фильтр по python.exe … hermes_cli.main … gateway run не использовать: Hermes запущен отдельным процессом (direct spawn) и таким фильтром не ловится. Чужие процессы агент не убивает — команды выполняет человек.

Проверка перед переустановкой (c и d должны быть OK):

directai-mcp doctor --preinstall

Обновление с бэкапом вне uv tool dir и откатом при ошибке (без exit — он закрывает окно PowerShell):

cd $env:USERPROFILE\directai-mcp
git pull
$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
$tooldir = uv tool dir
Copy-Item "$tooldir\directai-mcp" "$env:USERPROFILE\directai-mcp-tool-backup-$stamp" -Recurse
uv tool install --force --editable .
uv tool update-shell
if ($LASTEXITCODE -ne 0) {
  Remove-Item "$tooldir\directai-mcp" -Recurse -Force
  Copy-Item "$env:USERPROFILE\directai-mcp-tool-backup-$stamp" "$tooldir\directai-mcp" -Recurse
  Write-Output "ОТКАТ: инструмент восстановлен из бэкапа"
} else {
  directai-mcp check
  directai-mcp probe
  Remove-Item "$env:USERPROFILE\directai-mcp-tool-backup-$stamp" -Recurse -Force
}

init после обновления можно повторить: существующие конфиги не затрутся, недостающие (например, новые примеры) докопируются. После обновления откройте харнесы заново и запустите Hermes (сервер подхватывается при старте). Никогда не делайте cd внутрь каталога установки (uv tool dir): бэкап перед установкой — только вне tool dir (копии внутри tool dir uv считает инструментами и выдаёт malformed); бэкап удаляется только при успехе, при ошибке — откат из бэкапа.

7.1. Отдельный токен Метрики (v1.17.1)

Метрика больше не работает на токене Директа: у приложений «для авторизации пользователей» лимит 3 группы разрешений, поэтому права metrika:read и metrika:write живут в отдельном приложении Яндекс OAuth и хранятся в своём ключе Credential Manager (directai-mcp-metrika).

Поведение по умолчанию:

• чтение Метрики (metrika_traffic, metrika_goals_list, metrika_goals_report, metrika_bytime, metrika_direct_cpa, counter_check, снимки журнала) идёт отдельным токеном, если он есть;

• без отдельного токена чтение продолжает работать на токене Директа, а в ответе появляется примечание «Метрика читается токеном Директа…»;

• запись целей (metrika_goal_create/update/delete) без отдельного токена не начинается: Ошибка подготовки: запись целей Метрики требует отдельный токен Метрики (metrika:write)… — до обращения к API.

Выпуск токена (шаги выполняет владелец, токен в чат не передаётся):

1. В приложении Метрики включены права «Яндекс Метрика» → чтение и изменение (metrika:read + metrika:write), Redirect URI https://oauth.yandex.ru/verification_code — как у приложения Директа.

2. Откройте в браузере под своим логином (команда сама напечатает ссылку с client_id приложения Метрики):

   directai-mcp set-metrika-token --login ВАШ_ЛОГИН

3. Разрешите доступ, скопируйте токен из адресной строки и вставьте его в скрытое поле, которое задаёт команда. Client secret приложения DirectAI не знает и не хранит — OAuth-поток проходит в браузере, как для Директа.

4. Проверка: directai-mcp check (строка «Метрика: …») и directai-mcp doctor (проверка l. Метрика). В describe_action без аргументов тоже есть строка «Метрика: отдельный токен / токен Директа».

Что показывают проверки (значение токена не печатается нигде):

• источник токена и его длина;

• client_id приложения, выпустившего токен (login.yandex.ru/info) — так видно, что Метрике достался именно токен приложения Метрики; если приложение чужое, check и doctor об этом предупреждают;

• читается ли список счётчиков;

• право metrika:write не проверяется: Яндекс не отдаёт scopes токена, а выяснить его можно только записью цели. Поэтому в выводе честно сказано, что право подтвердит первая запись (при 403 сервер объяснит, как перевыпустить токен).

Отозвать токен — на стороне Яндекс ID (правки приложения → «Отозвать токены»); новый токен выпускается той же командой.

7.2. Секреты в логах (v1.17.2)

• Логи HTTP-клиентов (httpx, httpcore) всегда на уровне WARNING: на INFO логгер пишет URL запроса целиком, а значит и query-параметры. Поднимать их уровень нельзя.

• Дополнительно все обработчики логов чистят значения параметров oauth_token, token, apikey, api_key, access_token, refresh_token → ***. Тексты сетевых ошибок Метрики чистятся тоже.

• Токены передаются только заголовками (Authorization: OAuth / Bearer / Api-Key) и никогда не попадают в URL, ответы инструментов, журнал операций и предпросмотр плана.

• Файл лога: %USERPROFILE%\.directai\logs\directai.log. Если секрет туда попал (например, старая версия): перевыпустите токен и удалите файл — он пересоздаётся при следующем запуске.

Remove-Item "$env:USERPROFILE\.directai\logs\directai.log"

8. Типичные ошибки

8.1. Диагностика (doctor)

При проблеме подключения — сначала doctor (агент — см. AGENTS.md §4.1):

directai-mcp doctor
directai-mcp doctor --skip-api     # без сети
directai-mcp doctor --json         # машинный вывод для скилла
directai-mcp doctor --preinstall   # строгая проверка перед переустановкой

Одиннадцать проверок по порядку (версия, exe, процессы, блокировка файла, конфиг, токены, API, Hermes, Аудитории, ретаргетинг, каталог планов) — каждая OK / WARN / FAIL с причиной и рекомендуемым действием. Код возврата: 0 — всё OK, 1 — есть WARN, 2 — есть FAIL. Токены не печатаются (только есть/нет/длина). Занятый exe и работающие сессии по умолчанию — INFO, а не тревога; строго (WARN/FAIL) — только с --preinstall перед переустановкой. Диагностика read-only: ничего не останавливает и не правит, чинит человек готовым блоком из skills/directai-connection-doctor/references/playbooks.md.

Скилл directai-connection-doctor (триггеры: «MCP не работает», «os error 32», «hermes не видит», коды 513/58/53) лежит в репозитории (skills/directai-connection-doctor/); установка локально — скопировать папку в %USERPROFILE%\.agents\skills\directai-connection-doctor.

8.2. Скиллы сценариев (v1.11.0)

• directai-campaign-audit (skills/directai-campaign-audit/): разбор кампании — настройки, stats_compare 14 vs 14 (Δ = A−B, Δ% от базы B), срезы, гигиена, план улучшений. Только чтение. Триггеры: «разбери кампанию», «почему просела», «что улучшить», ID кампании.

• directai-campaign-create (skills/directai-campaign-create/): кампания из описания или YAML (references/campaign-template.yaml) — бриф, phrases_forecast, структура таблицей → «да», запись через планы, кампания остаётся остановленной. Триггеры: «создай кампанию», описание товара/услуги.

• Установка локально — скопировать папку скилла в %USERPROFILE%\.agents\skills\<имя>. Общие правила обоих скиллов: бюджеты не менять без явного «да» владельца (план «ОПАСНАЯ ОПЕРАЦИЯ»), запись только prepare → подтверждение → apply → read-back, DisplayUrlPath всегда заполнять.

9. Что отложено

Актуальный список — в BACKLOG.md (пункты 4–10: правила бизнеса, Вордстат, упущенный спрос, напоминания, лиды, позиции SERP, VK Ads) и в «Замеченные хвосты» там же. Устаревший список «что отложено» здесь больше не ведётся.

10. Знания Директа (пакет A1–A11 + B2)

Авторство части знаний: см. NOTICE.md (awaik/direct-mcp-ai-project, MIT).

• A1: ENABLE_AREA_OF_INTEREST_TARGETING отменено 31.08.2026 — только чтение (campaigns_get + campaign_setting_notices); запись отклоняется. Поля из notices не писать никогда.

• A2: Директ сам добавляет минус-слова в пересекающиеся фразы группы (keywords_list); автоминус не считать ошибкой.

• A3: операторы минус-фраз — см. раздел «Минус-фразы» ниже.

• A4: корректировки — разные категории перемножаются, внутри категории наибольшая, −100% низший приоритет, групповая перекрывает кампанию; в конверсионных — влияет на CPA/ДРР (bid_modifiers_set).

• A5: GoalId 12 = вовлечённые сессии, 13 = все приоритетные цели (служебные).

• A6: атрибуция — Метрика с 25.06.2026 cross-device, у Директа свои enum; каждый stats_* показывает attribution {requested, effective, source}.

• A7: WB_MAXIMUM_CLICKS требует WeeklySpendLimit; AVERAGE_CPC отдельная стратегия с AverageCpc (strategies_get).

• A8: ЕПК/текстово-графические — RETARGETING с goal_id; AUDIENCE только медийные; поиск AND, сети OR (audiences_list).

• A9: макросы трекинга (campaigns_update/adgroups_update, TrackingParams).

• A10: Турбо-блоки, clients.site, CPM-видео — только интерфейс.

• A11: интенты — 5 классов; цену/отзывы/гео не минусовать автоматически.

Минус-фразы

• "..." — запрос только из этих слов; [] — порядок; ! — словоформа; + — обязательность; полное пересечение минуса с ключом отменяет минус.

• Проверка конфликтов — в dump_to_xlsx.py (функция neg_match), тесты на вымышленных фразах.

Атрибуция

Фактическая модель Reports API отдельно не возвращает: в effective подставляется запрошенная модель (effective_attribution), source — откуда взялась (api — явно в параметрах, config — дефолт accounts.toml). effective=null, source="not_reported" — только если модели действительно нет. Без целей Reports игнорирует AttributionModels (фактически LC) — это помечается в ответе отдельно.

11. Статусы поиска (B1, v1.6.0)

Каждый ответ campaigns_get/campaigns_list несёт строку Статус поиска: <lookup_status>, presence=..., proves_account_empty=... и то же в dump-конверте/manifest (lookup_status).

Проверка Reports для statistics_only — только когда Campaigns API вернул пусто по явному ID; один лёгкий отчёт (CAMPAIGN_PERFORMANCE_REPORT, CampaignId, Impressions/Clicks, период по умолчанию 90 дней, параметр lookup_days переопределяет). Пустой campaigns_list — proves_account_empty=false + причины (фильтр, права, логин): пусто ≠ объекта нет. Запись разрешена только при resolved+configured (guard отклоняет остальное до API).

12. Основная цель (B3, v1.6.0)

accounts.toml: необязательное поле кабинета primary_conversion_goal_id (вымышленный пример: 900000123) и переопределение по кампании [aliases.<имя>.campaigns.<campaign_id>] primary_conversion_goal_id (также [accounts.<имя>.campaigns.<id>], пример: 900000456). Приоритет: явный параметр запроса primary_goal > кампания > кабинет > нет. Валидация: целое > 0; служебные 12/13 допустимы, но check предупреждает с расшифровкой (вовлечённые сессии / все приоритетные цели); сверка с целями Метрики — best-effort, отсутствие доступа — предупреждение, не ошибка. stats_*/stats_compare: блок Цель: id=..., label=..., source=param|campaign|account|none рядом с атрибуцией; CPA/CR — по этой цели; при source=none — как в v1.5.0

• warning «основная цель не задана, CPA по всем целям». Правило для агентов: перед оптимизацией читать журнал кампании (campaign_journal) и считать CPA по основной цели.

13. Журнал кампании (v1.13.0)

Один Markdown-файл на кампанию: что меняли, почему и что стало с результатами (<reports_dir>/journals/<login>/<campaign_id>.md, перезаписывается при каждом campaign_journal; источник правды — journal.sqlite). Привязка операций — таблица operation_campaigns (схему operations не меняли; старые записи привязаны backfill при первом connect). Снимки результатов — campaign_snapshots (direct: показы/клики/расход/CTR/CPC/конверсии из stats_compare-логики; metrika: визиты/отказы/цели/CPA из metrika_direct_cpa-логики; цель по умолчанию — основная; будущие даты отклоняются до API, как в v1.12.1). Заметки — campaign_notes (hypothesis|decision|observation|todo).

Инструменты (все read; заметки и снимки пишут только локально, без write API Директа и без планов): campaign_journal (сборка + файл), campaign_journal_snapshot, campaign_journal_note, фильтр get_operation_log(campaign_id=...). Δ в таблице снимков: Δ = A−B, Δ% от B.