Kaption WhatsApp (Cloud)

kaption-mcp-remote

WhatsApp 向けクラウド MCP リレーです。AI アシスタント（Claude、ChatGPT、Cursor など）が、Model Context Protocol を通じて WhatsApp の会話を操作できます。

セットアップガイド： kaptionai.com/mcp — WhatsApp を Claude、ChatGPT、または Cursor に接続します。

稼働中： mcp.kaptionai.com（正式な URL）および mcp-ext.kaptionai.com（既存の接続との後方互換性を保つ別名）

このリレーはメッセージを読み取ることはできません。AI クライアントと Kaption ブラウザー拡張機能の間で MCP ツール呼び出しを転送します。すべての処理はブラウザー内でローカルに行われます。ソースコードは公開されているため（BUSL-1.1）、ご自身で確認できます。

アーキテクチャ

AI Client (Claude/ChatGPT/Cursor)
    │
    │ OAuth 2.1 + SSE/Streamable HTTP
    ▼
┌─────────────────────────────────────┐
│  Cloudflare Worker                  │
│  mcp.kaptionai.com                 │
│                                     │
│  ┌────────────┐  ┌──────────────┐  │
│  │ OAuthProv  │  │ Next.js      │  │
│  │ /sse /mcp  │  │ /authorize   │  │
│  │ /token     │  │ /ext-auth    │  │
│  │ /register  │  │ / (landing)  │  │
│  └─────┬──────┘  └──────────────┘  │
│        │                            │
│  ┌─────▼──────┐  ┌──────────────┐  │
│  │ RelayMCP   │  │ Deployment   │  │
│  │ (DO)       │  │ ChainDO      │  │
│  └─────┬──────┘  └──────────────┘  │
│        │                            │
│  ┌─────▼──────┐                    │
│  │ RelayRoom  │ ◄── WebSocket ──┐  │
│  │ (DO/accountRef) │            │  │
│  └────────────┘                 │  │
└─────────────────────────────────┼──┘
                                  │
                          Browser Extension
                          (WhatsApp Web tab)

Durable Objects

DO	キー	用途
RelayMCP	OAuth セッション	McpAgent — ツールを登録し、JSON-RPC を RelayRoom に中継
RelayRoom	不透明な accountRef	拡張機能との WebSocket ブリッジ、認証ハンドシェイク、リクエストとレスポンスの照合
DeploymentChainDO	"main"	デプロイの透明性を確保する追記専用ハッシュチェーン

リクエストの流れ

1. AI クライアントが /.well-known/oauth-authorization-server を通じて MCP サーバーを検出します
2. クライアントが POST /register（RFC 7591）を通じて動的に登録します
3. ユーザーが /authorize で WhatsApp OTP 認証を行います
4. クライアントが /token でコードをトークンに交換します
5. クライアントが SSE（/sse）または Streamable HTTP（/mcp）を通じてツール呼び出しを送信します
6. RelayMCP DO が呼び出しを受け取り、該当する accountRef の RelayRoom にルーティングします
7. RelayRoom が WebSocket 経由で JSON-RPC を拡張機能に転送します
8. 拡張機能が WhatsApp Web のコンテキスト内で実行され、結果を返します
9. 結果が RelayRoom → RelayMCP → AI クライアントの順に返されます

ルーティングテーブル

パス	メソッド	認証	ハンドラー
/	GET	—	Next.js ランディングページ
/authorize	GET	—	Next.js OTP フォーム（HMAC 署名済み oauthReqInfo）
/authorize/send-otp	POST	—	Next.js API ルート → rest-api
/authorize/verify	GET/POST	—	Next.js OTP 検証 → OAuthProvider の completeAuthorization
/authorize/reviewer-login	POST	静的レビュー用認証情報	設定済みの合成レビュー用電話番号に対するパスワード認証
/register	POST	—	OAuthProvider（RFC 7591 動的クライアント登録）
/token	POST	—	OAuthProvider（トークン交換）
/sse	GET	OAuth トークン	RelayMCP DO（SSE トランスポート）
/mcp	POST	OAuth トークン	RelayMCP DO（Streamable HTTP）
/ws/ext	GET	認証メッセージ内の JWT/トークン	RelayRoom DO（WebSocket アップグレード）
/ext-auth/*	各種	—	Next.js 拡張機能認証ページおよび API
/transparency	GET	—	DeploymentChainDO（チェーン履歴）
/transparency/latest	GET	—	DeploymentChainDO（最新のエントリー）
/transparency/verify	GET	—	DeploymentChainDO（チェーンの整合性）
/transparency/gaps	GET	CF トークン	CF デプロイとチェーンの相互照合
/transparency/append	POST	DEPLOY_API_KEY	エントリーの追加（CI のみ）

MCP ツール

16 個の公開ツールが拡張機能に転送されます（リレーはこれらを実行しません）。

ツール	説明
query	会話、連絡先、メッセージ、文字起こし、ラベル、コミュニティ、セッションを検索します
summarize_conversation	会話の要約を取得または生成します
manage_labels	WhatsApp Business のラベルを追加／削除／作成／消去します
manage_notes	連絡先のメモを取得／設定します（Business アカウント）
download_media	メッセージ内の画像／動画／音声／ドキュメントをダウンロードします
manage_chat	アーカイブ、ピン留め、ミュート、既読／未読の設定、下書きの設定／消去を行います
manage_reminders	個人的なリマインダーを作成／一覧表示／完了／削除します
manage_scheduled_messages	メッセージを将来の配信に向けて予約します — Kaption の番号（ボット、デフォルト）から、またはこのコンピューター上の自分の番号から（mode: "local"。グループにも送信可能）
manage_lists	個人的なチャットリスト（カスタムカテゴリー）を管理します
list_contacts、get_contact、get_contact_groups	連絡先とそのグループへの所属情報を読み取ります
list_groups、get_group	キャッシュ済みまたはライブのグループメタデータを読み取ります
export_contacts	連絡先を CSV または JSON としてエクスポートします
get_analytics	WhatsApp の利用状況、ランキング、応答時間、エクスポートを分析します

get_api_info はローカル専用です。プライベートな REST 接続認証情報を返すため、クラウド側のインターフェースから意図的に除外されています。

デプロイのセキュリティ

すべてのデプロイには暗号署名が付与され、改ざんを検知できる透明性チェーンに記録されます。詳しくは SECURITY.md をご覧ください。

パイプライン

GitHub Actions (push to main)
    │
    ├─ 1. Run tests
    ├─ 2. Build worker (OpenNext + wrap)
    ├─ 3. SHA-256 manifest every generated code and asset file
    ├─ 4. Pre-deploy: Sigstore sign the manifest → Rekor log
    ├─ 5. Deploy to Cloudflare
    ├─ 6. Post-deploy: verify hash unchanged, sign attestation → Rekor
    └─ 7. Append to transparency chain (hash-linked)

毎日のハートビートによる再デプロイ（UTC 6 時）により、コードの変更がなくてもチェーンが維持されます。

デプロイは制限されています — ローカルで wrangler deploy を実行しないでください

本番デプロイはすべて GitHub Actions 経由で行われます。複数の層でこれを強制しています。

1. wrangler.jsonc は gitignore されています。scripts/build-config.mjs は wrangler.template.jsonc からこれを生成し、GITHUB_ACTIONS=true と GITHUB_RUN_ID が設定されていない場合（または開発用の KAPTIONAI_LOCAL_DEV=1 が設定されていない場合）は実行を拒否します。
2. npm run predeploy は、同じ CI 環境変数が設定されていない場合に中断します。
3. main ブランチは保護されており、レビュー済みの PR と test、deploy、verify の各チェックの成功が必須です。
4. CODEOWNERS により、すべての PR は @kshmir のレビューを経由します。

変更をリリースするには、PR を作成 → レビューと CI の成功 → main にマージ → Actions がビルド、署名（Sigstore）、デプロイを行い、透明性チェーンに追加します。ラップトップから npx wrangler deploy を実行すると、デプロイ対象の wrangler.jsonc が存在しないため、手順 1 で失敗します。

デプロイの検証

# 1. Check the transparency chain
curl -s https://mcp.kaptionai.com/transparency/latest | jq .

# 2. Verify chain integrity
curl -s https://mcp.kaptionai.com/transparency/verify | jq .

# 3. Verify Sigstore signature (requires cosign)
COMMIT=$(curl -s https://mcp.kaptionai.com/transparency/latest | jq -r '.event.commitSha')
cosign verify-blob \
  --bundle build-manifest.sigstore.json \
  --certificate-identity-regexp "https://github.com/Kaption-AI/mcp-extension-remote/.*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  build-manifest.json

API エンドポイント

透明性 API（公開、認証不要）

# Full chain history (paginated)
GET /transparency?limit=50&offset=0

# Latest deployment
GET /transparency/latest

# Verify chain integrity
GET /transparency/verify

MCP（OAuth で保護）

# SSE transport (for Claude Code, Cursor)
GET /sse

# Streamable HTTP transport
POST /mcp

開発

# Install dependencies
npm install

# Run tests
npm test

# Dev server (Next.js only — no Worker routing)
npm run dev

# Build the full worker (OpenNext + custom wrapper)
npm run build:worker

プロジェクト構成

src/
  index.ts            # Worker entry — Hono routing, OAuthProvider composition
  relay-mcp.ts        # RelayMCP Durable Object (McpAgent)
  relay-room.ts       # RelayRoom Durable Object (WebSocket bridge)
  deployment-chain.ts # DeploymentChainDO (transparency log)
  otp.ts              # OTP generation, verification, JWT, HMAC, rate limiting
  schemas.ts          # Zod schemas for API request validation
  tools.ts            # MCP tool definitions (forwarded, not executed)
  types.ts            # TypeScript interfaces (Env, DeploymentEvent, etc.)
app/
  page.tsx            # Landing page (multilingual, client-side i18n)
  layout.tsx          # Root layout
  i18n.ts             # i18next init (8 languages)
  locales/            # Translation JSON files
  authorize/          # OAuth OTP flow pages + API routes
  ext-auth/           # Extension auth pages + API routes
scripts/
  wrap-worker.mjs     # Post-build: wraps OpenNext output with custom routing

環境変数

Vars（wrangler.jsonc）

変数	説明
INTERNAL_API_BASE_URL	バックエンド API のベース URL
BUILD_HASH	ワーカーバンドルの SHA-256（CI によって設定）
COMMIT_SHA	Git コミット SHA（CI によって設定）

シークレット（wrangler secret put）

シークレット	説明
INTERNAL_API_KEY	rest-api OTP エンドポイント用の API キー
DEPLOY_API_KEY	透明性チェーンへの追記用 API キー
JWT_SECRET	共有 JWT 署名シークレット（rest-api、schedule、metadata の各 Worker と同じもの）
PHONE_REF_SECRET	電話番号から不透明な永続アカウント参照を導出するための HMAC シークレット
EPHEMERAL_STATE_SECRET	短期間有効なログインヒント、検証チケット、暗号化されたセッションの電話番号ペイロード用の暗号化シークレット
OPENAI_APPS_CHALLENGE_TOKEN	OpenAI プラグインポータルが発行する、ドメイン検証用の正確なトークン
OPENAI_REVIEW_PASSWORD_SHA256	高エントロピーのレビュアーパスワードの小文字 SHA-256 16 進ダイジェスト
OPENAI_REVIEW_PHONE	専用のレビューユーザー名として使用し、合成アカウントの不透明な参照を導出する電話番号

3 つの OPENAI_* 値は、GitHub Actions のリポジトリシークレットとしても設定します。 3 つすべてをまとめて追加してから、手動の Test, Build & Deploy ワークフローを実行してください。CI は一時的なモード 0600 のファイルにこれらを書き込み、 そのファイルを wrangler deploy --secrets-file に渡すため、レビュー設定はコードと同じ 署名・証明済みの Worker バージョンに含まれます。3 つの値のうち一部しか存在しない場合、 ワークフローはフェイルクローズし、デプロイ直後に一時ファイルを削除します。 このファイルに記載されていない既存の Worker シークレットは保持されます。

関連プロジェクト

• Kaption Extension — Chrome／Edge／Firefox 向けブラウザー拡張機能（リレーのもう一方）
• @kaptionai/mcp-extension — ローカル MCP ブリッジ（お使いのマシン上で動作し、クラウドリレーは不要です）

ライセンス

BUSL-1.1

1 回限りの添付ファイルアップロード

create_attachment_upload({name,mime,size,target_session?}) は選択された Rust コアに転送されます。コアは所有者専用の MCP_LOCAL_SEND フラグを確認し、Kaption JWT を使用して schedule Worker 上に同一ユーザー用のアップロード枠を作成します。15 分以内に uploadUrl へ 生バイト列を PUT し、その後 1 時間以内に attachment:{ref:attachmentRef} を送信します。コアは この参照を 1 回だけ使用し、即時または将来のスケジュール送信用にバイト列をローカルに保存します。 最大 8 MiB です。既存の同意／事前確認の制限が適用されます。リレーはローカルファイルを読み取らず、 サードパーティーの URL も取得しません。また、添付ファイルの path および url フィールドは拒否します。