Metadata-Version: 2.4
Name: xmlriver-mcp-toolkit
Version: 0.2.0
Summary: Independent XMLRiver MCP server, async client and SEO collection CLI
Project-URL: Repository, https://github.com/dietbear13/xmlriver_mcp
Author: Mikhail Bulgakov
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: filelock<4,>=3.25
Requires-Dist: httpx<0.29,>=0.28.1
Requires-Dist: mcp<2,>=1.27
Requires-Dist: pydantic<3,>=2.13
Requires-Dist: pyyaml<7,>=6
Description-Content-Type: text/markdown

# XMLRiver MCP Toolkit

**Поисковая выдача Google и Яндекса, частотность запросов Wordstat и проверка позиций сайта — прямо в вашем AI-помощнике.**

Подключите инструмент к Claude, Codex или Cursor и ставьте задачи обычным языком.
Помощник обратится к XMLRiver и вернёт данные: запросы, частотности, позиции и ссылки.
**Фразы можно вставить прямо в чат. Создавать CSV и YAML вручную для работы через MCP не нужно.**
Если инструмент уже подключён и отвечает, переходите к примерам ниже: повторная установка не требуется.

Это независимый проект, не официальный продукт XMLRiver. Для работы нужен собственный аккаунт XMLRiver.

<!-- mcp-name: io.github.dietbear13/xmlriver-mcp-toolkit -->

## Что умеет

| Задача | Что получите |
|---|---|
| Подобрать запросы в Wordstat | Расширения исходной фразы с частотностью; по желанию — похожие запросы |
| Посмотреть динамику спроса | Данные Wordstat за выбранный период |
| Собрать выдачу | Ссылки и заголовки результатов Google или Яндекса для нужного региона и устройства |
| Найти сайт в выдаче | Все найденные вхождения домена и их позиции среди органических результатов |
| Снять позиции по списку фраз | Результаты, история прогонов и обновлённый CSV |
| Сравнить регионы | Выдача по каждой связке «фраза × регион × поисковик» и совпадения с ожидаемыми доменами |
| Проверить счёт | Баланс XMLRiver и стоимость запросов для Google и Яндекса |

## Как пользоваться после подключения

Напишите помощнику задачу обычным языком. Укажите сайт, поисковик, регион, устройство и нужную глубину проверки. Список фраз вставьте в то же сообщение.

> Проверь позиции example.org в Яндексе и Google по Москве, мобильная выдача, первые пять страниц. Фразы:
>
> - кофемашина для дома
> - купить кофемашину
> - ремонт кофемашин
>
> Покажи таблицу: фраза, поисковик, позиция и найденная ссылка. Если сайт не найден, укажи фактически проверенную глубину.

Помощник сам обращается к XMLRiver по каждой фразе и собирает ответ. Можно попросить подобрать семантику, сравнить выдачу или посмотреть сезонность спроса. Дополнительные примеры есть ниже.

### Что выполняется автоматически

MCP даёт помощнику инструменты для баланса, подбора фраз Wordstat, истории спроса и поисковой выдачи. Для списка есть инструмент `batch`: он принимает до 100 фраз за один вызов и обрабатывает их параллельно, до 9 запросов одновременно. Помощник передаёт список и общие настройки, затем оформляет результаты.

> Через batch собери Wordstat по фразам «кофемашина», «кофеварка», «кофе в зёрнах». Регион Москва, до 50 расширений каждой фразы, частотность от 100. Используй до 9 параллельных запросов и не больше 30 HTTP-попыток. Покажи общий список.

Для выдачи используется операция `serp`, для расширений — `wordstat_top`, для динамики спроса — `wordstat_history`. Все фразы внутри одного пакета используют одинаковые параметры. Результаты возвращаются в порядке исходного списка; у каждой фразы есть свой статус и число HTTP-попыток.

Для большого сбора с кэшем, историей и сохранением результатов в пакете есть отдельная команда. Если помощнику доступен терминал и запись файлов, попросите его выполнить весь сбор:

> Сними позиции example.org по этому списку в Яндексе по Москве, мобильная выдача, глубина 50. Используй пакетный сбор XMLRiver с лимитом 100 HTTP-попыток. Сам подготовь нужные файлы, сначала покажи объём задания, затем запусти сбор и сохрани результат.

В таком режиме помощник сам готовит задание и запускает команду. Если клиент умеет только вызывать MCP, используйте `batch` прямо из чата: сервер сам сохраняет его результаты, доступ помощника к терминалу для этого не нужен.

**Заданием управляет помощник.** У MCP нет собственного расписания или фоновой очереди, которая продолжает сбор после закрытия чата. Команды `positions run`, `regions run`, `batch` и MCP-инструмент `batch` сохраняют результаты на диск по мере получения. При повторе задания используются сохранённые фразы и страницы. Одиночные MCP-вызовы `serp`, `wordstat_top` и `wordstat_history` возвращают данные в чат; для сохранения используйте `batch`, в том числе со списком из одной фразы.

## Первое подключение

Этот раздел нужен один раз. Если XMLRiver уже подключён, попросите помощника проверить баланс и начинайте работу.

1. Зарегистрируйтесь на [xmlriver.com](https://xmlriver.com/) и пополните баланс.
2. Возьмите в кабинете свой **user** и **key**. Они есть в примере адреса API-запроса: `user=...` и `key=...`.
3. Выберите один способ запуска ниже.
4. Добавьте сервер и ключи в настройки помощника.

**Самый простой способ для нового пользователя — запуск через `uvx`.** Установите [uv](https://docs.astral.sh/uv/getting-started/installation/) один раз. При первом подключении `uvx` сам скачает пакет и его зависимости. Отдельно устанавливать пакет через `pip` или `uv tool install` не требуется.

**Если пакет уже установлен через `pip` или `uv tool install`,** используйте команду `xmlriver-mcp` из установленного окружения. Повторно устанавливать пакет или добавлять `uv` ради MCP не нужно. В примерах настроек замените `command` на полный путь к `xmlriver-mcp` (в Windows — `xmlriver-mcp.exe`), а `args` на `[]`. Вариант с `pip` требует Python 3.11 или новее.

## Где хранить ключи

**PowerShell для настройки ключей не нужен.** Проще всего один раз записать их в файл настроек MCP: в блок `env` для Claude/Cursor или `mcp_servers.xmlriver.env` для Codex. Готовые примеры приведены ниже. Клиент передаст ключи серверу при запуске.

Также сервер принимает `XMLRIVER_USER` и `XMLRIVER_KEY` из окружения процесса. Этот вариант подходит для терминала, скриптов и автоматических заданий.

**Файл `.env` сам пакет автоматически не читает.** Он сработает, только если ваш клиент или запускной скрипт загружает его и передаёт значения серверу. Просто положить `.env` рядом с проектом недостаточно.

Ключи не отправляйте в чат и не выкладывайте в GitHub. Файл настроек с ключами храните локально; если он лежит в Git-проекте, исключите его из коммитов.

## Подключение к Claude и Cursor

MCP — способ подключить внешний инструмент к AI-помощнику. После подключения помощник сможет сам запрашивать данные XMLRiver.

Откройте файл настроек MCP:

- **Claude Desktop:** Settings → Developer → Edit Config.
- **Claude Code:** файл `.mcp.json` в папке вашего проекта.
- **Cursor:** файл `.cursor/mcp.json` в папке проекта.

Добавьте запись ниже. Замените `ВАШ_USER` и `ВАШ_KEY` своими значениями из XMLRiver.
Если в файле уже есть другие серверы, добавьте только блок `xmlriver` внутрь существующего `mcpServers`.

```json
{
  "mcpServers": {
    "xmlriver": {
      "command": "uvx",
      "args": ["--from", "xmlriver-mcp-toolkit==0.2.0", "xmlriver-mcp"],
      "env": {
        "XMLRIVER_USER": "ВАШ_USER",
        "XMLRIVER_KEY": "ВАШ_KEY"
      }
    }
  }
}
```

Сохраните файл и перезапустите помощника. При первом запуске `uvx` скачает пакет.
Если помощник не находит `uvx`, укажите полный путь к нему в поле `command`.
В Windows узнать путь можно командой `where.exe uvx`.

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

Добавьте в файл `~/.codex/config.toml` (в Windows — `%USERPROFILE%\.codex\config.toml`):

```toml
[mcp_servers.xmlriver]
command = "uvx"
args = ["--from", "xmlriver-mcp-toolkit==0.2.0", "xmlriver-mcp"]

[mcp_servers.xmlriver.env]
XMLRIVER_USER = "ВАШ_USER"
XMLRIVER_KEY = "ВАШ_KEY"
```

Замените значения ключей, сохраните файл и начните новую сессию Codex.

## Что попросить у помощника

Начните с простого:

> Проверь баланс XMLRiver.

Затем попробуйте SEO-задачи:

> Через Wordstat подбери 50 расширений запроса «кофемашина для дома» по Москве. Оставь запросы с частотностью от 100. Похожие запросы не добавляй.

> Посмотри динамику спроса по запросу «купить велосипед» с 01.01.2026 по 31.03.2026.

> Собери первые три страницы выдачи Google по запросу «ремонт кофемашин» в Москве для мобильных устройств. Покажи ссылки и позиции example.org.

> Покажи выдачу Яндекса по запросу «доставка цветов» в Санкт-Петербурге. Регион 2, устройство — компьютер, одна страница.

Если помощник просит выбрать инструмент, используются названия:
`get_balance`, `wordstat_top`, `wordstat_history`, `serp`, `batch`.

## Скорость и параллельный сбор

По умолчанию сервер и пакетные команды работают с **9 одновременными запросами**. XMLRiver указывает 10 потоков; один оставлен в запасе. Это лимит одновременной обработки, а не обещание 9 готовых ответов в секунду. Отдельно пакет ограничивает начало запросов: не больше 9 за скользящую секунду. Фактическая скорость зависит от сервиса.

Если свободных каналов не хватает, пакет снижает параллельность и делает общую паузу для запросов этого клиента. После 20 успешных ответов поднимает её на один, максимум до заданного значения. При блокировке учитывает `Retry-After` и указанное сервисом время ожидания. Если время не указано для ошибки 115 или HTTP 429, пауза составляет 10 минут. Длительный сбор может завершиться по лимиту времени раньше окончания паузы; полученные результаты сохраняются в пакетных командах.

Каждый запрос повторяется не больше трёх раз при временных ошибках. Ошибки ключа, баланса и доступа по IP останавливают дальнейшую отправку в пакетном задании. Уже отправленные запросы могут завершиться. Повторы входят в `max_attempts`.

В MCP-настройках можно уменьшить предел через `XMLRIVER_CONCURRENCY`, например до `3`. Частота старта регулируется отдельно через `XMLRIVER_RATE_MAX` и `XMLRIVER_RATE_WINDOW` (по умолчанию `9` и `1` секунда). В YAML для позиций и регионов используются `concurrency`, `rate_max` и `rate_window`. Для одного запуска также можно передать `--concurrency 3`.

Ограничение действует внутри одного запущенного клиента. Если одновременно запускаете несколько MCP-серверов, команд или сторонних парсеров с одним аккаунтом XMLRiver, распределите доступные потоки между ними. Например, два процесса по 4 запроса оставят запас до лимита сервиса.

Источники: [лимит потоков XMLRiver](https://xmlriver.com/blog/nastrojka-xmlriver-key-collector-google-yandex-wordstat.html), [ошибки и временная блокировка Wordstat](https://xmlriver.com/apiwordstatnew/apiwn-errors/).

## Что будет, если сбор остановится

**Пакетный сбор записывает каждый полученный результат сразу, а не в конце задания.** Ответ Wordstat, каждая страница поисковой выдачи и начало каждой HTTP-попытки попадают в журнал с принудительной записью на диск. Ошибки и незавершённые фразы тоже сохраняются. Большие ответы файлового сбора хранятся на диске; в памяти остаются входной список, служебные сведения и текущие запросы.

- Успешные фразы берутся из кэша при повторном запуске, без нового запроса к XMLRiver.
- Если по фразе успели получить только часть страниц, сбор продолжится со следующей сохранённой страницы. Это действует в пределах срока кэша и при тех же параметрах.
- При обычной остановке сохраняется итоговый частичный отчёт. При принудительном завершении процесса уже записанные данные остаются в журнале; отчёт можно восстановить командой ниже.
- Параметр `refresh` в MCP или `--refresh` в команде запускает сбор заново. Для продолжения после сбоя его добавлять не нужно.

**Где лежат данные:** у команд — в `xmlriver-data` рядом с файлом задания, либо в папке из `--workspace`. У MCP-инструмента `batch` — в `.xmlriver/data` внутри домашней папки пользователя. Для другой папки добавьте `XMLRIVER_WORKSPACE` в настройки окружения MCP. Путь к отчёту возвращается в ответе инструмента.

В каждой папке прогона есть `journal.jsonl` с записями по мере получения, `data.jsonl` с итоговыми результатами и `manifest.json` со статусом и счётчиками. Пока сбор идёт, самые свежие данные находятся в журнале. Чтобы восстановить итоговый файл после аварийного завершения:

```sh
xmlriver recover --workspace xmlriver-data --run ИДЕНТИФИКАТОР_ПРОГОНА
```

Команда ничего не запрашивает у XMLRiver. Для продолжения сбора повторите исходное задание. Запрос, который был отправлен, но ответ на который не успел сохраниться, может потребовать повтора; поэтому оценка расходов остаётся приблизительной.

## Дополнительно: большой список Wordstat или выдачи

Если помощнику доступны терминал и файлы, он может сам подготовить задание и запустить эту команду. Для самостоятельного запуска сохраните `batch.json`:

```json
{
  "operation": "wordstat_top",
  "queries": ["кофемашина", "кофеварка", "кофе в зёрнах"],
  "parameters": {"regions": 213, "limit": 50, "min_frequency": 100},
  "concurrency": 9,
  "max_attempts": 100
}
```

Ключи должны быть переданы в окружение команды, как описано ниже.

```sh
xmlriver batch --input batch.json --dry-run
xmlriver batch --input batch.json
```

Команда возвращает краткий итог и пути к файлам, не печатая всю семантику в терминал. Она принимает до 100 000 исходных фраз. Одновременно выполняется только заданное число запросов, а не весь список сразу. По умолчанию на весь запуск отводится час; изменить срок можно через `--deadline 7200` (секунды). Для увеличения бюджета измените `max_attempts` в задании, максимум 10 000 попыток за запуск.

Рядом появится `xmlriver-data` с результатами прогонов и кэшем успешных фраз. После остановки повторите ту же команду: результаты за последние 24 часа будут взяты из кэша, остальные фразы соберутся заново. Чтобы принудительно обновить все данные, добавьте `--refresh`. При изменении региона, устройства или других параметров старый кэш не используется.

Для поисковой выдачи замените `operation` на `serp`, а параметры задайте, например, так:

```json
{"engine": "yandex", "region": 213, "device": "mobile", "pages": 5, "target_domain": "example.org"}
```

## Дополнительно: запуск из терминала без помощника

Для обычной работы через чат этот раздел можно пропустить. Здесь описан ручной запуск большого сбора с кэшем, историей и обновлением таблицы. Помощник с доступом к терминалу может выполнить эти шаги за вас.

**1. Проверьте, доступна ли команда:**

```sh
xmlriver --help
```

Если она работает, переходите к ключам. Если пакет ещё не установлен как отдельная команда, установите его один раз:

```sh
uv tool install xmlriver-mcp-toolkit==0.2.0
```

**2. Передайте ключи команде.** Если они уже есть в окружении терминала, этот шаг пропустите. Ключи из настроек MCP относятся к серверу, запущенному помощником, и не обязательно доступны отдельному терминалу.

Один из способов задать их для текущего окна Windows PowerShell:

```powershell
$env:XMLRIVER_USER = "ВАШ_USER"
$env:XMLRIVER_KEY = "ВАШ_KEY"
```

В macOS или Linux:

```sh
export XMLRIVER_USER="ВАШ_USER"
export XMLRIVER_KEY="ВАШ_KEY"
```

**3. Подготовьте CSV с запросами.** Например, `keywords.csv`:

```csv
phrase
кофемашина для дома
купить кофемашину
ремонт кофемашин
```

**4. Рядом создайте файл `positions.yaml`:**

```yaml
target_domain: example.org
include_subdomains: true
csv: keywords.csv
column: phrase
depth: 50
max_attempts: 100
concurrency: 9
engines:
  - name: yandex
    region: 213
    device: mobile
  - name: google
    region: 1011969
    device: mobile
```

Замените `example.org` своим доменом. Здесь заданы Москва, мобильная выдача и пять страниц на запрос.
`include_subdomains: true` включает поддомены сайта.
`max_attempts: 100` ограничивает общее число HTTP-попыток, включая повторы после ошибок.

**5. Посмотрите объём задания без списаний:**

```sh
xmlriver positions run --config positions.yaml --dry-run
```

**6. Запустите сбор:**

```sh
xmlriver positions run --config positions.yaml
```

Рядом с конфигурацией появится папка `xmlriver-data` с результатами и историей.
Команда напечатает `run_id` — идентификатор прогона. Чтобы добавить позиции в CSV:

```sh
xmlriver positions update-csv --config positions.yaml --run ВАШ_RUN_ID
```

Исходные колонки и порядок строк сохраняются. Перед обновлением создаётся резервная копия.
Для Яндекса и Google записываются отдельные даты съёма.

## Дополнительно: пакетная проверка по регионам

В [примере конфигурации](examples/positions.yaml) есть блок `regions`. Добавьте нужные города,
их ID в Яндексе и Google, а в `expected_hosts` — домены, которые ожидаете увидеть в выдаче.

```sh
xmlriver regions validate --config positions.yaml
xmlriver regions run --config positions.yaml --dry-run
xmlriver regions run --config positions.yaml
```

Google-регионы сверяются со справочником XMLRiver. Проверка Яндекс-региона делает запрос «погода»
и ищет признаки города в выдаче: это подсказка для проверки настройки, а не гарантия.
Чтобы заново скачать справочник Google, добавьте к `regions validate` параметр `--refresh`.

## Расходы и особенности данных

- **Запросы оплачиваются с вашего баланса XMLRiver.** Сам пакет бесплатный.
- Одна страница выдачи — отдельный запрос к сервису. Больше страниц, фраз и регионов — больше запросов.
- Можно запросить от 1 до 10 страниц. Страница может содержать меньше 10 органических результатов, поэтому пять страниц не гарантируют 50 ссылок.
- Позиция — номер органического результата в полученной последовательности. Рекламные блоки в этот номер не входят.
- Повтор после сетевой ошибки тоже может привести к списанию. Счётчик попыток и оценка расходов не заменяют данные кабинета XMLRiver.
- Результаты массового съёма хранятся в кэше 24 часа. Повторный запуск с теми же параметрами использует их. Для нового съёма добавьте `--refresh`.
- `--dry-run` не обращается к API и ничего не записывает. Команды проверки баланса и регионов обращаются к сети.
- В Wordstat по умолчанию используются Москва и все устройства; в SERP — Москва и мобильные устройства.

Если в результате указана неизвестная стоимость (`null`), тариф не задан или не получен. Это не означает бесплатный сбор.

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

- **Не удаётся запустить сервер:** проверьте установку `uv` и путь к `uvx`, затем перезапустите помощника.
- **Ошибка авторизации:** проверьте `XMLRIVER_USER` и `XMLRIVER_KEY` в настройках.
- **Недостаточно средств:** пополните баланс XMLRiver.
- **Неверный регион:** у Яндекса и Google разные справочники ID. [Справочник Google](https://xmlriver.com/files/geo.csv).
- **Не принимается период Wordstat:** даты должны быть в формате `дд.мм.гггг`; ограничения на длительность периода описаны в [документации XMLRiver](https://xmlriver.com/apiwordstatnew/apiwn-about/).

Сообщить об ошибке можно в [Issues](https://github.com/dietbear13/xmlriver_mcp/issues). Укажите команду и текст ошибки, удалив ключи и другие личные данные.

Лицензия [MIT](LICENSE). Для разработчиков: [CONTRIBUTING.md](CONTRIBUTING.md).
