SalesBuildr

SalesBuildr MCP 服务

一个用于集成 SalesBuildr 报价与销售平台的 Model Context Protocol（MCP）服务。采用决策树架构，可提供特定领域的工具，同时避免让大模型不堪重负。

架构

该服务采用决策树模式：

1. 在根节点，仅提供 salesbuildr_navigate
2. 用户选择一个领域（companies、contacts、products、opportunities、quotes）
3. 随后提供该领域专用的工具以及 salesbuildr_back
4. 工具调用会路由到与 SalesBuildr API 交互的领域处理程序

交互式报价卡片（MCP Apps）

在 MCP Apps 宿主（Claude Desktop/web）中，salesbuildr_quotes_get 会呈现为交互式只读报价卡片，显示标题、状态、公司/联系人、日期、明细项和总计；在其他宿主中，纯 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）进行品牌定制——无需重新构建。

领域

领域	工具	描述
companies	5	公司/账户管理（列出、获取、创建、更新、删除）
contacts	5	联系人管理（列出、获取、创建、更新、删除）
products	2	产品目录（列出、获取）
opportunities	4	销售管道（列出、获取、创建、更新）
quotes	3	带明细项的报价管理（列出、获取、创建）

一键部署

重要

点击之前请注意： 此服务依赖 @wyre-technology/node-salesbuildr， 该包托管于 GitHub Packages npm 注册表。GitHub Packages 不允许匿名访问—— 即使该包是公开的，每次 npm install 也都需要令牌。云端构建器会为你运行 npm install， 因此你必须提供令牌，否则构建会因 npm error 401 Unauthorized ... npm.pkg.github.com 而失败。

1. 创建一个具有 read:packages 权限范围的 GitHub Personal Access Token （经典令牌）。 任何 GitHub 账户都可以——读取其公开包无需加入 wyre-technology 组织。
2. 部署流程提示时，将令牌添加为构建变量：
   • Cloudflare Workers → 将名为 NODE_AUTH_TOKEN 的构建变量设为你的 PAT （Workers → Settings → Build → Variables and Secrets）。
   • DigitalOcean App Platform → 设置名为 GITHUB_TOKEN 的加密环境变量， 并将作用范围设为 Build Time，值为你的 PAT（Dockerfile 会读取该变量以完成安装）。

安装

此软件包发布于 GitHub Packages npm 注册表，即使是公开软件包也需要令牌。完成一次身份验证后即可安装：

# Authenticate npm to GitHub Packages (token needs the read:packages scope)
export NODE_AUTH_TOKEN=$(gh auth token)   # or a PAT with read:packages

npm install @wyre-ai/salesbuildr-mcp

仓库中的 .npmrc 已将 @wyre-technology 作用域指向 GitHub Packages，并从 NODE_AUTH_TOKEN 读取令牌，因此无需进行其他配置。

配置

复制 .env.example。Stdio 和 AUTH_MODE=env 会读取 SalesBuildr 变量。网关模式不会读取。

环境变量

变量	必需	默认值	描述
SALESBUILDR_API_KEY	用于 stdio 和 AUTH_MODE=env	-	SalesBuildr API 密钥
SALESBUILDR_BASE_URL	否	库默认值	租户专属基础 URL（例如 https://mytenant.salesbuildr.com）
MCP_TRANSPORT	否	stdio	stdio 或 http
MCP_HTTP_PORT	否	8080	HTTP 服务端口
MCP_HTTP_HOST	否	设置了真实密钥时为 0.0.0.0	设置 CONDUIT_S2S_SECRET 时使用的绑定地址。容器镜像会设置为 0.0.0.0。未设置密钥时，MCP_ALLOW_INSECURE_DEV=1 会改为绑定 127.0.0.1。
AUTH_MODE	否	镜像外为 env	env 或 gateway。容器镜像和 Compose 的默认值为 gateway。Gateway 模式要求每个 /mcp 请求都包含 X-SalesBuildr-API-Key，且绝不会回退使用 SALESBUILDR_*。
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 会导致启动被拒绝。已知占位密钥仍会被拒绝。

/health 和 /healthz 无需身份验证，也不会读取凭据。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-SalesBuildr-API-Key。该标头是此请求唯一的凭据来源。缺少该标头的请求会返回 401，且不会从环境变量读取 SALESBUILDR_API_KEY。

Stdio 模式（Claude Desktop）

将以下内容添加到 Claude Desktop 配置（claude_desktop_config.json）中：

{
  "mcpServers": {
    "salesbuildr": {
      "command": "npx",
      "args": ["@wyre-ai/salesbuildr-mcp"],
      "env": {
        "SALESBUILDR_API_KEY": "your-api-key"
      }
    }
  }
}

HTTP 模式（Gateway）

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http AUTH_MODE=gateway node dist/index.js

在 gateway 模式下，通过请求标头传递凭据。Gateway 还会使用 X-Gateway-S2S 对每个请求进行签名（参见HTTP 身份验证）：

X-Gateway-S2S: t=<unix seconds>,v1=<hex hmac-sha256>
X-SalesBuildr-API-Key: your-api-key

Docker

镜像在容器内的 0.0.0.0（MCP_HTTP_HOST）上监听，且默认使用 AUTH_MODE=gateway。请将端口发布到环回地址，并传入真实的 S2S 密钥。在 gateway 模式下，SalesBuildr API 密钥会随每个请求通过 X-SalesBuildr-API-Key 传入，不会从环境变量读取。

docker run -d \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/salesbuildr-mcp:latest

若未设置 CONDUIT_S2S_SECRET，Compose 会拒绝启动；它会设置 AUTH_MODE=gateway，不会设置 SALESBUILDR_API_KEY 或 env_file，并发布 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

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

docker run -d \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e SALESBUILDR_API_KEY=your-api-key \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/salesbuildr-mcp:latest

不使用密钥的本地 HTTP 仅适用于开发环境。它会绑定 127.0.0.1 并记录警告。使用非环回地址的 MCP_HTTP_HOST 会导致启动退出：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

开发

# Install dependencies
npm install

# Run tests
npm test

# Type check
npm run typecheck

# Build
npm run build

# Run locally (stdio)
SALESBUILDR_API_KEY=your-key npm start

# Run locally (HTTP). Refuses to start until CONDUIT_S2S_SECRET is a real secret.
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http SALESBUILDR_API_KEY=your-key npm start

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

许可证

Apache-2.0