Spanning Cloud Backup

Spanning Cloud Backup MCP サーバー

Model Context Protocol サーバーとして、 Spanning Cloud Backup API を Claude やその他の MCP クライアントに公開します。

機能

M365、Google Workspace、Salesforce のテナントにおける SaaS バックアップの状況を AI アシスタントに直接提示します。バックアップ対象のユーザーの一覧表示、対象サービスの確認、バックアップ履歴の参照、復元のキュー登録、管理者アクティビティとライセンス使用状況の監査を行えます。

• インタラクティブなバックアップ状況カード（MCP Apps、SEP-1865）：spanning_get_user は、MCP Apps ホスト（Claude Desktop/web）で読み取り専用のインタラクティブカードとして表示されます。ユーザーのバックアップ状況、ライセンス状態、最終バックアップ、サービスごとの対象範囲が表示されます。デフォルトでは中立的なデザインで、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）でブランドに合わせて変更できます。その他のホストでのプレーンな JSON の動作に変更はありません。ui/ を編集した後は、npm run build:ui で埋め込みカードを再ビルドしてください。

ツール

ツール	目的
spanning_list_users	組織内のバックアップ対象ユーザーを一覧表示します
spanning_get_user	1 人のユーザーの詳細を取得します
spanning_list_services	ユーザーが対象となっているサービスを一覧表示します
spanning_list_backups	ユーザーとサービスのバックアップ実行履歴を一覧表示します
spanning_queue_restore	復元をキューに登録します（破壊的操作 — 確認が必要です）
spanning_get_restore_status	復元の進行状況を確認します
spanning_list_audit_log	管理者監査ログ（期間の入力を求めます）
spanning_get_license_usage	使用中のライセンス数と購入済みライセンス数を確認します
spanning_status	サーバーの状態／稼働状況

認証情報

.env.example をコピーし、以下の変数を設定してください。サンプル内の CONDUIT_S2S_SECRET は空のままにしてください。実際のシークレットは決してコミットしないでください。

ローカル（env モード）

export SPANNING_PLATFORM="m365"        # or "gws" or "salesforce"
export SPANNING_ADMIN_EMAIL="..."
export SPANNING_API_TOKEN="..."

stdio トランスポートはこれらの変数を読み取り、CONDUIT_S2S_SECRET は使用しません。

HTTP トランスポート

MCP_TRANSPORT=http の場合、CONDUIT_S2S_SECRET が必要です。空の場合、または既知のプレースホルダー（changeme、change-me、secret、placeholder、example、replace-me、replace-with-a-real-secret、your-secret、your-s2s-secret、s2s-secret）の場合、プロセスはエラーをログに記録して、ゼロ以外の終了コードで終了します。シークレットの値がログに記録されることはありません。openssl rand -hex 32 を使って生成してください。

MCP_ALLOW_INSECURE_DEV=1 はローカル開発専用です。CONDUIT_S2S_SECRET なしで HTTP を起動し、警告をログに記録します。X-Gateway-S2S の確認は行わず、127.0.0.1 のみでリッスンします。ループバック以外の MCP_HTTP_HOST（0.0.0.0 を含む）は 127.0.0.1 に上書きされ、その上書きがログに記録されます。既知のプレースホルダーシークレットは引き続き拒否されます。

MCP_HTTP_HOST が未設定の場合、デフォルトは 127.0.0.1 です。CONDUIT_S2S_SECRET が設定されている場合、MCP_HTTP_HOST の設定が適用されます。コンテナーイメージでは MCP_HTTP_HOST=0.0.0.0 と AUTH_MODE=gateway が設定されています。

X-Gateway-S2S

実際の 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}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

ホスト型（ゲートウェイモード）

AUTH_MODE=gateway（Docker イメージおよび Compose のデフォルト）では、すべての /mcp リクエストに次の 3 つのヘッダーが必要です。プロセス環境内の SPANNING_* へのフォールバックはありません。

• X-Spanning-Platform（必須。m365 | gws | salesforce のいずれか）
• X-Spanning-Admin-Email（必須）
• X-Spanning-API-Token（必須、シークレット）

これらのヘッダーが 1 つでも欠けているリクエストには、HTTP 401 が返されます。上記の署名付き curl にこれらを追加してください。ゲートウェイの Compose サービスでは、SPANNING_PLATFORM、SPANNING_ADMIN_EMAIL、SPANNING_API_TOKEN は設定されません。

/health は引き続き認証なしで利用でき、認証情報を読み取りません。

シングルテナント HTTP（AUTH_MODE=env）

/mcp には引き続き、有効な X-Gateway-S2S ヘッダーが必要です。ベンダーの認証情報は SPANNING_PLATFORM、SPANNING_ADMIN_EMAIL、SPANNING_API_TOKEN から取得します。これらはそのプロセスに渡してください。ゲートウェイの Compose サービスには追加しないでください。

変数	必須	説明
SPANNING_PLATFORM	stdio および AUTH_MODE=env	m365、gws、または salesforce
SPANNING_ADMIN_EMAIL	stdio および AUTH_MODE=env	Spanning 管理者アカウントのメールアドレス
SPANNING_API_TOKEN	stdio および AUTH_MODE=env	Spanning API トークン
MCP_TRANSPORT	いいえ	stdio（デフォルト）または http
AUTH_MODE	いいえ	gateway（Docker イメージおよび Compose）または env。ゲートウェイモードでは X-Spanning-* ヘッダーが必要で、SPANNING_* へのフォールバックはありません。
CONDUIT_S2S_SECRET	HTTP では必須	サービス間 HMAC シークレット。空、または既知のプレースホルダーの場合、HTTP はエラーをログに記録してゼロ以外の終了コードで終了します。これが設定されていないと Compose は起動しません。実際の値をコミットしないでください。
MCP_ALLOW_INSECURE_DEV	いいえ	CONDUIT_S2S_SECRET なしで HTTP を起動する場合に限り、ローカル開発用に 1 を設定します。警告をログに記録し、X-Gateway-S2S をスキップして、127.0.0.1 のみでバインドします。
MCP_HTTP_HOST	いいえ	MCP_TRANSPORT=http の場合のバインドアドレス。デフォルトは 127.0.0.1 です。CONDUIT_S2S_SECRET が設定されている場合に適用されます。コンテナーイメージでは 0.0.0.0 が設定されます。
MCP_HTTP_PORT	いいえ	HTTP ポート。デフォルトは 8080 です。

実行

npm install
npm run build
npm start                       # stdio

# HTTP refuses to start until CONDUIT_S2S_SECRET is a real secret
CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" MCP_TRANSPORT=http 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

Docker

イメージはコンテナー内で 0.0.0.0 をリッスンし、デフォルトで AUTH_MODE=gateway に設定されます。ポートをループバックに公開し、S2S シークレットを渡してください。ゲートウェイモードでは、Spanning の認証情報はリクエストごとにヘッダーとして渡されます。

docker build --secret id=npmrc,src=$HOME/.npmrc -t spanning-mcp .
docker run --rm \
  -e CONDUIT_S2S_SECRET \
  -p 127.0.0.1:8080:8080 \
  spanning-mcp

Compose は CONDUIT_S2S_SECRET が未設定の場合に起動を拒否し、AUTH_MODE=gateway を設定して、127.0.0.1:8080:8080 を公開します。また、静的な Spanning 認証情報は注入しません。

CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" docker compose up --build

イメージのビルドには GitHub Packages の npmrc が必要です（docker build --secret id=npmrc,src=$HOME/.npmrc）。シングルテナント HTTP でも引き続き S2S シークレットが必要で、その後 SPANNING_* が使用されます。

docker run --rm \
  -e CONDUIT_S2S_SECRET \
  -e AUTH_MODE=env \
  -e SPANNING_PLATFORM=m365 \
  -e [email protected] \
  -e SPANNING_API_TOKEN \
  -p 127.0.0.1:8080:8080 \
  spanning-mcp

ライセンス

Apache 2.0 — LICENSE を参照してください。