HaloPSA

HaloPSA MCP 服务

一个用于与 HaloPSA 交互的模型上下文协议（MCP）服务，采用决策树架构，可高效加载工具。

一键部署

重要

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

1. 创建一个具有 read:packages 范围的 GitHub Personal Access Token（个人访问令牌） （classic token）。 任何 GitHub 账户都可以——读取其公开包不需要加入 wyre-technology 组织。
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 目标目前只是一个精简的入口点（在 Workers 传输适配器推出之前，/mcp 路由会返回 501），最适合网关式 部署；如需完整的可自托管服务，建议使用 DigitalOcean 或预构建的 容器镜像（ghcr.io/wyre-ai/halopsa-mcp）。

架构

此 MCP 服务采用分层工具加载方式，而非一开始就公开所有工具：

1. 导航阶段：最初只公开一个导航工具（halopsa_navigate）
2. 选择领域：用户选择一个领域（工单、客户、资产、Agent、发票、类别）
3. 领域工具：选择后，服务公开对应领域的专用工具
4. 延迟加载：按需加载领域处理程序和 HaloPSA 客户端

此架构具有以下优点：

• 降低认知负担（可供选择的工具更少）
• 缩短初始加载时间
• 更好地组织相关操作
• 导航状态清晰

交互式工单卡片（MCP Apps）

在 MCP Apps 宿主（Claude Desktop/web）中，halopsa_tickets_get 会渲染为交互式卡片， 可通过卡片内的“添加备注”功能调用 halopsa_tickets_add_action 完成往返交互；在其他宿主中， 纯 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/halopsa-mcp

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

配置

设置以下环境变量：

变量	必需	描述
HALOPSA_CLIENT_ID	是	OAuth 2.0 Client ID
HALOPSA_CLIENT_SECRET	是	OAuth 2.0 Client Secret
HALOPSA_TENANT	二选一	租户名称（例如，yourcompany）
HALOPSA_BASE_URL	二选一	显式指定的基础 URL（例如，https://yourcompany.halopsa.com）

使用方法

独立运行

# Set credentials
export HALOPSA_CLIENT_ID="your-client-id"
export HALOPSA_CLIENT_SECRET="your-client-secret"
export HALOPSA_TENANT="yourcompany"

# Run the server
npx @wyre-ai/halopsa-mcp

Claude Desktop 配置

添加到 Claude Desktop 的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "halopsa": {
      "command": "npx",
      "args": ["@wyre-ai/halopsa-mcp"],
      "env": {
        "HALOPSA_CLIENT_ID": "your-client-id",
        "HALOPSA_CLIENT_SECRET": "your-client-secret",
        "HALOPSA_TENANT": "yourcompany"
      }
    }
  }
}

Docker

docker build -t halopsa-mcp .
docker run -e HALOPSA_CLIENT_ID=xxx -e HALOPSA_CLIENT_SECRET=xxx -e HALOPSA_TENANT=yourcompany halopsa-mcp

可用领域

工单

管理支持工单、创建新工单、更新状态以及添加操作/备注。

工具：

• halopsa_tickets_list - 按筛选条件列出工单（仅支持 category_1；不接受 category_2–category_4）
• halopsa_tickets_get - 获取工单详情
• halopsa_tickets_create - 创建新工单（可选填写 category_1–category_4）
• halopsa_tickets_update - 更新现有工单（可选填写 category_1–category_4）
• halopsa_tickets_add_action - 向工单添加备注/操作

类别

查询 Halo 工单类别，以便分诊时按对应级别的类别名称设置 category_1–category_4。

工具：

• halopsa_categories_list - 列出一页工单类别（limit 默认为 50；page_no 从 1 开始）
• halopsa_categories_get - 按 ID 获取类别

客户

管理 HaloPSA 中的公司/客户。

工具：

• halopsa_clients_list - 列出客户
• halopsa_clients_get - 获取客户详情
• halopsa_clients_create - 创建新客户
• halopsa_clients_search - 按名称搜索客户

资产

管理配置项/资产。

工具：

• halopsa_assets_list - 按筛选条件列出资产
• halopsa_assets_get - 获取资产详情
• halopsa_assets_search - 搜索资产
• halopsa_assets_list_types - 列出可用资产类型

Agent

查看技术人员和团队。

工具：

• halopsa_agents_list - 列出 Agent/技术人员
• halopsa_agents_get - 获取 Agent 详情
• halopsa_teams_list - 列出团队

发票

查看账单和发票。

工具：

• halopsa_invoices_list - 按筛选条件列出发票
• halopsa_invoices_get - 获取发票详情

导航工具

始终可用：

• halopsa_navigate - 选择要操作的领域
• halopsa_status - 显示当前状态和凭据状态
• halopsa_back - 返回主菜单（处于某个领域时）

示例工作流

User: Check my tickets
Claude: [calls halopsa_navigate with domain="tickets"]
       -> Navigated to tickets domain. Available tools: ...

User: List open tickets
Claude: [calls halopsa_tickets_list with open_only=true]
       -> [ticket list results]

User: Now show me clients
Claude: [calls halopsa_back]
       -> Navigated back to main menu.
       [calls halopsa_navigate with domain="clients"]
       -> Navigated to clients domain.

速率限制

HaloPSA 的速率限制为每 3 分钟 500 次请求。底层的 @asachs01/node-halopsa 客户端会通过请求节流自动处理此限制。

许可证

Apache-2.0