Atera

Atera MCP 服务

用于与 Atera RMM API 交互的模型上下文协议（MCP）服务。采用决策树架构，实现高效的工具发现并减少上下文开销。

一键部署

重要

点击之前请注意： 此服务依赖 @wyre-technology/node-atera， 该包托管在 GitHub Packages npm 注册表中。GitHub Packages 不支持 匿名访问——即使该包是公开的，每次 npm install 仍需要令牌。云端构建器会替你运行 npm install，因此你必须提供令牌，否则 构建会失败，并显示 npm error 401 Unauthorized ... npm.pkg.github.com。

1. 创建一个具有 read:packages 范围的 GitHub Personal Access Token（经典令牌）。 任何 GitHub 账号均可——读取其公开软件包不需要成为 WYRE-AI 组织的成员。
2. 部署流程提示时，将其添加为构建变量：
   • Cloudflare Workers → 将名为 NODE_AUTH_TOKEN 的构建变量设置为你的 PAT （Workers → Settings → Build → Variables and Secrets）。
   • DigitalOcean App Platform → 将名为 GITHUB_TOKEN 的加密环境变量 设置为你的 PAT，并将范围设为 Build Time（.do/app.yaml 已声明该变量）。

说明

DigitalOcean 目标会构建完整的 Docker 镜像，并通过 HTTP 运行完整的 MCP 服务——这是推荐给运维人员的方案。Cloudflare Workers 目标目前只是一个精简的入口存根（/mcp 路由会返回 501 Not Implemented），最适合网关式部署；如需完整的可自托管服务，建议使用 DigitalOcean 或预构建的容器镜像 （ghcr.io/wyre-ai/atera-mcp）。

功能

• 决策树导航：工具按领域组织（客户、Agent、工单、警报、联系人）。先导航到某个领域，再使用该领域专属的工具。
• 延迟加载客户端：仅在首次需要时实例化 Atera 客户端，从而缩短启动时间。
• 全面覆盖 API：支持客户管理、设备/Agent 监控、工单操作、警报处理和联系人管理。
• 速率限制处理：通过 node-atera 客户端内置速率限制（700 次请求/分钟）。
• 交互式工单卡片（MCP Apps）：在 MCP Apps 宿主（Claude Desktop/web）中，atera_tickets_get 会渲染为交互式卡片，并支持通过 atera_tickets_add_comment 在卡片内完成“添加评论”的往返操作（默认仅内部可见）；在其他宿主中，纯 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）进行品牌定制——无需重新构建。

安装

此软件包发布在 GitHub Packages npm 注册表中，即使是公开的软件包也需要令牌。 完成一次身份验证后即可安装：

# Authenticate npm to GitHub Packages (token needs the read:packages scope)
export NODE_AUTH_TOKEN=$(gh auth token)   # or a PAT with read:packages

npm install @wyre-ai/atera-mcp

仓库的 .npmrc 已将 @wyre-ai 作用域指向 GitHub Packages，并从 NODE_AUTH_TOKEN 读取令牌，因此无需其他配置。

或者从源代码构建：

git clone https://github.com/WYRE-AI/atera-mcp.git
cd atera-mcp
npm install
npm run build

配置

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

变量	必填	描述
ATERA_API_KEY	stdio 和 AUTH_MODE=env 时必填	Atera API 令牌或旧版 API 密钥，获取路径为 Admin > Data management > API。JWT 令牌通过 Authorization: Bearer 发送；旧版密钥通过 X-API-KEY 发送。Compose 网关服务不会加载此变量。
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	gateway（Docker 镜像和 Compose 的默认值）或 env。网关模式要求每个 /mcp 请求都携带 X-Atera-API-Key，且不会回退到 ATERA_API_KEY。env 仅在 S2S 身份验证成功后使用该变量。
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。

/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。

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-Atera-API-Key: $ATERA_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 模式下，/mcp 还要求 X-Atera-API-Key。该标头是此请求唯一的凭据来源。在 AUTH_MODE=env 模式下，如果请求未携带该标头，已签名请求会使用环境变量中的 ATERA_API_KEY。

获取 API 密钥

1. 以管理员身份登录 Atera
2. 前往 Admin > Data management > API
3. 创建 API 令牌（JWT）或复制旧版 API 密钥

JWT 令牌（签发者为 AteraInterop）通过 Authorization: Bearer 进行身份验证。 旧版静态密钥通过 X-API-KEY 进行身份验证。此服务端会根据密钥格式选择 标头，包括已安装的 node-atera 客户端仍只发送 X-API-KEY 的情况。

用法

与 Claude Desktop 搭配使用

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "atera": {
      "command": "npx",
      "args": ["@wyre-ai/atera-mcp"],
      "env": {
        "ATERA_API_KEY": "your-api-key-here"
      }
    }
  }
}

与 MCP Gateway 搭配使用

在网关注册表中配置：

{
  "name": "atera-mcp",
  "command": "node",
  "args": ["/path/to/atera-mcp/dist/index.js"],
  "env": {
    "ATERA_API_KEY": "${ATERA_API_KEY}"
  }
}

Docker

镜像在容器内的 0.0.0.0（MCP_HTTP_HOST）上监听，且默认使用 AUTH_MODE=gateway。将端口发布到回环地址，并传入真实的 S2S 密钥。在网关模式下，Atera API 密钥会随每个请求通过 X-Atera-API-Key 传入；不会从环境中读取。

# Generate the secret first: openssl rand -hex 32
docker build -t atera-mcp .
docker run \
  -e CONDUIT_S2S_SECRET \
  -p 127.0.0.1:8080:8080 \
  atera-mcp

如果未设置 CONDUIT_S2S_SECRET，Compose 将拒绝启动；它会将 AUTH_MODE 默认设为 gateway，不会注入 ATERA_API_KEY，并发布 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍要求设置 S2S 密钥，然后使用 ATERA_API_KEY：

docker run \
  -e CONDUIT_S2S_SECRET \
  -e AUTH_MODE=env \
  -e ATERA_API_KEY=your-key \
  -p 127.0.0.1:8080:8080 \
  atera-mcp

不使用密钥的本地 HTTP 仅供开发使用。它只绑定到 127.0.0.1，并会记录警告。非回环地址的 MCP_HTTP_HOST 会被忽略，并记录覆盖情况：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

决策树架构

此服务采用基于导航的工具发现方式：

1. 开始：仅提供 atera_navigate 工具
2. 导航：使用某个领域（customers、agents、tickets、alerts、contacts）调用 atera_navigate
3. 工具列表刷新：服务声明 tools.listChanged，并发送 notifications/tools/list_changed，以便客户端重新获取 tools/list
4. 领域工具：刷新后，即可使用特定领域的工具
5. 返回：使用 atera_back 返回领域选择（这也会发送 notifications/tools/list_changed）

此架构：

• 缩小工具列表，提升大模型性能
• 按逻辑对相关操作进行分组
• 最大限度减少上下文窗口的占用

可用领域

客户

管理客户（公司）记录。

• atera_customers_list - 分页列出客户
• atera_customers_get - 按 ID 获取客户
• atera_customers_create - 创建新客户

Agent

管理安装了 Atera Agent 的设备/终端。

• atera_agents_list - 列出 Agent，可选按客户筛选
• atera_agents_get - 按 ID 获取 Agent
• atera_agents_get_by_machine - 按机器名称获取 Agent

工单

管理服务工单。

• atera_tickets_list - 根据筛选条件列出工单
• atera_tickets_get - 按 ID 获取工单
• atera_tickets_create - 创建新工单
• atera_tickets_update - 更新现有工单

警报

监控设备和 Agent 发出的警报。

• atera_alerts_list - 根据筛选条件列出警报
• atera_alerts_get - 按 ID 获取警报
• atera_alerts_by_agent - 列出某个 Agent 的警报
• atera_alerts_by_device - 列出某台设备的警报

联系人

管理客户联系人。

• atera_contacts_list - 列出所有联系人
• atera_contacts_get - 按 ID 获取联系人
• atera_contacts_by_customer - 列出某个客户的联系人

对话示例

User: List all open tickets

Claude: I'll navigate to the tickets domain and list open tickets.
[Calls atera_navigate with domain: "tickets"]
[Calls atera_tickets_list with ticketStatus: "Open"]

Result: Found 15 open tickets...

开发

# Install dependencies
npm install

# Build
npm run build

# Run in development
npm run dev

# Type check
npm run typecheck

# Lint
npm run lint

# Test
npm run test

API 速率限制

Atera API 每分钟允许 700 次请求。底层的 node-atera 客户端会通过请求排队机制自动处理速率限制。

许可证

Apache-2.0

参与贡献

欢迎贡献！请阅读我们的贡献指南，并向 main 分支提交 PR。