**Русский** · [English](README.en.md)

# yaseo

Напишите Claude «Проверь сайт example.ru» и получите план: что поправить на сайте, в каком порядке и на каком основании.

Бесплатный плагин yaseo для Claude Code показывает сайт с двух сторон: каким его видит Яндекс и каким его видят ИИ-поиски. Сделан для маркетологов и владельцев бизнеса, которые уже работают в Claude Code.

![Claude Code проверяет сайт через yaseo и отдаёт план правок](docs/demo/site-check.png)

## Первая проверка без ключей

Для первой проверки не нужны ни ключи, ни карта.

1. Поставьте [Claude Code](https://code.claude.com/docs/en/setup) и [uv](https://docs.astral.sh/uv/getting-started/installation/).
2. В Claude Code введите по очереди две команды:
   ```text
   /plugin marketplace add https://github.com/novyiblog-tech/yaseo.git
   ```
   ```text
   /plugin install yaseo@yaseo
   ```
3. Напишите Claude:
   ```text
   Проверь сайт example.ru
   ```

Claude обойдёт до 30 страниц, посмотрит, пускает ли сайт ботов ИИ-поиска, и соберёт план правок. Денег это не стоит: yaseo обращается только к вашему сайту.

Если терминал для вас в новинку, есть инструкция с проверкой после каждого шага: [docs/INSTALL.md](docs/INSTALL.md).

## Что вы получите

### План правок

Ради него всё и затевалось. В каждом пункте плана есть страница, что на ней сейчас (цитата или число с датой замера), что сделать, готовая инструкция для Claude или разработчика и способ проверить результат. Порядок задают правила: сначала всё, что мешает индексации, потом страницы, которым до верха выдачи осталось немного. Роста позиций план не обещает.

Если у Claude есть доступ к коду сайта, он выполнит пункт сразу. Сначала покажет, что поменяет, и сохранит только после вашего согласия.

### Каким вас видит Яндекс

- Технический аудит: индексация, битые ссылки, редиректы, title и description, canonical, разметка, перелинковка.
- Позиции по вашим запросам с историей замеров: что выросло и что просело.
- Спрос по Wordstat и подбор запросов для раздела сайта.
- Живая выдача, конкуренты в топе и запросы, по которым они есть в выдаче, а вас там нет.
- Бриф статьи по составу топа. Проверка, та ли страница сайта вышла по запросу статьи.
- Показы и клики из Вебмастера, поведение из Метрики. Эти отчёты пока запускаются из терминала.

### Каким вас видят ИИ-поиски

- Готовность сайта: пускает ли robots.txt ботов ИИ-поиска, есть ли `llms.txt` и разметка JSON-LD. Бесплатно, без ключей.
- Цитирование: ссылаются ли на ваш сайт генеративный ответ Яндекса, Perplexity, OpenAI, Gemini и Claude, каким адресом и кого называют вместо вас. Проверки копятся в истории.

## Когда нужны ключи

Аудит, готовность к ИИ-поиску и план работают без ключей. Позиции, выдачу, Wordstat и генеративный ответ yaseo берёт из официального Yandex Search API. Для них нужен ключ Yandex AI Studio с привязанной картой. Как его получить: [INSTALL.md, шаг 5](docs/INSTALL.md#5-подключить-яндекс). Где лежат ключи и как их сменить: [docs/KEYS.md](docs/KEYS.md).

Ключи вписываются одной командой в терминале:

```
uvx --from git+https://github.com/novyiblog-tech/yaseo@v0.1.3 yaseo init
```

За обращения платите вы, по прайсу Яндекса: https://aistudio.yandex.ru/ru/docs/search-api/pricing. Перед платным шагом Claude называет, сколько будет обращений, и ждёт вашего «да». Дороже всего генеративный ответ Яндекса: на 16.09.2026 это 5 080 ₽ за 1 000 запросов. Ключи Perplexity, OpenAI, Gemini и Claude добавляются по желанию, платите по своему тарифу у провайдера.

Сам yaseo бесплатный. Код открыт, лицензия MIT.

## О чём можно попросить

```text
Проверь сайт example.ru
```

```text
Дай план, как поднять позиции example.ru
```

```text
Собери семантику для раздела «ремонт квартир»
```

```text
Подготовь бриф статьи под запрос «как выбрать ламинат»
```

```text
Какие у нас позиции и что изменилось?
```

```text
Цитирует ли ИИ-поиск example.ru по запросу «где заказать ремонт»?
```

---

Дальше подробности для тех, кому интересно, как всё устроено.

## Как устроен

- Данные Яндекса приходят от самого Яндекса, через официальный Yandex Search API. Регион по умолчанию: вся Россия.
- Выдача по одному запросу скачет: три запроса подряд могут дать 11, 6 и 5 место. Поэтому запрос, который уже бывал в топе, трекер снимает три раза и записывает медиану. Запрос, которого в топе не было, снимается один раз: ещё два «нет в топе» ничего бы не добавили. Трекер смотрит топ-10.
- У каждого вывода есть доказательство. Если источник промолчал, yaseo пишет «нет данных» и число не подставляет.
- Всё накопленное лежит у вас, в локальной базе SQLite.
- MCP-сервер написан на Python и обходится стандартной библиотекой, внешних зависимостей нет.

## Другие способы установки

Плагин из раздела выше подключает MCP-сервер `yaseo` и семь скиллов: `yaseo-setup`, `seo-site-check`, `keyword-research`, `position-tracking`, `content-brief`, `improve-positions`, `ai-visibility`. Сервер запускается командой `uvx --from git+https://github.com/novyiblog-tech/yaseo@v0.1.3 yaseo-mcp`, поэтому без `uv` он не поднимется.

### Только MCP-сервер

Для Claude Code без плагина:

```
claude mcp add --transport stdio yaseo -- uvx --from git+https://github.com/novyiblog-tech/yaseo@v0.1.3 yaseo-mcp
```

В другом MCP-клиенте укажите команду `uvx` с аргументами `--from git+https://github.com/novyiblog-tech/yaseo@v0.1.3 yaseo-mcp`.

Команда `yaseo` в терминале насовсем:

```
uv tool install git+https://github.com/novyiblog-tech/yaseo@v0.1.3
yaseo --help
```

### Из исходников

```
git clone https://github.com/novyiblog-tech/yaseo
cd yaseo
uv run yaseo --help
uv run yaseo-mcp < /dev/null   # сервер стартует и сразу выходит: так проверяется запуск
```

Список инструментов вручную:

```
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | uv run yaseo-mcp
```

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

В колонке «тратит» сказано, к какому платному API обращается инструмент и сколько раз за вызов. «Нет» значит, что инструмент читает локальную базу или ходит только на ваш сайт. Глубина выдачи набирается страницами по 10 результатов: топ-10 стоит одно обращение, топ-30 три, топ-50 (это предел) пять.

| инструмент | что делает | тратит |
|---|---|---|
| `whoami` | откуда взяты ключи, чего не хватает, где база, какой домен по умолчанию | нет |
| `research_keywords` | расширить 1–5 фраз через Wordstat: частотность и связанные запросы | Wordstat, 1 на фразу |
| `get_keyword_metrics` | частотность и конкурентность, до 25 запросов | Wordstat и Search API, по 1 на запрос |
| `get_serp_results` | живая выдача Яндекса по запросу | Search API, по страницам глубины `n` (для топ-10 одно) |
| `find_serp_competitors` | кто повторяется в выдаче по набору до 10 запросов | Search API, 1 на запрос |
| `get_competition` | конкурентность с разбором по факторам и доказательствами | Search API, 1 на запрос |
| `build_brief` | разведка перед статьёй: топ, форматы, разрывы, подзапросы | Wordstat 1, Search API по страницам глубины `n` (для топ-10 одно) |
| `expand_query_pool` | кандидаты в пул отслеживания с причиной; запись при `apply=true` | Wordstat, 1 |
| `track_query` | поставить запросы на отслеживание или снять | нет |
| `run_tracking` | снять позиции и записать в историю. Останавливается до первого запроса, если обращений выйдет больше потолка `YASEO_TRACKING_MAX_CALLS` или домен мерили недавно (с `now=true` снимает всё равно) | Search API, до 3 снимков на запрос × страницы глубины (для топ-10 одно обращение на снимок) |
| `get_positions` | текущие позиции и изменение к прошлому замеру | нет |
| `get_position_history` | история позиций по запросу, динамика конкурентности | нет |
| `get_competitor_keywords` | где конкурент в топе, а вас нет, по накопленным снимкам | нет |
| `audit_site` | технический аудит сайта; только http/https, внутренние адреса только с `YASEO_ALLOW_PRIVATE=1` | нет |
| `check_articles` | вышла ли по запросу именно эта статья блога. Останавливается до первого запроса, если обращений выйдет больше потолка `articles_max_calls` / `YASEO_ARTICLES_MAX_CALLS` | Search API, по страницам глубины на каждый уникальный запрос; общий запрос нескольких статей оплачивается один раз |
| `get_article_effectiveness` | отчёт по статьям и список каннибализаций | нет |
| `get_storage_stats` | что накоплено в базе | нет |
| `get_action_plan` | план правок по приоритету: доказательство, инструкция для Claude, способ проверки | нет: ходит только на сам сайт, остальное берёт из базы |
| `geo_readiness` | готовность сайта к ИИ-поиску; только http/https, внутренние адреса только с `YASEO_ALLOW_PRIVATE=1` | нет |
| `geo_providers` | какие ИИ-провайдеры настроены и каких ключей не хватает | нет |
| `geo_check_visibility` | цитирует ли ИИ-поиск сайт; без `confirm` возвращает только смету | только с `confirm=true` и списком `providers` |
| `geo_history` | история проверок: доля цитирований, частые конкуренты | нет |

Смету в самом коде считают три инструмента. `run_tracking` и `check_articles` останавливаются до первого платного запроса, если выходят за потолок. `geo_check_visibility` без `confirm=true` ничего не тратит. Остальные платные инструменты (`get_keyword_metrics`, `get_serp_results`, `find_serp_competitors`, `get_competition`, `build_brief`, `research_keywords`, `expand_query_pool`) тратят сразу при вызове, и смету перед ними называет Claude по инструкции из скилла.

Провайдер `yandex` в `geo_check_visibility` означает генеративный ответ YandexGPT по результатам Поиска (`POST /v2/gen/search` в Yandex Search API). С «Нейро» и Алисой его путать не стоит. У каждого источника в ответе есть признак `used`, и показанный источник не всегда использован: в прогоне 16.09.2026 из пяти источников в ответ пошли три. Процитированным yaseo считает сайт, только если его источник использован.

## Как собирается план

`get_action_plan` (в терминале `yaseo plan --domain example.ru`) строит список правок из того, что уже измерено или проверяется бесплатно: технического аудита, готовности к ИИ-поиску, истории позиций, выгрузок Вебмастера, реестра статей и накопленных снимков выдачи. Платных запросов он не делает. Если каких-то данных нет, план называет инструмент, который их даст, и сколько это стоит.

Общего балла нет, порядок задают правила:

1. Индексация. Критичные находки аудита: страница не отдаётся, битая внутренняя ссылка, цепочка редиректов, noindex или Disallow у адреса из sitemap.xml. Сюда же robots.txt, который не отдаётся.
2. Быстрые выигрыши. Запрос уже показывается, но не на верхних местах: по Вебмастеру средняя позиция 4–15, по трекеру позиция 4–10 (трекер снимает топ-10, и спрос по запросу должен быть известен). Страницу доводят под запрос, текущие title и H1 приводятся цитатой.
3. Сниппет. Не меньше 30 показов, ноль кликов, позиция не ниже 10-й.
4. Каннибализация. Две страницы сайта претендуют на один запрос.
5. ИИ-поиск. robots.txt закрывает ботов ИИ-поиска, нет `llms.txt`, нет JSON-LD. Запрет для Google-Extended на Google Поиск не влияет, и план об этом пишет.
6. Разрывы с конкурентами. Конкурент есть в накопленной выдаче по запросу с известной частотностью, а у сайта страницы под этот запрос нет.
7. Остальное. Прочие находки аудита, по одному пункту на каждый вид.

В каждом пункте указаны страница, что сейчас (цитата или число, источник, дата замера), что сделать, блок «Инструкция для Claude» для своего Claude или разработчика, как проверить результат и когда ждать эффекта. Позиции план предлагает переснимать не раньше срока из настроек трекера.

Параметры: `domain`, `url` (адрес для аудита), `max_pages` (по умолчанию 30), `sections` (какие разделы собрать), `limit` (по умолчанию 10 пунктов, остальные сворачиваются в счётчик по разделам) и `fresh_audit`. Если аудита в базе нет или ему больше 7 дней, он проводится заново и сохраняется.

Как разобрать план и выполнять его по пункту, описано в скилле `improve-positions`.

## Настройки

| переменная | что задаёт | по умолчанию |
|---|---|---|
| `YASEO_DOMAIN` | домен сайта для «наших» позиций | не задан; если в базе один проект, берётся его домен |
| `YASEO_DB` | путь к базе SQLite | `~/.local/share/yaseo/yaseo.db` |
| `YASEO_ENV_FILE` | свой файл с ключами | не задан |
| `YASEO_USE_PROXY` | `1`: ходить к Яндексу через системный прокси | `0`, к Яндексу напрямую |
| `YASEO_TRACKING_MAX_CALLS` | потолок обращений к Search API за один прогон позиций | `1000` |
| `YASEO_TRACKING_MIN_INTERVAL_DAYS` | сколько суток выжидать между прогонами по одному домену (`yaseo track --run` и `run_tracking`); снять ограничение на один раз: `--сейчас` в терминале, `now=true` в MCP | `13` |
| `YASEO_TRACKING_FILE` | файл настроек трекера | `~/.config/yaseo/tracking.json` |
| `YASEO_ARTICLES_MAX_CALLS` | потолок обращений к Search API за прогон `check_articles` / `yaseo articles --check` | `100` |
| `YASEO_ALLOW_PRIVATE` | `1`: пускать аудит и проверку готовности на внутренние адреса (localhost, `10.0.0.0/8`, `192.168.0.0/16` и подобные); у `yaseo audit` и `yaseo plan` для этого есть флаг `--allow-private` | `0`, отказ |
| `YASEO_RATES` | свой файл тарифов для сметы | встроенный `rates.json` |
| `YASEO_RATE_SEARCH_API`, `YASEO_RATE_WORDSTAT` | цена одного обращения в рублях, для сметы | из `rates.json` |

Если заданы `XDG_DATA_HOME` и `XDG_CONFIG_HOME`, каталоги данных берутся оттуда.

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

Что заложено в код:

- Содержимое сайтов и ответы ИИ-провайдеров выводятся отдельным подписанным блоком как данные. Инструкции внутри них Claude не выполняет.
- Запросы с ключом или токеном идут только по https и не следуют за перенаправлениями, так что ключ не уедет на чужой домен. За этим следит общий сетевой слой `net.py`.
- Сканер ходит только по http и https. На localhost и внутренние адреса (`10.0.0.0/8`, `192.168.0.0/16` и подобные) он пойдёт только с вашего разрешения: `YASEO_ALLOW_PRIVATE=1` или флаг `--allow-private` у `yaseo audit` и `yaseo plan`. Адреса-числа вроде `127.0.0.1`, `[::1]` и `10.0.0.5` отсекаются всегда. Имена сайтов проверяются по адресу, который вернул DNS. За прокси в режиме fake-ip (адреса `198.18.0.0/15`) такая проверка бессильна: любое имя получает подставной адрес.

## Приватность

Куда уходят данные:

- Яндекс (`searchapi.api.cloud.yandex.net`): ваши запросы для Wordstat, выдачи и генеративного ответа, вместе с вашим ключом.
- Яндекс ID, Вебмастер и Метрика (`oauth.yandex.ru`, `api.webmaster.yandex.net`, `api-metrika.yandex.net`), если вы подключили OAuth. Проверка токена `yaseo yandex --check` заодно спрашивает API Директа (`api.direct.yandex.com`), открыт ли он этому токену.
- ИИ-провайдеры (`api.perplexity.ai`, `api.openai.com`, `generativelanguage.googleapis.com`, `api.anthropic.com`), если вы положили их ключ, выбрали провайдера и подтвердили проверку. Уходит текст запроса. Ссылки-переадресации в источниках Gemini yaseo раскрывает запросом `HEAD`.
- Сайты, которые вы проверяете: аудит и проверка готовности читают их страницы.

Телеметрии нет. Кроме перечисленных адресов, yaseo никуда ничего не отправляет. Это видно по коду: все сетевые обращения идут через `net.py`, а зовут его только `yandex_serp.py`, `wordstat_client.py`, `yandex_auth.py`, `audit.py`, `geo/providers.py` и `geo/readiness.py`.

Что хранится у вас:

- ключи: `~/.config/yaseo/.env`, доступ только у владельца;
- база: `~/.local/share/yaseo/yaseo.db`: снимки выдачи, позиции, статьи, ответы ИИ-провайдеров (текст и исходный ответ API);
- снапшоты Wordstat и отчёты: там же, в `~/.local/share/yaseo/`.

Ключи ни в каком выводе не печатаются целиком.

## Ограничения

- Ссылок yaseo не видит, поэтому конкурентность считается только по составу выдачи.
- Глубже топ-50 выдача не снимается. Для задач пакета дальние места ничего не решают, а каждые 10 мест стоят ещё одного платного обращения.
- Wordstat принимает 100 запросов в час, большие списки придётся делить.
- Ноль в Wordstat ещё не значит, что спроса нет: редкие формулировки Wordstat может не показать.
- Генеративный ответ Яндекса дорогой и принимает не больше одного запроса в секунду.
- Ответы ИИ меняются от раза к разу. Один прогон даёт снимок, картину дают повторы и история.
- Вебмастер и Метрика пока доступны только из терминала.
- Лимиты и цены Яндекса меняются, сверяйтесь с https://aistudio.yandex.ru/ru/docs/search-api/concepts/limits и https://aistudio.yandex.ru/ru/docs/search-api/pricing.

## Лицензия

MIT, см. [LICENSE](LICENSE).