# Yandex Wordstat MCP для Open WebUI

MCP-сервер для работы с **Yandex Wordstat v2 API** (исследование ключевых слов и анализ поисковых трендов) с **in-memory кэшированием**, обёрнутый в [mcpo](https://github.com/open-webui/mcpo)-прокси для интеграции с [Open WebUI](https://docs.openwebui.com/features/extensibility/mcp/).

## Архитектура

```
Open WebUI  ──HTTP/OpenAPI──▶  mcpo (proxy)  ──stdio──▶  Node MCP Server  ──HTTPS──▶  Yandex Wordstat v2 API
                               :8000                     (with TTL cache)
```

- **MCP-сервер** (`src/index.mjs`) — stdio-транспорт, 5 инструментов Wordstat, TTL-кэш
- **mcpo** — конвертирует stdio MCP → OpenAPI HTTP (нужно для Open WebUI, который поддерживает только Streamable HTTP)
- **Кэш** — in-memory TTL (1 час для запросов, 24 часа для дерева регионов)

## Инструменты

| Инструмент | Описание |
|------------|----------|
| `get-regions-tree` | Дерево регионов (топ-N уровней) |
| `get-region-children` | Дочерние регионы конкретного региона |
| `top-requests` | Популярные запросы по ключевому слову (30 дней) + похожие |
| `dynamics` | Динамика поисковых запросов (день/неделя/месяц) |
| `regions` | Региональное распределение с индексом аффинитивности |

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

### 1. Получение ключей Yandex Cloud

1. В [консоли Yandex Cloud](https://console.yandex.cloud/) создайте сервисный аккаунт с ролью `search-api.webSearch.user`
2. Создайте API-ключ с областью `yc.search-api.execute`
3. Запишите folder ID

### 2. Настройка

```bash
cp .env.example .env
# Отредактируйте .env — впишите ключи
```

### 3. Запуск

```bash
docker compose up -d --build
```

Проверьте, что сервис работает:
```bash
curl http://localhost:8000/docs
```

### 4. Подключение к Open WebUI

1. Откройте **Admin Settings → External Tools** в Open WebUI
2. Нажмите **+ (Add Server)**
3. **Type**: `OpenAPI` (mcpo отдаёт именно OpenAPI, не MCP)
4. **URL**: `http://<IP-сервера>:8000`
5. **Auth**: `Bearer`
6. **Key**: значение `MCPO_API_KEY` из `.env`
7. Сохраните. Проверьте подключение кнопкой **Verify Connection**

Теперь инструменты Wordstat доступны в чате через **+ → Integrations → Tools**.

## Локальный запуск (без Docker)

```bash
npm install
YANDEX_SEARCH_API_KEY=your_key YANDEX_FOLDER_ID=your_folder node src/index.mjs
```

## Кэширование

| Данные | TTL |
|--------|-----|
| Дерево регионов | 24 часа |
| Top requests | 1 час |
| Dynamics | 1 час |
| Regional distribution | 1 час |

Максимум 500 записей в кэше, eviction по LRU.

## Переменные окружения

| Переменная | Описание | Обязательно |
|------------|----------|-------------|
| `YANDEX_SEARCH_API_KEY` | API-ключ Yandex Cloud | ✅ |
| `YANDEX_FOLDER_ID` | ID каталога Yandex Cloud | ✅ |
| `MCPO_API_KEY` | Bearer-ключ для доступа к mcpo | ✅ |
| `MCPO_PORT` | Порт mcpo (по умолчанию 8000) | ❌ |

## Публикация Docker-образа (GitHub Container Registry)

Проект включает GitHub Actions workflow (`.github/workflows/docker-publish.yml`), который автоматически собирает и публикует образ в GHCR при пуше в `main` или создании тега `v*`.

### Как опубликовать

1. Создайте репозиторий на GitHub и запушьте код:
```bash
git remote add origin https://github.com/<username>/yandex_mcp.git
git push -u origin main
```

2. GitHub Actions автоматически соберёт образ и опубликует его как:
```
ghcr.io/<username>/yandex_mcp:latest
```

3. Для релиза конкретной версии создайте тег:
```bash
git tag v1.0.0
git push origin v1.0.0
```
Это создаст образы `ghcr.io/<username>/yandex_mcp:1.0.0` и `ghcr.io/<username>/yandex_mcp:1.0`.

4. На хостинге используйте готовый образ — укажите `GHCR_OWNER` в `.env`:
```bash
GHCR_OWNER=<username>
docker compose pull && docker compose up -d
```

### Локальная сборка (вместо готового образа)

Если хотите собирать локально, раскомментируйте `build: .` в `docker-compose.yml`:
```yaml
services:
  yandex-wordstat-mcp:
    # image: ghcr.io/...
    build: .
```

## Лимиты

- Rate limit: 10 запросов/сек (клиентский)
- Биллинг: через Yandex Cloud (Search API)

## Лицензия

MIT