Mailprotector

mailprotector-mcp

适用于 Mailprotector 的 MCP 服务——面向 MSP 的电子邮件安全管理（CloudFilter、Bracket、SafeSend、XtraMail）：客户、域、用户、隔离区、允许/阻止规则、日志、配置，以及通过路由器提供的完整长尾 API。

基于 MCP 2026-07-28 规范，通过拆分的 v2 SDK （@modelcontextprotocol/server / /node / /client ^2.0.0-beta.5）构建，并采用双时代服务模式：一个共享的 McpServerFactory 位于 createMcpHandler({ legacy: 'stateless' }) 之后，可同时响应采用 2025 时代 initialize 握手的客户端（目前为 WYRE 网关）和现代 2026-07-28 信封客户端——所有调用方看到的工具集均为相同且确定的 22 项。仅以 GHCR 容器形式发布（不提供 MCPB 包）。

工具（22 项一等工具 + 路由的长尾工具）

路由器：mailprotector_status、mailprotector_list_categories、 mailprotector_list_category_tools、mailprotector_execute_tool。

提升的一类读取操作：mailprotector_customers_list/get、mailprotector_domains_list/get、 mailprotector_users_list/get/find_by_address、mailprotector_user_groups_list、 mailprotector_messages_list、mailprotector_allow_block_rules_list、 mailprotector_logs_list、mailprotector_configuration_get。

提升的一类写入操作：mailprotector_customers_create、mailprotector_domains_create、 mailprotector_messages_release / release_many（⚠ 高影响）， mailprotector_allow_block_rules_create（⚠ 高影响），以及 ⚠ 破坏性操作——不可逆的 mailprotector_allow_block_rules_delete。

路由器类别（通过 mailprotector_execute_tool 路由的 52 项操作）： resellers（增删改查）、customers（更新/删除）、domains （更新/删除/移动/别名）、user_groups（增删改查 + 服务）、users （创建/批量创建/更新/删除/重置密码/别名）、managers（增删改查 + 通知目标）、configuration（更新）、statements、 email_routing（域|用户组的目标/源）、user_syncs（增删改查 + 计划 + 筛选条件）、 notifications（用户通知目标）、results（按代码查找）。所有路由的删除操作均为 ⚠ 破坏性操作，且需要确认；使用 mailprotector_list_category_tools 发现架构。

作用域工具

Mailprotector 的层级为 Provider → Reseller → Customer → Domain → User Group → User， 许多操作可在多个作用域下执行。作用域工具接受 scope （reseller | customer | domain | user_group | user，具体取值因工具而异）以及 scope_id； 当 scope 为 "reseller" 时，scope_id 默认为绑定的 reseller。

删除确认（MRTR 询问机制）

每项删除操作都会经过 SDK v2 MRTR 接口：处理程序返回 input_required，交互式客户端会显示确认提示，拒绝后则取消删除。未声明具备询问能力的调用方——包括 WYRE Conduit 网关等无状态的 2025 时代调用方——会按约定继续执行：此处的询问机制纯属附加功能，网关则通过自身的服务端逐工具分类门控来控制破坏性工具的访问。

凭据

环境变量（env 模式）	网关标头（AUTH_MODE=gateway）	备注
MAILPROTECTOR_API_KEY	X-Mailprotector-Api-Key	每个经理角色各有一个，从 Web 控制台的个人资料页面获取。以 Authorization: Bearer 形式发送。
MAILPROTECTOR_RESELLER_ID	X-Mailprotector-Reseller-Id	MSP 的经销商 ID — 作用域工具的默认范围。
MAILPROTECTOR_BASE_URL（可选）	—	默认为 https://emailservice.io。

复制 .env.example。网关 Compose 服务不会加载 MAILPROTECTOR_API_KEY 或 MAILPROTECTOR_RESELLER_ID。

变量	必需	描述
MCP_TRANSPORT	否	stdio（默认）或 http。容器镜像设置为 http。
AUTH_MODE	否	gateway（Docker 镜像和 Compose）或 env。网关模式要求每个 /mcp 请求都携带 X-Mailprotector-Api-Key 和 X-Mailprotector-Reseller-Id，且绝不会回退到 MAILPROTECTOR_*。env 仅在 S2S 身份验证成功后使用这些变量。未设置时默认为 env（stdio 和单租户 HTTP）。
CONDUIT_S2S_SECRET	HTTP 必需	服务到服务密钥。若该值为空或为已知占位值（changeme、secret、replace-me、replace-with-a-real-secret、your-s2s-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。

在网关模式下，若请求缺少任一凭据标头（或经销商 ID 不是数字）， 则会在 MCP 处理程序运行前返回 401（JSON-RPC 错误 -32001）——不会 回退到环境凭据。

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-Mailprotector-Api-Key: $MAILPROTECTOR_API_KEY" \
  -H "X-Mailprotector-Reseller-Id: $MAILPROTECTOR_RESELLER_ID" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 模式下，/mcp 还要求 X-Mailprotector-Api-Key 和 X-Mailprotector-Reseller-Id。这些标头是该请求唯一的凭据来源。AUTH_MODE=env 仍要求已签名的 X-Gateway-S2S 标头，然后使用环境中的 MAILPROTECTOR_API_KEY 和 MAILPROTECTOR_RESELLER_ID。

运行

export NODE_AUTH_TOKEN=$(gh auth token)   # GitHub Packages auth for @wyre-ai/* + @wyre-technology/*
npm install
npm run build
node dist/index.js                        # stdio (default; no S2S secret)
# HTTP refuses to start until CONDUIT_S2S_SECRET is a real secret
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http node dist/index.js
# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 MCP_TRANSPORT=http node dist/index.js
node scripts/smoke-dual-era.mjs           # proves both protocol eras serve the same tools

Docker（根据机群规定使用 linux/amd64）。镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），且默认使用 AUTH_MODE=gateway。将端口发布到环回地址，并传入有效的 S2S 密钥。在网关模式下，Mailprotector 凭据会随每个请求以标头形式传入，不会从环境中读取。

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

未设置 CONDUIT_S2S_SECRET 时，Compose 会拒绝启动。网关服务会设置 AUTH_MODE=gateway，不会注入 MAILPROTECTOR_API_KEY 或 MAILPROTECTOR_RESELLER_ID，并发布 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍要求 S2S 密钥，然后使用 MAILPROTECTOR_API_KEY 和 MAILPROTECTOR_RESELLER_ID。它与上面的网关 Compose 服务相互独立。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e MAILPROTECTOR_API_KEY=... \
  -e MAILPROTECTOR_RESELLER_ID=... \
  -p 127.0.0.1:8080:8080 \
  mailprotector-mcp

Wire 说明（预期的双时代行为）

• 旧时代的 POST 响应采用 SSE 帧格式（text/event-stream）——解析最后一行 data:。
• 旧时代的 GET/DELETE 会话操作会返回 405：无状态服务不支持会话。

许可证

Apache-2.0