Syncro

Syncro MCP 服务

适用于 Syncro MSP 的模型上下文协议（MCP）服务，采用决策树架构，便于高效导航工具。

一键部署

运维人员须知 — GitHub Packages 身份验证（一键部署必需）。 此服务依赖私有的 @wyre-technology/node-syncro SDK，该 SDK 托管在 GitHub Packages 上。GitHub Packages 每次安装都需要身份验证令牌 （即使是公开的软件包也不允许匿名读取），因此云构建程序会在 npm install 期间因 401 Unauthorized 而失败，除非你提供令牌。创建一个具有 read:packages 范围的 GitHub 个人访问令牌，并将其提供给构建程序：

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

如需本地运行 npm install，请先运行 export NODE_AUTH_TOKEN=$(gh auth token)。

功能

• 决策树架构：按领域组织工具，并按需加载
• 领域导航：在客户、工单、资产、联系人和发票之间导航
• 按需加载：按需加载领域处理程序和 Syncro 客户端
• 全面覆盖 Syncro API：访问 Syncro MSP 的关键功能
• 交互式工单卡片（MCP Apps）：在 MCP Apps 宿主（Claude Desktop／web）中，syncro_tickets_get 会呈现为交互式卡片，并支持在卡片内通过 syncro_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）进行品牌定制，无需重新构建。

安装

WYRE MCP 服务通过 OCI/GHCR 镜像以及（在可用时）MCPB 捆绑包分发。npm 软件包 @wyre-ai/syncro-mcp 也发布在 GitHub Packages（npm.pkg.github.com）；安装时需要经过身份验证且具有 read:packages 范围的 .npmrc（在本地运行 export NODE_AUTH_TOKEN=$(gh auth token)）。

选项 1：WYRE MCP Gateway（推荐）

使用托管网关 mcp.wyre.ai — 在网关 UI 中粘贴你的 Syncro API 密钥即可。

{
  "mcpServers": {
    "syncro": {
      "type": "http",
      "url": "https://mcp.wyre.ai/v1/syncro/mcp",
      "headers": {
        "X-Syncro-Api-Key": "${SYNCRO_API_KEY}"
      }
    }
  }
}

选项 2：Claude Code CLI（从 GitHub 运行）

claude mcp add syncro \
  -e SYNCRO_API_KEY=your-api-key \
  -e SYNCRO_SUBDOMAIN=your-subdomain \
  -- npx -y github:WYRE-AI/syncro-mcp

选项 3：Docker（GHCR）

镜像在容器内监听 0.0.0.0，并默认使用 AUTH_MODE=gateway。将端口发布到回环地址，并传入服务间密钥。在网关模式下，Syncro 凭据会作为请求头随每个请求传入；不会从环境变量中读取。

docker run --rm \
  -e CONDUIT_S2S_SECRET=your-s2s-secret \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/syncro-mcp:latest

当 CONDUIT_S2S_SECRET 未设置时，Compose 会拒绝启动；它会在没有静态 SYNCRO_* 凭据的情况下运行 AUTH_MODE=gateway，并发布 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET=your-s2s-secret docker compose up

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，然后使用 SYNCRO_API_KEY：

docker run --rm \
  -e CONDUIT_S2S_SECRET=your-s2s-secret \
  -e AUTH_MODE=env \
  -e SYNCRO_API_KEY=your-api-key \
  -e SYNCRO_SUBDOMAIN=your-subdomain \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/syncro-mcp:latest

选项 4：从源代码安装

git clone https://github.com/WYRE-AI/syncro-mcp.git
cd syncro-mcp
npm ci
npm run build
node dist/index.js

配置

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

变量	必填	说明
SYNCRO_API_KEY	stdio 和 AUTH_MODE=env 时必填	你的 Syncro API 密钥
SYNCRO_SUBDOMAIN	否	你的 Syncro 子域名（如适用）
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	gateway（Docker 镜像和 Compose 默认值）或 env。Gateway 模式要求每个 /mcp 请求都携带 X-Syncro-API-Key，且绝不会回退到 SYNCRO_*。只有在 S2S 身份验证成功后，env 模式才会使用这些变量。
CONDUIT_S2S_SECRET	HTTP 必填	服务间密钥。如果该值为空或为已知占位值（changeme、your-s2s-secret、replace-with-a-real-secret、secret、未解析的 ${...} 值以及其他示例字符串），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（包括 0.0.0.0）会被忽略，并记录覆盖情况。若密钥是已知占位值，仍会拒绝启动。
MCP_HTTP_HOST	否	当 MCP_TRANSPORT=http 且已设置 CONDUIT_S2S_SECRET 时的绑定地址。未设置时默认为 127.0.0.1。容器镜像会设置为 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。其值格式为 t=<unix seconds>,v1=<hex>，其中十六进制字符串是以 CONDUIT_S2S_SECRET 为密钥、对字面字符串 t=<unix seconds> 计算得到的 HMAC-SHA256（64 位小写十六进制字符）。时间戳与服务器时钟的偏差必须在 300 秒以内。若缺少标头或标头无效，将在读取供应商凭据前返回 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-Syncro-API-Key: $SYNCRO_API_KEY" \
  -H "X-Syncro-Subdomain: $SYNCRO_SUBDOMAIN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-Syncro-API-Key（X-Syncro-Subdomain 为可选项）。这些标头是该请求唯一的凭据来源。若请求缺少 API 密钥，将返回 401，且不会回退到进程环境中的 SYNCRO_API_KEY。

在 AUTH_MODE=env 模式下，/mcp 仍要求有效的 X-Gateway-S2S 标头。如果请求未携带 X-Syncro-API-Key，则会从 SYNCRO_API_KEY 和 SYNCRO_SUBDOMAIN 获取供应商凭据。

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

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

获取 API 密钥

1. 登录你的 Syncro MSP 账户
2. 前往 Settings > API Tokens
3. 生成具有适当权限的新 API 令牌

架构

决策树导航

服务器采用分层方式发现工具：

1. 初始状态：仅公开导航和状态工具
2. 完成导航后：可使用特定领域的工具
3. 返回导航：回到主菜单以切换领域

这样可以减轻认知负担，并提高大模型选择工具的准确性。

可用领域

领域	说明	工具
customers	管理客户账户	list、get、create、search
tickets	管理支持工单	list、get、create、update、add_comment
assets	管理配置项	list、get、search
contacts	管理客户联系人	list、get、create
invoices	查看和管理账单	list、get、create、email

工具参考

导航工具

syncro_navigate

导航到某个领域以使用其工具。

{
  "domain": "customers" | "tickets" | "assets" | "contacts" | "invoices"
}

syncro_back

从任意领域返回主菜单。

syncro_status

显示当前导航状态和凭据状态。

Customers 领域

syncro_customers_list

按可选筛选条件列出客户。

{
  "query": "search term",
  "business_name": "Company Inc",
  "email": "[email protected]",
  "include_disabled": false,
  "page": 1,
  "per_page": 25
}

syncro_customers_get

按 ID 获取指定客户。

{
  "customer_id": 123
}

syncro_customers_create

创建新客户。

{
  "business_name": "Acme Corp",
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]"
}

syncro_customers_search

按查询字符串搜索客户。

{
  "query": "acme",
  "limit": 25
}

工单领域

syncro_tickets_list

按可选筛选条件列出工单。

{
  "customer_id": 123,
  "status": "Open",
  "user_id": 456,
  "resolved": false
}

syncro_tickets_get

按 ID 获取指定工单。

{
  "ticket_id": 789
}

syncro_tickets_create

创建新工单。

{
  "customer_id": 123,
  "subject": "Network Issue",
  "problem_type": "Network",
  "comment_body": "Initial description"
}

syncro_tickets_update

更新现有工单。

{
  "ticket_id": 789,
  "status": "Resolved",
  "user_id": 456
}

syncro_tickets_add_comment

为工单添加评论。

{
  "ticket_id": 789,
  "body": "Comment text",
  "hidden": false
}

资产领域

syncro_assets_list

按可选筛选条件列出资产。

{
  "customer_id": 123,
  "asset_type": "Desktop"
}

syncro_assets_get

按 ID 获取指定资产。

{
  "asset_id": 456
}

syncro_assets_search

按查询内容或序列号搜索资产。

{
  "query": "workstation",
  "asset_serial": "SN12345"
}

联系人领域

syncro_contacts_list

按可选筛选条件列出联系人。

{
  "customer_id": 123,
  "query": "john"
}

syncro_contacts_get

按 ID 获取指定联系人。

{
  "contact_id": 789
}

syncro_contacts_create

创建新联系人。

{
  "customer_id": 123,
  "name": "Jane Smith",
  "email": "[email protected]"
}

发票领域

syncro_invoices_list

按可选筛选条件列出发票。

{
  "customer_id": 123,
  "status": "sent",
  "since_date": "2024-01-01"
}

syncro_invoices_get

按 ID 获取指定发票。

{
  "invoice_id": 456
}

syncro_invoices_create

创建新发票。

{
  "customer_id": 123,
  "due_date": "2024-02-01"
}

syncro_invoices_email

将发票通过电子邮件发送给客户。

{
  "invoice_id": 456,
  "subject": "Your Invoice"
}

速率限制

Syncro API 的速率限制为每分钟 180 个请求。底层的 @wyre-technology/node-syncro 库会自动处理速率限制。

开发

# Install dependencies. The @wyre-technology/node-syncro SDK lives on GitHub
# Packages, so authenticate first:
export NODE_AUTH_TOKEN=$(gh auth token)
npm install

# Build
npm run build

# Run in development (stdio)
npm run dev

# HTTP refuses to start until CONDUIT_S2S_SECRET is a real secret
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http npm start

# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 MCP_TRANSPORT=http npm start

# Type check
npm run typecheck

# Lint
npm run lint

许可证

Apache-2.0