SpamTitan

SpamTitan MCP 服务

用于 SpamTitan 邮件安全的模型上下文协议（MCP）服务。支持 AI 助手管理隔离区、维护允许列表和阻止列表，以及查看邮件筛选统计信息。

这是一个 模型上下文协议（MCP） 服务，可将 Claude（或任何兼容 MCP 的 AI）连接到你的 SpamTitan 环境。

属于 MSP Claude Plugins 生态系统的一部分——这是一个不断扩展的 MSP 技术栈 AI 集成套件。由 MSP 为 MSP 打造。

安装

npm install @wyre-ai/spamtitan-mcp

配置

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

变量	必填	说明
SPAMTITAN_API_KEY	stdio 和 AUTH_MODE=env 模式下必填	SpamTitan API 密钥
SPAMTITAN_BASE_URL	否	SpamTitan 实例 URL，包括任何路径前缀（例如 https://mail.example.com/spamtitan/）。默认值为 https://api-spamtitan.titanhq.com。在网关模式下，每个请求中的 X-SpamTitan-Base-URL 标头优先。
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	gateway（Docker 镜像和 Compose）或 env。网关模式要求每个 /mcp 请求都携带 X-SpamTitan-API-Key，且不会回退到 SPAMTITAN_API_KEY。env 模式仅在 S2S 身份验证成功后使用该变量。未设置时默认为 env（stdio 和单租户 HTTP）。
CONDUIT_S2S_SECRET	HTTP 模式下必填	服务间密钥。当此变量为空或为已知占位符（changeme、secret、replace-me、your-s2s-secret、replace-with-a-real-secret 及其他示例值）时，HTTP 服务会记录错误并以非零状态码退出。使用 openssl rand -hex 32 生成密钥。未设置此变量时，Compose 不会启动。此值绝不会写入日志。
MCP_ALLOW_INSECURE_DEV	否	仅在本地开发时设为 1，以便在未设置 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告、不强制验证 X-Gateway-S2S，且仅绑定到 127.0.0.1。如果 MCP_HTTP_HOST 不是回环地址，则拒绝启动。已知占位符密钥仍会导致启动失败。
MCP_HTTP_HOST	否	设置了有效 CONDUIT_S2S_SECRET 时的绑定地址。未设置时使用 0.0.0.0，即历史容器绑定地址。镜像和 Compose 会在容器内将其设为 0.0.0.0。
MCP_HTTP_PORT	否	HTTP 端口。默认值为 8080。

/health 和 /healthz 无需身份验证，也不会读取凭据。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>，其中十六进制值是以 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-SpamTitan-API-Key: $SPAMTITAN_API_KEY" \
  -H "X-SpamTitan-Base-URL: $SPAMTITAN_BASE_URL" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-SpamTitan-API-Key。该标头是此请求唯一的 API 密钥来源。X-SpamTitan-Base-URL 为可选项；若存在，则用于选择租户实例。AUTH_MODE=env 仍要求提供经过签名的 X-Gateway-S2S 标头，然后使用环境变量中的 SPAMTITAN_API_KEY 和 SPAMTITAN_BASE_URL。

用法

使用 Claude Desktop 运行

将以下内容添加到 Claude Desktop 的 claude_desktop_config.json 中：

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

使用 Claude Code（CLI）运行

claude mcp add spamtitan-mcp \
  -e SPAMTITAN_API_KEY=your-value \
  -- npx -y @wyre-ai/spamtitan-mcp

Docker

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

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

如果未设置 CONDUIT_S2S_SECRET 或其值为空，Compose 将拒绝启动。网关服务会设置 AUTH_MODE=gateway，不会注入 SPAMTITAN_API_KEY 或 SPAMTITAN_BASE_URL，并发布 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，然后使用 SPAMTITAN_API_KEY 和 SPAMTITAN_BASE_URL。它与上述网关 Compose 服务分开。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e SPAMTITAN_API_KEY=your-value \
  -e SPAMTITAN_BASE_URL=https://mail.example.com/spamtitan/ \
  -p 127.0.0.1:8080:8080 \
  spamtitan-mcp

不使用密钥的本地 HTTP 仅适用于开发环境。它会绑定到 127.0.0.1 并记录警告。若 MCP_HTTP_HOST 不是回环地址（包括镜像默认值 0.0.0.0），启动将退出：

MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_ALLOW_INSECURE_DEV=1 npm start

可用域

列表

管理允许列表和阻止列表

隔离区

查看和管理邮件隔离区

统计信息

邮件过滤统计信息和报告

功能

• 交互式隔离邮件卡片（MCP Apps，SEP-1865） — 在 MCP Apps 宿主（Claude Desktop/web）中，spamtitan_get_message 会呈现为只读交互式卡片；在其他宿主中的纯 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）进行品牌化，无需重新构建。编辑 ui/ 后，使用 npm run build:ui 重新构建卡片包。

开发

# Clone the repository
git clone https://github.com/WYRE-AI/spamtitan-mcp.git
cd spamtitan-mcp

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

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

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

贡献

欢迎贡献！如果存在 CONTRIBUTING.md，请参阅该文件；也可以提出 issue 讨论更改。

许可证

根据 Apache License, Version 2.0 授权。详情请参阅 LICENSE。