webroot-mcp

用于 Webroot（OpenText 端点安全 / SecureAnywhere，通过 Global Site Manager "GSM" 控制台管理）的 MCP 服务器。将 Webroot Unity API 的 GSM 控制台站点、端点、分组、策略、威胁历史、实时 Agent 状态以及 DNS Protection（DNSP）方法以 MCP 工具的形式暴露出来。

概述

• 无状态 HTTP 服务。不会持久化任何凭据——每个请求都通过请求头自带凭据，仅在该单个请求的生命周期内使用。

• 支持并发请求；每个请求的凭据隔离通过 Python contextvars 实现，而非使用全局/共享客户端实例。

• 入口点：POST /mcp（MCP 协议）和 GET /health（健康检查）。

• 默认端口：8080（可通过 MCP_HTTP_PORT 配置）。

Related MCP server: kaseya-vsa-mcp

身份验证

Webroot Unity API 实现标准 OAuth2，使用密码授权（password grant）：

POST https://unityapi.webrootcloudav.com/auth/token
  grant_type=password&username=...&password=...&client_id=...&client_secret=...
  &scope=Console.GSM SkyStatus.GSM
-> {"access_token": "...", "expires_in": 299, "refresh_token": "...", ...}

访问令牌仅 ~5 分钟有效，因此该服务器在每次工具调用时都会重新进行全新的身份验证，而不是在 MCP 请求之间缓存令牌——不缓存也不持久化任何内容。每次真实的 API 调用都会发送 Authorization: Bearer <access_token>。

HEADER 授权参数说明

缺少任一请求头将返回 401：

{
  "error": "Missing credentials",
  "message": "This server requires the X-Webroot-Username, X-Webroot-Password, X-Webroot-Client-Id, X-Webroot-Client-Secret, X-Webroot-Parent-Keycode headers",
  "required_headers": ["X-Webroot-Username", "X-Webroot-Password", "X-Webroot-Client-Id", "X-Webroot-Client-Secret", "X-Webroot-Parent-Keycode"],
  "optional_headers": []
}

无效凭据会在内部登录步骤中表现为结构化的工具级错误（参见下文"错误处理"），而不是来自该服务器的 HTTP 级错误。

环境变量

MCP 端点

• POST /mcp — MCP 协议（流式 HTTP 传输）

• GET /health — 健康检查，返回 {"status": "ok"}（纯本地探测，不依赖 Webroot API）

工具列表

全部 10 个工具均为只读（readOnlyHint=True）；该服务不包含任何写入/删除工具。

page_size/batch_size 上限：厂商公开的 API 参考文档未对上述任何端点的这些参数说明最大值，因此该服务器自行设置默认值（50）和硬上限（200），而不是透传无界值。

响应为厂商的 JSON，以紧凑格式序列化（不进行美化打印，ensure_ascii=False），并限制在 20,000 个字符以内——过大的列表字段会以 truncated/original_count 标记截断，绝不会返回无界的数据块。

错误处理

错误以带内 JSON 信封的形式返回（正常的工具结果字符串，而非 MCP 协议错误）：

{"error": {"code": "not_found", "message": "...", "retryable": false}}

code 属于固定词汇表之一：not_configured、unauthorized、not_found、invalid_argument、rate_limited、upstream_error。retryable 告知调用方重试同一调用是否可能成功（rate_limited/upstream_error 为 true，否则为 false）。空结果集（例如没有端点的站点）是正常的成功结果，而非 not_found 错误。

对 Webroot API 的出站调用使用 5 秒连接 / 30 秒读取超时，并对 429/5xx 响应进行最多 3 次带退避的重试（遵循 Retry-After，上限 20 秒），在进程生命周期内复用单个连接池 HTTP 客户端。

测试示例

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-Webroot-Username: admin@example.com" \
  -H "X-Webroot-Password: <your-password>" \
  -H "X-Webroot-Client-Id: <your-client-id>" \
  -H "X-Webroot-Client-Secret: <your-client-secret>" \
  -H "X-Webroot-Parent-Keycode: <your-parent-keycode>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "webroot_get_sites",
      "arguments": {}
    }
  }'

已在线验证（2026-07-30）：针对真实 GSM 控制台，通过该运行中的服务器使用真实凭据对全部 10 个工具进行了端到端调用：webroot_get_sites 返回了 92 个真实站点（例如 "Pinnacle Technologies"、"Hohimer Wealth Management"）；webroot_get_policies 返回了 11 个真实策略；webroot_get_agent_status 返回了真实的每设备状态数据；webroot_get_endpoints 和 webroot_get_groups（使用真实站点 ID）均返回了真实数据（6 个端点，1 个包含 46 台设备的分组）；webroot_get_threat_history 对真实的 2 个月时间范围返回了有效（空）结果。4 个 DNS Protection 工具（webroot_get_dnsp_categories/_block_reasons/_traffic_summary/_blocked_traffic）均正确访问了 API 并返回了厂商自身的 dnsp_not_enabled 错误——证明请求/身份验证管道是正确的；只是该特定测试账户的 GSM 控制台未启用 DNS Protection（参见"已知差距"）。

API 参考

• 公开，无需登录：https://unityapi.webrootcloudav.com/Docs/en/APIDoc （指南完整介绍了 OAuth2 身份验证；API 参考涵盖每个方法的参数和响应结构）

已知差距

• 范围恰好是 MSPbots 配置的 10 个端点，而非厂商的完整 API 面——Unity API 还涵盖 ECom（许可证订购/管理）、通知、Agent 命令下发、站点创建/编辑以及 OpenText Secure Cloud 平台 API；这些不在本服务范围内。

• 4 个 DNS Protection（DNSP）工具无法用真实数据验证——DNS Protection 是一个附加产品，测试账户的 GSM 控制台未启用该产品（dnsp_not_enabled 错误，已在线确认）。其他 6 个工具使用完全相同的访问令牌成功获取了真实数据，确认这是账户功能差距，而非实现缺陷。

• webroot_get_endpoints/webroot_get_groups/webroot_get_threat_history 需要经过身份验证的 GSM 用户实际有权访问的 site_id——Webroot GSM 访问是按站点授权的；对用户未被授予访问权限的站点调用这些方法会返回干净的 "User does not have access to this console" 错误（测试期间在 92 个站点中的 1 个上在线观察到），而非该服务器的缺陷。

• webroot_get_threat_history 拒绝超过 3 个月的日期范围（Invalid data entered - Date Range Over 3 Months，已在线确认）——该服务器不强制或自动拆分该范围；它按原样透传 start_date/end_date。