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アカウントが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は、バージョン、解決された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設定時は省略）

書き込みは1分間に10回に制限されているため、必須フィールドはリクエスト送信前に検証され、書き込み呼び出しは自動的に再試行されません。読み取り呼び出しは429および5xx応答で2回再試行し、Retry-Afterを尊重します。

hibob_create_positionは、最初のオープニング（HiBobでは必須）とオプションの予算とともに、呼び出しごとに1つのポジションを作成します。

フィールド早見表

ポジションの作成に必須：

ポジションで更新可能：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でそれらを解決してください。

開発

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