hibob-advanced-mcp

Un servidor MCP para la Workforce Planning API de HiBob: puestos planificados, sus vacantes y sus presupuestos.

Esto complementa una integración estándar de HRIS de HiBob en lugar de reemplazarla. La funcionalidad común de HRIS (personas, tiempo libre, documentos) pertenece a la integración principal; este servidor expone la superficie de Workforce Planning que no tiene equivalente en otros sistemas HRIS, por lo que puede habilitarse solo para los clientes que planifican la plantilla en HiBob.

Se ejecuta a través de stdio, se puede instalar con uvx y se autentica con un usuario de servicio de API de HiBob.

Configuración de HiBob

1. En HiBob, ve a Settings → Integrations → API service users y crea un usuario de servicio. HiBob muestra el ID de usuario de servicio y el token una sola vez: copia ambos ahora, ya que no se pueden recuperar más tarde.

2. Crea (o reutiliza) un grupo de permisos que contenga a ese usuario de servicio y concédele:

   Features → Workforce planning → Position management → Manage positions

   Los usuarios de servicio no tienen permisos por defecto. Sin esta concesión, cada llamada devuelve 403, y este servidor te indicará que añadas exactamente este permiso.

3. Si tu cuenta de HiBob restringe el acceso a la API por dirección IP, permite la IP de salida del lugar donde se ejecute este servidor.

El uso de solo lectura también necesita la misma concesión: HiBob no ofrece un permiso de Workforce Planning más restringido. Usa HIBOB_READ_ONLY=true (abajo) si quieres que el propio servidor se niegue a realizar cambios.

Configuración

Se respetan las variables de proxy estándar (HTTPS_PROXY, ALL_PROXY). Un proxy SOCKS5 necesita el extra opcional socks; consulta la línea de instalación a continuación.

Ejecución

Fijado a un commit, que es como debería desplegarse:

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

Desde una copia local del repositorio, durante el desarrollo:

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

--test imprime la versión, la URL base de la API resuelta, si las credenciales están establecidas (nunca sus valores), el estado de solo lectura y todas las herramientas registradas, y luego sale. Verifica una instalación sin necesidad de un cliente MCP ni credenciales reales.

Con un proxy 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>"
      }
    }
  }
}

Integración con un MCP en sandbox

Para un host que ejecuta servidores MCP como subprocesos en sandbox usando el formato de configuración de Claude Desktop, la configuración de integración es:

{
  "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"
  }
}

Pega el token del usuario de servicio en el campo de clave secreta de la integración: $SECRET_KEY se sustituye por él dentro del sandbox, por lo que el token nunca se almacena en la propia configuración. El ID de usuario de servicio no es un secreto y se introduce literalmente.

No se necesita el argumento --with 'mcp<2': este paquete fija el propio SDK de MCP.

Herramientas

Los IDs de campo se pasan como asignaciones planas, por ejemplo {"/position/fte": 100}. El prefijo /position/ puede omitirse ({"fte": 100}). El servidor envuelve los valores en el sobre {"value": ...} de HiBob por ti y aplana los resultados de búsqueda de nuevo.

Lectura

Los resultados de búsqueda se devuelven como {"count": N, "entries": [{"values": {...}, "display": {...}}]}. values contiene los valores brutos, incluidos los IDs que necesitan las herramientas de escritura; display contiene las etiquetas legibles por humanos de HiBob. Las búsquedas de vacantes y presupuestos están paginadas por cursor y devuelven has_more y next_cursor; la búsqueda de posiciones no tiene paginación, así que solicita solo los campos que necesites y filtra donde puedas.

Escritura (omitida cuando se establece HIBOB_READ_ONLY)

Las escrituras están limitadas a diez llamadas por minuto, por lo que los campos obligatorios se validan antes de enviar una solicitud y las llamadas de escritura nunca se reintentan automáticamente. Las llamadas de lectura se reintentan dos veces ante respuestas 429 y 5xx, respetando Retry-After.

hibob_create_position crea una posición por llamada, junto con su primera vacante (HiBob requiere una) y un presupuesto opcional.

Hoja de referencia de campos

Requeridos para crear una posición:

Actualizables en una posición: name, effectiveDate, managerPositionId, positionType, fte, employmentType, department, site, jobProfile, reason.

Campos filtrables: /position/status, /position/name, /position/hasOpenRequests, /position/id; /positionOpening/id, /positionOpening/status (vacant, starting, filled, departing), /positionOpening/positionOpeningName.

Campos como department, site y jobProfile aceptan IDs de elementos de lista de HiBob, no nombres. Resuélvelos con hibob_get_company_named_lists antes de crear o actualizar una posición.

Desarrollo

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

El lint, el formato y los tipos se aplican en 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

La comprobación de tipos es deliberadamente no estricta: las anotaciones se verifican donde existen, pero se permite código sin tipar. El paquete incluye un marcador py.typed, por lo que sus anotaciones son visibles para cualquier cosa que lo importe.

Inspecciona las herramientas de forma interactiva:

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

Licencia

MIT