# seo-factory-mcp

MCP-сервер + скиллы для Claude Code: **SEO контент-фабрика и цикл роста блога** —
без сервера и крона, агент запускается когда вы просите.

Работает с любым сайтом, реализующим zaytsv-совместимый article-API
(см. [контракт](skills/seo-content-factory/reference/site-contract.md)):
переписали клон под другую тематику, оставили эндпоинты — подключается одной
командой `add_site`. Сайтов может быть несколько.

- 📝 **Публикация с валидацией** — errors блокируют, warnings предупреждают:
  FAQ-секция (FAQPage-разметка), обложка первой картинкой (переживает PUT),
  title ≤60, description ≤160, внутренние ссылки
- 🔗 **Перелинковка** — тематический скоринг (тот же, что виджет «Читайте также»
  на сайте): статьи-сироты без входящих ссылок + доноры, готовые markdown-сниппеты
- 🔍 **Майнинг «второй страницы»** — сопоставление запросов Яндекс.Вебмастера со
  статьями: что дожать, что написать (пара к MCP [yandex-marketing](https://github.com/skiddgoddamn/yandex-marketing-mcp))
- 🧾 **Контент-аудит** — без FAQ, короткие, без обложки, мало ссылок
- 📦 **Без зависимостей** — чистый Node ≥18, ставится и запускается сразу

## Установка

**Вариант A — плагин Claude Code (рекомендуется: тулы + скиллы-плейбуки):**

```
/plugin marketplace add skiddgoddamn/seo-factory-mcp
/plugin install seo-factory@seo-factory
```

**Вариант B — любой MCP-клиент через npx** (только тулы, без скиллов) —
см. [examples/.mcp.json](examples/.mcp.json).

## Подключение сайта

1. Откройте `<ваш-сайт>/articles/api`, создайте токен (вид `zmcp_…`, показывается один раз).
2. Скажите агенту: «подключи сайт https://ваш-сайт.ru с токеном zmcp_…» — он вызовет
   `add_site` (валидирует контракт и токен живыми запросами; невалидное не сохраняется).
3. Конфиг: `~/.seo-factory-mcp/config.json` (несколько сайтов, дефолтный, `articlePath`
   для блога не на `/articles`, `yandexHost` для цикла роста, `hiddenTags` для скрытых тем).

Быстрый старт без add_site: env `SEO_FACTORY_BASE_URL` (+ `SEO_FACTORY_TOKEN`).
Read-only тулы (аудиты, списки, подбор ссылок) работают и вовсе без токена.

## Использование

> напиши и опубликуй статью про выбор CRM для малого бизнеса

Скилл **seo-content-factory** проверит дубли, соберёт перелинковку, напишет текст
с FAQ и обложкой, провалидирует и опубликует.

> что дожать в блоге по данным поиска?

Скилл **seo-growth-loop** возьмёт запросы позиций 8–30 из Вебмастера (если подключён
yandex-marketing MCP), найдёт сирот, соберёт приоритизированный план и исполнит.

## Тулы (13)

| Тул | Что делает |
|---|---|
| `setup` | статус конфига и живой auth-probe по всем сайтам + онбординг |
| `add_site` | добавить/обновить сайт (живая валидация; alias, articlePath, yandexHost, hiddenTags) |
| `list_articles` | лёгкий список с фильтрами (tag/query), скрытые помечаются |
| `get_article` | полная статья по slug (id для update/delete — в ответе) |
| `publish_article` | валидация → POST; финальный slug/URL из ответа |
| `update_article` | resolve по slug → PUT; ловит затирание обложки; 403-готча |
| `delete_article` | ⚠️ confirm:true; предупреждает: IndexNow об удалении не узнаёт |
| `upload_image` | картинка → URL (вставить `![](url)` первой строкой = обложка) |
| `validate_article` | офлайн-линтер: errors/warnings/facts |
| `audit_orphans` | статьи-сироты + доноры (граф «Читайте также») |
| `audit_content` | аудит полных тел: FAQ/длина/обложка/ссылки |
| `suggest_links` | тематически близкие + готовые сниппеты перелинковки |
| `match_queries` | запросы Вебмастера → «дожать slug» / «написать новую» |

Большие входы/выходы — через файлы (`contentFile`, `queriesFile`, `saveToFile`),
чтобы не гнать мегабайты через контекст модели.

## Сосуществование с zaytsv-mcp

У [zaytsv-mcp](https://github.com/skiddgoddamn/zaytsv-mcp) есть простые `article_*`
тулы на тот же API. Если установлены оба плагина — для статей предпочитайте
**seo-factory**: здесь валидация, защита обложки от PUT-затирания и перелинковка;
`article_*` в zaytsv-mcp остаются для быстрых правок без SEO-обвязки.

## Разработка

```bash
npm run check   # синтаксис всех .mjs
npm test        # 18 юнитов (node --test) + smoke по stdio
```

Тесты уводят конфиг в temp через `SEO_FACTORY_CONFIG_DIR` — живой
`~/.seo-factory-mcp/config.json` не трогается.

Публикация: тег `vX.Y.Z` → GitHub Actions (ассерт синка версий → тесты →
`npm publish --provenance`).

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

- Токен `zmcp_…` даёт **полный доступ к аккаунту** сайта (не только статьи).
  Не коммитьте его; в конфигах клиентов храните ссылку `${SEO_FACTORY_TOKEN}`, не значение.
- Файл конфига пишется с mode 0600 (на Windows это no-op — при необходимости
  ограничьте доступ ACL).
- `add_site` не сохраняет токен, не прошедший живую проверку; отзыв — на
  `<сайт>/articles/api`.

## Лицензия

MIT