{
  "markdown": "# @wyre-ai/immybot-mcp\n\nMCP server for ImmyBot - Windows endpoint management and software deployment automation.\n\n## Features\n\n- 🔐 **OAuth 2.0 Authentication** - Microsoft Entra ID client credentials\n- 🏢 **Multi-tenant Support** - Per-instance subdomain configuration  \n- 🧭 **Decision Tree Navigation** - Organized tool discovery by domain\n- 💻 **Comprehensive Coverage** - Computers, software, deployments, scripts, tenants, maintenance sessions, tasks\n- ⚡ **Gateway Ready** - Stateless per-request operation for WYRE MCP Gateway\n- 🚀 **Docker Deployment** - Container-ready with health checks\n- 📊 **Structured Logging** - Detailed operation tracking\n\n## Quick Start\n\n### Docker (Recommended)\n\n```bash\ndocker run -d \\\n  --name immybot-mcp \\\n  -p 8080:8080 \\\n  -e AUTH_MODE=gateway \\\n  -e MCP_HTTP_PORT=8080 \\\n  -e LOG_LEVEL=info \\\n  ghcr.io/wyre-ai/immybot-mcp:latest\n```\n\n### Direct Installation\n\n```bash\nnpm install @wyre-ai/immybot-mcp\nnpx @wyre-ai/immybot-mcp\n```\n\n## Navigation\n\nThe server uses decision-tree navigation to organize tools by domain:\n\n1. **Start** → `immybot_navigate` → Choose domain\n2. **Domain tools** → Domain-specific operations  \n3. **Return** → `immybot_back` → Main navigation\n\n### Available Domains\n\n- **computers** - Device and endpoint management\n- **software** - Application and package management  \n- **deployments** - Software deployment configuration\n- **scripts** - PowerShell script execution and management\n- **tenants** - Client organization management\n- **maintenance_sessions** - Device maintenance and state reconciliation\n- **tasks** - Background operation monitoring\n\n## Authentication\n\nImmyBot uses OAuth 2.0 with Microsoft Entra ID:\n\n### Required Configuration\n\n| Field | Description | Example |\n|-------|-------------|---------|\n| `instanceSubdomain` | ImmyBot instance subdomain | `acmemsp` |\n| `tenantId` | Microsoft Entra tenant ID | `12345678-1234-1234-1234-123456789abc` |\n| `clientId` | Application (client) ID | `87654321-4321-4321-4321-cba987654321` |\n| `clientSecret` | Client secret value | `your-client-secret` |\n\n### Setup Steps\n\n1. **Register Enterprise Application** in Microsoft Entra ID\n2. **Grant ImmyBot API permissions** to the application\n3. **Create client secret** for the application  \n4. **Configure application** in ImmyBot settings\n\nOAuth scope: `api://{client_id}/.default`\n\n## Usage Examples\n\n### 1. Navigate to Computers Domain\n\n```javascript\n// Start navigation\nawait callTool('immybot_navigate', { domain: 'computers' });\n\n// List computers\nawait callTool('immybot_computers_list', { \n  tenantId: 1,\n  isOnline: true \n});\n\n// Get computer details\nawait callTool('immybot_computers_get', { computerId: 123 });\n```\n\n### 2. Software Management\n\n```javascript\n// Navigate to software domain\nawait callTool('immybot_navigate', { domain: 'software' });\n\n// Search for software\nawait callTool('immybot_software_search', { query: 'Chrome' });\n\n// Install software (stages for maintenance session)\nawait callTool('immybot_software_install', {\n  softwareId: 456,\n  computerIds: [123, 124, 125],\n  autoUpdate: true\n});\n```\n\n### 3. Maintenance Sessions\n\n```javascript\n// Navigate to maintenance sessions\nawait callTool('immybot_navigate', { domain: 'maintenance_sessions' });\n\n// Start maintenance session (reconciles deployments)\nawait callTool('immybot_maintenance_sessions_start', {\n  computerId: 123,\n  sessionType: 'Manual'\n});\n\n// Check session status\nawait callTool('immybot_maintenance_sessions_get', { sessionId: 789 });\n```\n\n## Two-Step Deployment Model\n\n⚠️ **Important**: ImmyBot uses a two-step deployment workflow:\n\n1. **Configure desired state** - Software installations create deployments\n2. **Reconcile via maintenance session** - Sessions apply the desired state\n\n```javascript\n// Step 1: Stage software installation\nawait callTool('immybot_software_install', {\n  softwareId: 123,\n  computerIds: [456]\n});\n// ↑ This creates a deployment, does NOT install immediately\n\n// Step 2: Reconcile state\nawait callTool('immybot_maintenance_sessions_start', {\n  computerId: 456\n});\n// ↑ This runs the maintenance session to actually install software\n```\n\n## Environment Variables\n\n### Gateway Mode (Docker)\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `AUTH_MODE` | `direct` | Set to `gateway` for WYRE MCP Gateway |\n| `MCP_TRANSPORT` | `stdio` | Transport mode (`http` or `stdio`) |\n| `MCP_HTTP_PORT` | `8080` | HTTP server port |\n| `LOG_LEVEL` | `info` | Logging level (`debug`, `info`, `warn`, `error`) |\n\n### Direct Mode (CLI)\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `IMMYBOT_INSTANCE_SUBDOMAIN` | ✅ | ImmyBot instance subdomain |\n| `IMMYBOT_TENANT_ID` | ✅ | Microsoft Entra tenant ID |\n| `IMMYBOT_CLIENT_ID` | ✅ | Application client ID |\n| `IMMYBOT_CLIENT_SECRET` | ✅ | Client secret |\n\n## Tools Reference\n\n### Navigation Tools\n\n| Tool | Description |\n|------|-------------|\n| `immybot_navigate` | Navigate to domain |\n| `immybot_status` | Show current state |\n| `immybot_back` | Return to main menu |\n\n### Computers Tools\n\n| Tool | Description |\n|------|-------------|\n| `immybot_computers_list` | List computers with filtering |\n| `immybot_computers_get` | Get computer details |\n| `immybot_computers_search` | Search computers by name |\n| `immybot_computers_inventory` | Get hardware/software inventory |\n| `immybot_computers_create` | Create computer record |\n| `immybot_computers_deployments` | List computer deployments |\n| `immybot_computers_trigger_checkin` | Force agent check-in |\n\n### Software Tools\n\n| Tool | Description |\n|------|-------------|\n| `immybot_software_list_global` | List global software packages |\n| `immybot_software_list` | List all software (global + tenant) |\n| `immybot_software_get` | Get software details |\n| `immybot_software_search` | Search software by name |\n| `immybot_software_versions` | List software versions |\n| `immybot_software_latest_version` | Get latest version |\n| `immybot_software_categories` | List categories |\n| `immybot_software_publishers` | List publishers |\n| `immybot_software_install` | Stage software installation |\n| `immybot_software_stats` | Get installation statistics |\n\n## Error Handling\n\nThe server provides structured error responses:\n\n```json\n{\n  \"content\": [{\"type\": \"text\", \"text\": \"Error: Authentication failed\"}],\n  \"isError\": true\n}\n```\n\nCommon error types:\n- **Authentication errors** - Invalid credentials or expired tokens\n- **Not found errors** - Resource doesn't exist  \n- **Validation errors** - Missing or invalid parameters\n- **Rate limit errors** - Too many requests\n- **Server errors** - Internal ImmyBot API issues\n\n## Development\n\n### Build from Source\n\n```bash\ngit clone https://github.com/WYRE-AI/immybot-mcp.git\ncd immybot-mcp\nnpm install\nnpm run build\nnpm start\n```\n\n### Testing\n\n```bash\nnpm test\n```\n\n### Docker Build\n\n```bash\ndocker build -t immybot-mcp --build-arg NODE_AUTH_TOKEN=$GITHUB_TOKEN .\n```\n\n## Support\n\n- [ImmyBot API Documentation](https://docs.immy.bot/reference/api-documentation/)\n- [Microsoft Entra App Registration](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)\n- [WYRE MCP Gateway](https://github.com/wyre-technology/mcp-gateway)\n\n## License\n\nApache-2.0 - see [LICENSE](LICENSE) for details. ",
  "bytes": 7302,
  "sha": "09baa04e9e52a53196224b44a1f1af669996f5cdabd3ba9c521bf23e7ff949fa",
  "repo_slug": "wyre-ai/immybot-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_wyre_ai_immybot_mcp_15c2911b/readme"
}