io.github.wyre-technology/immybot-mcp

Official

by wyre-technology · TypeScript

ImmyBot

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

Manage Windows software deployment, maintenance, and tenant operations.

Topics

immybotmcpmspwindows

README.md7 KBView on GitHub

@wyre-technology/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
🧭 Decision Tree Navigation - Organized tool discovery by domain
💻 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)

bash

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

Direct Installation

bash

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

The server uses decision-tree navigation to organize tools by domain:

Start → immybot_navigate → Choose domain
Domain tools → Domain-specific operations
Return → immybot_back → Main navigation

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

Field	Description	Example
`instanceSubdomain`	ImmyBot instance subdomain	`acmemsp`
`tenantId`	Microsoft Entra tenant ID	`12345678-1234-1234-1234-123456789abc`
`clientId`	Application (client) ID	`87654321-4321-4321-4321-cba987654321`
`clientSecret`	Client secret value	`your-client-secret`

Setup Steps

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

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

Usage Examples

1. Navigate to Computers Domain

javascript

// 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. Software Management

javascript

// 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. Maintenance Sessions

javascript

// 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 });

Two-Step Deployment Model

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

Configure desired state - Software installations create deployments
Reconcile via maintenance session - Sessions apply the desired state

javascript

// 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

Environment Variables

Gateway Mode (Docker)

Variable	Default	Description
`AUTH_MODE`	`direct`	Set to `gateway` for WYRE MCP Gateway
`MCP_TRANSPORT`	`stdio`	Transport mode (`http` or `stdio`)
`MCP_HTTP_PORT`	`8080`	HTTP server port
`LOG_LEVEL`	`info`	Logging level (`debug`, `info`, `warn`, `error`)

Direct Mode (CLI)

Variable	Required	Description
`IMMYBOT_INSTANCE_SUBDOMAIN`	✅	ImmyBot instance subdomain
`IMMYBOT_TENANT_ID`	✅	Microsoft Entra tenant ID
`IMMYBOT_CLIENT_ID`	✅	Application client ID
`IMMYBOT_CLIENT_SECRET`	✅	Client secret

Tools Reference

Tool	Description
`immybot_navigate`	Navigate to domain
`immybot_status`	Show current state
`immybot_back`	Return to main menu

Computers Tools

Tool	Description
`immybot_computers_list`	List computers with filtering
`immybot_computers_get`	Get computer details
`immybot_computers_search`	Search computers by name
`immybot_computers_inventory`	Get hardware/software inventory
`immybot_computers_create`	Create computer record
`immybot_computers_deployments`	List computer deployments
`immybot_computers_trigger_checkin`	Force agent check-in

Software Tools

Tool	Description
`immybot_software_list_global`	List global software packages
`immybot_software_list`	List all software (global + tenant)
`immybot_software_get`	Get software details
`immybot_software_search`	Search software by name
`immybot_software_versions`	List software versions
`immybot_software_latest_version`	Get latest version
`immybot_software_categories`	List categories
`immybot_software_publishers`	List publishers
`immybot_software_install`	Stage software installation
`immybot_software_stats`	Get 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-technology/immybot-mcp.git
cd immybot-mcp
npm install
npm run build
npm start

Testing

bash

npm test

Docker Build

bash

docker build -t immybot-mcp --build-arg NODE_AUTH_TOKEN=$GITHUB_TOKEN .

Support

License

Apache-2.0 - see LICENSE for details.

Install

Configuration

Environment variables

IMMYBOT_TENANT_IDrequired

ImmyBot Azure AD tenant ID

IMMYBOT_CLIENT_IDrequired

ImmyBot OAuth client ID

IMMYBOT_CLIENT_SECRETrequiredsecret

ImmyBot OAuth client secret

IMMYBOT_INSTANCE_SUBDOMAINrequired

ImmyBot instance subdomain (e.g. 'acme' for acme.immy.bot)

MCP_TRANSPORTdefault stdio

Transport mode for the server. Set to 'stdio' for local CLI use; the image defaults to 'http' for gateway hosting.

AUTH_MODEdefault env

Credential source: 'env' reads vars locally, 'gateway' expects header injection from the WYRE MCP Gateway.

LOG_LEVELdefault info

Log verbosity: debug, info, warn, error

claude_desktop_config.json

{
  "mcpServers": {
    "immybot-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/wyre-technology/immybot-mcp:v1.2.3"
      ],
      "env": {
        "IMMYBOT_TENANT_ID": "<YOUR_IMMYBOT_TENANT_ID>",
        "IMMYBOT_CLIENT_ID": "<YOUR_IMMYBOT_CLIENT_ID>",
        "IMMYBOT_CLIENT_SECRET": "<YOUR_IMMYBOT_CLIENT_SECRET>",
        "IMMYBOT_INSTANCE_SUBDOMAIN": "<YOUR_IMMYBOT_INSTANCE_SUBDOMAIN>",
        "MCP_TRANSPORT": "stdio",
        "AUTH_MODE": "env",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Topics

@wyre-technology/immybot-mcp

Features

Quick Start

Docker (Recommended)

Direct Installation

Navigation

Available Domains

Authentication

Required Configuration

Setup Steps

Usage Examples

1. Navigate to Computers Domain

2. Software Management

3. Maintenance Sessions

Two-Step Deployment Model

Environment Variables

Gateway Mode (Docker)

Direct Mode (CLI)

Tools Reference

Navigation Tools

Computers Tools

Software Tools

Error Handling

Development

Build from Source

Testing

Docker Build

Support

License

Install

Configuration