# Yandex Semantic Core MCP

MCP-сервер для сбора реальных данных Yandex Wordstat v2 и управляемого
исследования семантического ядра. Работает локально через stdio, использует
Yandex Cloud Search API и не требует внешних Python-пакетов.

Проект повторяет полезную архитектурную идею
[`ЯДрышко`](https://github.com/Horosheff/yadryshko-semantic-core-subagent):
Wordstat остаётся источником частот, а подключённый AI-агент выполняет очистку,
разметку интентов, кластеризацию и подготовку отчёта. В отличие от референса,
здесь Wordstat MCP входит в сам проект, без промежуточного SaaS.

## Что внутри

| Возможность | MCP name | Что возвращает |
|---|---|---|
| Проверка подключения | `wordstat_get_user_info` | Готовность API и число доступных регионов |
| Топ запросов | `wordstat_get_top_requests` | Реальные фразы, частоты и ассоциации за 30 дней |
| Динамика | `wordstat_get_dynamics` | Дневной, недельный или месячный ряд |
| Спрос по регионам | `wordstat_get_regions` | Частота, доля и affinity index |
| Дерево регионов | `wordstat_get_regions_tree` | ID и названия регионов Wordstat |
| Workflow | MCP prompt `semantic-core` | Последовательность полного исследования |
| Методология | MCP resources | Правила качества, результат и настройка Yandex |

Сервер не вычисляет и не дополняет частоты. Значения в ответах инструментов
приходят непосредственно из Wordstat v2.

## Быстрый запуск

Требуется Python 3.10 или новее.

```bash
git clone https://github.com/zaborlux/yandex-semantic-core-mcp.git
cd yandex-semantic-core-mcp
export YANDEX_SEARCH_API_KEY='ваш API key'
export YANDEX_FOLDER_ID='ваш Folder ID'
python3 server.py
```

При прямом запуске процесс ожидает MCP JSON-RPC в stdin. Обычно его запускает
Cursor, Claude, Codex или другой MCP-клиент.

Полная настройка:

1. [Подготовить Yandex Cloud](docs/yandex-cloud-setup.md).
2. [Подключить MCP-клиент](docs/mcp-client-setup.md).
3. Вызвать `wordstat_get_user_info`.
4. Запустить prompt `semantic-core` или сформулировать задачу обычным текстом.

## Пример запроса агенту

```text
Собери семантическое ядро для https://example.ru.
Регион: Москва, Wordstat ID 213.
Цель: заявки на услугу.
Исключить: вакансии и бесплатные скачивания.
Используй prompt semantic-core и реальные данные Wordstat.
```

## Структура

```text
yandex-semantic-core-mcp/
├── server.py
├── pyproject.toml
├── .env.example
├── docs/
│   ├── architecture.md
│   ├── mcp-client-setup.md
│   ├── semantic-core-workflow.md
│   ├── troubleshooting.md
│   └── yandex-cloud-setup.md
├── examples/
│   └── mcp-config.json
└── tests/
    └── test_server.py
```

## Проверка

```bash
python3 -m unittest discover -s tests -v
```

Проверить только MCP handshake можно без ключа:

```bash
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | python3 server.py
```

Для обращения к Wordstat нужны Yandex Cloud API key и Folder ID.

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

- Не коммитьте API key и не помещайте его в `.env.example`.
- Создайте отдельный сервисный аккаунт с единственной ролью
  `search-api.webSearch.user`.
- Ограничьте API key областью `yc.search-api.execute`.
- Сервер не пишет ключ, Folder ID, запросы или ответы в stdout: stdout занят
  MCP-протоколом.
- Сырые результаты Wordstat храните отдельно от выводов AI.

## Ограничения

- Транспорт — локальный stdio; публичного HTTP endpoint нет.
- Обход сайта, live SERP, GSC и Яндекс Вебмастер не входят в сервер.
- Кластеризацию делает подключённая модель по встроенной методологии; она должна
  явно отмечать отсутствие live SERP-проверки.
- Использование Search API тарифицируется и ограничивается квотами Yandex Cloud.

## Документы

- [Архитектура](docs/architecture.md)
- [Настройка Yandex Cloud](docs/yandex-cloud-setup.md)
- [Настройка MCP-клиентов](docs/mcp-client-setup.md)
- [Workflow семантического ядра](docs/semantic-core-workflow.md)
- [Диагностика](docs/troubleshooting.md)

## Лицензия

MIT.