# hh-ru MCP server

MCP-сервер для поиска вакансий в России и на удалёнке прямо из AI-ассистента
(Claude Desktop, Cursor, Claude Code и других MCP-клиентов).

Под капотом — официальные и открытые API нескольких площадок, собранные в один
набор инструментов:

| Площадка | Ключ нужен? | Что даёт |
| --- | --- | --- |
| [hh.ru](https://hh.ru) | опционально (OAuth) | основной поиск вакансий по РФ |
| [Работа России](https://trudvsem.ru) (`trudvsem`) | нет | государственный портал вакансий |
| [SuperJob](https://superjob.ru) | да (`SUPERJOB_APP_KEY`) | вакансии SuperJob |
| Remotive / RemoteOK / Jobicy | нет | зарубежная IT-удалёнка |

Сервер написан на [FastMCP](https://github.com/modelcontextprotocol/python-sdk),
работает по транспорту `stdio` и обращается к API через
[`curl_cffi`](https://github.com/lexiforest/curl_cffi) с имитацией браузера
(`chrome120`), чтобы обходить базовую анти-бот защиту.

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

| Инструмент | Площадка | Описание |
| --- | --- | --- |
| `search_vacancies` | hh.ru | поиск вакансий с фильтрами (регион, зарплата, опыт, формат работы, сортировка) |
| `get_vacancy` | hh.ru | полное описание вакансии по `id` |
| `find_area_id` | hh.ru | поиск `id` региона/города для фильтра `area` |
| `search_trudvsem` | Работа России | поиск вакансий, фильтр по региону и зарплате |
| `find_superjob_town` | SuperJob | поиск `id` города для фильтра `town` |
| `search_superjob` | SuperJob | поиск вакансий (нужен ключ приложения) |
| `search_remote_jobs` | Remotive/RemoteOK/Jobicy | агрегатор зарубежной удалёнки (англоязычные запросы) |

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

- Python 3.12+
- Зависимости из [`requirements.txt`](requirements.txt): `mcp`, `curl_cffi`

## Установка

```bash
git clone <repo-url>
cd MCP

python -m venv .venv
# Windows (PowerShell):
.venv\Scripts\Activate.ps1
# Linux / macOS:
source .venv/bin/activate

pip install -r requirements.txt
```

## Настройка

Все переменные окружения **опциональны** — сервер запустится и без них,
но с ограничениями. Список — в [`.env.example`](.env.example):

| Переменная | Назначение |
| --- | --- |
| `HH_TOKEN` | OAuth-токен hh.ru. Рекомендуется: без него поиск может возвращать `403`, если IP попал в чёрный список. Получить на [dev.hh.ru](https://dev.hh.ru). |
| `HH_CLIENT_ID`, `HH_CLIENT_SECRET` | Альтернатива `HH_TOKEN` — токен получается автоматически по `client_credentials`. |
| `HH_PROXY` | Прокси для запросов к hh.ru (`http://user:pass@host:port`). |
| `SUPERJOB_APP_KEY` | Secret key приложения SuperJob. Нужен только для `search_superjob` и `find_superjob_town`. Получить на [api.superjob.ru](https://api.superjob.ru). |

### Подключение к MCP-клиенту

Скопируйте [`.mcp.json.example`](.mcp.json.example) в `.mcp.json` (или добавьте
запись в конфиг вашего клиента) и пропишите ключи и путь к Python из вашего
виртуального окружения:

```json
{
  "mcpServers": {
    "hh-ru": {
      "command": "/абсолютный/путь/.venv/bin/python",
      "args": ["/абсолютный/путь/server.py"],
      "env": {
        "HH_TOKEN": "ваш_токен",
        "SUPERJOB_APP_KEY": "ваш_ключ"
      }
    }
  }
}
```

> Пример конфига также включает сервер `playwright` — он не обязателен для
> поиска, но удобен, если AI-ассистент должен ещё и открывать страницы вакансий
> в браузере.

## Запуск

Обычно сервер запускает сам MCP-клиент по конфигу выше. Для ручной проверки:

```bash
python server.py
```

Сервер общается по `stdio` (ждёт MCP-протокол на stdin/stdout) — это нормально,
что в терминале нет вывода.

## Примечания

- **hh.ru и `403`.** Поисковый API hh.ru может банить IP. Если видите ошибку
  про чёрный список — задайте `HH_TOKEN`, используйте `HH_PROXY` или смените сеть
  (например, мобильный интернет).
- **Зарубежная удалёнка.** `search_remote_jobs` возвращает в основном вакансии,
  где компании не нанимают резидентов РФ. Проверяйте поле `location` и требования
  по юрисдикции/релокации.
- **Безопасность.** Не коммитьте реальные ключи. `.env` и `.mcp.json` добавлены
  в [`.gitignore`](.gitignore); для публикации используйте `*.example`-шаблоны.

## Структура

```
.
├── server.py            # MCP-сервер и все инструменты
├── requirements.txt     # зависимости
├── .env.example         # шаблон переменных окружения
├── .mcp.json.example    # шаблон конфига MCP-клиента
└── .gitignore
```