SuperOps

SuperOps.ai MCP 服务

面向 Claude 的 MCP 服务，使用 SuperOps.ai 的 GraphQL API 提供与其 PSA/RMM 平台交互的工具。

一键部署

运维人员须知——GitHub Packages 身份验证。 此软件包发布在 GitHub Packages 的 @wyre-ai 作用域下，每次安装都需要身份验证令牌（GitHub Packages 不支持匿名读取，即使是公开软件包也不例外）。请创建具有 read:packages 作用域的 GitHub Personal Access Token，并将其提供给云构建器：

• Cloudflare Workers — 将名为 NODE_AUTH_TOKEN 的构建变量设为你的 PAT。
• DigitalOcean App Platform — 将名为 GITHUB_TOKEN 的构建时密钥设为你的 PAT。

本地安装时，请在运行 npm install 前执行 export NODE_AUTH_TOKEN=$(gh auth token)。

功能

• 决策树架构：导航至各个域（客户端、工单、资产、技术人员），查看相关工具
• 延迟加载：按需加载域模块，加快启动速度
• 完整的 CRUD 操作：列出、获取、创建和更新实体
• GraphQL 支持：使用自定义查询执行高级操作
• 交互式工单卡片（MCP Apps）：工单结果会在 MCP Apps 宿主中呈现为交互式卡片 — 默认采用中性样式，可通过注入 window.__BRAND__ 或设置 MCP_BRAND_* 环境变量进行品牌定制

交互式工单卡片（MCP Apps）

superops_tickets_get 会在 MCP Apps 宿主（Claude Desktop/web）中呈现为交互式卡片；卡片内的“添加备注”往返操作由 superops_tickets_add_note 完成，始终发布仅供内部查看的备注（isPublic: false）；在其他宿主中，纯 JSON 行为保持不变。 卡片默认采用中性样式，可通过注入 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）进行品牌定制 — 无需重新构建。

安装

# The @wyre-ai scope lives on GitHub Packages and needs a token to install:
export NODE_AUTH_TOKEN=$(gh auth token)
npm install @wyre-ai/superops-mcp

配置

复制 .env.example，并设置以下变量。示例中的 CONDUIT_S2S_SECRET 请留空；使用 openssl rand -hex 32 生成真实值，且不要将其提交到代码仓库。

export SUPEROPS_API_TOKEN="your-api-token"
export SUPEROPS_SUBDOMAIN="yourcompany"
export SUPEROPS_REGION="us"  # or "eu" for EU region

变量	必需	说明
SUPEROPS_API_TOKEN	用于 stdio 和 AUTH_MODE=env	SuperOps.ai API 令牌
SUPEROPS_SUBDOMAIN	用于 stdio 和 AUTH_MODE=env	SuperOps.ai 子域名
SUPEROPS_REGION	否	us（默认）或 eu
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	env（Docker 外部的默认值）或 gateway。镜像和 Compose 的默认值为 gateway。网关模式要求每个 /mcp 请求都携带 X-SuperOps-API-Token 和 X-SuperOps-Subdomain，且绝不会回退到 SUPEROPS_*。
CONDUIT_S2S_SECRET	HTTP 必需	用于 X-Gateway-S2S 的 HMAC 密钥。若值为空或为已知占位符（replace-with-a-real-secret、your-s2s-secret、changeme 等），则会记录错误并以非零状态退出。未设置时，Compose 不会启动。此值绝不会被记录。
MCP_ALLOW_INSECURE_DEV	否	仅在本地开发时设为 1，即可在没有 CONDUIT_S2S_SECRET 的情况下启动 HTTP。此设置会记录警告、不强制要求 X-Gateway-S2S，并且只绑定 127.0.0.1。若 MCP_HTTP_HOST 不是回环地址，则拒绝启动。即使设置此标志，已知占位符密钥仍会被拒绝。
MCP_HTTP_HOST	否	设置了真实 CONDUIT_S2S_SECRET 时的绑定地址。默认为 127.0.0.1。容器镜像设为 0.0.0.0。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。

/health 无需身份验证，也不会读取凭据。stdio 传输不使用 CONDUIT_S2S_SECRET。

HTTP authentication

设置 MCP_TRANSPORT=http 后，只要设置了 CONDUIT_S2S_SECRET，每个 /mcp 请求都必须包含 X-Gateway-S2S。标头值为 t=<unix seconds>,v1=<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}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 模式下，还需添加 X-SuperOps-API-Token 和 X-SuperOps-Subdomain。缺少凭据标头时，返回 HTTP 401，且不会回退到环境变量中的 SUPEROPS_*。在 AUTH_MODE=env 模式下，已签名的请求会使用进程环境中的这些变量。

无法对请求签名的独立本地使用方式：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

启动时会记录一条警告，跳过 S2S 检查，并且只绑定到 127.0.0.1。请勿将该端口发布到本地回环地址之外。

获取 API 令牌

1. 登录 SuperOps.ai
2. 点击设置图标 >“My Profile”
3. 转到“API token”选项卡
4. 点击“Generate token”
5. 复制并安全保存令牌

在 Claude Desktop 中使用

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "superops": {
      "command": "npx",
      "args": ["@wyre-ai/superops-mcp"],
      "env": {
        "SUPEROPS_API_TOKEN": "your-api-token",
        "SUPEROPS_SUBDOMAIN": "yourcompany",
        "SUPEROPS_REGION": "us"
      }
    }
  }
}

可用的域和工具

导航

• superops_navigate - 导航到某个域
• superops_back - 返回主菜单
• superops_test_connection - 测试 API 连通性

客户域

• superops_clients_list - 按筛选条件列出客户
• superops_clients_get - 获取客户详情
• superops_clients_search - 按名称搜索客户

工单域

• superops_tickets_list - 按筛选条件列出工单
• superops_tickets_get - 获取工单详情
• superops_tickets_create - 创建新工单
• superops_tickets_update - 更新工单状态/指派
• superops_tickets_add_note - 为工单添加备注
• superops_tickets_log_time - 记录工单耗时

资产域

• superops_assets_list - 列出资产/终端
• superops_assets_get - 获取资产详情
• superops_assets_software - 获取软件清单
• superops_assets_patches - 获取补丁状态

技术人员域

• superops_technicians_list - 列出技术人员
• superops_technicians_get - 获取技术人员详情
• superops_technicians_groups - 列出技术人员组

自定义域

• superops_custom_query - 运行自定义 GraphQL 查询
• superops_custom_mutation - 运行自定义 GraphQL mutation

使用示例

User: What tools are available?
Claude: Use superops_navigate to select a domain...

User: Navigate to tickets
Claude: [calls superops_navigate with domain: "tickets"]
Now in tickets domain. Available tools: superops_tickets_list, superops_tickets_get...

User: Show open high priority tickets
Claude: [calls superops_tickets_list with status: ["Open"], priority: ["High"]]
Here are the open high priority tickets...

Docker

镜像会在容器内的 0.0.0.0（MCP_HTTP_HOST）上监听，默认使用 AUTH_MODE=gateway，并且在 CONDUIT_S2S_SECRET 不是有效密钥时拒绝启动。请将端口发布到本地回环地址。在 gateway 模式下，每个请求都会通过标头携带 SuperOps 凭据；不会从环境中读取这些凭据。

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

如果未设置 CONDUIT_S2S_SECRET，Compose 会拒绝启动；它会设置 AUTH_MODE=gateway，发布 127.0.0.1:8080:8080，并且不会将 SUPEROPS_API_TOKEN 或 SUPEROPS_SUBDOMAIN 传入容器：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

按照 HTTP authentication 中的相同方式对 /mcp 请求签名。gateway 模式的调用还需发送供应商标头：

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-SuperOps-API-Token: $SUPEROPS_API_TOKEN" \
  -H "X-SuperOps-Subdomain: $SUPEROPS_SUBDOMAIN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，然后使用 SUPEROPS_API_TOKEN 和 SUPEROPS_SUBDOMAIN。DigitalOcean 一键式模板使用此模式：将 CONDUIT_S2S_SECRET 设置为运行时密钥。

速率限制

SuperOps.ai API 对每个 API 令牌的速率限制为每分钟 800 个请求。

分页

SuperOps 使用基于页码的分页，而非游标。列表工具接受 page （从 1 开始，默认值为 1）和 pageSize（默认值为 50，最大值为 100），并返回包含 page、pageSize、totalCount 和 hasMore 的 listInfo 块。

hasMore 有三种状态： 有下一页时为 true，没有下一页时为 null——绝不会是 false。可在 hasMore === true 时循环，或根据 totalCount 翻页；循环直到 hasMore === false 永远不会终止。

筛选

筛选器是 { attribute, operator, value } 形式的 condition 子句，并且可以组合——{ joinOperator: "and" | "or", operands: [ … ] } 支持递归嵌套。 以下运算符已通过实时租户验证：

运算符	值
is, isNot, contains, notContains, startsWith, endsWith	字符串
includes, notIncludes	数组

API 不接受 equals 和 in。includes 匹配完整值，而 contains 匹配子字符串——使用 includes: ["Windows"] 筛选 OS 平台时不会匹配任何内容，因为 SuperOps 存储的是 "Microsoft Windows 10 Pro"。

有两点需要注意，因为这两种情况都不会报告错误：

• 筛选字段的实际取值范围之外的值会返回 零行，而不是错误。结果为空，可能是值无效，而非租户为空。
• 筛选 JSON 列（software）而不是其中的路径（software.name），也会静默返回 零行。

对于标准工具无法表达的筛选语义，请使用 superops_custom_query。

架构一致性

schema/superops.graphql 是 SuperOps GraphQL 架构的随项目分发副本：

# Authoritative — generated from live introspection
SUPEROPS_API_TOKEN=... SUPEROPS_SUBDOMAIN=... node scripts/fetch-schema.mjs

# No credentials? Falls back to scraping the published API reference
node scripts/fetch-schema.mjs

优先使用内省，并注意已提交的架构本身就是内省生成的结果。已发布的文档声明有 276 个类型 / 76 个查询 / 63 个变更，而实时 API 报告的是 404 / 116 / 83；文档完全省略了弃用信息，并且声明了两个实时 API 中不存在的类型（FieldType、TicketType）——依据这些文档进行验证，会让 API 实际拒绝的文档通过。

src/domains/graphql-schema.test.ts 会在每次运行 npm test 时，依据该架构验证 src/ 中的每个 GraphQL 文档，因此，引用了 SuperOps 未定义字段的查询会在 CI 中失败，而不是等到运行时才失败。SuperOps API 变更后，请重新生成架构并再次运行测试。

许可证

Apache-2.0

支持

如需报告问题或提出功能请求，请访问 GitHub 仓库。