# Just-Magic MCP Server

MCP сервер для работы с API сервиса [Just-Magic.org](https://just-magic.org) — платформы для SEO-автоматизации и работы с семантикой.

## Возможности

Сервер предоставляет следующие инструменты:

### 📊 Информация и управление задачами
- **justmagic_info** — информация об аккаунте (тариф, баланс, срок действия)
- **justmagic_list_tasks** — список задач пользователя
- **justmagic_get_task** — получение результатов задачи

### 🔍 Кластеризация и анализ
- **justmagic_cluster** — кластеризация семантического ядра по топам Яндекс/Google
- **justmagic_text_analyzer** — анализ текстовой оптимизации страниц
- **justmagic_thematic_classifier** — тематическая классификация запросов

### 📝 LSI и тексты
- **justmagic_aquarelle** — LSI-анализ текста на тематичность запросу
- **justmagic_aquarelle_generator** — генерация списка LSI-слов для написания текста

### 📈 Частотность и подсказки
- **justmagic_wordstat_frequency** — сбор частотности из Яндекс.Wordstat
- **justmagic_wordstat_suggestions** — сбор подсказок Wordstat
- **justmagic_suggestions_parser** — парсер поисковых подсказок с итерациями

### 🔗 Распределение и расширение
- **justmagic_markers_online** — распределение запросов по страницам сайта
- **justmagic_expand_semantics** — расширение семантического ядра
- **justmagic_regex_search** — поиск в базе ключевых слов по регулярному выражению

## Требования

- Python 3.10+
- Аккаунт Just-Magic.org с тарифом "Эцилопп" или выше (для доступа к API)

## Установка

Распакуйте архив (или склонируйте репозиторий) в удобное место, например `~/code/just-magic-mcp`, и создайте виртуальное окружение с зависимостями:

```bash
cd ~/code/just-magic-mcp
python3 -m venv venv
./venv/bin/pip install "mcp>=1.0.0,<2" "httpx>=0.27.0"
```

> ⚠️ Важно: нужна библиотека `mcp` версии **1.x** — с mcp 2.0 сервер не запустится. Команда выше ставит правильную версию.

Проверка, что всё собралось:

```bash
./venv/bin/python -c "import server; print('OK')"
```

## Настройка

### 1. Получите API-ключ

Войдите в [личный кабинет Just-Magic](https://just-magic.org/lk/lk.php) и скопируйте ваш API-ключ.

Ключ передаётся серверу через переменную окружения `JUSTMAGIC_API_KEY`. Её **не нужно** экспортировать глобально в шелле — она задаётся в конфиге того клиента, который запускает сервер (Claude Desktop или Hermes), см. ниже.

### 2а. Подключение к Claude Desktop

Добавьте в файл конфигурации Claude Desktop:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "just-magic": {
      "command": "/ПОЛНЫЙ/ПУТЬ/К/just-magic-mcp/venv/bin/python",
      "args": ["/ПОЛНЫЙ/ПУТЬ/К/just-magic-mcp/server.py"],
      "env": {
        "JUSTMAGIC_API_KEY": "ваш_api_ключ"
      }
    }
  }
}
```

Замените `/ПОЛНЫЙ/ПУТЬ/К/` на реальный путь (например `/Users/ivan/code/`) и вставьте свой API-ключ вместо `ваш_api_ключ`. После этого перезапустите Claude Desktop.

### 2б. Подключение к Hermes

**Способ 1 — интерактивно через CLI:**

```bash
hermes mcp add
```

На вопросы мастера ответьте: transport — `stdio`, command — полный путь к `venv/bin/python`, args — полный путь к `server.py`, переменная окружения — `JUSTMAGIC_API_KEY` со значением вашего ключа.

**Способ 2 — вручную.** Добавьте в `~/.hermes/config.yaml` блок верхнего уровня:

```yaml
mcp_servers:
  just-magic:
    command: /ПОЛНЫЙ/ПУТЬ/К/just-magic-mcp/venv/bin/python
    args:
      - /ПОЛНЫЙ/ПУТЬ/К/just-magic-mcp/server.py
    env:
      JUSTMAGIC_API_KEY: ${JUSTMAGIC_API_KEY}
```

А сам ключ положите в файл `~/.hermes/.env` (создайте, если его нет):

```
JUSTMAGIC_API_KEY=ваш_api_ключ
```

Ссылка `${JUSTMAGIC_API_KEY}` в конфиге подставится из `.env` автоматически — так ключ не хранится в config.yaml. Можно и вписать ключ прямо в `env:` в config.yaml, но вариант с `.env` аккуратнее.

После правки конфига начните новую сессию Hermes, чтобы инструменты подгрузились. Проверить подключение: `hermes mcp list` и `hermes mcp test just-magic`.

### Дополнительные переменные окружения (необязательно)

- `JUSTMAGIC_DB_PATH` — путь к локальной SQLite-базе для сохранения результатов (по умолчанию `~/justmagic_results.db`).

## Примеры использования

### Кластеризация запросов

```
Кластеризуй эти запросы для Москвы:
- купить ноутбук
- ноутбук цена
- ноутбук для работы
- ноутбук игровой
```

### Анализ текста страницы

```
Проанализируй текстовую оптимизацию страницы https://example.com/notebook 
по запросам: купить ноутбук, ноутбук недорого
```

### Сбор LSI-слов

```
Сгенерируй список LSI-слов для написания текста про "ремонт квартир"
```

### Проверка стоимости задачи

Все инструменты поддерживают параметр `just_ask: true` — при его установке задача не выполняется, а только рассчитывается её стоимость.

```
Сколько будет стоить кластеризация 1000 запросов?
```

## Асинхронная работа

Just-Magic.org использует асинхронную модель выполнения задач:

1. Вы ставите задачу → получаете `tid` (ID задачи)
2. Проверяете статус через `justmagic_get_task`
3. Когда задача готова, получаете результат

Рекомендуемый интервал проверки: **30+ секунд**.

## Коды регионов Яндекса

Некоторые популярные регионы:

| Код | Регион |
|-----|--------|
| 213 | Москва |
| 2 | Санкт-Петербург |
| 54 | Екатеринбург |
| 43 | Казань |
| 47 | Нижний Новгород |
| 65 | Новосибирск |
| 11119 | Вся Россия |

Полный список: [Яндекс.Помощь](https://yandex.ru/dev/xml/doc/dg/reference/regions.html)

## Лицензия

MIT

## Ссылки

- [Just-Magic.org](https://just-magic.org)
- [Документация API](https://just-magic.org/info/api.php)
- [Telegram-канал](https://t.me/justmagicorg)
- [MCP Specification](https://modelcontextprotocol.io)