ScalePad

scalepad-mcp

适用于 ScalePad 平台的 MCP 服务，涵盖 Core、Lifecycle Manager、ControlMap、Backup Radar 和 Quoter。该服务基于 MCP SDK v2（2026-07-28 规范）原生构建，支持双时代服务：同一端点既能响应采用旧版 2025 年时代 initialize 握手的客户端，也能响应现代信封客户端。

架构

工具界面采用扁平结构：所有工具都会预先通过 tools/list 暴露，以兼容各种客户端。导航工具用于辅助发现，不会构成使用门槛。

工具	用途
scalepad_navigate	描述某个产品领域的工具（core、lifecycle-manager、controlmap、backup-radar、quoter），用于帮助和发现，不是前置条件
scalepad_status	显示凭据状态和可用领域

产品领域

领域	工具前缀	覆盖范围
core	scalepad_core_	统一平台数据（只读，仅限美国）：客户端、联系人、成员、站点、商机、硬件／SaaS 资产、产品目录、服务合同、工单、集成
lifecycle-manager	scalepad_lm_	客户互动／路线图工作流：计划、目标、会议、行动项、评估、交付成果、预算、合同、工作区
controlmap	scalepad_cm_	每个客户端的合规数据：风险、控制措施、证据、政策、框架、评估、行动项（地区：us、eu、ca、au）
backup-radar	scalepad_br_	只读备份健康状况和备份设备清单（地区：us、eu）
quoter	scalepad_quoter_	报价、目录、联系人、供应商和独立 OAuth 辅助工具（默认使用 ScalePad 托管的 Quoter API）

所有工具随时都可以调用；scalepad_navigate 只是汇总某个领域的工具。

凭据

一个 ScalePad API 密钥（由管理员在 ScalePad 应用中生成）即可用于所有产品；未激活订阅的产品对应端点会返回 402。

复制 .env.example，并设置以下变量。请将该文件中的 CONDUIT_S2S_SECRET 留空。

环境变量（AUTH_MODE=env，stdio／本地模式的默认值）

变量	是否必需	说明
SCALEPAD_API_KEY	stdio 和 AUTH_MODE=env 模式下必需	以 x-api-key 的形式转发至 api.scalepad.com
SCALEPAD_REGION	否	us（默认值）、eu、ca 或 au — 为 ControlMap（us／eu／ca／au）和 Backup Radar（us／eu）选择区域基础 URL；Core 和 Lifecycle Manager 仅限美国
QUOTER_CLIENT_ID	否	仅用于独立的 api.quoter.com OAuth 路径（Quoter Account > API Keys，仅限 Account Owner）
QUOTER_CLIENT_SECRET	否	与 QUOTER_CLIENT_ID 配套使用
MCP_TRANSPORT	否	stdio（默认值）或 http
AUTH_MODE	否	gateway（Docker 镜像和 Compose 的默认值）或 env。Gateway 模式要求每个 /mcp 请求都携带 X-ScalePad-Api-Key，且不会回退到 SCALEPAD_*。env 仅在 S2S 身份验证成功后使用这些变量。
CONDUIT_S2S_SECRET	HTTP 模式下必需	服务间密钥。如果该值为空或是已知占位符（如 changeme、your-s2s-secret 及类似的示例复制值），HTTP 服务会记录错误并以非零状态码退出。未设置此变量时，Compose 不会启动。切勿提交真实值。此值绝不会被记录。
MCP_ALLOW_INSECURE_DEV	否	仅在本地开发时设为 1，以便在没有 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告，且不会强制执行 X-Gateway-S2S。即使 MCP_HTTP_HOST 是 0.0.0.0 这样的宽泛地址，监听地址也会强制设为 127.0.0.1。仍会拒绝已知的占位符密钥。
MCP_HTTP_HOST	否	当 MCP_TRANSPORT=http 且已设置 CONDUIT_S2S_SECRET 时使用的绑定地址。未设置时，服务会绑定到 127.0.0.1。容器镜像会将其设为 0.0.0.0。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。

/health 和 /healthz 无需身份验证，也不会读取凭据。stdio 传输方式不使用 CONDUIT_S2S_SECRET。

网关请求头（AUTH_MODE=gateway，托管部署）

请求头	必填
X-Gateway-S2S	是，当设置了 CONDUIT_S2S_SECRET 时
X-ScalePad-Api-Key	是
X-ScalePad-Region	否
X-Quoter-Client-Id	否
X-Quoter-Client-Secret	否

在网关模式下，凭据会根据这些请求头按请求绑定。不带 X-ScalePad-Api-Key 的 /mcp 请求会在任何 MCP 处理开始前被拒绝，并返回 401 JSON-RPC 错误；不会回退到环境变量凭据。/health 仍无需身份验证。

X-Gateway-S2S 签名

当 MCP_TRANSPORT=http 且设置了 CONDUIT_S2S_SECRET 时，每个 /mcp 请求都必须包含 X-Gateway-S2S。如果缺少该请求头或其无效，则会在读取供应商凭据前返回 401。

请求头的值为 t=<unix seconds>,v1=<hex>。v1 是对 ASCII 字符串 t=<unix seconds> 计算的 HMAC-SHA256（64 个小写十六进制字符），密钥为 CONDUIT_S2S_SECRET。与服务器时钟相差超过 300 秒的时间戳会被拒绝。

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}`;

传输方式

• stdio（默认）：node dist/index.js — 用于 Claude Desktop / CLI。不使用 CONDUIT_S2S_SECRET。
• HTTP：MCP_TRANSPORT=http node dist/index.js — 提供 /mcp（双时代，legacy: 'stateless'）、/health 和 /healthz。在 CONDUIT_S2S_SECRET 为有效密钥之前拒绝启动。MCP_HTTP_PORT 默认值为 8080。设置密钥后，MCP_HTTP_HOST 会生效；如果未设置，则默认为 127.0.0.1。如果未设置密钥，则只有通过 MCP_ALLOW_INSECURE_DEV=1 才能启动，且监听地址仅为 127.0.0.1。

开发

export NODE_AUTH_TOKEN=$(gh auth token)   # GitHub Packages read access
npm ci
npm run build       # tsup (transpile-only; domains stay lazily importable)
npm test            # vitest (HTTP layer: health, 401 gate, dual-era tools/list, fail-closed S2S)
npm run smoke       # dual-era smoke against dist/index.js (loopback, insecure-dev bypass)
npm run typecheck

领域处理器位于 src/domains/<slug>.ts，每个文件都导出 export const handler: DomainHandler（参见 src/utils/types.ts），并通过 src/domains/index.ts 延迟加载。

未设置密钥时的本地 HTTP：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

Docker

镜像会在容器内的 0.0.0.0（MCP_HTTP_HOST）上监听，并默认使用 AUTH_MODE=gateway。只有启动时要求必须配置有效的 CONDUIT_S2S_SECRET，该绑定才是安全的。请将端口发布到回环地址并传入 S2S 密钥。在网关模式下，ScalePad 凭据通过每个请求的请求头传入，不会从环境中读取。

docker build --build-arg NODE_AUTH_TOKEN=$(gh auth token) -t scalepad-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  scalepad-mcp

未设置 CONDUIT_S2S_SECRET 时，Compose 会拒绝启动。网关服务不会设置 SCALEPAD_API_KEY、QUOTER_CLIENT_ID 或 QUOTER_CLIENT_SECRET，也不会使用 env_file，因此项目的 .env 无法向容器注入静态供应商凭据。Compose 仍会从该文件插值获取 CONDUIT_S2S_SECRET。它会发布 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

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

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e SCALEPAD_API_KEY=your-value \
  -e SCALEPAD_REGION=us \
  -p 127.0.0.1:8080:8080 \
  scalepad-mcp

未设置密钥时的本地 HTTP 仅用于开发。它只绑定到 127.0.0.1（非回环地址的 MCP_HTTP_HOST，包括 0.0.0.0，都会被覆盖），并会记录警告：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

该镜像默认使用 AUTH_MODE=gateway，用于部署在 WYRE MCP 网关之后的托管环境。

许可证

Apache-2.0 — 详见 LICENSE。