VMware VDI (Horizon)

VMware VDI（Horizon）

面向 VMware / Omnissa Horizon VDI 的 AI 驱动智能运维——通过 Horizon 8 Connection Server REST API 管理桌面池、RDS 场、已发布的应用、用户会话、桌面计算机、授权、即时克隆映像，以及 Horizon 事件、运行状况和统计信息。提供 MCP 服务（供 AI Agent 使用）和 CLI（供帮助台和脚本使用）两种形式。属于 VMware 技能系列。

免责声明：这是由社区维护的开源项目，与 VMware, Inc.、Broadcom Inc. 或 Omnissa, LLC. 无关联，未获得其认可或赞助。“VMware”“Horizon”和“Omnissa”是各自所有者的商标。源代码采用 MIT 许可证，公开可审查。

状态：v1.0.0（测试版）。 REST 端点已根据官方 Horizon Server API 验证； GET 响应字段投影采用防御性处理，仍待通过实时 Connection Server 验证 （字段名称不匹配会导致结果为空，不会崩溃——参见测试版说明）。

升级到 2.0

2.0 将全部 27 个 MCP 工具重命名，使每个名称都以动词开头（例如，ad_user_search → search_ad_users、app_pool_list → list_app_pools、entitlement_add → add_entitlement）。完整的新旧名称对照表见 RELEASE_NOTES.md。其他内容均无变化：工具、参数、安全防护机制和 CLI 命令都相同。如果 Agent 提示词、脚本或 ~/.vmware/rules.yaml 中指定了工具名称，请更新；不过，使用旧名称编写的拒绝规则在 vmware-policy ≥ 1.18 中仍然有效（vmware-audit policy 会列出因重命名而扩大适用范围的规则），而 vmware-pilot ≥ 1.13 会转换已保存工作流中的旧名称。 如果低于 2.0 的安装与当前版本共用该 rules.yaml，也请将其升级到 vmware-policy ≥ 1.18.2：该版本会针对新旧名称逐一匹配每条规则，因此同一个文件可供两者使用。

为什么选择 vmware-vdi

其他 VMware 系列技能都止步于 vСenter VM。Horizon 桌面池运行在这些 VM 之上——因此，vmware-aiops 可以重置底层 VM，却无法查看用户会话、将用户注销、禁用桌面池或推送黄金映像。vmware-vdi 正好填补了 VDI 日常运营中的这一空白——解决“谁卡在故障桌面上了”“将这个用户注销，以便解锁其配置文件”“为什么这个池无法置备”“今晚将修补后的映像推送到 Finance”等问题，并采用该系列的治理式运维机制：每项写入操作都会经过审计、预览影响范围，并由 Horizon 账户自身的 RBAC 角色授权。

功能 — 27 个 MCP 工具（16 个读取 / 11 个写入）

类别	工具
监控	健康摘要 · 会话列表/详情 · 机器列表/详情 · 事件列表
统计	会话并发统计 · 各池利用率
管理	池列表/详情 · 场列表 · 应用池列表 · 权限列表 · 映像列表 · AD 搜索 · 启用/禁用池 · 添加/移除权限
运维操作	注销/断开会话 · 发送会话消息 · 重置/维护/移除机器
任务	任务状态 · 推送映像 · 取消任务

读取操作严格来说不会造成破坏。写入操作会预览影响范围，在 CLI 中进行二次确认，并记录到审计日志 ~/.vmware/audit.db。push_desktop_pool_image 会重建池中的每台桌面——这是该工具集单次调用中影响范围最大的操作。其预览会在确认前显示受影响桌面数和会话数，以及 occupancy：若这些计数可信，则为 determined；若存在无法归属到任何池或场的会话，则为 unknown。若 occupancy 为 unknown，系统会拒绝确认，而不是报告未经核实的零；如需覆盖，必须使用 --acknowledge-unknown-occupancy，且此操作会记录在审计行中。未指定桌面池的机器也会导致桌面数成为下限（“至少 N 台”）；此时系统会拒绝确认，且没有覆盖选项。

在 MCP 中，每个受控写入操作都接受 confirm（默认为 false）。未提供该参数的调用会返回 blast_radius——包括对象身份、计数、最多 20 个标识符、blockers 和 unmeasured——且不会更改任何内容；执行操作的响应中也会包含相同字典。Agent 应向用户展示该信息，并仅在用户同意后传入 confirm=true。如果影响范围所依赖的信息无法读取——例如机器状态、会话用户、任务类型或状态、池的启用标志、池的当前权限——则会拒绝 confirm=true，并在消息中指出需要检查的内容。

快速开始

uv tool install vmware-vdi
vmware-vdi init      # friendly wizard: connect to a Connection Server + discover your pools
vmware-vdi doctor    # verify config / credentials / connectivity
vmware-vdi health    # one-glance VDI health

vmware-vdi init 会提示输入 Connection Server 主机、管理员用户名、AD 域和密码；随后写入 ~/.vmware-vdi/config.yaml 和权限为 0600 的 .env 文件（密码经过混淆处理）；测试登录；成功后，发现你的池、机器和会话，并提供可尝试的后续命令。

工作流示例

帮助台 — 用户的桌面卡住了

vmware-vdi session list --user alice
vmware-vdi machine list --state AGENT_UNREACHABLE
vmware-vdi session logoff --user alice --dry-run   # preview which sessions
vmware-vdi session logoff --user alice             # double-confirm, then logs off + audits

补丁夜 — 推送新的黄金映像

vmware-vdi image list
vmware-vdi pool push-image --id pool-fin --dry-run  # BLAST RADIUS: N desktops, M logged-in users
vmware-vdi pool push-image --id pool-fin            # double-confirm; returns a task
vmware-vdi task status --pool pool-fin              # track progress

MCP 服务

{
  "mcpServers": {
    "vmware-vdi": {
      "command": "vmware-vdi",
      "args": ["mcp"],
      "env": { "VMWARE_VDI_CONFIG": "~/.vmware-vdi/config.yaml" }
    }
  }
}

使用已安装的 vmware-vdi mcp 控制台脚本（而非 uvx），可避免每次启动都重新解析 PyPI 依赖——这对于企业 TLS 代理环境尤为重要。

支持的版本

• VMware Horizon 8.x（主要版本）——Connection Server REST API /rest/v1。
• 最新 Omnissa Horizon（2406 / 2412+）——相同的 /rest/v1 系列。

安全性

• 授权 = Horizon RBAC。 此工具不会限制读取与写入操作；将目标指向具有只读 Horizon 管理员角色的账号后，所有写入操作都会在 Connection Server 处被拒绝，无法绕过。
• 凭据仅存放在 ~/.vmware-vdi/.env 中（权限为 0600，静态存储时以 b64: 混淆）；配置文件仅包含主机/用户名/域。若要实现真正的机密保护，请从密钥管理器注入 VMWARE_VDI_<TARGET>_PASSWORD。
• 默认启用 TLS 验证。所有来自 Connection Server 的文本都会经过 sanitize() 处理，以防范提示词注入。
• 不会向外发起调用，唯一例外是连接到已配置的 Connection Server——没有 Webhook，也没有遥测数据。

请参阅 SECURITY.md 和 skills/vmware-vdi/references/setup-guide.md。

Beta 说明

REST 端点已根据官方 Horizon Server API 操作索引验证。GET 响应的 字段名称（以及少数写入请求体）采用防御式处理（使用带回退值的 .get()），且尚待通过实时 Connection Server 验证。字段名称不匹配时，列表会读取为空，而不会导致崩溃。 首次在真实 Horizon 环境中使用时，应运行 vmware-vdi init 并确认会话／虚拟机／池的投影；如果某个投影 看起来为空，请附上原始 *_get 输出提交问题。质量：32 个回归测试，ruff 检查通过，bandit 结果为 0，工具端点已固定为经过验证的规范。

配套技能

这是 VMware 技能系列的一部分——按需安装所需模块：

• vmware-aiops — 为桌面提供支持的 vCenter VM（电源、快照、克隆、迁移）
• vmware-monitor — 只读 vSphere 监控
• vmware-nsx-security — 桌面网络微分段
• vmware-aria · vmware-nsx · vmware-storage · vmware-vks · vmware-avi · vmware-harden

远程访问（HTTPS）和限制工具

默认情况下，vmware-vdi mcp 通过 stdio 与一个本地客户端通信，并提供所有工具。以下两个选项可以改变这一点 （vmware-policy ≥ 1.21.0）。

通过 HTTPS 提供服务，以便其他机器上的客户端连接。每个调用方都需要一个 bearer token：

vmware-audit token create alice          # prints the token once; give it to alice
vmware-audit token list                  # names only
vmware-audit token revoke alice          # refused from its next request, no restart
vmware-vdi mcp --transport https --host 0.0.0.0 --port 8443 \
    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
    --public-name mcp.example.com

连接客户端（此处以 Claude Code 为例；任何支持 streamable HTTP 和自定义请求头的 MCP 客户端均可）：

claude mcp add --transport http vmware-vdi https://mcp.example.com:8443/mcp \
    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"

{
  "mcpServers": {
    "vmware-vdi": {
      "type": "http",
      "url": "https://mcp.example.com:8443/mcp",
      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
    }
  }
}

• 如果没有 token，服务不会启动；它会拒绝超出 --public-name 范围的 Host/Origin 值，并在绑定前检查未认证请求是否会收到 401。请使用客户端信任的、适用于这些名称的证书。
• 如果位于同一台机器上、负责终止 TLS 的反向代理后面，请使用 --transport http --host 127.0.0.1 --public-name mcp.example.com，并透传 Authorization 请求头。
• 如果位于另一台机器上的负载均衡器或网关后面，请保留 --transport https（自签名证书也可以），在 --public-name 中列出负载均衡器发送的 Host 主机名，并让其转发 Authorization。其健康检查可使用 GET /healthz，此请求无需 token，只会返回 {"status": "ok"}（vmware-policy ≥ 1.23.0）。
• 每个请求都发送 traceparent 或 X-Request-ID，即可将其记录在审计行中；随后运行 vmware-audit log --correlation-id ID，即可查找同一平台请求背后的调用。
• 审计日志会将每个调用方记录为 token:<name>。调用会并行执行，无论是否指定目标：每个目标最多保留 VMWARE_MCP_POOL_SIZE 个会话（默认为 2），每个会话都是在目标上的一次登录。如果调用发现所有会话都在使用中，最多会等待 300 s。
• 任何能够访问此端点的人都将使用此服务的账户进行操作。 Token 用于识别调用方，不会授予任何平台权限。每个权限级别都应运行一个独立端点。
• 一个端点供多个人员或角色使用： 运行一次 vmware-audit roles enable，然后为每个 token 分配一个角色（vmware-audit token create NAME --role reader，或在 roles.yaml 中设置包含工具和目标的角色；vmware-policy ≥ 1.24.0）。角色会限制 token 可在此端点调用的工具；它无法授予超出该账户权限的权限。请参阅 vmware-policy 的 README 中的“Roles for network callers”。

仅提供只读工具，以及你选择的写入工具：

vmware-vdi mcp --expose read --allow-write add_entitlement
# or: VMWARE_VDI_MCP_EXPOSE=read VMWARE_VDI_MCP_ALLOW_WRITE=add_entitlement vmware-vdi mcp

未提供的工具不会出现在客户端的工具列表中。值无效或包含未知的写入工具都会导致服务停止（exit 2）。这只会限制提供给客户端的工具；它不是授权机制，因此账户本身应遵循最小权限原则。

详情：skills/vmware-vdi/references/setup-guide.md（“Serving MCP over HTTPS”、“Limiting which tools are offered”）。

许可证

MIT — 参见 LICENSE。