Kaseya VSA

Kaseya VSA MCP 服务

用于 Kaseya VSA RMM API 的模型上下文协议（MCP）服务。 向 AI 助手提供受管终端、软件 / 硬件清单、补丁状态、Agent 过程、警报、Service Desk 工单、组织和机器组。

工具

工具	说明
kaseya_vsa_list_agents	列出受管终端（Agent）。可选 $filter。
kaseya_vsa_get_agent	按 ID 获取 Agent 详情（在 MCP Apps 宿主中以交互式卡片呈现）。
kaseya_vsa_get_software_inventory	获取 Agent 已安装的软件。
kaseya_vsa_get_hardware_inventory	获取 Agent 的硬件审计信息。
kaseya_vsa_get_patch_status	获取 Agent 待安装和已安装的补丁。
kaseya_vsa_deploy_patches_now	强制在 Agent 上部署补丁（具有破坏性——需要确认）。
kaseya_vsa_list_procedures	列出可运行的 Agent 过程。
kaseya_vsa_run_procedure	在 Agent 上执行过程（具有破坏性——需要确认）。
kaseya_vsa_list_alarms	列出未关闭的警报（可选状态筛选；缺少时会询问日期范围）。
kaseya_vsa_list_tickets	列出 Service Desk 工单（若未启用 SD 模块，则返回友好提示）。
kaseya_vsa_list_organizations	列出租户组织。
kaseya_vsa_list_machine_groups	列出机器组层级结构。

当用户遗漏必需筛选条件或执行具有破坏性的操作时，服务会使用 MCP elicitation 提示用户选择或确认。

交互式设备卡片（MCP Apps）

在 MCP Apps 宿主（Claude Desktop/web）中，kaseya_vsa_get_agent 会呈现为只读交互式设备卡片，显示终端名称、在线状态、组织、机器组、操作系统、IP 地址和上次签入时间。卡片默认采用中性样式，可通过 window.__BRAND__ 注入或 MCP_BRAND_* 环境变量（MCP_BRAND_NAME、MCP_BRAND_LOGO_URL、MCP_BRAND_PRIMARY_COLOR、MCP_BRAND_ACCENT_COLOR、MCP_BRAND_BG、MCP_BRAND_TEXT）进行品牌定制，这些设置会在服务启动时应用。其他宿主中的纯 JSON 行为保持不变。编辑 ui/ 后，使用 npm run build:ui 重新生成嵌入式 bundle。

配置

复制 .env.example，并设置以下变量。

变量	必需	描述
KASEYA_VSA_TENANT_URL	stdio 和 AUTH_MODE=env 模式下必需	完整的基础 URL，包含 /api/v1.0。Compose 网关服务不会加载此变量。
KASEYA_VSA_USERNAME	stdio 和 AUTH_MODE=env 模式下必需	本地身份验证用户名（需配合密码）。Compose 网关服务不会加载此变量。
KASEYA_VSA_PASSWORD	stdio 和 AUTH_MODE=env 模式下必需	本地身份验证密码（机密）。Compose 网关服务不会加载此变量。
KASEYA_VSA_K1_TOKEN	stdio 和 AUTH_MODE=env 模式下必需	Kaseya One SSO 令牌（可替代用户名和密码）。Compose 网关服务不会加载此变量。
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	gateway（Docker 镜像和 Compose 的默认值）或 env（未设置时的代码默认值）。网关模式要求每个 /mcp 请求都包含 X-Kaseya-VSA-* 标头，且绝不会回退到 KASEYA_VSA_*。只有在 S2S 身份验证成功后，env 模式才会使用这些变量。
CONDUIT_S2S_SECRET	HTTP 模式下必需	服务间密钥。使用 openssl rand -hex 32 生成。如果该变量为空或为已知占位值（changeme、your-s2s-secret、secret、placeholder、未解析的 ${...} 值及类似的公开示例），HTTP 服务器会记录错误并以非零状态码退出。未设置此变量时，Compose 不会启动。切勿提交真实值。该值绝不会被记录。
MCP_ALLOW_INSECURE_DEV	否	仅限本地开发时，精确设置为 1，以便在未设置 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告，不强制要求 X-Gateway-S2S，并强制将监听地址设为 127.0.0.1，即使 MCP_HTTP_HOST 设置为范围更广的地址。仍会拒绝已知占位密钥。
MCP_HTTP_HOST	否	MCP_TRANSPORT=http 时的绑定地址。未设置时默认为 127.0.0.1。设置了 CONDUIT_S2S_SECRET 时会遵循此值。容器镜像将其设置为 0.0.0.0。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。

stdio 和 AUTH_MODE=env 模式下，用户名和密码组合或 KASEYA_VSA_K1_TOKEN 必须提供其一。

/health 无需身份验证，也不会读取凭据。stdio 传输不使用 CONDUIT_S2S_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。

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-Kaseya-VSA-Tenant-Url，以及以下其中一项：（X-Kaseya-VSA-Username 和 X-Kaseya-VSA-Password）或 X-Kaseya-VSA-K1-Token。这些标头是该请求唯一的凭据来源。请求缺少这些标头时会返回 401，且不会回退到进程环境中的 KASEYA_VSA_*。

每个通过验证的请求都会创建一个全新的服务实例，凭据彼此隔离，不会造成跨租户的 process.env 污染。

本地开发

npm install
npm run build
KASEYA_VSA_TENANT_URL=https://vsa.example.com/api/v1.0 \
  KASEYA_VSA_USERNAME=... \
  KASEYA_VSA_PASSWORD=... \
  npm start

未设置 CONDUIT_S2S_SECRET 时，HTTP 会拒绝启动：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http npm start
curl http://127.0.0.1:8080/health

不设置密钥启动本地 HTTP 仅适用于开发环境。它只会绑定到 127.0.0.1，并记录警告。非环回地址的 MCP_HTTP_HOST 会被忽略，并记录此覆盖操作：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

Docker

镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），默认使用 AUTH_MODE=gateway。将端口发布到环回地址，并传入 S2S 密钥。在网关模式下，Kaseya 凭据会作为请求头随每个请求传入，不会从环境变量中读取。

docker build -t kaseya-vsa-mcp .
docker run --rm \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  kaseya-vsa-mcp

未设置 CONDUIT_S2S_SECRET 时，Compose 会拒绝启动；它会设置 AUTH_MODE=gateway，不会注入静态 KASEYA_VSA_* 凭据，并会发布 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，然后使用 KASEYA_VSA_*：

docker run --rm \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e KASEYA_VSA_TENANT_URL=https://vsa.example.com/api/v1.0 \
  -e KASEYA_VSA_USERNAME=... \
  -e KASEYA_VSA_PASSWORD=... \
  -p 127.0.0.1:8080:8080 \
  kaseya-vsa-mcp

许可证

Apache-2.0