# DirectAlert MCP

Source-based MCP gateway для AI-агентов: документация через documentation_get, данные Яндекс Директа через direct(action + args).

## 1. Что это такое

DirectAlert MCP позволяет AI-агенту читать документацию и работать с данными Яндекс Директа в рамках прав пользователя и выбранного Workspace.

Публичный каталог теперь source-based: текущие инструменты — documentation_get и direct. Будущие Bitrix и Метрика добавляются отдельными source tools, когда для них есть handlers, docs и проверки.

## 2. Подключение в Codex

Codex хранит MCP-настройки в config.toml. Для пользовательского подключения DirectAlert добавьте сервер в ~/.codex/config.toml:

```toml
[mcp_servers.DirectAlert]
url = "https://direct-alert.ru/mcp"
```

После этого запустите вход:

```bash
codex mcp login DirectAlert
```

Важно: Не отправляйте агенту пароли, токены и другие секретные данные. Вход выполняется через браузер.

## 3. Workflow агента

1. Discover tools: агент должен увидеть только documentation_get и direct.
2. Если action неизвестен, агент вызывает documentation_get с source=direct и mode=index.
3. Для точных параметров агент вызывает documentation_get с source=direct и action=<action>.
4. Сначала агент вызывает direct action session.context.
5. Затем агент выбирает Workspace и вызывает direct action accounts.list.
6. Дальше агент вызывает direct с action, common scope fields и args.

```text
direct({
  "action": "campaigns.list",
  "workspace_id": 2,
  "account_id": 1,
  "provider_mode": "auto",
  "args": {
    "limit": 3,
    "view": "summary"
  }
})
```

Старый bootstrap с get_ready, созданием AGENTS.md, русских папок и audit-doc больше не является публичным MCP-контрактом.

## 4. Public tools

| Tool | Назначение |
| --- | --- |
| documentation_get | Читает file-backed source/action документацию. |
| direct | Выполняет documented Direct source actions через action + args. |

## 5. Direct actions

Полный список actions агент получает через documentation_get({source:"direct", mode:"index"}). Ниже ключевые actions, которые чаще всего нужны для проверки подключения и анализа.

| Action | Назначение |
| --- | --- |
| session.context | Получить пользователя и доступные Workspace. |
| accounts.list | Получить аккаунты в выбранном Workspace. |
| campaigns.list | Получить список кампаний. |
| campaign.get | Получить одну кампанию по campaign_id. |
| reports.capabilities | Получить поля и правила Direct Reports. |
| reports.submit | Проверить или поставить offline-отчёт; для безопасной проверки используйте dry_run. |
| reports.get | Получить статус и страницу результата отчёта. |
| budgets.get | Получить бюджеты Direct. |
| changes.check | Проверить изменения Direct через read-only Changes methods. |
| snapshots.list | Найти доступные JSON-снапшоты аккаунта. |
| snapshots.links.get | Получить временные ссылки на ready-снапшоты. |
| snapshots.request | Поставить или дедуплицировать запрос на сбор снапшота. |
| raw.get | Экспертный read-only запрос к Direct API по allowlist. |

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

MCP-документация хранится файлами Markdown с TOML frontmatter внутри backend_v2. documentation_get возвращает index, section, action-card или lexical search candidates.

Default output компактный: index отдаёт refs, а не весь manual. Примеры и schema запрашиваются отдельно.

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

- Workspace/account scope проверяется на каждом action.
- account_id — внутренний идентификатор DirectAlert из accounts.list.
- Не передавайте OAuth/access/refresh tokens, cookies, Authorization headers, API keys, private keys и passwords.
- raw.get ограничен read-only allowlist Direct API.
- snapshots.request и reports.submit используют idempotent/request-flow; для отчётов безопасная проверка выполняется через dry_run.

## 8. Частые проблемы

### Агент не видит инструменты

Проверьте, что MCP-сервер DirectAlert добавлен, вход выполнен, а клиент MCP обновил список инструментов. Актуальный каталог должен показывать documentation_get и direct.

### Нет аккаунтов

Проверьте, что аккаунты добавлены в DirectAlert и выбран правильный Workspace. Агент должен сначала вызвать session.context, затем accounts.list.