ImmyBot

@wyre-ai/immybot-mcp

ImmyBot 用の MCP サーバー。Windows エンドポイント管理とソフトウェア展開を自動化します。

機能

• 🔐 OAuth 2.0 認証 - Microsoft Entra ID クライアント資格情報
• 🏢 マルチテナント対応 - インスタンスごとのサブドメイン設定
• 🧭 決定木ナビゲーション - ドメインごとに整理されたツールの検出
• 💻 包括的なカバー範囲 - コンピューター、ソフトウェア、展開、スクリプト、テナント、メンテナンスセッション、タスク
• ⚡ ゲートウェイ対応 - WYRE MCP Gateway 向けのリクエストごとのステートレスな操作
• 🚀 Docker デプロイ - ヘルスチェック付きのコンテナー対応
• 📊 構造化ログ - 詳細な操作追跡

クイックスタート

Docker（推奨）

イメージはコンテナー内の 0.0.0.0 でリッスンし、デフォルトで AUTH_MODE=gateway に設定されています。ポートをループバックで公開し、実際の CONDUIT_S2S_SECRET を渡してください。ゲートウェイモードでは、ImmyBot の資格情報は各リクエストのヘッダーで渡され、環境変数からは読み込まれません。

docker run -d \
  --name immybot-mcp \
  -p 127.0.0.1:8080:8080 \
  -e CONDUIT_S2S_SECRET \
  -e AUTH_MODE=gateway \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_PORT=8080 \
  -e LOG_LEVEL=info \
  ghcr.io/wyre-ai/immybot-mcp:latest

CONDUIT_S2S_SECRET が設定されていない場合、Compose は起動を拒否します。ゲートウェイサービスでは IMMYBOT_* 変数も env_file も設定されていないため、プロジェクトの .env から静的なベンダー資格情報を注入することはできません。127.0.0.1:8080:8080 でポートを公開します。

# openssl rand -hex 32 — do not use a placeholder such as changeme
CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" docker compose up

直接インストール

npm install @wyre-ai/immybot-mcp
npx @wyre-ai/immybot-mcp

ナビゲーション

このサーバーでは、ドメインごとにツールを整理するために決定木ナビゲーションを使用します。

1. 開始 → immybot_navigate → ドメインを選択
2. ドメインツール → ドメイン固有の操作
3. 戻る → immybot_back → メインナビゲーション

利用可能なドメイン

• computers - デバイスとエンドポイントの管理
• software - アプリケーションとパッケージの管理
• deployments - ソフトウェア展開の設定
• scripts - PowerShell スクリプトの実行と管理
• tenants - クライアント組織の管理
• maintenance_sessions - デバイスのメンテナンスと状態の調整
• tasks - バックグラウンド操作の監視

認証

ImmyBot は Microsoft Entra ID を使用した OAuth 2.0 に対応しています。

必須の設定

フィールド	説明	例
instanceSubdomain	ImmyBot インスタンスのサブドメイン	acmemsp
tenantId	Microsoft Entra テナント ID	12345678-1234-1234-1234-123456789abc
clientId	アプリケーション（クライアント）ID	87654321-4321-4321-4321-cba987654321
clientSecret	クライアントシークレットの値	your-client-secret

設定手順

1. Microsoft Entra ID でエンタープライズアプリケーションを登録します
2. アプリケーションにImmyBot API のアクセス許可を付与します
3. アプリケーション用のクライアントシークレットを作成します
4. ImmyBot の設定でアプリケーションを構成します

OAuth スコープ：api://{client_id}/.default

使用例

1. Computers ドメインに移動

// Start navigation
await callTool('immybot_navigate', { domain: 'computers' });

// List computers
await callTool('immybot_computers_list', { 
  tenantId: 1,
  isOnline: true 
});

// Get computer details
await callTool('immybot_computers_get', { computerId: 123 });

2. ソフトウェアの管理

// Navigate to software domain
await callTool('immybot_navigate', { domain: 'software' });

// Search for software
await callTool('immybot_software_search', { query: 'Chrome' });

// Install software (stages for maintenance session)
await callTool('immybot_software_install', {
  softwareId: 456,
  computerIds: [123, 124, 125],
  autoUpdate: true
});

3. メンテナンスセッション

// Navigate to maintenance sessions
await callTool('immybot_navigate', { domain: 'maintenance_sessions' });

// Start maintenance session (reconciles deployments)
await callTool('immybot_maintenance_sessions_start', {
  computerId: 123,
  sessionType: 'Manual'
});

// Check session status
await callTool('immybot_maintenance_sessions_get', { sessionId: 789 });

2 段階の展開モデル

⚠️ 重要：ImmyBot では、2 段階の展開ワークフローを使用します。

1. 目標状態を設定 - ソフトウェアのインストールによって展開が作成されます
2. メンテナンスセッションで調整 - セッションによって目標状態が適用されます

// Step 1: Stage software installation
await callTool('immybot_software_install', {
  softwareId: 123,
  computerIds: [456]
});
// ↑ This creates a deployment, does NOT install immediately

// Step 2: Reconcile state
await callTool('immybot_maintenance_sessions_start', {
  computerId: 456
});
// ↑ This runs the maintenance session to actually install software

環境変数

.env.example をコピーし、以下の変数を設定してください。

ゲートウェイモード（Docker）

変数	デフォルト	説明
AUTH_MODE	direct	WYRE MCP Gateway を使用するには gateway を設定します。ゲートウェイモードでは、各 /mcp リクエストに4つの x-immybot-* 認証情報ヘッダーが必要で、IMMYBOT_* へのフォールバックは行いません。Docker イメージと Compose のデフォルトは gateway です。
MCP_TRANSPORT	stdio	トランスポートモード（http または stdio）
MCP_HTTP_PORT	8080	HTTP サーバーのポート
MCP_HTTP_HOST	実際の CONDUIT_S2S_SECRET が設定されていて、この変数が未設定の場合は 0.0.0.0。安全でない開発用バイパスの場合は 127.0.0.1	バインドアドレス。シークレットが設定されている場合は、0.0.0.0 を含め、この値が適用されるため、コンテナーのデプロイでも到達可能な状態が保たれます。イメージと Compose では 0.0.0.0 が設定されます。
CONDUIT_S2S_SECRET	—	HTTP で必須です。/mcp で X-Gateway-S2S と照合する HMAC シークレットです。openssl rand -hex 32 で生成します。空または既知のプレースホルダーの場合、HTTP サーバーはエラーをログに記録し、ゼロ以外のステータスで終了します。この値がログに記録されることはありません。
MCP_ALLOW_INSECURE_DEV	未設定	CONDUIT_S2S_SECRET なしで HTTP を起動するには、値を正確に 1 に設定します。警告をログに記録し、X-Gateway-S2S を強制せず、127.0.0.1 のみでバインドします。ループバック以外の MCP_HTTP_HOST が設定されている場合、起動を拒否します。プレースホルダーのシークレットが設定されている場合も、起動を拒否します。ローカル開発専用です。
LOG_LEVEL	info	ログレベル（debug、info、warn、error）

/health は認証不要のままで、認証情報を読み取りません。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

ダイレクトモード（CLI）

変数	必須	説明
IMMYBOT_INSTANCE_SUBDOMAIN	✅	ImmyBot インスタンスのサブドメイン
IMMYBOT_TENANT_ID	✅	Microsoft Entra テナント ID
IMMYBOT_CLIENT_ID	✅	アプリケーションのクライアント ID
IMMYBOT_CLIENT_SECRET	✅	クライアントシークレット

HTTP 認証

MCP_TRANSPORT=http かつ CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストに X-Gateway-S2S が必要です。この検証は src/s2s-verify.ts の verifyS2sHeader で行います。ヘッダーの値は t=<unix seconds>,v1=<hex> で、hex は CONDUIT_S2S_SECRET をキーとして、リテラル文字列 t=<unix seconds> の HMAC-SHA256 を計算したものです（小文字の16進数64文字）。タイムスタンプはサーバーの時刻から300秒以内でなければなりません。ヘッダーがない場合、または無効な場合は、ベンダーの認証情報が読み取られる前に HTTP 401 が返されます。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H 'X-ImmyBot-Instance-Subdomain: acmemsp' \
  -H 'X-ImmyBot-Tenant-Id: 12345678-1234-1234-1234-123456789abc' \
  -H 'X-ImmyBot-Client-Id: 87654321-4321-4321-4321-cba987654321' \
  -H 'X-ImmyBot-Client-Secret: your-client-secret' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

AUTH_MODE=gateway の場合、4つの X-ImmyBot-* ヘッダーが必須です。いずれかが欠けているリクエストには HTTP 401 が返され、プロセス環境の IMMYBOT_* へのフォールバックは行われません。ダイレクトモード（AUTH_MODE が未設定）の場合も、有効な X-Gateway-S2S ヘッダーが必要で、その後 IMMYBOT_* 環境変数が使用されます。ダイレクトモードでは X-ImmyBot-* ヘッダーを読み取りません。

シークレットなしのローカル HTTP は開発専用です。127.0.0.1 にバインドし、警告をログに記録します。ループバック以外の MCP_HTTP_HOST（イメージのデフォルトである 0.0.0.0 を含む）が設定されている場合、起動は終了します。このポートをループバック以外に公開しないでください。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

ツールリファレンス

ナビゲーションツール

ツール	説明
immybot_navigate	ドメインに移動
immybot_status	現在の状態を表示
immybot_back	メインメニューに戻る

コンピューターツール

ツール	説明
immybot_computers_list	コンピューターの一覧をフィルタリングして表示
immybot_computers_get	コンピューターの詳細を取得
immybot_computers_search	名前でコンピューターを検索
immybot_computers_inventory	ハードウェア／ソフトウェアのインベントリを取得
immybot_computers_create	コンピューターのレコードを作成
immybot_computers_deployments	コンピューターのデプロイ一覧を表示
immybot_computers_trigger_checkin	エージェントのチェックインを強制

ソフトウェアツール

ツール	説明
immybot_software_list_global	グローバルなソフトウェアパッケージを一覧表示します
immybot_software_list	すべてのソフトウェア（グローバル＋テナント）を一覧表示します
immybot_software_get	ソフトウェアの詳細を取得します
immybot_software_search	名前でソフトウェアを検索します
immybot_software_versions	ソフトウェアのバージョンを一覧表示します
immybot_software_latest_version	最新バージョンを取得します
immybot_software_categories	カテゴリを一覧表示します
immybot_software_publishers	発行元を一覧表示します
immybot_software_install	ソフトウェアのインストールを準備します
immybot_software_stats	インストール統計を取得します

エラー処理

サーバーは構造化されたエラーレスポンスを返します。

{
  "content": [{"type": "text", "text": "Error: Authentication failed"}],
  "isError": true
}

一般的なエラーの種類：

• 認証エラー - 認証情報が無効、またはトークンの有効期限が切れています
• 見つからないエラー - リソースが存在しません
• 検証エラー - パラメーターが不足しているか、無効です
• レート制限エラー - リクエストが多すぎます
• サーバーエラー - ImmyBot API 内部の問題です

開発

ソースからビルド

git clone https://github.com/WYRE-AI/immybot-mcp.git
cd immybot-mcp
npm install
npm run build
npm start

テスト

npm test

Docker ビルド

docker build -t immybot-mcp --secret id=npmrc,src=$HOME/.npmrc .

チェックイン済みの Compose ファイルはゲートウェイモードです。CONDUIT_S2S_SECRET が必要で、静的な IMMYBOT_* 認証情報は渡しません。

サポート

• ImmyBot API ドキュメント
• Microsoft Entra アプリ登録
• WYRE MCP ゲートウェイ

ライセンス

Apache-2.0。詳細は LICENSE を参照してください。