# DirectAI MCP

Локальный MCP-сервер для Яндекс Директа: ИИ-ассистент читает статистику
и управляет вашими кампаниями через официальный API. Сервер работает
на вашем компьютере, для одного пользователя и ничего не выставляет
в интернет.

Поддерживается Windows 11 и PowerShell. macOS и Linux не тестировались.
Сервер бесплатный; нужен только одобренный доступ к API Директа.

Работает с MCP-клиентами: OpenCode, Codex, Claude Code, Claude Desktop,
Hermes и другими.

> ИИ-агент? Следуй [AGENTS.md](AGENTS.md).

## Что умеет

- **Статистика и аналитика.** Показы, клики, расход, конверсии по кабинетам,
  кампаниям, группам, объявлениям, фразам, запросам, регионам, площадкам
  и устройствам. Сравнение периодов, произвольные отчёты.
- **Управление кампаниями.** Создание и изменение кампаний, групп,
  объявлений и фраз; ставки, корректировки, минус-фразы, быстрые ссылки;
  ключевые цели, дневной бюджет, расписание показов.
- **Яндекс Метрика.** Визиты, отказы, цели и CR по источникам; связка
  расходов Директа с заявками и CPA; запись целей счётчика.
- **Wordstat и исследование спроса.** Частотность, динамика, регионы,
  прогноз ставок по существующим фразам и спрос по новым.
- **Ретаргетинг и аудитории.** Условия, привязки к группам, сегменты;
  запись по умолчанию выключена.
- **Аудит и журнал.** Разбор кампании с планом улучшений, история правок,
  снимки результатов, заметки и проверка ручных изменений.

Полный список (57 действий чтения и 25 записи) — в
[docs/actions.md](docs/actions.md).

## Быстрый старт

1. **Требования.** Windows 11, аккаунт Директа с кампанией, приложение
   на oauth.yandex.ru и одобренная заявка на доступ к API. Начните
   с заявки: одобрение занимает до нескольких дней.

2. **Установка.**

   ```powershell
   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
   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
   ```

3. **Аккаунты.** Впишите реальный логин в `%USERPROFILE%\.directai\accounts.toml`
   (`[auth] login` и `[aliases.*]` вместо демо-примеров).

4. **Токен.** Получите его по ссылке из пройденной авторизации и введите
   скрытым полем в своём терминале:

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

   Токен хранится в Credential Manager Windows. Не передавайте его
   в чат, аргументы командной строки или файлы репозитория.

5. **Проверка.**

   ```powershell
   directai-mcp check
   directai-mcp probe
   ```

   `check` обращается к API Директа (мало баллов: проверка доступа и список
   кампаний) и показывает `OK` по каждому аккаунту. `probe` — локальная
   проверка MCP без обращения к рекламному API: две строки `OK` (версия
   сервера и найденный инструмент), баллы не тратятся.

6. **Подключение клиента** — см. раздел ниже, затем перезапустите харнес.

Подробная процедура: создание OAuth-приложения, подача заявки, отдельные
токены Метрики, Вебмастера и Wordstat — в
[docs/getting-started.md](docs/getting-started.md).

## Подключение к ИИ-агенту

Команда запуска везде одна — `directai-mcp` без аргументов (STDIO).
Пример для OpenCode, файл `%USERPROFILE%\.config\opencode\opencode.json`:

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

Готовые блоки для Codex, Claude Desktop, Claude Code и Hermes —
в [examples/harness-configs.md](examples/harness-configs.md). Если клиент
не видит команду, укажите полный путь: `(Get-Command directai-mcp).Source`.

## Примеры

**Расходы и конверсии за неделю.**

> Покажи расход, клики и конверсии по всем аккаунтам за последние 7 дней
> и сравни с предыдущей неделей.

Агент вызовет `stats_summary` и `stats_compare` — цифры должны совпасть
с веб-интерфейсом Директа.

**Аудит кампании.**

> Разбери кампанию 900000456: что изменилось за месяц, где потери,
> что улучшить.

Агент прочитает журнал, настройки и статистику, покажет отчёт и план
улучшений — без записи.

**Расписание показов.**

> Включи показы в субботу с 12 до 13, остальные дни не трогай.

```json
{"name": "campaigns_update",
 "params": {"account": "active", "campaign_ids": [900000456],
            "schedule": {"days": [6], "from_hour": 12, "to_hour": 13}}}
```

Меняются только указанные дни; Пн–Пт сохраняются. Правила расписания —
в [docs/actions.md](docs/actions.md#расписание-показов-campaigns_update-schedule).

Любая запись проходит предварительный просмотр «было → станет»
и ваше явное подтверждение: `plan_write` → согласие → `apply_write`.
Прямых изменений без плана нет.

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

- **Guard.** Защита включена по умолчанию и сверяет живое имя кампании
  через API. В режиме `block` политические запреты (бюджеты, стратегия,
  ключевые цели, переименование, модерация, пауза кампаний, правки вне
  тестовых) блокируют операцию. В режиме `confirm` те же операции
  допускаются только через план с пометкой «⚠ ОПАСНАЯ ОПЕРАЦИЯ»
  и явное подтверждение владельца на этот план.
- **Обычные боевые правки** идут через план в обоих режимах: фразы
  (добавление, пауза/запуск), объявления (создание, тексты, ссылки), ссылки
  и уточнения, регионы групп, минус-фразы (добавление), ставки
  и корректировки (кроме удаления), ExcludedSites (добавление), расписание.
  Правка набора минус-фраз кампании и пауза объявлений сюда не входят —
  это политические операции.
- **Жёсткие ограничения** от режима не зависят: объект не найден, поле
  `read_only`, выключенные Аудитории и ретаргетинг, сегмент без префикса
  `[TEST DirectAI]`, неизвестное действие.
- **План и проверка.** План живёт 15 минут и применяется ровно один раз.
  После записи сервер сам перечитывает объект (read-back) и сверяет
  результат; неясный итог помечается `unverified` и вручную проверяется.
- **Журнал.** Все операции DirectAI пишутся в `journal.sqlite`; ручные
  правки в кабинете видны через `changes_check`.
- **Токены.** Только Credential Manager или переменная окружения.
  В логи и URL не попадают; текст блокировки guard — защита, а не ошибка,
  обходить её нельзя.

Подробно: [docs/safety.md](docs/safety.md).

## Документация

| Раздел | Где |
|---|---|
| Установка, OAuth, аккаунты, токены | [docs/getting-started.md](docs/getting-started.md) |
| Каталог действий и ограничения API | [docs/actions.md](docs/actions.md) |
| Guard, планы, read-back, токены | [docs/safety.md](docs/safety.md) |
| Обновление, doctor, ошибки | [docs/troubleshooting.md](docs/troubleshooting.md) |
| Конфиги харнесов | [examples/harness-configs.md](examples/harness-configs.md) |
| Инструкции для ИИ-агентов | [AGENTS.md](AGENTS.md) |
| Публичный обзор проекта | [docs/PUBLIC-OVERVIEW.md](docs/PUBLIC-OVERVIEW.md) |
| История изменений | [CHANGELOG.md](CHANGELOG.md) |
| Технические решения и отступления | [DECISIONS.md](DECISIONS.md) |
| Планы и отложенные задачи | [BACKLOG.md](BACKLOG.md) |

Лицензия — [LICENSE](LICENSE), авторство части знаний —
[NOTICE.md](NOTICE.md).