Metadata-Version: 2.4
Name: xmlriver-mcp-toolkit
Version: 0.1.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 и вернёт данные: запросы, частотности, позиции и ссылки.
Для массового съёма позиций есть отдельные команды с сохранением результатов в файлы.

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

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

## Что умеет

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

## Что нужно для начала

1. Зарегистрируйтесь на [xmlriver.com](https://xmlriver.com/) и пополните баланс.
2. Возьмите в кабинете XMLRiver свой **user** и **key**. Они есть в примере адреса API-запроса: `user=...` и `key=...`.
3. Установите [uv](https://docs.astral.sh/uv/getting-started/installation/) — небольшую программу, которая скачает и запустит этот инструмент.
4. Подключите сервер в своём AI-помощнике по инструкции ниже.

Ключи XMLRiver — личные. Не отправляйте их в чат и не выкладывайте в GitHub.

## Подключение к 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.1.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.1.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`.

## Массовая проверка позиций

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

**1. Установите пакет:**

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

**2. Задайте ключи для текущего окна терминала.** В 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
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).
