{"id":50735382,"url":"https://github.com/wyre-technology/immybot-mcp","last_synced_at":"2026-06-10T13:01:21.142Z","repository":{"id":356385464,"uuid":"1224189447","full_name":"wyre-technology/immybot-mcp","owner":"wyre-technology","description":"MCP server for ImmyBot — Windows software deployment \u0026 maintenance automation","archived":false,"fork":false,"pushed_at":"2026-05-29T19:02:04.000Z","size":184,"stargazers_count":0,"open_issues_count":12,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T20:22:01.237Z","etag":null,"topics":["immybot","mcp","msp","windows"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wyre-technology.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-29T03:30:33.000Z","updated_at":"2026-05-29T19:00:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wyre-technology/immybot-mcp","commit_stats":null,"previous_names":["wyre-technology/immybot-mcp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/wyre-technology/immybot-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyre-technology%2Fimmybot-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyre-technology%2Fimmybot-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyre-technology%2Fimmybot-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyre-technology%2Fimmybot-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wyre-technology","download_url":"https://codeload.github.com/wyre-technology/immybot-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyre-technology%2Fimmybot-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34153483,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["immybot","mcp","msp","windows"],"created_at":"2026-06-10T13:01:20.230Z","updated_at":"2026-06-10T13:01:21.136Z","avatar_url":"https://github.com/wyre-technology.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @wyre-technology/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-technology/immybot-mcp:latest\n```\n\n### Direct Installation\n\n```bash\nnpm install @wyre-technology/immybot-mcp\nnpx @wyre-technology/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-technology/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. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwyre-technology%2Fimmybot-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwyre-technology%2Fimmybot-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwyre-technology%2Fimmybot-mcp/lists"}