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. 导航到计算机领域

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

两步部署模型

⚠️ 重要：ImmyBot 使用两步部署工作流：

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 请求都携带四个 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	未设置	精确设为 1，即可在未设置 CONDUIT_S2S_SECRET 的情况下启动 HTTP。系统会记录警告、不强制校验 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（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 模式下，必须提供这四个 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	强制 Agent 签到

软件工具

工具	描述
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。