# mutagen-ru-mcp

[![npm](https://img.shields.io/npm/v/mutagen-ru-mcp)](https://www.npmjs.com/package/mutagen-ru-mcp)
[![CI](https://github.com/SVorobiev-ru/mutagen-ru-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/SVorobiev-ru/mutagen-ru-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/node/v/mutagen-ru-mcp)](package.json)

> **Неофициальный проект, не связан с Мутагеном. Данные принадлежат Мутагену (mutagen.ru).**

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

Мутаген для нейросетей. `mutagen-ru-mcp` — MCP-сервер для [Мутагена](https://mutagen.ru): Claude Code, Claude Desktop, Codex, Cursor, VS Code, Windsurf и другие MCP-клиенты получают частоты Вордстата, хвосты, конкуренцию, отчеты Мега-инструмента и готовые сценарии: «собери ядро за 20 ₽», «разложи фразы по страницам», «дай минус-слова для Директа». Перед каждым платным вызовом агент видит смету, а жесткий предел трат задаете вы.

Мутаген для кода. Тот же пакет — это CLI `mutagen-ru` и типизированная библиотека для Node.js. Ядро можно пересобирать по расписанию в GitHub Actions или cron, выгружать в CSV, XLSX и JSON, складывать в базу и получать pull request с новыми фразами раз в неделю. Кэш, журнал задач и лимит бюджета работают одинаково в MCP, CLI и библиотеке.

## Содержание

- [Быстрый старт](#быстрый-старт)
- [Что можно делать](#что-можно-делать)
- [Подключение к своим проектам](#подключение-к-своим-проектам)
- [Инструменты MCP и команды CLI](#инструменты-mcp-и-команды-cli)
- [Как экономить](#как-экономить)
- [Настройки](#настройки)
- [Ограничения и честные оговорки](#ограничения-и-честные-оговорки)
- [FAQ](#faq)
- [Участие в проекте](#участие-в-проекте)
- [Лицензия](#лицензия)

## Быстрый старт

Нужен Node.js 22.12 или новее.

### 1. Ключ API

1. Зарегистрируйтесь на [mutagen.ru](https://mutagen.ru/?r=94674) (партнерская ссылка автора проекта; обычная регистрация — на https://mutagen.ru).
2. Возьмите ключ в кабинете: https://mutagen.ru/?api_config. Там же включите «Разрешить подключение только с ip» — API работает только по HTTP, см. [ограничения](#ограничения-и-честные-оговорки).
3. Пополните баланс. Парсер Вордстата и проверка конкуренции списываются с баланса (от 0,02 ₽ за запрос). Отчеты Мега-инструмента через API доступны только с подпиской: [тарифы](https://mutagen.ru/serp/?tarif).

### 2. Проверка

```bash
export MUTAGEN_API_KEY=ваш_ключ
npx -y -p mutagen-ru-mcp mutagen-ru balance
```

Баланс бесплатный. Если ответ пришел, ключ работает.

MCP-сервер запускается так: `npx -y mutagen-ru-mcp`. Обычно его запускает сам клиент, команда ниже уже вписана в конфиги.

### 3. Подключение к нейросети

Во всех примерах `MUTAGEN_BUDGET_RUB` — предел трат в рублях на весь процесс MCP-сервера (пока клиент его не перезапустит). Без него действует 50 ₽.

<details open>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add --env MUTAGEN_API_KEY=ваш_ключ --env MUTAGEN_BUDGET_RUB=50 \
  --transport stdio --scope user mutagen -- npx -y mutagen-ru-mcp
```

`--scope user` подключает сервер во всех проектах. Проверка: `claude mcp get mutagen`.
</details>

<details>
<summary><b>Claude Desktop</b></summary>

Файл `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):

```json
{
  "mcpServers": {
    "mutagen": {
      "command": "npx",
      "args": ["-y", "mutagen-ru-mcp"],
      "env": {
        "MUTAGEN_API_KEY": "ваш_ключ",
        "MUTAGEN_BUDGET_RUB": "50"
      }
    }
  }
}
```

После правки перезапустите Claude Desktop.
</details>

<details>
<summary><b>Codex</b></summary>

`~/.codex/config.toml`:

```toml
[mcp_servers.mutagen]
command = "npx"
args = ["-y", "mutagen-ru-mcp"]
startup_timeout_sec = 30   # первый запуск npx скачивает пакет
tool_timeout_sec = 120

[mcp_servers.mutagen.env]
MUTAGEN_API_KEY = "ваш_ключ"
MUTAGEN_BUDGET_RUB = "50"
```

Чтобы не хранить ключ в файле, замените таблицу `env` строкой `env_vars = ["MUTAGEN_API_KEY"]`: Codex передаст переменную из вашего окружения. Тот же сервер одной командой: `codex mcp add mutagen --env MUTAGEN_API_KEY=ваш_ключ -- npx -y mutagen-ru-mcp`.
</details>

<details>
<summary><b>Cursor</b></summary>

`.cursor/mcp.json` в проекте или `~/.cursor/mcp.json` для всех проектов:

```json
{
  "mcpServers": {
    "mutagen": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mutagen-ru-mcp"],
      "env": {
        "MUTAGEN_API_KEY": "${env:MUTAGEN_API_KEY}",
        "MUTAGEN_BUDGET_RUB": "50"
      }
    }
  }
}
```

`${env:MUTAGEN_API_KEY}` берет ключ из окружения, поэтому файл можно класть в git.
</details>

<details>
<summary><b>VS Code</b></summary>

`.vscode/mcp.json`. VS Code спросит ключ при первом запуске и сохранит его в защищенном хранилище:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "mutagen-key",
      "description": "Ключ API Мутагена (https://mutagen.ru/?api_config)",
      "password": true
    }
  ],
  "servers": {
    "mutagen": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mutagen-ru-mcp"],
      "env": {
        "MUTAGEN_API_KEY": "${input:mutagen-key}",
        "MUTAGEN_BUDGET_RUB": "50"
      }
    }
  }
}
```
</details>

<details>
<summary><b>Windsurf</b></summary>

Файл `mcp_config.json` открывается из панели Cascade: меню `...` → MCPs → Open MCP config file. Сейчас он лежит в `~/.config/devin/mcp_config.json` (Windows: `%APPDATA%\devin\mcp_config.json`), в старых версиях Windsurf — в `~/.codeium/windsurf/mcp_config.json`.

```json
{
  "mcpServers": {
    "mutagen": {
      "command": "npx",
      "args": ["-y", "mutagen-ru-mcp"],
      "env": {
        "MUTAGEN_API_KEY": "${env:MUTAGEN_API_KEY}",
        "MUTAGEN_BUDGET_RUB": "50"
      }
    }
  }
}
```
</details>

Те же конфиги отдельными файлами лежат в [examples/clients](examples/clients).

**Сервер по HTTP.** Для клиентов, которые подключаются по адресу, есть Streamable HTTP:

```bash
MUTAGEN_API_KEY=ваш_ключ npx -y mutagen-ru-mcp --http --port 3333
# адрес для клиента: http://127.0.0.1:3333/mcp
```

Если слушать не localhost (`--host 0.0.0.0`), обязателен токен `MUTAGEN_MCP_HTTP_TOKEN`: клиент передает его в заголовке `Authorization: Bearer ...`. Запросы из браузера с заголовком `Origin` сервер принимает только с localhost; другие адреса перечислите через запятую в `MUTAGEN_MCP_ALLOWED_ORIGINS`. Бюджет `MUTAGEN_BUDGET_RUB` общий для всех HTTP-сессий процесса.

## Что можно делать

Ниже — запросы, как их пишут в чате, инструменты, которые вызовет агент, и что получится. Ниша для примеров — натяжные потолки, регион Вордстата — Россия (225). Где написано «живой ответ», это настоящий результат запроса к Мутагену от 14.10.2026, сокращенный до первых строк. Где написано «пример», таблица показывает форму ответа, а цифры условные.

Цены взяты из живой проверки 14.10.2026: частота 0,02 ₽ за фразу и вид, «Ключи Вордстата» 0,02 ₽ (200 фраз) или 0,20 ₽ (2000 фраз), конкуренция 0,30 ₽ за фразу. Отчеты Мега-инструмента денег не списывают, но требуют подписку и расходуют суточную квоту запросов.

### 1. Собрать семантическое ядро для нового сайта или раздела

> Собери семантическое ядро для раздела «натяжные потолки» по маркерам «натяжные потолки» и «потолки под ключ». Бюджет 15 рублей, регион Россия.

Агент: `mutagen_build_core` с `dry_run: true` → показывает смету → после вашего «да» тот же вызов без `dry_run`. Сценарий собирает хвосты маркеров, убирает дубли и явный мусор («скачать», «вакансии», «б/у» и т. п.), снимает точную частоту `"!фраза"` и группирует фразы в кластеры. MCP-prompt `build-core` ведет агента по этим шагам.

Смета — живой ответ `--dry-run` для двух маркеров:

| Шаг | Метод | Единиц | Сумма |
|---|---|---|---|
| Хвосты маркеров (200 фраз) | `parser.get`, `wordstat_key_50` | 2 | 0,04 ₽ |
| Точная частота | `parser.mass.new`, `wordstat_qs` | 500 | 10,00 ₽ |
| **Итого** | | | **10,04 ₽** |

Если бюджет меньше сметы, план уменьшается до бюджета: при 1,5 ₽ сценарий честно пишет «план уменьшен: max_phrases 500 → 73». Результат — таблица и файл (пример):

| Фраза | Базовая частота | "!Точная" | Кластер | Маркер |
|---|---|---|---|---|
| натяжной потолок цена | 55 926 | 1 011 | натяжной потолок цена | натяжные потолки |
| сколько стоит натяжной потолок | 18 667 | 1 382 | сколько стоит натяжной потолок | натяжные потолки |
| … | | | | |

Цена: по смете, не больше `budget_rub`. CLI: `mutagen-ru core "натяжные потолки" "потолки под ключ" --budget 15 -o core.xlsx`.

### 2. Расширить ядро хвостами и подсказками

> Вот наше ядро (core.csv). Найди новые фразы, которых в нем еще нет, бюджет 5 рублей.

Агент: `mutagen_expand_core` (маркеры по умолчанию — главные фразы кластеров) или `mutagen_wordstat_keywords` по одной фразе. Живой ответ «Ключи Вордстата», 200 фраз, 0,02 ₽:

| Фраза | Частотность |
|---|---|
| натяжной потолок | 1 073 667 |
| потолок под натяжной потолок | 56 753 |
| натяжной потолок цена | 55 926 |
| установка натяжных потолков | 52 489 |
| натяжные потолки фото | 40 119 |
| натяжной потолок своими руками | 32 939 |
| … еще 194 строки | |

С подпиской Мега-инструмента `source: "serp"` берет хвосты из базы Мутагена (`report_keyword_tailings`), без подписки — из Вордстата. `source: "auto"` выбирает сам. CLI: `mutagen-ru keywords "натяжные потолки" --depth 200 -o tails.csv`, `mutagen-ru expand -i core.csv --budget 5`.

### 3. Снять базовую и точную частоту, оценить конкуренцию

> Сними базовую и точную частоту по этим четырем фразам. Потом проверь конкуренцию у двух самых частотных.

Агент: `mutagen_frequency` с `types: ["wordstat_n", "wordstat_qs"]`, затем `mutagen_competition`. Живой ответ, 4 фразы × 2 вида = 0,16 ₽:

| Фраза | Базовая | "!Точная" |
|---|---|---|
| натяжной потолок цена | 62 529 | 1 011 |
| установка натяжных потолков | 54 907 | 593 |
| натяжной потолок купить | 27 870 | 694 |
| сколько стоит натяжной потолок | 20 422 | 1 382 |

Доступны все виды частотности Вордстата: базовая `n`, "фразовая" `q`, "!точная" `qs`, [порядок] `no`, "[порядок]" `qo`, "[!точный порядок]" `qso`. Конкуренция — шкала Мутагена 0–25 (ниже 5 — низкая), плюс частота в кавычках, число хвостов, ставки Директа и витальный сайт (пример):

| Фраза | Конкуренция (0–25) | Частота "в кавычках" | Хвосты |
|---|---|---|---|
| натяжной потолок цена | 12 | 4 800 | 950 |

Цена: частота 0,02 ₽ × фраза × вид, конкуренция 0,30 ₽ × фраза, повтор той же фразы в течение 7 дней бесплатный. Конкуренция зависит от связи Мутагена с Яндекс Директом и может считаться очень долго, см. [ограничения](#ограничения-и-честные-оговорки). CLI: `mutagen-ru freq -t n,qs -i phrases.txt`, `mutagen-ru competition -i top.txt`.

### 4. Кластеризовать фразы и разложить их по страницам

> Разложи фразы из tails.csv по страницам: какие фразы вести на одну страницу.

Агент: `mutagen_cluster`. Три режима:

- `lexical` — бесплатно и без обращения к API: группировка по общим словам с учетом словоформ (стеммер Snowball);
- `serp` — по совпадению URL в топе выдачи, как кластеризация на сайте Мутагена; нужна подписка, 1 запрос квоты на фразу, до 300 фраз;
- `project` — забрать готовые кластеры проекта «Избранного» по его id (бесплатно).

Живой ответ, `lexical`, 40 фраз, бесплатно (сокращено):

| Кластер | Фраза | Частота |
|---|---|---|
| натяжной потолок цена | натяжной потолок цена | 55 926 |
| натяжной потолок цена | стоимость натяжного потолка | 11 164 |
| натяжной потолок цена | натяжной потолок цена за м2 | 4 421 |
| точечные светильники для натяжного потолка | точечные светильники для натяжного потолка | 5 767 |
| точечные светильники для натяжного потолка | встраиваемый светильник в натяжной потолок | 3 499 |
| натяжные потолки скрытый карниз | скрытый карниз в натяжном потолке | 3 650 |

Лексическая группировка грубая: фразы с одинаковыми словами она объединяет, даже если интент разный (в живом прогоне «светильники» и «монтаж» попали в кластер «цена»). Для раскладки по страницам точнее режим `serp`. CLI: `mutagen-ru cluster -i tails.csv`, `mutagen-ru cluster --mode serp -i tails.csv`.

### 5. Выбрать Title, H1 и Description по частотам

> Предложи Title, H1 и Description для страницы цен на натяжные потолки по этим фразам.

Агент: `mutagen_title_h1`. Если у фраз уже есть частоты, это бесплатно. Если нет, сценарий снимет точную частоту: 0,02 ₽ за фразу. Живой ответ на 15 фраз кластера «цена»:

| Элемент | Текст | Обоснование |
|---|---|---|
| Title | Натяжной потолок цена — с установкой, за метр | главная фраза «натяжной потолок цена» (55 926) + хвосты фраз «потолок натяжной цена с установкой» (21 548) и «натяжной потолок цена за метр» (6 884) |
| H1 | Потолок натяжной цена с установкой | вторая по частоте формулировка (21 548) |
| Description | Натяжной потолок цена: с установкой, за метр. Узнайте подробнее на сайте! | главная фраза + те же уточнения + призыв |

Слова не склоняются: уточнения берутся целыми фразами кластера или их хвостами в том виде, в каком они есть в Вордстате, поэтому заготовка не собирает слова разных фраз в одну неграмотную группу. Город добавляется через запятую. Это заготовка с обоснованием по частотам, а не готовый текст: ее правит редактор. Параметры `brand` и `city` добавляют бренд и город. CLI: `mutagen-ru title -i price.csv --city Москва`.

### 6. Найти фразы, по которым нет страницы

> Какие запросы конкурентов из топа есть у них и нет у нашего сайта example.ru?

С подпиской агент вызовет `mutagen_content_gap`: ключи вашего домена и 5 конкурентов (их Мутаген находит сам, или задайте `competitors`), разница — фразы, по которым у вас нет страницы. Цена: 1 запрос квоты на домен. Пример:

| Фраза | Частота | Конкурентов | Лучшая позиция | Лучший конкурент |
|---|---|---|---|---|
| натяжной потолок в ванной | 17 610 | 3 | 2 | a.ru |

Без подписки: выгрузите список фраз, под которые у вас уже есть страницы (`pages.txt`), и сравните его с ядром бесплатной локальной операцией:

```bash
mutagen-ru text compare -i pages.txt -i core.csv --implicit
```

Строки с `only_b` — фразы ядра без страницы. `--implicit` считает одинаковыми фразы, которые отличаются только формой слов или порядком.

### 7. Проверить позиции

> На каких позициях example.ru по запросам про натяжные потолки?

Агент: `mutagen_domain_report` с `report_keywords_organic` (ключи и позиции домена) или `mutagen_keyword_report` с `report_keyword_positions_organic` (топ-50 по фразе). Нужна подписка, 1 запрос квоты. Пример (колонки отчета Мутагена):

| keyword | position | region_wsn | page |
|---|---|---|---|
| натяжные потолки под ключ | 7 | 3 100 | https://example.ru/catalog/ |

Честно: это позиции из базы Мутагена, которую он обновляет периодически, а не съем выдачи в реальном времени. В API нет инструмента, который проверит позицию прямо сейчас. Бесплатной альтернативы внутри Мутагена нет. Позиции своего сайта можно смотреть в Яндекс Вебмастере.

### 8. Подготовить ядро для Директа: минус-слова

> Подготовь минус-слова для кампании по натяжным потолкам.

Агент: `mutagen_minus_words` (MCP-prompt `direct-prep`). По готовому списку фраз — бесплатно, по маркерам — сначала собирает «Ключи Вордстата» (0,02 ₽ за маркер). Живой ответ на 200 фраз, бесплатно:

```text
-своими -руками -видео -фото -как -сделать -самостоятельно -авито
```

| Слово | Категория | Спорно | Фраз | Сумма частот |
|---|---|---|---|---|
| своими руками | Своими руками | нет | 9 | 65 594 |
| фото | Фото и видео | нет | 3 | 45 175 |
| работа | Работа и вакансии | да | 1 | 9 173 |
| отзывы | Отзывы и обсуждения (спорно) | да | 1 | 7 130 |

Спорные слова в строку не попадают: решение за вами (`include_disputed` или `--disputed` добавит их). Ставки и прогноз Директа — `mutagen_direct_bids`, 0,02 ₽ за фразу, но сейчас этот сбор может идти очень долго, см. [ограничения](#ограничения-и-честные-оговорки). CLI: `mutagen-ru minus -i tails.csv`, `mutagen-ru minus "натяжные потолки" --budget 1`.

### 9. Сравнить с конкурентами

> Кто конкуренты example.ru в выдаче и по каким запросам они нас обходят?

Агент: `mutagen_domain_report` с `report_domain_competitors` (конкуренты по пересечению ключей), затем `report_keywords_organic` по конкуренту и `mutagen_content_gap`. Все это — отчеты Мега-инструмента: нужна подписка, 1 запрос квоты на отчет. Пример (колонки отчета Мутагена):

| domain | visibility | domain_organic_keywords |
|---|---|---|
| a.ru | 41,2 | 5 600 |

Без подписки: соберите ядро по маркерам, которые продвигает конкурент (`mutagen_build_core`), и сравните его со своим списком через `mutagen_text` с операцией `compare`.

### 10. Составить контент-план статей по ядру

> Составь контент-план информационных статей по этим фразам.

Агент: `mutagen_content_plan` (MCP-prompt `content-plan`). По готовому списку — бесплатно: сценарий находит вопросы, группирует их и сортирует темы по сумме частот. По маркерам — сначала собирает фразы (с подпиской — хвосты-вопросы Мега-инструмента, без нее — Вордстат). Живой ответ на 200 фраз, бесплатно:

| Тема статьи | Главный запрос | Сумма частот | Вопросов |
|---|---|---|---|
| Как снять натяжной потолок? | как снять натяжной потолок | 154 372 | 26 |
| Натяжной потолок сколько? | натяжной потолок сколько | 55 783 | 3 |
| Чем отмыть натяжной потолок? | чем отмыть натяжной потолок | 10 198 | 2 |
| Можно ли делать натяжной потолок? | можно ли делать натяжной потолок | 2 376 | 1 |
| Что сначала обои или натяжной потолок? | что сначала обои или натяжной потолок | 2 282 | 1 |

Заголовки — черновые, их стоит переписать. Для выбранных тем агент может вызвать `mutagen_title_h1`. CLI: `mutagen-ru plan -i tails.csv -o plan.xlsx`.

## Подключение к своим проектам

Все примеры лежат в [examples/](examples). Для CLI в CI и cron есть два важных флага: `--yes` подтверждает смету без вопроса (без него неинтерактивный запуск дороже 1 ₽ завершится с кодом 3) и `--budget N` ограничивает траты одного запуска.

### Сбор по расписанию: GitHub Actions

[examples/github-actions/weekly-core.yml](examples/github-actions/weekly-core.yml) — раз в неделю собирает ядро и сохраняет XLSX и отчет о тратах как артефакт сборки. Ключ хранится в секрете репозитория `MUTAGEN_API_KEY`.

```yaml
- run: npm install --global mutagen-ru-mcp
- run: mutagen-ru core "натяжные потолки" --budget 20 --yes -o out/core.xlsx
  env:
    MUTAGEN_API_KEY: ${{ secrets.MUTAGEN_API_KEY }}
    MUTAGEN_BUDGET_RUB: "20"
```

### Сбор по расписанию: cron

[examples/cron/weekly-core.sh](examples/cron/weekly-core.sh) пишет ядро в файл с датой, строка для `crontab -e` — в [examples/cron/crontab.txt](examples/cron/crontab.txt):

```cron
0 6 * * 1  /path/to/weekly-core.sh >> /var/log/mutagen-core.log 2>&1
```

### Выгрузка в CSV, XLSX, JSON

У любой команды CLI есть `-o файл.csv|.xlsx|.json|.ndjson`, у любого инструмента MCP — `save_as`. Файлы MCP ложатся только в каталог `MUTAGEN_OUTPUT_DIR` (по умолчанию `./mutagen-results`): относительный `save_as` считается от него, путь наружу (`..`, ссылки) отклоняется. Существующий файл MCP не перезаписывает, а сохраняет результат рядом как «имя (2).csv»; заменить файл — `overwrite: true`. Только для stdio `MUTAGEN_ALLOW_ANY_OUTPUT_PATH=1` разрешает любой путь. CSV рассчитан на русский Excel: разделитель «;», десятичная запятая, BOM, защита от формул в ячейках. В конце каждого файла есть строка «Данные: Мутаген (mutagen.ru)» (в XLSX — лист «Источник»): этого требуют условия API Мутагена.

```bash
mutagen-ru freq -t n,qs -i phrases.txt -o freq.xlsx
mutagen-ru keywords "натяжные потолки" --format json > tails.json
```

### Google Таблицы

Есть два честных способа:

1. **Разово.** Файл → Импорт → Загрузка → `core.csv`, тип разделителя «Точка с запятой».
2. **Автоматически.** `IMPORTDATA` читает только CSV с запятыми или TSV по публичной ссылке. [examples/google-sheets/to-sheets-csv.mjs](examples/google-sheets/to-sheets-csv.mjs) переводит JSON-выгрузку CLI в CSV с запятыми. Положите его в публичный репозиторий или на любой публичный адрес и вставьте в ячейку:

   ```text
   =IMPORTDATA("https://raw.githubusercontent.com/SVorobiev-ru/REPO/main/semantic/core.sheets.csv")
   ```

   Google Таблицы перечитывают файл сами, с задержкой. Файл из приватного репозитория так не открыть.

### База данных

[examples/db/to-sqlite.mjs](examples/db/to-sqlite.mjs) складывает JSON-выгрузку в SQLite через встроенный `node:sqlite` (Node 22.13+ или 24), с датой сбора. По этой таблице легко смотреть историю частот:

```bash
mutagen-ru core "натяжные потолки" --budget 20 --yes -o core.json
node examples/db/to-sqlite.mjs core.json semantic.db
```

### Скрипт на Node

Библиотека экспортирует то же, на чем работают CLI и MCP: клиент API (`MutagenClient`), сессию с бюджетом, кэшем и журналом (`MutagenSession`), сценарии (`buildCore`, `expandCore`, кластеризация, минус-слова и другие), локальную обработку фраз и выгрузку (`writeTable`). Полный пример — [examples/node/build-core.mjs](examples/node/build-core.mjs):

```js
import { BudgetError, buildCore, loadConfig, MutagenSession, writeTable } from "mutagen-ru-mcp";

const session = MutagenSession.fromConfig(loadConfig()); // ключ и бюджет из переменных окружения
const params = { seeds: ["натяжные потолки"], budgetRub: 15 };

let result;
try {
  result = await buildCore(session, params);
} catch (error) {
  if (!(error instanceof BudgetError) || error.kind !== "needs_confirmation") throw error;
  // Смета выше MUTAGEN_AUTO_APPROVE_RUB: подтверждаем ее токеном из ошибки.
  result = await buildCore(session, params, { confirmToken: error.confirmToken });
}
await writeTable(result.table, "core.xlsx");
```

### Агент, который раз в неделю обновляет ядро и открывает PR

[examples/github-actions/weekly-core-pr.yml](examples/github-actions/weekly-core-pr.yml): CLI собирает ядро, бесплатная локальная команда `mutagen-ru text compare` сравнивает его с прошлым `semantic/core.csv`, новые фразы попадают в `semantic/new-phrases.txt`, и [peter-evans/create-pull-request@v8](https://github.com/peter-evans/create-pull-request) открывает PR с обновленным ядром. Вы смотрите diff и решаете, что взять.

Для этого в настройках репозитория включите Settings → Actions → General → Workflow permissions → «Allow GitHub Actions to create and approve pull requests».

## Инструменты MCP и команды CLI

22 инструмента MCP и 18 команд CLI. Группа — значение для `MUTAGEN_TOOLS`.

| Инструмент MCP | Команда CLI | Что делает | Цена | Группа |
|---|---|---|---|---|
| `mutagen_balance` | `balance` | Баланс аккаунта | бесплатно | basic |
| `mutagen_spending` | `spending` | Траты и остаток бюджета, журнал платных вызовов | бесплатно, локально | basic |
| `mutagen_estimate` | `estimate` | Смета плана вызовов | бесплатно, локально | basic |
| `mutagen_mass_tasks` | `mass list` | Массовые задания парсера | бесплатно | basic |
| `mutagen_mass_result` | `mass get <id>` | Результат массового задания | бесплатно | basic |
| `mutagen_project_keywords` | `projects <id>` | Ключи и кластеры проекта «Избранного» | бесплатно | basic |
| `mutagen_frequency` | `freq` | Частотность Вордстата, 6 видов, регион | 0,02 ₽ × фраза × вид | parser |
| `mutagen_wordstat_keywords` | `keywords` | Левая колонка Вордстата: 200 или 2000 фраз | 0,02 ₽ (200), 0,20 ₽ (2000) | parser |
| `mutagen_direct_bids` | `bids` | Ставки и прогноз Яндекс Директа | 0,02 ₽ × фраза | parser |
| `mutagen_competition` | `competition` | Конкуренция 0–25 и статистика фразы | 0,30 ₽ × фраза, повтор за 7 дней бесплатно | parser |
| `mutagen_keyword_report` | `report keyword <отчет> <фраза>` | Отчеты по фразе: статистика, хвосты, вопросы, вариации, LSI, топ-50, реклама | подписка, 1 запрос квоты | serp |
| `mutagen_domain_report` | `report domain <отчет> <домен>` | Отчеты по сайту: ключи, рост и падение, страницы, конкуренты, реклама | подписка, 1 запрос квоты | serp |
| `mutagen_page_report` | `report page <отчет> <URL>` | Отчеты по странице: ключи, конкуренты, упущенные ключи | подписка, 1 запрос квоты | serp |
| `mutagen_serp_report` | `report raw <отчет>` | Любой отчет `mutagen.serp.report` с фильтрами | подписка, 1 запрос квоты | serp |
| `mutagen_build_core` | `core` | Семантическое ядро по маркерам | по смете, не больше бюджета | scenarios |
| `mutagen_expand_core` | `expand` | Новые фразы для готового ядра | по смете, не больше бюджета | scenarios |
| `mutagen_cluster` | `cluster` | Кластеры: лексически, по выдаче, из «Избранного» | бесплатно; по выдаче — подписка, 1 запрос квоты на фразу | scenarios |
| `mutagen_title_h1` | `title` | Title, H1, Description кластера | бесплатно с частотами, иначе 0,02 ₽ × фраза | scenarios |
| `mutagen_content_gap` | `gap` | Фразы конкурентов, которых нет у сайта | подписка, 1 запрос квоты на домен | scenarios |
| `mutagen_minus_words` | `minus` | Минус-слова для Директа | по фразам бесплатно, по маркерам по смете | scenarios |
| `mutagen_content_plan` | `plan` | Контент-план из вопросов | по фразам бесплатно, по маркерам по смете | scenarios |
| `mutagen_text` | `text <операция>` | Дубли и неявные дубли, словарь, комбинатор, сравнение списков, фильтр, вопросы, подсчет | бесплатно, без API | text |

У платных инструментов MCP есть `dry_run` (только смета), `confirm_token` (подтверждение сметы), `force_refresh` (не брать из кэша), `save_as` и `overwrite` (сохранить в файл в `MUTAGEN_OUTPUT_DIR`, заменить существующий), `fields` и `limit` (сократить ответ). В CLI им соответствуют `--dry-run`, `--yes`, `--refresh`, `-o`, `--limit`. Справка по каждой команде: `mutagen-ru <команда> --help`.

Еще MCP-сервер отдает:

- ресурсы `mutagen://reference/reports` (отчеты и колонки Мега-инструмента), `mutagen://reference/regions` (регионы), `mutagen://reference/prices` (цены методов и дата проверки);
- prompts `build-core`, `expand-core`, `direct-prep`, `content-plan` — готовые сценарии для агента.

Коды выхода CLI: `0` — успех, `1` — ошибка API, `2` — неверные аргументы, `3` — нужно подтверждение сметы (`--yes`), `4` — превышен бюджет или включен режим «только бесплатное», `130` — прервано.

## Как экономить

- **Смета до трат.** `--dry-run` в CLI и `dry_run: true` в MCP показывают план и цену без обращения к API. `mutagen_estimate` и `mutagen-ru estimate` считают смету любого плана: `mutagen-ru estimate --freq 500 -t n,qs --competition 50` → 35,00 ₽.
- **Лимит бюджета.** `MUTAGEN_BUDGET_RUB` (по умолчанию 50 ₽) — жесткий предел трат на один запуск CLI или на весь процесс MCP-сервера: все его сессии, в том числе HTTP, тратят один общий бюджет до перезапуска. Вызов, который в него не помещается, отклоняется до обращения к API. `--budget N` в CLI ограничивает один запуск. Сценарии с бюджетом уменьшают план так, чтобы в него уложиться.
- **Порог подтверждения.** Вызовы до `MUTAGEN_AUTO_APPROVE_RUB` (по умолчанию 1 ₽) идут без вопросов. Дороже — CLI спрашивает «Продолжить?» или ждет `--yes`, а MCP возвращает смету и `confirm_token`. Если клиент умеет спрашивать человека через свой интерфейс (elicitation), подтверждение спрашивается у вас.
- **Режим «только бесплатное».** `MUTAGEN_FREE_ONLY=1` или `--free-only`: любой платный вызов отклоняется, бесплатные (баланс, массовые задания, локальная обработка) работают.
- **Кэш.** Готовые частоты и конкуренция хранятся 7 дней, отчеты Мега-инструмента — 1 день (`MUTAGEN_CACHE_TTL_*_DAYS`). Повторный запрос из кэша бесплатный. Баланс и статусы задач не кэшируются. Обойти кэш: `--refresh` или `force_refresh`, отключить: `--no-cache` или `MUTAGEN_NO_CACHE=1`.
- **Журнал и бесплатные повторы.** Каждая платная задача пишется в журнал. Если ответ потерялся или задача еще считается, повтор того же вызова подхватывает уже оплаченную задачу и не платит второй раз. MCP ждет результат около 45 секунд, потом отвечает `processing`; повторите вызов позже — это бесплатно. Новую платную задачу вместо зависшей создает `--new-task` или `new_task: true`.
- **Меньше инструментов — меньше контекста.** Описания и схемы всех 22 инструментов занимают около 34 тыс. символов контекста агента. `MUTAGEN_TOOLS` оставляет только нужные группы: например, `basic,parser,text` — около 14 тыс. символов. Группы: `basic`, `parser`, `serp`, `scenarios`, `text`.
- **Большие результаты — в файл.** MCP отдает агенту сводку и первые строки, полный результат — в файл `save_as`. `fields` и `limit` убирают лишние колонки и строки, например 30 колонок прогноза Директа.
- **Своя обработка бесплатна.** Дубли, неявные дубли, словарь, фильтр по словам, лексическая кластеризация, минус-слова и контент-план по готовому списку работают локально, без ключа и без денег.

## Настройки

Все настройки — переменные окружения. Пример — [.env.example](.env.example).

| Переменная | По умолчанию | Что задает |
|---|---|---|
| `MUTAGEN_API_KEY` | — | Ключ API. Без него работают только локальные операции |
| `MUTAGEN_BUDGET_RUB` | `50` | Предел трат, ₽: на запуск CLI или на процесс MCP-сервера (общий для всех сессий) |
| `MUTAGEN_AUTO_APPROVE_RUB` | `1` | До этой суммы вызов идет без подтверждения, ₽ |
| `MUTAGEN_FREE_ONLY` | `0` | `1` — отклонять любой платный вызов |
| `MUTAGEN_TOOLS` | все группы | Группы инструментов MCP: `basic,parser,serp,scenarios,text` |
| `MUTAGEN_OUTPUT_DIR` | `./mutagen-results` | Куда MCP сохраняет файлы; `save_as` не выходит за этот каталог |
| `MUTAGEN_ALLOW_ANY_OUTPUT_PATH` | `0` | `1` — `save_as` может указывать любой путь; только для stdio, по HTTP не действует |
| `MUTAGEN_MCP_WAIT_SECONDS` | `45` | Сколько вызов MCP ждет задачу Мутагена, прежде чем ответить `processing` |
| `MUTAGEN_MCP_HTTP_TOKEN` | — | Bearer-токен для `--http`; обязателен, если `--host` не localhost |
| `MUTAGEN_MCP_ALLOWED_ORIGINS` | — | Браузерные `Origin` через запятую, которым кроме localhost разрешен `--http`; без них запросы с `Origin` отклоняются |
| `MUTAGEN_CACHE_DIR` | `~/.cache/mutagen-ru-mcp` | Каталог кэша (Windows: `%LOCALAPPDATA%\mutagen-ru-mcp\cache`) |
| `MUTAGEN_STATE_DIR` | `~/.local/state/mutagen-ru-mcp` | Каталог журнала задач (Windows: `%LOCALAPPDATA%\mutagen-ru-mcp\state`) |
| `MUTAGEN_CACHE_TTL_FREQUENCY_DAYS` | `7` | Срок кэша частот, дней |
| `MUTAGEN_CACHE_TTL_COMPETITION_DAYS` | `7` | Срок кэша конкуренции, дней |
| `MUTAGEN_CACHE_TTL_REPORT_DAYS` | `1` | Срок кэша отчетов, дней |
| `MUTAGEN_NO_CACHE` | `0` | `1` — не читать и не писать кэш |
| `MUTAGEN_PRICES_JSON` | — | Переопределить цены методов, если Мутаген их изменит |
| `MUTAGEN_CONCURRENCY` | `2` | Одновременных запросов к API |
| `MUTAGEN_RPS` | `3` | Запросов в секунду |
| `MUTAGEN_BASE_URL` | `http://api.mutagen.ru/json` | Адрес API |

## Ограничения и честные оговорки

- **API только по HTTP.** HTTPS у `api.mutagen.ru` нет, ключ уходит по сети открытым текстом в адресе запроса. Включите в кабинете белый список IP («Разрешить подключение только с ip»): тогда украденный ключ не сработает с чужого адреса. В наших логах, ошибках и файлах ключ заменяется на `***`.
- **Отчеты Мега-инструмента — только по подписке.** Хвосты из базы, вопросы, LSI, позиции, ключи сайтов и страниц, конкуренты, кластеризация по выдаче и поиск пробелов без подписки возвращают «нужна подписка» (ошибка 111). Вместе с ошибкой агент получает подсказку, чем заменить отчет без подписки.
- **Лимиты подписки.** Отчеты расходуют суточную квоту запросов, а строки в отчете и выгрузки за месяц ограничены тарифом. По сайту на 14.10.2026: «Простой» — 950 ₽ в месяц, 300 запросов в сутки, 20 000 строк в отчете; «Расширенный» — 1 250 ₽, 1 500 запросов; «Продвинутый» — 2 450 ₽, 6 000 запросов. Актуально — на [странице тарифов](https://mutagen.ru/serp/?tarif). Когда квота кончается, Мутаген отвечает ошибкой 112.
- **Нет списка проектов «Избранного».** Метода в API нет, хотя он описан в документации. Ключи проекта доступны по id, а id берется из адреса страницы проекта в кабинете (Избранное → проект). Создавать проекты и добавлять в них ключи через API нельзя.
- **Нет правой колонки Вордстата.** «Ключи Вордстата» отдают только левую колонку: 200 или 2000 фраз.
- **Конкуренция и ставки Директа могут висеть.** Оба сбора зависят от связи Мутагена с Яндекс Директом. В октябре 2026 года они считались больше 40 минут. Деньги списываются при постановке задачи; повторный опрос бесплатный, и повтор того же вызова подхватывает уже оплаченную задачу. Если задача висит больше 2 часов, ответ прямо говорит о вероятном сбое на стороне Мутагена или Директа и советует проверить кабинет или написать в поддержку. Конкуренция считается без учета региона — так и на сайте Мутагена.
- **Частоты Вордстата приблизительны и меняются.** Это оценка Яндекса, она плавает от месяца к месяцу. Разные способы сбора дают разные числа: в живой проверке «натяжной потолок цена» в левой колонке Вордстата — 55 926, а отдельным запросом базовой частоты — 62 529. Сравнивайте фразы, собранные одним способом.
- **Позиции — из базы Мутагена.** Это не съем выдачи в реальном времени: база обновляется периодически.
- **Подтверждение через агента — защита от случайности, а не от злого умысла.** Если клиент MCP не умеет спрашивать человека, `confirm_token` получает сам агент и может подтвердить смету без вас. Жесткий предел — только `MUTAGEN_BUDGET_RUB`. Ставьте его таким, какой не жалко потерять.
- **Функций сайта, которых нет в API, у нас тоже нет.** Мы не автоматизируем веб-интерфейс Мутагена: только официальный API и локальная обработка. Рейтинги сайтов, создание проектов, кластеризация на стороне Мутагена недоступны.

## FAQ

**Это официальный клиент Мутагена?**
Нет. Это независимый проект с открытым кодом, он не связан с Мутагеном. Данные принадлежат Мутагену, в каждом ответе и файле стоит пометка «Данные: Мутаген (mutagen.ru)».

**Нужна ли подписка?**
Для частот, «Ключей Вордстата», конкуренции, ставок Директа и всех локальных операций — нет, хватит баланса. Подписка нужна для отчетов Мега-инструмента: хвостов из базы, позиций, ключей сайтов, конкурентов, кластеризации по выдаче.

**Сколько стоит собрать ядро?**
Два маркера, по 200 хвостов, точная частота для 500 фраз — 10,04 ₽. Проверка конкуренции для топ-20 фраз добавит 6 ₽. Точную смету для своих параметров покажет `--dry-run`.

**Что работает без ключа?**
`mutagen_text` и `mutagen-ru text`, лексическая кластеризация, минус-слова и контент-план по готовому списку фраз, Title и H1 по фразам с частотами. Они не обращаются к API.

**Агент может потратить все деньги?**
Не больше `MUTAGEN_BUDGET_RUB` за запуск CLI или за время работы MCP-сервера. Каждый вызов дороже `MUTAGEN_AUTO_APPROVE_RUB` требует подтверждения. Для полной уверенности включите `MUTAGEN_FREE_ONLY=1`.

**Конкуренция ответила `processing`. Деньги списаны?**
Да, при постановке задачи. Повторите тот же вызов позже: он найдет задачу в журнале и не заплатит второй раз.

**Почему частоты отличаются от того, что я вижу в Вордстате?**
Вордстат показывает оценку, которая меняется, а разные виды частотности и способы сбора дают разные числа. См. [ограничения](#ограничения-и-честные-оговорки).

**Как подключить к клиенту, которого нет в списке?**
Любой MCP-клиент со stdio запускает сервер командой `npx -y mutagen-ru-mcp` с переменной `MUTAGEN_API_KEY`. Клиентам, которые подключаются по адресу, подойдет `npx -y mutagen-ru-mcp --http`.

## Участие в проекте

Ошибки, идеи и новые методы API — в [issues](https://github.com/SVorobiev-ru/mutagen-ru-mcp/issues). Как запустить проект, тесты и стиль коммитов — в [CONTRIBUTING.md](CONTRIBUTING.md). Об уязвимостях — по [SECURITY.md](SECURITY.md), не в открытых issue. Пожалуйста, никогда не публикуйте свой ключ API в issue и логах.

## Лицензия

[MIT](LICENSE). Проект неофициальный и не связан с Мутагеном. «Мутаген» и mutagen.ru принадлежат их владельцам. Данные, полученные через API, принадлежат Мутагену; условия их использования — в [документации API](https://mutagen.ru/?p=api) и [пользовательском соглашении](https://mutagen.ru/?p=pay_info).