Printix

Printix MCP 服务

面向 AI 助手和 WYRE Conduit 网关的 MCP 服务，用于访问 Printix Cloud Print API（现隶属于 Tungsten Automation），支持查询打印机／队列、站点、工作站，以及只读查询用户／群组。

身份验证

Printix 按租户签发一对 client_id／client_secret，可通过 Printix Administrator 控制面板获取。WYRE 级别没有统一的集成凭据；每个由 MSP 管理的客户租户都需提供自己的凭据对，并且每个租户一次只能有一对凭据处于有效状态（签发新凭据会使之前的凭据失效）。

这对凭据会通过 POST https://auth.printix.net/oauth/token 交换为有效期较短（约 1 小时）的 OAuth 访问令牌（grant_type=client_credentials，client_id／client_secret 放在表单正文中）。本服务会在内部处理这项交换，并在令牌过期或被拒绝时以相同方式重新进行身份验证——Printix 不支持刷新令牌（已于 2024-12-17 移除；文档将此前的刷新令牌方案描述为“非标准 OAuth2”）。

调用方只需提供以下两个长期有效的值，无需提供短期访问令牌。

Printix Cloud Print API 中的每个资源都位于租户路径下（/cloudprint/tenants/{tenantId}/...）。本服务会针对每对凭据调用 API 根路径一次，以解析租户 ID（GET /cloudprint 是文档所述的 HATEOAS 入口点，会“返回可访问租户的链接列表”），并将其与访问令牌一同缓存。

配置

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

环境变量	描述
PRINTIX_CLIENT_ID	从 Printix Administrator 控制面板获取的客户端 ID。供 stdio 使用，也供 AUTH_MODE=env 时的 HTTP 使用。
PRINTIX_CLIENT_SECRET	与客户端 ID 配对的客户端密钥。供 stdio 使用，也供 AUTH_MODE=env 时的 HTTP 使用。
MCP_TRANSPORT	stdio（默认）或 http。
AUTH_MODE	env（默认；读取 PRINTIX_*）或 gateway（每个请求通过 X-Printix-Client-ID 和 X-Printix-Client-Secret 传入凭据，且绝不会回退到环境变量）。Docker 镜像和 Compose 文件默认使用 gateway。
CONDUIT_S2S_SECRET	启动 HTTP 传输所必需。用于根据 /mcp 上的 X-Gateway-S2S 进行验证的 HMAC 密钥。使用 openssl rand -hex 32 生成。如果该值为空或是已知占位符（例如 replace-with-a-real-secret），进程会记录错误并以非零状态码退出。此值绝不会写入日志。未设置时，Compose 不会启动。
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	设置了有效的 CONDUIT_S2S_SECRET 时使用的绑定地址。未设置时默认为 127.0.0.1。容器镜像设置为 0.0.0.0。未设置密钥时，监听器会强制绑定到 127.0.0.1。
MCP_HTTP_PORT	HTTP 端口。默认为 8080。
LOG_LEVEL	debug | info（默认）| warn | error。

/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-Printix-Client-ID: your-client-id' \
  -H 'X-Printix-Client-Secret: your-client-secret' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-Printix-Client-ID 和 X-Printix-Client-Secret。这些标头是该请求唯一的凭据来源。请求缺少任一标头时会返回 401，且不会回退使用进程环境中的 PRINTIX_CLIENT_ID / PRINTIX_CLIENT_SECRET。

在 AUTH_MODE=env（单租户 HTTP）模式下，/mcp 仍要求有效的 X-Gateway-S2S 标头。供应商凭据来自 PRINTIX_CLIENT_ID 和 PRINTIX_CLIENT_SECRET。

工具

租户

• printix_get_tenant - 获取此凭据对所属的租户（租户 ID 及其 API 根链接）。

打印机 / 队列

• printix_list_printers - 列出打印队列/打印机，可按需筛选并分页。
• printix_get_printer - 获取单个打印机/队列及其属性/功能。

站点

• printix_list_sites - 分页列出站点（实体位置）。
• printix_get_site - 获取单个站点的详细信息。

工作站

• printix_list_workstations - 分页列出工作站监控数据。
• printix_get_workstation - 获取单个工作站的详细信息。

用户（只读）

• printix_list_users - 列出用户，可按查询/角色筛选并分页。
• printix_get_user - 按 ID 查找单个用户。

组（只读）

• printix_list_groups - 分页列出/搜索组。
• printix_get_group - 获取单个组的详细信息。

范围

这是一个 v1 功能集，涵盖 Printix Cloud Print API 中面向 MSP 的机群监控/管理价值，不涉及终端用户打印作业工作流。目前明确不在范围内的内容：

• 打印作业（提交/检索/删除）- 属于终端用户打印工作流，不属于 MSP 管理价值。
• 卡片（注册/搜索/删除）- 小众的身份验证卡功能。
• 网络和SNMP 配置- 配置工作量大、风险较高的写入功能。
• 用户和组变更（创建/删除）- 会产生实际的账户管理影响（许可、移除访问权限）；用户和组均仅开放读取（列表/获取）。之后值得单独审慎决策。

一旦明确存在 MSP 工作流需求，可在后续添加这些功能。

此服务基于 Cloud Print API（printix.github.io）构建，而非范围更窄的 Partner API（printix.bitbucket.io）；后者面向租户配置，而非日常机群管理。

开发

npm install
npm run build
npm test
npm run lint   # tsc --noEmit

# HTTP refuses to start until CONDUIT_S2S_SECRET is set
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

Docker

镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），并默认使用 AUTH_MODE=gateway。将端口发布到回环地址，并传入 S2S 密钥。在 gateway 模式下，Printix 凭据通过每个请求的标头传入，不会从环境中读取。

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

如果未设置 CONDUIT_S2S_SECRET，Compose 将拒绝启动。仓库中提供的服务使用 gateway 模式：它不会设置 PRINTIX_CLIENT_ID 或 PRINTIX_CLIENT_SECRET，也不使用 env_file，因此项目 .env 无法向容器注入静态供应商凭据。它将端口发布到 127.0.0.1:8080:8080。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍要求 S2S 密钥，然后使用 PRINTIX_CLIENT_ID 和 PRINTIX_CLIENT_SECRET。不要将其用于 gateway Compose 服务。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e PRINTIX_CLIENT_ID=your-client-id \
  -e PRINTIX_CLIENT_SECRET=your-client-secret \
  -p 127.0.0.1:8080:8080 \
  printix-mcp

不带密钥的本地 HTTP 仅用于开发。它只绑定 127.0.0.1（若设置了更宽泛的 MCP_HTTP_HOST，则会覆盖该设置并记录日志），并会记录警告：

MCP_ALLOW_INSECURE_DEV=1 npm run start:http