Kaseya BMS

Kaseya BMS MCP 服务

适用于 Kaseya BMS PSA API 的 Model Context Protocol（MCP）服务。 向 AI 助手提供工单、账户、联系人、合同、工时记录、服务 目录和知识库。

工具

工具	描述
kaseya_bms_list_tickets	列出工单。可选 $filter；如果省略，则选择状态。
kaseya_bms_get_ticket	按 ID 获取工单。
kaseya_bms_create_ticket	创建新工单（有破坏性操作——需要确认）。
kaseya_bms_add_ticket_note	向工单追加备注（有破坏性操作——需要确认）。
kaseya_bms_list_time_entries	按日期范围列出工时记录（24 小时 / 7 天 / 30 天 / 自定义 / 全部）。
kaseya_bms_list_accounts	账户（客户）。
kaseya_bms_list_contacts	联系人。
kaseya_bms_list_contracts	合同。
kaseya_bms_list_service_catalog	服务目录条目。
kaseya_bms_search_knowledge_base	搜索知识库。

如果用户省略必需的筛选条件或执行有破坏性的操作，服务会使用 MCP elicitation 提示用户选择或确认。

交互式工单卡片（MCP Apps）

在 MCP Apps 宿主（Claude Desktop/web）中，kaseya_bms_get_ticket 会呈现为交互式卡片，支持通过 kaseya_bms_add_ticket_note 在卡片内往返添加备注（始终仅发布为内部备注）；在其他宿主中，纯 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）进行品牌定制，无需重新构建。 编辑 ui/ 后，使用 npm run build:ui 重新生成嵌入式 bundle。

配置

复制 .env.example。Stdio 和 AUTH_MODE=env 会读取 Kaseya BMS 变量。Gateway 模式不会读取。

变量	必需	描述
KASEYA_BMS_TENANT_SUBDOMAIN	对 stdio 和 AUTH_MODE=env 必需	租户子域名（例如 yourcompany）
KASEYA_BMS_API_TOKEN	对 stdio 和 AUTH_MODE=env，以下凭据之一	BMS API 令牌
KASEYA_BMS_K1_TOKEN	对 stdio 和 AUTH_MODE=env，以下凭据之一	Kaseya One SSO 令牌
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	env（默认）或 gateway。Gateway 模式要求每个 /mcp 请求都携带 X-Kaseya-BMS-Tenant-Subdomain，以及 X-Kaseya-BMS-API-Token 或 X-Kaseya-BMS-K1-Token，且绝不会回退到 KASEYA_BMS_*。
CONDUIT_S2S_SECRET	HTTP 模式必需	服务间密钥。如果该值为空或为已知占位值，HTTP 服务会记录错误并以非零状态退出。Compose 未设置该值时不会启动。切勿提交真实值。可使用 openssl rand -hex 32 生成。
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 时使用的绑定地址。未设置时使用 0.0.0.0，这是容器镜像设置的值，因此容器部署会在容器内的所有接口上监听。未设置密钥时，开发绕过模式会改为绑定 127.0.0.1。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。

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

HTTP 身份验证

设置 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 后，每个 /mcp 请求都必须包含 X-Gateway-S2S。其值为 t=<unix seconds>,v1=<hex>，其中 v1 是以 CONDUIT_S2S_SECRET 为密钥、对确切字符串 t=<unix seconds> 计算的 HMAC-SHA256（64 个小写十六进制字符）。时间戳必须在服务器时钟的 300 秒范围内。缺少标头或标头无效时会返回 401。该密钥绝不会写入日志。

import { createHmac } from "node:crypto";

const t = Math.floor(Date.now() / 1000);
const v1 = createHmac("sha256", process.env.CONDUIT_S2S_SECRET)
  .update(`t=${t}`)
  .digest("hex");
const xGatewayS2s = `t=${t},v1=${v1}`;

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-Kaseya-BMS-Tenant-Subdomain，以及 X-Kaseya-BMS-API-Token 或 X-Kaseya-BMS-K1-Token。这些标头是该请求唯一的凭据来源。缺少这些标头的请求会返回 401，且不会从环境中读取 KASEYA_BMS_*。每个请求都会创建一个凭据相互隔离的全新服务实例。

Docker Compose

仓库中提交的 Compose 服务采用网关模式。它发布 127.0.0.1:8080:8080，要求设置 CONDUIT_S2S_SECRET，且不设置 KASEYA_BMS_TENANT_SUBDOMAIN、KASEYA_BMS_API_TOKEN、KASEYA_BMS_K1_TOKEN 或 env_file。镜像构建会从 npmrc 构建密钥中读取 GitHub Packages 凭据（仓库的 .npmrc 仅设置注册表）。

CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" docker compose up --build

单租户 HTTP（AUTH_MODE=env）仍要求提供 S2S 密钥，然后使用 KASEYA_BMS_*：

docker build -t kaseya-bms-mcp .
docker run --rm \
  -e CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" \
  -e AUTH_MODE=env \
  -e KASEYA_BMS_TENANT_SUBDOMAIN=yourcompany \
  -e KASEYA_BMS_API_TOKEN=... \
  -p 127.0.0.1:8080:8080 \
  kaseya-bms-mcp

本地开发

npm install
npm run build
KASEYA_BMS_TENANT_SUBDOMAIN=yourcompany \
  KASEYA_BMS_API_TOKEN=... \
  npm start

在 CONDUIT_S2S_SECRET 为真实密钥之前，HTTP 不会启动：

MCP_TRANSPORT=http CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" npm start
curl http://127.0.0.1:8080/health

不设置密钥的本地 HTTP 仅用于开发环境。它会绑定到 127.0.0.1 并记录警告：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

许可证

Apache-2.0