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（规范地址）以及 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 完成授权
/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 时间 6am）可确保即使没有代码更改，链也会持续活跃。

部署设有门禁——切勿在本地运行 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 会在第 1 步失败，因为没有可供部署的 wrangler.jsonc。

验证部署

# 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

环境变量

变量（wrangler.jsonc）

变量	描述
INTERNAL_API_BASE_URL	后端 API 基础 URL
BUILD_HASH	Worker 程序包的 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 十六进制摘要
OPENAI_REVIEW_PHONE	用作专用审核用户名，并用于派生合成账户的不透明引用的电话号码

这三个 OPENAI_* 值也配置为 GitHub Actions 仓库密钥。请一并添加这三个值，然后运行手动的 Test, Build & Deploy 工作流。CI 会将它们写入一个临时的 0600 权限文件，并将该文件传递给 wrangler deploy --secrets-file，因此审核配置会与代码一起部署到同一个经过签名和证明的 Worker 版本中。如果这三个值不全，工作流会安全地拒绝继续，并在部署后立即删除临时文件。该文件中未列出的现有 Worker 密钥会予以保留。

相关项目

• Kaption Extension — Chrome/Edge/Firefox 浏览器扩展（中继的另一端）
• @kaptionai/mcp-extension — 本地 MCP 桥接（在你的设备上运行，无需云中继）

许可证

BUSL-1.1

一次性附件上传

create_attachment_upload({name,mime,size,target_session?}) 会转发给选定的 Rust 核心；核心会检查仅限所有者使用的 MCP_LOCAL_SEND 标志，并使用其 Kaption JWT 在 schedule Worker 上创建同一用户的上传槽位。在 15 分钟内将原始字节 PUT 到 uploadUrl，然后在一小时内发送 attachment:{ref:attachmentRef}。核心会一次性消费该引用，并在本地存储字节，以便立即发送或安排后续发送。最大 8 MiB；现有的征求同意／先询问限制仍然适用。中继不会读取本地文件或获取第三方 URL，并会拒绝 path 和 url 附件字段。