# MCP-сервер для Huntflow — вакансии, кандидаты и резюме ATS через ИИ

Если вы искали, как подключить Huntflow к нейросети, найти кандидата и прочитать его резюме не листая карточки в ATS — это оно. 14 инструментов и 2 скилла: вакансии, кандидаты, резюме, этапы подбора, справочники, аккаунты. Спрашиваете «кто застрял на этапе техинтервью» — получаете список, а не выгрузку в CSV.

[![npm](https://img.shields.io/npm/v/@theyahia/huntflow-mcp)](https://www.npmjs.com/package/@theyahia/huntflow-mcp)
[![CI](https://github.com/theYahia/huntflow-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/theYahia/huntflow-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Часть серии [WWmcp](https://github.com/theYahia/WWmcp) (46 серверов).

> **Важно:** в npm опубликована только устаревшая `@theyahia/huntflow-mcp@1.1.1`. Она жёстко ходит на
> `api.huntflow.ai`, игнорирует `HUNTFLOW_BASE_URL` и `HUNTFLOW_REFRESH_TOKEN`, поэтому с токеном от
> `api.huntflow.ru` всегда отвечает «неверный токен». Ставьте сервер из исходников (ниже).

## Установка

### Из исходников (рекомендуется)
```bash
git clone https://github.com/<your-github-user>/huntflow-mcp.git
cd huntflow-mcp
npm install   # заодно собирает dist/ (скрипт prepare)
```
```json
{
  "mcpServers": {
    "huntflow": {
      "command": "node",
      "args": ["C:/path/to/huntflow-mcp/dist/index.js"],
      "env": {
        "HUNTFLOW_TOKEN": "ваш-access-token",
        "HUNTFLOW_REFRESH_TOKEN": "ваш-refresh-token",
        "HUNTFLOW_BASE_URL": "https://api.huntflow.ru/v2"
      }
    }
  }
}
```
Без клонирования — прямо с GitHub: `"command": "npx", "args": ["-y", "github:<your-github-user>/huntflow-mcp"]`.

`HUNTFLOW_BASE_URL`: `https://api.huntflow.ru/v2` (по умолчанию) или `https://api.huntflow.ai/v2` —
это разные системы, токен действует только на той, где он выпущен.

### Claude Desktop (stdio, npm — после публикации ≥ 1.2.1)
```json
{
  "mcpServers": {
    "huntflow": {
      "command": "npx",
      "args": ["-y", "@theyahia/huntflow-mcp"],
      "env": {
        "HUNTFLOW_TOKEN": "ваш-access-token",
        "HUNTFLOW_REFRESH_TOKEN": "ваш-refresh-token"
      }
    }
  }
}
```

### Streamable HTTP
```bash
HUNTFLOW_TOKEN=ваш-токен npx @theyahia/huntflow-mcp --http
# POST /mcp, GET /health на 127.0.0.1:3000 (PORT=...)
```

### Smithery
```bash
npx @smithery/cli install @theyahia/huntflow-mcp
```

## Получение токена

Настройки HuntFlow → вкладка **«API-токены» (API Tokens)** → создать токен. Выданная пара включает **access-токен** (живёт ~7 дней) и **refresh-токен** (~14 дней). Сервер автоматически обновляет access-токен через `POST /token/refresh` при истечении и **сохраняет ротированную пару** в файл состояния (`HUNTFLOW_TOKEN_FILE`), переживая рестарты. Если задать только `HUNTFLOW_TOKEN` без refresh — сервер проработает до истечения access-токена (~7 дней), затем потребуется новый токен.

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

| Переменная | Обяз. | Описание |
|------------|:---:|----------|
| `HUNTFLOW_TOKEN` | да | Access-токен (Настройки → API-токены) |
| `HUNTFLOW_REFRESH_TOKEN` | нет | Refresh-токен — включает авто-обновление при 401 |
| `HUNTFLOW_TOKEN_FILE` | нет | Файл для хранения ротированной пары (по умолчанию `~/.huntflow-mcp/token.json`) |
| `HUNTFLOW_BASE_URL` | нет | По умолчанию `https://api.huntflow.ru/v2` |
| `HUNTFLOW_READ_ONLY` | нет | `1` — отключить инструменты записи (останутся 14 инструментов чтения) |
| `NODE_OPTIONS` | нет | `--use-system-ca` — если запросы падают с ошибкой сертификата (корпоративный прокси) |
| `HUNTFLOW_USER_AGENT` | нет | User-Agent (обязателен для API; есть дефолт) |
| `HUNTFLOW_TIMEOUT_MS` | нет | Таймаут запроса, мс (по умолчанию 10000) |
| `HUNTFLOW_DISABLE_RATELIMIT` | нет | `1` — отключить клиентский лимит 10 req/s |
| `PORT` | нет | Порт HTTP-сервера (по умолчанию 3000) |
| `HUNTFLOW_HTTP_HOST` | нет | Хост привязки HTTP (по умолчанию `127.0.0.1`) |
| `HUNTFLOW_HTTP_SECRET` | нет | Если задан — требует `Authorization: Bearer <secret>` на `/mcp` |
| `HUNTFLOW_ALLOWED_HOSTS` | нет | Список host:port для защиты от DNS-rebinding |

## Инструменты (23)

### Чтение (14)

| Инструмент | Описание |
|------------|----------|
| `list_accounts` | Список доступных аккаунтов |
| `list_vacancies` | Список вакансий (фильтры `opened`/`state`/`mine`, пагинация) |
| `get_vacancy` | Полная информация о вакансии |
| `search_applicants` | Поиск кандидатов (`q` + фильтры vacancy/status/tag) |
| `list_vacancy_applicants` | Кандидаты, прикреплённые к конкретной вакансии |
| `get_applicant` | Полная информация о кандидате |
| `get_applicant_resumes` | Список резюме (external) кандидата |
| `get_resume` | Полное тело конкретного резюме (external) |
| `list_stages` | Этапы воронки подбора (статусы вакансий) |
| `list_coworkers` | Сотрудники/рекрутеры аккаунта |
| `list_sources` | Справочник источников кандидатов |
| `list_rejection_reasons` | Справочник причин отказа |
| `list_divisions` | Справочник подразделений |
| `list_tags` | Справочник тегов |

### Запись (9)

Меняют данные в Huntflow от имени владельца токена. Удаления нет. Отключаются целиком через `HUNTFLOW_READ_ONLY=1`.

| Инструмент | Описание |
|------------|----------|
| `create_applicant` | Создать кандидата |
| `update_applicant` | Изменить поля кандидата (только переданные) |
| `add_applicant_to_vacancy` | Прикрепить кандидата к вакансии на этап |
| `change_applicant_status` | Перевести кандидата на другой этап (отказ с причиной, найм) |
| `add_applicant_comment` | Комментарий в ленту кандидата |
| `set_applicant_tags` | Задать теги кандидата (заменяет весь список) |
| `create_vacancy` | Создать вакансию |
| `update_vacancy` | Изменить поля вакансии (только переданные) |
| `set_vacancy_state` | Закрыть / приостановить / возобновить вакансию |

Списочные инструменты возвращают курированный набор полей (экономия токенов) + `structuredContent`; передайте `raw: true` для полного сырого ответа. Пагинация — параметры `page`/`count`.

## Скиллы (Prompts)

| Скилл | Описание |
|-------|----------|
| `skill-applicants` | Кандидаты на вакансию — таблица с этапами и сводкой |
| `skill-vacancy-stats` | Статистика по вакансии — воронка, сроки, конверсия |

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

```bash
npm install
npm test           # vitest
npm run typecheck  # tsc --noEmit
npm run lint       # eslint
npm run format     # prettier --write
npm run dev        # tsx src/index.ts
npm run build      # tsc
```

## Лицензия
MIT

---

Часть [WWmcp](https://github.com/theYahia/WWmcp) · Telegram: [@vhodvai](https://t.me/vhodvai)