Customer Thermometer

Customer Thermometer MCP 服务

面向 AI 助手和 WYRE Conduit 网关的 MCP 服务，用于访问 Customer Thermometer 的客户反馈 / NPS 调查 API，包括温度计、收件人列表、发送和报告。

身份验证

Customer Thermometer 使用单个静态 API 密钥进行身份验证，该密钥可在账户的 Integration 设置中生成。此连接器支持“Super API key”（拥有完整账户访问权限）或权限范围更窄的“sub-API key”。

配置

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

环境变量	说明
CUSTOMERTHERMOMETER_API_KEY	Customer Thermometer 签发的 API 密钥。供 stdio 使用；当 AUTH_MODE=env 时也供 HTTP 使用。
MCP_TRANSPORT	stdio（默认）或 http。
AUTH_MODE	env（默认，读取上方的变量）或 gateway（API 密钥通过每个请求中的 X-CustomerThermometer-Api-Key 传入，绝不会回退到环境变量）。Docker 镜像和 Compose 文件默认使用 gateway。
CONDUIT_S2S_SECRET	HTTP 必需。用于校验 /mcp 上 X-Gateway-S2S 的 HMAC 密钥。使用 openssl rand -hex 32 生成。如果该变量为空或为已知占位值（changeme、your-s2s-secret、replace-with-a-real-secret 及其他公开示例），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。未设置密钥时，监听地址仅为 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。该标头的值为 t=<unix seconds>,v1=<hex>。<hex> 是对字面字符串 t=<unix seconds>（使用相同的 t= 前缀和时间戳）计算的 HMAC-SHA256，以 CONDUIT_S2S_SECRET 为密钥，并编码为 64 位小写十六进制字符。时间戳与服务器时钟的偏差必须在 300 秒以内。标头缺失或无效时，会返回 HTTP 401，且不会读取供应商凭据。

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-CustomerThermometer-Api-Key。该标头是该请求唯一的凭据来源。请求未提供该标头时会返回 401，且不会回退到 CUSTOMERTHERMOMETER_API_KEY。

请求限制

• HTTP 请求正文的大小上限为 256 KiB（262144 字节）。X-Gateway-S2S 校验通过后，若 Content-Length 超出上限，则返回包含 JSON-RPC 错误的 413；没有 Content-Length 的正文则由 MCP SDK 传输限制大小。未经身份验证的请求仍会先收到 401。
• tools/call 参数最多允许 10,000 个元素（任意深度的每个数组项和对象键均计为一个元素）。输入超过上限时会返回带有 isError 的工具结果，且不会分派执行。

这些限制用于应对 CVE-2026-111768 / GHSA-46jr-4wx8-v453（验证期间的内存耗尽）和 GHSA-f897-62hf-6gxq（缺少请求正文 / 批处理上限）。

工具

列表

• customerthermometer_get_thermometers - 列出账户中的所有调查模板（Thermometers）。
• customerthermometer_get_recipient_lists - 列出账户中的所有收件人列表。

收件人

• customerthermometer_add_recipient_to_list - 将收件人添加到列表。
• customerthermometer_unsubscribe_recipient - 将电子邮件地址添加到账户的退订列表。

发送

• customerthermometer_send_email - 向一位收件人发送一份 Email Thermometer 调查。
• customerthermometer_get_credits - 查看账户剩余的 Thermometer 发送额度。

报告

• customerthermometer_get_nps_value - 查看净推荐值，可按群发或日期范围筛选。
• customerthermometer_get_happiness_value - 查看幸福度百分比，可按群发或日期范围筛选。
• customerthermometer_get_blast_results - 查看原始调查回复，可按温度、群发或日期范围筛选。
• customerthermometer_get_comments - 查看回复中留下的自由文本评论，可按温度、群发或日期范围筛选。

返回 XML 的读取端点（getThermometers、getRecipientLists、getBlastResults、getComments）会采用通用方式解析，而不是映射到手写的架构。供应商的 API 文档没有公布这些响应的元素名称，因此解析后的结构会直接传递，不会冒险使用与实际响应不匹配的架构。

范围

这是一个 v1 接口，涵盖核心调查工作流：列出温度计和列表、添加和取消订阅收件人、发送调查，以及读取 NPS／幸福度／回复／评论报告。目前明确不在范围内的端点：logResponse 和 deleteResponse——这两个端点具有破坏性、价值较低，会修改或丢弃现有回复数据。如有需求，可在后续添加。

开发

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

Docker

容器内的镜像会监听 0.0.0.0（MCP_HTTP_HOST），并默认使用 AUTH_MODE=gateway。请将端口发布到回环地址并传入 S2S 密钥。在网关模式下，API 密钥会通过每个请求中的 X-CustomerThermometer-Api-Key 传入，不会从环境中读取。每个 /mcp 请求还必须包含有效的 X-Gateway-S2S 签名（参见HTTP 身份验证）。

docker build -t customer-thermometer-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  customer-thermometer-mcp

如果未设置 CONDUIT_S2S_SECRET，Compose 将拒绝启动；默认将 AUTH_MODE 设为 gateway，发布 127.0.0.1:8080:8080，且不会设置 CUSTOMERTHERMOMETER_API_KEY：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

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

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e CUSTOMERTHERMOMETER_API_KEY="$CUSTOMERTHERMOMETER_API_KEY" \
  -p 127.0.0.1:8080:8080 \
  customer-thermometer-mcp

在 CONDUIT_S2S_SECRET 为真实密钥之前，HTTP 服务会拒绝启动。未设置密钥的本地 HTTP 仅用于开发：它只绑定到 127.0.0.1，并会记录警告。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

MCP_ALLOW_INSECURE_DEV=1 npm run start:http