# YWM MCP — Яндекс.Вебмастер для Claude

MCP-сервер и CLI-выгрузчик в одном файле. Парный к `gsc-mcp`: те же имена CSV,
та же структура `summary.md`, те же названия метрик — чтобы выгрузки Яндекса и
Google можно было положить рядом.

Главное, ради чего он существует: **API Search Console не отдаёт внешние ссылки**,
отчёт по ссылкам живёт только в интерфейсе. API Вебмастера отдаёт — и список
доноров, и историю изменения их количества. То есть текущий ссылочный профиль
сайта вы получаете бесплатно, без подписки на Ahrefs.

Два режима:

- **CLI** — запустили, получили папку CSV + `summary.md`.
- **MCP** — подключается к Claude Desktop, данные запрашиваются прямо в чате.

---

## 1. Установка

```bash
pip install -r requirements.txt
```

Python 3.10+. Из зависимостей только `mcp` — HTTP на стандартной библиотеке.
Если нужен исключительно CLI, можно вообще ничего не ставить.

---

## 2. Токен

Никаких сервисных аккаунтов и облачных проектов, в отличие от Google.

1. Откройте [oauth.yandex.ru/client/new](https://oauth.yandex.ru/client/new).
2. Название приложения — любое, например `ywm-export`.
3. Платформа: **Веб-сервисы**. Redirect URI: `https://oauth.yandex.ru/verification_code`
4. Доступы: найдите **Яндекс.Вебмастер** и отметьте
   **«Получение информации о сайтах пользователя»** (`webmaster:hostinfo`).
5. Создайте приложение и скопируйте **ClientID**.
6. Откройте в браузере, подставив свой ClientID:

   ```
   https://oauth.yandex.ru/authorize?response_type=token&client_id=ВАШ_CLIENT_ID
   ```

7. Нажмите «Разрешить» — токен появится прямо на странице.

Сохраните его:

```bash
# Linux / WSL / macOS
export YWM_TOKEN="<ВАШ_ТОКЕН>"

# или в файл, чтобы не светить в истории команд
echo "<ВАШ_ТОКЕН>" > ~/.ywm_token && chmod 600 ~/.ywm_token
export YWM_TOKEN_FILE=~/.ywm_token
```

```powershell
# Windows, навсегда
setx YWM_TOKEN "<ВАШ_ТОКЕН>"
```

Токен даёт доступ ко всем сайтам аккаунта. Держите его вне общих папок и
вне репозиториев — по нему видно всё, что видно в Вебмастере.

---

## 3. Проверка и выгрузка

```bash
python3 ywm_mcp.py list
```

Выведет подтверждённые сайты и их `host_id`. Пусто — значит сайт не подтверждён
в Вебмастере под этим аккаунтом.

```bash
python3 ywm_mcp.py export \
  --host "example.com" \
  --days 90 \
  --out "~/seo-exports/ywm_export" \
  --brand "example.com,бренд,brand name"
```

`--host` принимает и голый домен, и полный URL, и `host_id` — скрипт сам разберётся.

### Что появится в папке

| файл | что внутри |
|---|---|
| `summary.md` | Сводка: ИКС, страницы в поиске, итоги, ссылочный профиль, быстрые победы |
| **`donors.csv`** | **Домены-доноры со счётчиком ссылок. Главный файл** |
| **`external_links.csv`** | Все внешние ссылки: откуда, куда, когда обнаружены |
| `links_history.csv` | Динамика количества ссылок. Резкий скачок = чья-то массовая закупка |
| `queries.csv` | Запросы: показы, клики, CTR, средняя позиция показа и клика |
| `dates.csv` | Дневной ряд показов и кликов |
| `striking_distance.csv` | Запросы на позициях 5–20 — рабочий список под ссылки |
| `pages_in_search.csv` | Сколько страниц в индексе, по датам |
| `page_samples.csv` | Примеры страниц в поиске |
| `indexing_history.csv` | Обход по кодам ответа: 2xx / 3xx / 4xx / 5xx |
| `diagnostics.csv` | Проблемы сайта по уровням критичности |
| `broken_links.csv` | Внутренние битые ссылки |
| `sitemaps.csv` | Карты сайта и число URL в них |

CSV в UTF-8 с BOM — Excel открывает кириллицу корректно.

Точечные команды без полной выгрузки:

```bash
python3 ywm_mcp.py links   --host example.com --out ./links
python3 ywm_mcp.py queries --host example.com --days 180 --limit 100
```

---

## 4. Подключение к Claude Desktop

```json
{
  "mcpServers": {
    "yandex-webmaster": {
      "command": "python",
      "args": ["D:\\projects\\ywm-mcp\\ywm_mcp.py"],
      "env": {
        "YWM_TOKEN": "y0_ВАШ_ТОКЕН",
        "YWM_OUT_DIR": "D:\\projects\\ywm_export"
      }
    }
  }
}
```

Если сервер запускается из WSL, а Claude Desktop стоит на Windows:

```json
{
  "command": "wsl.exe",
  "args": ["-e", "python3", "/home/USER/ywm-mcp/ywm_mcp.py"]
}
```

---

## 5. Инструменты MCP

| инструмент | зачем |
|---|---|
| `list_hosts` | Подтверждённые сайты. Проверка токена |
| `site_summary` | ИКС, страницы в поиске, исключённые, счётчик проблем |
| `top_queries` | Запросы с показами, кликами, CTR и позицией; фильтр по устройству |
| `striking_distance` | Запросы на позициях 5–20 |
| **`backlinks`** | **Внешние ссылки, сгруппированные по доменам-донорам** |
| `backlinks_history` | Динамика количества ссылок во времени |
| `traffic_history` | Дневной ряд показов, кликов, CTR, позиции |
| `pages_in_search` | Динамика индекса и примеры страниц |
| `diagnostics` | Проблемы, которые видит Яндекс |
| `broken_links` | Внутренние битые ссылки |
| `sitemaps` | Карты сайта |
| `export_all` | Полная выгрузка в CSV прямо из чата |

Примеры формулировок:

> Покажи доноров example.com — есть ли среди них мусорные
> Найди запросы на позициях 5–20 в Яндексе
> Сравни динамику ссылок за полгода — были ли резкие скачки

---

## 6. Что важно знать про данные

**Показы Яндекса и показы Google — разные величины.** Методики подсчёта не
совпадают. Сравнивайте динамику внутри каждой системы и структуру спроса, но не
складывайте абсолютные числа и не делите одно на другое.

**Позиция показа и позиция клика — разные метрики.** Яндекс отдаёт обе.
`AVG_SHOW_POSITION` сопоставима с «средней позицией» Google; `AVG_CLICK_POSITION`
показывает, с какой позиции реально кликают, и обычно она заметно выше.

**Ссылки — это выборка.** Вебмастер отдаёт `count` (сколько всего знает) и
примеры постранично. Скрипт по умолчанию тянет до 5000 ссылок и честно пишет в
`summary.md`, если упёрся в лимит. Поднять — флагом `--max-links`.

**Глубина истории по запросам ограничена.** Если API вернёт ошибку на длинном
периоде, уменьшите `--days`.

**Ни один эндпоинт не роняет выгрузку.** Если что-то недоступно по правам или
данных ещё нет, соответствующий CSV будет пустым, а причина попадёт в раздел
«Не удалось получить» в `summary.md`. Тихих провалов нет.

---

## 7. Если что-то не работает

| симптом | причина |
|---|---|
| `401` | Токен истёк или скопирован с лишними символами. Получите новый по шагу 6 |
| `403` | Приложение выпущено без доступа «Яндекс.Вебмастер». Пересоздайте с нужным правом |
| `404` на конкретном эндпоинте | Сайт не подтверждён, ещё не проиндексирован, или данных за период нет |
| `list` пуст | Под этим аккаунтом Яндекса нет подтверждённых сайтов |
| Пустой `queries.csv` | Слишком длинный период либо нет поискового трафика за него |
| Пустой `donors.csv` при живом сайте | Яндекс ещё не построил ссылочный отчёт — бывает на молодых сайтах |

---

## 8. Самопроверка

`_selftest.py` прогоняет весь код против поддельного API — без сети и без токена.
Проверяет пагинацию, лимиты, агрегацию доноров, разбор истории и то, что выгрузка
переживает отказ отдельного эндпоинта.

```bash
python3 _selftest.py
```