ImmyBot

io.github.WYRE-AI由 GitHub 帳號 WYRE-AI 發布v2.0.0更新於 Nov 21, 2026

MCP server for ImmyBot — Windows software deployment, maintenance, tenants, deployments.

概覽

AI 產生的概覽

把助理接入 ImmyBot,用於 Windows 端點管理:列出電腦、暫存軟體安裝、執行維護工作階段並查看工作。

可以做什麼
  • 列出、搜尋、檢視與建立電腦,查看硬體軟體清單與部署記錄,並強制代理回報
  • 瀏覽、搜尋與檢視軟體套件、版本、分類與發行者,並暫存安裝
  • 啟動並查詢維護工作階段,把期望狀態同步到裝置
  • 管理租用戶、PowerShell 指令碼與背景工作
  • 查看伺服器狀態與工具分組
適用情境
適合在 ImmyBot 管理 Windows 端點的 MSP 或 IT 管理員,希望助理不必切換到網頁主控台就能查詢裝置、規劃軟體推送,或觸發並追蹤維護工作階段。
執行需求
以本機程序(npm 套件或容器映像)透過 stdio 執行,或作為 HTTP 服務供閘道託管。直連模式需要來自 Microsoft Entra ID 應用程式註冊的 IMMYBOT_INSTANCE_SUBDOMAIN、IMMYBOT_TENANT_ID、IMMYBOT_CLIENT_ID 與 IMMYBOT_CLIENT_SECRET,且該應用程式需具備 ImmyBot API 權限。HTTP 模式另需 CONDUIT_S2S_SECRET 與 X-Gateway-S2S 簽章;閘道模式要求每個請求帶上四個 X-ImmyBot-* 標頭。
安裝前請注意
需要具備 ImmyBot API 權限的 Entra ID 用戶端密碼(IMMYBOT_CLIENT_SECRET),應盡量縮小應用程式權限範圍。工具會寫入正式端點:建立電腦、暫存軟體安裝與啟動維護工作階段都會改變裝置狀態,安裝須經維護工作階段同步後才真正生效。HTTP 模式必須使用真實的 CONDUIT_S2S_SECRET;不安全的開發繞過會關閉標頭驗證,只能綁定回送位址。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 ImmyBot,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

@wyre-ai/immybot-mcp

MCP server for ImmyBot - Windows endpoint management and software deployment automation.

Features

  • 🔐 OAuth 2.0 Authentication - Microsoft Entra ID client credentials
  • 🏢 Multi-tenant Support - Per-instance subdomain configuration
  • 🧭 Flat Tool List - Every tool is listed and callable immediately
  • 💻 Comprehensive Coverage - Computers, software, deployments, scripts, tenants, maintenance sessions, tasks
  • ⚡ Gateway Ready - Stateless per-request operation for WYRE MCP Gateway
  • 🚀 Docker Deployment - Container-ready with health checks
  • 📊 Structured Logging - Detailed operation tracking

Quick Start

Docker (Recommended)

The image listens on 0.0.0.0 inside the container and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass a real CONDUIT_S2S_SECRET. In gateway mode, ImmyBot credentials arrive on each request as headers; they are not read from the environment.

bash
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

Compose refuses to start when CONDUIT_S2S_SECRET is unset. The gateway service does not set IMMYBOT_* variables or env_file, so a project .env cannot inject static vendor credentials. It publishes 127.0.0.1:8080:8080:

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

Direct Installation

bash
npm install @wyre-ai/immybot-mcpnpx @wyre-ai/immybot-mcp

Tools

Every tool is listed by tools/list and callable immediately. There is no domain to enter first. The domains below are documentation groupings only.

Upgrading from 1.x? immybot_navigate and immybot_back are gone. Call the domain tools directly, for example immybot_computers_list. immybot_status still works and now lists the tool groups.

Available Domains

  • computers - Device and endpoint management
  • software - Application and package management
  • deployments - Software deployment configuration
  • scripts - PowerShell script execution and management
  • tenants - Client organization management
  • maintenance_sessions - Device maintenance and state reconciliation
  • tasks - Background operation monitoring

Authentication

ImmyBot uses OAuth 2.0 with Microsoft Entra ID:

Required Configuration

FieldDescriptionExample
instanceSubdomainImmyBot instance subdomainacmemsp
tenantIdMicrosoft Entra tenant ID12345678-1234-1234-1234-123456789abc
clientIdApplication (client) ID87654321-4321-4321-4321-cba987654321
clientSecretClient secret valueyour-client-secret

Setup Steps

  1. Register Enterprise Application in Microsoft Entra ID
  2. Grant ImmyBot API permissions to the application
  3. Create client secret for the application
  4. Configure application in ImmyBot settings

OAuth scope: api://{client_id}/.default

Usage Examples

1. Computers

javascript
// List computersawait callTool('immybot_computers_list', {   tenantId: 1,  isOnline: true });
// Get computer detailsawait callTool('immybot_computers_get', { computerId: 123 });

2. Software Management

javascript
// Search for softwareawait 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. Maintenance Sessions

javascript
// Start maintenance session (reconciles deployments)await callTool('immybot_maintenance_sessions_start', {  computerId: 123,  sessionType: 'Manual'});
// Check session statusawait callTool('immybot_maintenance_sessions_get', { sessionId: 789 });

Two-Step Deployment Model

⚠️ Important: ImmyBot uses a two-step deployment workflow:

  1. Configure desired state - Software installations create deployments
  2. Reconcile via maintenance session - Sessions apply the desired state
javascript
// Step 1: Stage software installationawait callTool('immybot_software_install', {  softwareId: 123,  computerIds: [456]});// ↑ This creates a deployment, does NOT install immediately
// Step 2: Reconcile stateawait callTool('immybot_maintenance_sessions_start', {  computerId: 456});// ↑ This runs the maintenance session to actually install software

Environment Variables

Copy .env.example and set the variables below.

Gateway Mode (Docker)

VariableDefaultDescription
AUTH_MODEdirectSet to gateway for WYRE MCP Gateway. Gateway mode requires the four x-immybot-* credential headers on each /mcp request and never falls back to IMMYBOT_*. The Docker image and Compose default to gateway.
MCP_TRANSPORTstdioTransport mode (http or stdio)
MCP_HTTP_PORT8080HTTP server port
MCP_HTTP_HOST0.0.0.0 when a real CONDUIT_S2S_SECRET is set and this is unset; 127.0.0.1 for the insecure-dev bypassBind address. A configured secret honors this value, including 0.0.0.0, so container deploys stay reachable. The image and Compose set 0.0.0.0.
CONDUIT_S2S_SECRET—Required for HTTP. HMAC secret checked against X-Gateway-S2S on /mcp. Generate with openssl rand -hex 32. If empty or a known placeholder, the HTTP server logs an error and exits non-zero. The value is never logged.
MCP_ALLOW_INSECURE_DEVunsetSet to exactly 1 to start HTTP without CONDUIT_S2S_SECRET. Logs a warning, does not enforce X-Gateway-S2S, and binds 127.0.0.1 only. A non-loopback MCP_HTTP_HOST refuses to start. A placeholder secret still refuses to start. Local development only.
LOG_LEVELinfoLogging level (debug, info, warn, error)

/health stays unauthenticated and does not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.

Direct Mode (CLI)

VariableRequiredDescription
IMMYBOT_INSTANCE_SUBDOMAIN✅ImmyBot instance subdomain
IMMYBOT_TENANT_ID✅Microsoft Entra tenant ID
IMMYBOT_CLIENT_ID✅Application client ID
IMMYBOT_CLIENT_SECRET✅Client secret

HTTP authentication

With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The check is verifyS2sHeader in src/s2s-verify.ts: the header value is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of the literal string t=<unix seconds> keyed with CONDUIT_S2S_SECRET (64 lowercase hex characters). The timestamp must be within 300 seconds of the server clock. A missing or invalid header is HTTP 401, before vendor credentials are read.

bash
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"}'

In AUTH_MODE=gateway, those four X-ImmyBot-* headers are required. A request missing any of them gets HTTP 401 and does not fall back to IMMYBOT_* in the process environment. Direct mode (AUTH_MODE unset) still requires a valid X-Gateway-S2S header, then uses the IMMYBOT_* environment variables. Direct mode does not read the X-ImmyBot-* headers.

Local HTTP without a secret is development-only. It binds 127.0.0.1 and logs a warning. A non-loopback MCP_HTTP_HOST (including the image default 0.0.0.0) makes startup exit. Do not publish that port off loopback.

bash
MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

Tools Reference

Status Tool

ToolDescription
immybot_statusShow the tool groups

Computers Tools

ToolDescription
immybot_computers_listList computers with filtering
immybot_computers_getGet computer details
immybot_computers_searchSearch computers by name
immybot_computers_inventoryGet hardware/software inventory
immybot_computers_createCreate computer record
immybot_computers_deploymentsList computer deployments
immybot_computers_trigger_checkinForce agent check-in

Software Tools

ToolDescription
immybot_software_list_globalList global software packages
immybot_software_listList all software (global + tenant)
immybot_software_getGet software details
immybot_software_searchSearch software by name
immybot_software_versionsList software versions
immybot_software_latest_versionGet latest version
immybot_software_categoriesList categories
immybot_software_publishersList publishers
immybot_software_installStage software installation
immybot_software_statsGet installation statistics

Error Handling

The server provides structured error responses:

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

Common error types:

  • Authentication errors - Invalid credentials or expired tokens
  • Not found errors - Resource doesn't exist
  • Validation errors - Missing or invalid parameters
  • Rate limit errors - Too many requests
  • Server errors - Internal ImmyBot API issues

Development

Build from Source

bash
git clone https://github.com/WYRE-AI/immybot-mcp.gitcd immybot-mcpnpm installnpm run buildnpm start

Testing

bash
npm test

Docker Build

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

The checked-in Compose file is gateway mode. It requires CONDUIT_S2S_SECRET and does not pass static IMMYBOT_* credentials.

Support

License

Apache-2.0 - see LICENSE for details.

來源:README.md,提交 dc8d0f0

工具

0
SourceWeft 曾在隔離沙箱中以無憑證方式啟動該軟體包一次,以列出其工具,但未能完成:該軟體包類型無法在沙箱中執行。

版本歷史

3
  1. v2.0.0最新Nov 20, 2026
  2. v1.2.14Oct 14, 2026
  3. v1.2.13Sep 16, 2026

評分

已滿足適用檢查項的 40%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分

    請在儲存庫或註冊中心條目中宣告授權條款。