hibob-advanced-mcp

HiBob의 Workforce Planning API용 MCP 서버 — 계획된 포지션, 해당 오프닝, 그리고 예산을 다룹니다.

이 서버는 표준 HiBob HRIS 통합을 대체하는 것이 아니라 보완합니다. 일반적인 HRIS 기능(인사, 휴가, 문서)은 기본 통합에 속하며, 이 서버는 다른 HRIS 시스템에는 없는 인력 계획 영역을 노출하므로 HiBob에서 헤드카운트를 계획하는 고객에게만 활성화할 수 있습니다.

stdio로 실행되며 uvx로 설치할 수 있고 HiBob API 서비스 사용자로 인증합니다.

HiBob 설정

1. HiBob에서 설정 → 통합 → API 서비스 사용자로 이동하여 서비스 사용자를 만듭니다. HiBob은 서비스 사용자 ID와 토큰을 한 번만 표시하므로 지금 둘 다 복사하세요. 나중에 다시 조회할 수 없습니다.

2. 해당 서비스 사용자가 포함된 권한 그룹을 만들고(또는 재사용하고) 다음 권한을 부여합니다:

   기능 → 인력 계획 → 포지션 관리 → 포지션 관리

   서비스 사용자는 기본적으로 권한이 없습니다. 이 권한이 없으면 모든 호출이 403을 반환하며, 이 서버는 정확히 이 권한을 추가하라고 안내합니다.

3. HiBob 계정이 IP 주소로 API 액세스를 제한하는 경우, 이 서버가 실행되는 곳의 아웃바운드 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는 버전, 확인된 API 기본 URL, 자격 증명 설정 여부(값은 절대 표시하지 않음), 읽기 전용 상태, 등록된 모든 도구를 출력한 후 종료합니다. 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 통합에 연결

Claude Desktop 구성 형태를 사용하여 MCP 서버를 샌드박스 하위 프로세스로 실행하는 호스트의 경우 통합 구성은 다음과 같습니다:

{
  "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가 이 값으로 대체되므로 토큰이 구성 자체에 저장되지 않습니다. 서비스 사용자 ID는 비밀이 아니므로 그대로 입력합니다.

--with 'mcp<2' 인자는 필요하지 않습니다. 이 패키지는 MCP SDK 자체를 고정합니다.

도구

필드 ID는 평면 매핑으로 전달됩니다(예: {"/position/fte": 100}). /position/ 접두사는 생략할 수 있습니다({"fte": 100}). 서버가 값을 HiBob의 {"value": ...} 봉투로 자동 감싸고, 검색 결과는 다시 평면화합니다.

읽기

검색 결과는 {"count": N, "entries": [{"values": {...}, "display": {...}}]} 형태로 반환됩니다. values는 쓰기 도구에 필요한 ID를 포함한 원시 값을 담고, display는 HiBob의 사람이 읽을 수 있는 라벨을 담습니다. 오프닝 및 예산 검색은 커서 페이지네이션을 사용하며 has_more와 next_cursor를 반환합니다. 포지션 검색에는 페이지네이션이 없으므로 필요한 필드만 요청하고 가능한 곳에서 필터링하세요.

쓰기(HIBOB_READ_ONLY 설정 시 생략됨)

쓰기 호출은 분당 10회로 제한되므로, 요청을 보내기 전에 필수 필드를 검증하며 쓰기 호출은 자동으로 재시도되지 않습니다. 읽기 호출은 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 목록 항목 ID를 받습니다. 포지션을 생성하거나 업데이트하기 전에 hibob_get_company_named_lists로 해당 ID를 확인하세요.

개발

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

타입 검사는 의도적으로 비엄격(non-strict)합니다. 주석이 있는 곳은 검사하지만, 타입이 없는 코드는 허용됩니다. 이 패키지에는 py.typed 마커가 포함되어 있어, 이를 임포트하는 모든 코드에서 주석을 볼 수 있습니다.

도구를 대화형으로 살펴보기:

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

라이선스

MIT