Mailprotector

mailprotector-mcp

Mailprotector 向けの MCP サーバーです。MSP 向けにメールセキュリティを管理します（CloudFilter、Bracket、SafeSend、XtraMail）。顧客、ドメイン、ユーザー、隔離、許可／ブロックルール、ログ、設定、およびルーター経由で利用できる API の全エンドポイントに対応しています。

分割された v2 SDK（@modelcontextprotocol/server / /node / /client ^2.0.0-beta.5）を使用し、MCP 2026-07-28 仕様に基づいて構築されています。2 世代のクライアントに対応しており、createMcpHandler({ legacy: 'stateless' }) の背後にある単一の McpServerFactory が、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（CRUD）、customers（更新／削除）、domains（更新／削除／移動／エイリアス）、user_groups（CRUD + サービス）、users（作成／一括作成／更新／削除／パスワードリセット／エイリアス）、managers（CRUD + 通知先）、configuration（更新）、statements、email_routing（domain|user_group の宛先／送信元）、user_syncs（CRUD + スケジュール + フィルター）、notifications（ユーザー通知先）、results（find_by_code）。ルーター経由の削除操作はすべて⚠ 破壊的で、確認が必須です。スキーマを確認するには 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 の既定値はバインドされたリセラーです。

削除の確認（MRTR エリシテーション）

すべての削除は SDK v2 の MRTR シームを通じて実行されます。ハンドラーは input_required を返し、対話型クライアントには確認プロンプトが表示され、拒否すると削除はキャンセルされます。エリシテーション機能を宣言していない呼び出し元（WYRE Conduit ゲートウェイなどのステートレスな 2025 年世代の呼び出し元を含む）では、連携契約に従って削除を続行します。ここでのエリシテーションは追加機能としてのみ提供され、ゲートウェイは独自のサーバー側のツールごとの分類ゲートによって、破壊的なツールへのアクセスを制御します。

認証情報

環境変数（env モード）	ゲートウェイヘッダー（AUTH_MODE=gateway）	備考
MAILPROTECTOR_API_KEY	X-Mailprotector-Api-Key	manager-role ごとに、ウェブコンソールのプロフィールページから取得します。Authorization: Bearer として送信されます。
MAILPROTECTOR_RESELLER_ID	X-Mailprotector-Reseller-Id	MSP の reseller 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	いいえ	CONDUIT_S2S_SECRET がなくても HTTP を起動する場合に限り、ローカル開発用として厳密に 1 を設定します。プロセスは警告をログに記録し、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 を使用しません。

ゲートウェイモードで、いずれかの認証情報ヘッダーが欠けている場合（または reseller id が数値でない場合）、MCP ハンドラーの実行前に 401（JSON-RPC エラー -32001）が返されます。env の認証情報にフォールバックすることはありません。

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（小文字の 16 進数 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