hibob-advanced-mcp

MCP-сервер для Workforce Planning API компании HiBob — запланированные позиции, их вакансии и бюджеты.

Это дополняет стандартную интеграцию с HRIS HiBob, а не заменяет её. Обычная функциональность HRIS (сотрудники, отпуска, документы) относится к основной интеграции; этот сервер предоставляет функциональность планирования персонала, у которой нет аналогов в других HRIS-системах, поэтому его можно включать только для клиентов, которые планируют штатную численность в HiBob.

Он работает через stdio, устанавливается с помощью uvx и аутентифицируется с помощью служебного пользователя API HiBob.

Настройка HiBob

1. В HiBob перейдите в Settings → Integrations → API service users и создайте служебного пользователя. HiBob показывает идентификатор служебного пользователя и токен только один раз — скопируйте оба сейчас, поскольку позже их нельзя будет получить.

2. Создайте (или переиспользуйте) группу разрешений, содержащую этого служебного пользователя, и предоставьте ей:

   Features → Workforce planning → Position management → Manage positions

   У служебных пользователей по умолчанию нет разрешений. Без этого разрешения каждый вызов возвращает 403, и этот сервер сообщит вам, что нужно добавить именно это разрешение.

3. Если ваша учётная запись HiBob ограничивает доступ к API по IP-адресу, разрешите исходящий IP-адрес того места, где запускается этот сервер.

Для использования в режиме только для чтения всё равно требуется то же разрешение — HiBob не предлагает более узкого разрешения для планирования персонала. Используйте HIBOB_READ_ONLY=true (ниже), если хотите, чтобы сам сервер отказывался вносить изменения.

Конфигурация

Стандартные переменные прокси (HTTPS_PROXY, ALL_PROXY) поддерживаются. Для SOCKS5-прокси требуется дополнительная опция socks — см. строку установки ниже.

Запуск

Закреплено за коммитом — именно так его следует развёртывать:

uvx --from 'git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>' hibob-advanced-mcp

Из локальной копии, во время разработки:

uvx --from . hibob-advanced-mcp --test

--test выводит версию, итоговый базовый URL API, установлены ли учётные данные (но никогда их значения), состояние read-only и каждый зарегистрированный инструмент, после чего завершает работу. Он проверяет установку без необходимости в MCP-клиенте или реальных учётных данных.

С SOCKS5-прокси:

uvx --from 'git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>[socks]' hibob-advanced-mcp

Claude Desktop

{
  "mcpServers": {
    "hibob-workforce-planning": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>",
        "hibob-advanced-mcp"
      ],
      "env": {
        "HIBOB_SERVICE_USER_ID": "<service user ID>",
        "HIBOB_SERVICE_USER_TOKEN": "<service user token>"
      }
    }
  }
}

Подключение к MCP-интеграции в песочнице

Для хоста, который запускает MCP-серверы как изолированные подпроцессы, используя формат конфигурации Claude Desktop, конфигурация интеграции выглядит так:

{
  "server_type": "sandboxed",
  "sandbox_command": "uvx",
  "sandbox_args": [
    "--from",
    "git+https://github.com/JustParent/hibob-advanced-mcp@<GIT_SHA>",
    "hibob-advanced-mcp"
  ],
  "sandbox_runtime": "python",
  "auth_type": "none",
  "sandbox_env": {
    "HIBOB_SERVICE_USER_ID": "<service user ID>",
    "HIBOB_SERVICE_USER_TOKEN": "$SECRET_KEY"
  }
}

Вставьте токен служебного пользователя в поле секретного ключа интеграции: внутри песочницы $SECRET_KEY заменяется на него, поэтому токен никогда не хранится в самой конфигурации. Идентификатор служебного пользователя не является секретом и вставляется как есть.

Аргумент --with 'mcp<2' не нужен — этот пакет сам фиксирует MCP SDK.

Инструменты

Идентификаторы полей передаются в виде плоских отображений, например {"/position/fte": 100}. Префикс /position/ можно опускать ({"fte": 100}). Сервер сам оборачивает значения в конверт HiBob {"value": ...}, а результаты поиска снова разворачивает.

Чтение

Результаты поиска возвращаются в виде {"count": N, "entries": [{"values": {...}, "display": {...}}]}. values содержит исходные значения, включая идентификаторы, необходимые инструментам записи; display содержит читаемые человеком метки HiBob. Поиск вакансий и бюджетов использует курсорную пагинацию и возвращает has_more и next_cursor; поиск позиций не имеет пагинации, поэтому запрашивайте только нужные поля и фильтруйте там, где можно.

Запись (опускается, когда установлено HIBOB_READ_ONLY)

Операции записи ограничены десятью вызовами в минуту, поэтому обязательные поля проверяются до отправки запроса, а вызовы записи никогда не повторяются автоматически. Вызовы чтения повторяются дважды при ответах 429 и 5xx с учётом Retry-After.

hibob_create_position создаёт одну позицию за вызов, вместе с её первой вакансией (HiBob требует её) и необязательным бюджетом.

Шпаргалка по полям

Обязательные поля для создания позиции:

У позиции можно обновлять: name, effectiveDate, managerPositionId, positionType, fte, employmentType, department, site, jobProfile, reason.

Поля для фильтрации: /position/status, /position/name, /position/hasOpenRequests, /position/id; /positionOpening/id, /positionOpening/status (vacant, starting, filled, departing), /positionOpening/positionOpeningName.

Такие поля, как department, site и jobProfile, принимают идентификаторы элементов списков HiBob, а не названия. Получайте их с помощью hibob_get_company_named_lists перед созданием или обновлением позиции.

Разработка

uv venv
uv pip install -e '.[test,lint,typecheck]'
pytest

Линтинг, форматирование и типы проверяются в CI:

ruff check .          # add --fix to apply the automatic fixes
ruff format .         # CI runs --check, so format before pushing
mypy                  # non-strict; paths come from pyproject.toml

Проверка типов намеренно нестрогая: аннотации проверяются там, где они есть, но нетипизированный код допускается. Пакет поставляется с маркером py.typed, поэтому его аннотации видны всему, что его импортирует.

Исследуйте инструменты в интерактивном режиме:

npx @modelcontextprotocol/inspector uvx --from . hibob-advanced-mcp

Лицензия

MIT