Relay

Relay

将每次 GitHub 推送更新为通俗易懂的客户进展

已上线：relay-vishnu.fly.dev。 安装 GitHub App，然后将 https://relay-vishnu.fly.dev/mcp 添加到你的 MCP 客户端，在 MCP Registry 中查找 Relay，或从 VS Code Marketplace 或 Open VSX 安装扩展。

Relay 是一款面向自由职业者和代理机构的 GitHub App。将它安装到你的代码库，为每个代码库指定一位客户，每次向主分支推送代码，Claude 都会生成一封简短、没有术语的邮件摘要。发送任何内容前，客户都需要通过邮件确认，并且每份摘要都包含一键退订链接。

工作原理

sequenceDiagram
    participant Dev
    participant GitHub
    participant Web as Relay web
    participant Queue as Postgres (pg-boss)
    participant Worker as Relay worker
    participant Claude
    participant Resend
    participant Client

    Dev->>GitHub: git push
    GitHub->>Web: POST /webhook/github (HMAC-signed, installation id)
    Web->>Web: verify signature, claim X-GitHub-Delivery
    alt duplicate, filtered, or client not confirmed
        Web-->>GitHub: 200 duplicate / filtered
    else new push for an active mapping
        Web->>Queue: enqueue process-push
        Web-->>GitHub: 202 accepted
        Queue->>Worker: job
        Worker->>Claude: summarize commits (structured output), unless over the monthly cap
        Claude-->>Worker: validated summary
        Worker->>Resend: digest email + List-Unsubscribe
        Resend-->>Client: digest
    end

• GitHub App：一次安装即可连接任意数量的代码库，无需个人访问令牌（ADR 002）。
• 多租户：每一行数据都属于某个安装；用户的权限由 GitHub 根据其可访问的安装决定；卸载时会删除该租户的数据。
• Postgres + pg-boss：Webhook 会立即返回 202，由独立的工作进程通过重试和退避机制发送摘要（ADR 003）。
• 内置同意机制：双重选择加入确认、带签名的一键退订（RFC 8058），以及仅通过 POST 修改状态的确认和退订页面。
• 成本控制：按安装设置 Claude 生成摘要的月度上限（超出后改为纯文本摘要）、跟踪令牌用量，并提供 CLAUDE_ENABLED 紧急停用开关。
• 规范优先：通过运行时和 CI 强制执行 OpenAPI 3.1 和 JSON Schema 契约。
• 支持 OAuth 2.1 的远程 MCP 服务：只需将一个 URL 添加到 Claude Code、Claude Desktop、VS Code 或 Cursor，通过 GitHub 登录，然后通过聊天管理 Relay（docs/mcp.md、ADR 004、ADR 005）。
• 控制面板：为不使用 MCP 的用户提供位于 /dashboard 的简洁服务端渲染界面。
• 更丰富的摘要（可选）：从 GitHub 获取已合并 PR 的描述，并通过 Anthropic 的 MCP 连接器从租户的工单跟踪系统获取问题详情，同时提供只读工具允许列表和回退机制（docs/summaries.md）。

本地运行

前置条件：Node.js 22.12+、Docker（用于 Postgres）、一个 GitHub App、Anthropic API 密钥和 Resend API 密钥。

git clone https://github.com/vishnumuthyalu/relay-extension.git
cd relay-extension
npm install
cp .env.example .env          # fill in the values; see docs/github-app.md
docker compose up -d db       # Postgres on localhost:5432 (dev + test databases)
npm run migrate
npm run dev                   # web process on :3000
npm run dev:worker            # worker process, in a second terminal

GitHub 必须能够访问你的机器，以便处理 Webhook 和登录，因此请运行隧道（ngrok http 3000），并将其 URL 用作 PUBLIC_URL，同时填入应用设置。

然后：

1. 打开 PUBLIC_URL/install，并将应用安装到一个代码库。
2. 打开 PUBLIC_URL/dashboard，并使用 GitHub 登录。
3. 在控制面板中、通过 API（见下文）或通过 MCP 工具，将代码库关联到一位客户。客户会收到确认邮件。
4. 客户确认后，向默认分支推送代码，或运行 node simulate-webhook.js。

若要改为在容器中运行全部服务：docker compose up --build。

部署

一个镜像、两个进程（web、worker）和一个 Postgres。托管实例运行在 Fly.io 上（一个 web 实例和一个 worker 实例），使用 Supabase Postgres；每次部署前，迁移都会作为 Fly 的发布命令运行。详见 docs/deploy.md。标签会触发发布：v* 部署后端并更新 MCP Registry 条目，ext-v* 发布 VS Code 扩展。

配置

所有设置均为环境变量；.env.example 列出了每个变量并加以说明。如果缺少必需值，Web 和 worker 进程将拒绝启动。

变量	必需	用途
DATABASE_URL	是	Postgres 连接字符串
PUBLIC_URL	是	公共基础 URL（webhook、登录回调、邮件链接）
SESSION_SECRET	是	32 个或更多随机字符；用于签署会话和邮件链接
GITHUB_APP_SLUG、GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET、GITHUB_WEBHOOK_SECRET	是	来自 GitHub App
ANTHROPIC_API_KEY	除非 CLAUDE_ENABLED=false	Claude API 密钥
RESEND_API_KEY、FROM_EMAIL	是	邮件发送（在 Resend 中验证你的发信域名）
ANTHROPIC_MODEL	否	默认值为 claude-haiku-4-5
DIGEST_MONTHLY_CAP	否	每个安装每月由 Claude 撰写的摘要数量上限，默认为 100
CLAUDE_ENABLED	否	false 会为所有人发送纯文本摘要
GITHUB_APP_ID、GITHUB_APP_PRIVATE_KEY	否	摘要中的拉取请求上下文
INTEGRATIONS_KEY	否	加密工单跟踪器令牌；启用跟踪器连接

API

JSON API 的说明见 spec/openapi.yaml，并会在运行时进行验证。它使用通过 使用 GitHub 登录 获取的会话 Cookie。

方法	路径	用途
GET	/api/me	你的信息以及你可以管理的安装
GET	/api/installations/{id}/mappings	客户端映射及其状态（pending、active、unsubscribed）
PUT	/api/installations/{id}/mappings/{owner}/{repo}	创建或更新映射；发送确认邮件
DELETE	/api/installations/{id}/mappings/{owner}/{repo}	停止发送该仓库的摘要
POST	/api/installations/{id}/mappings/{owner}/{repo}/test	向已确认的客户端发送示例摘要
GET	/api/installations/{id}/digests	摘要历史记录
GET	/api/installations/{id}/usage	本月用量及上限

其他路由：POST /webhook/github（GitHub App 投递）、/mcp（远程 MCP）、/oauth/* 和 /.well-known/*（面向 MCP 客户端的 OAuth）、/dashboard、/auth/login、/auth/callback、POST /auth/logout、/install、/confirm、/unsubscribe、/privacy、/health、/ready。

MCP 服务

远程：将 https://relay-vishnu.fly.dev/mcp 添加到你的 MCP 客户端（如果是你自己的部署，则添加 https://<host>/mcp）。例如：

claude mcp add --transport http relay https://relay-vishnu.fly.dev/mcp

本地连接到你自己的数据库：

RELAY_INSTALLATION_ID=12345678 npm run mcp   # stdio server for one installation
npm run mcp:inspect                          # open it in the MCP Inspector

客户端配置见 docs/mcp.md，工具契约见 spec/mcp-tools.md。

测试

测试使用真实的 Postgres 运行：每个测试文件都有自己的 schema，因此测试套件可以并行运行。docker compose up -d db 会创建 relay_test 数据库。

npm test
npm run lint
npx @stoplight/spectral-cli lint spec/openapi.yaml --ruleset .spectral.yaml

CI 会在 Node 22 和 24 上，通过 Postgres 服务容器运行相同的步骤；如果覆盖率下降，则构建失败（npm run test:coverage）。

项目结构

relay-extension/
├── server.js                 # Web process: webhooks, sign-in, API, email link pages
├── worker.js                 # Worker process: sends digests from the queue
├── lib/
│   ├── config.js             # Env validation
│   ├── db/                   # Postgres pool, migrations runner, tenant-scoped queries
│   ├── jobs/process-push.js  # One delivery: caps, Claude or fallback, email, records
│   ├── queue.js              # pg-boss setup
│   ├── service.js            # Per-installation operations shared by API and MCP
│   ├── pipeline.js           # Summarize + email
│   ├── claude.js             # Claude structured outputs + schema validation
│   ├── email.js              # Email HTML, unsubscribe headers, Resend
│   ├── links.js              # Signed confirm/unsubscribe links
│   ├── github.js             # GitHub OAuth (Sign in with GitHub)
│   ├── oauth/                # MCP authorization server: clients, tokens, JWT
│   ├── context/              # Optional PR and ticket context for summaries
│   ├── github-app.js         # GitHub App JWT and installation tokens
│   ├── crypto-box.js         # AES-256-GCM for stored tracker tokens
│   ├── html.js, csrf.js      # Server-rendered pages and form protection
│   ├── security.js           # Webhook HMAC verification
│   └── retry.js              # Retry with backoff for Claude and Resend
├── routes/                   # webhook, mcp, oauth, auth, dashboard, api, email links
├── migrations/               # Numbered SQL migrations
├── mcp/                      # MCP server, tools, resources, stdio entrypoint
├── spec/                     # OpenAPI, JSON Schemas, webhook and MCP contracts
├── tests/                    # Jest suites + helpers (per-file Postgres schema)
├── extension/                # VS Code extension: registers the remote MCP server
├── server.json               # MCP Registry entry
├── fly.toml                  # Fly.io deployment (web + worker, migrations on release)
├── docs/                     # GitHub App, MCP, summaries, deployment, ADRs, sequence diagram
├── docker-compose.yml
└── Dockerfile

安全

• Webhook 会先通过 HMAC-SHA256（恒定时间）验证，然后才会有任何操作读取请求正文。
• 投递 ID 会以原子方式认领，因此重复投递和重新投递都不会导致重复发送。
• 会话使用带签名的 httpOnly Cookie，并设置 SameSite=Lax。JSON API 只接受 JSON 请求正文，从而阻止跨站表单提交。
• 租户数据始终按安装查询，其他租户的安装会返回 404。
• 邮件链接经过 HMAC 签名，并绑定到当前地址。更改客户端的邮箱会使旧链接失效。
• 所有渲染到邮件或页面中的内容都会进行 HTML 转义。提交文本会作为不可信数据传给 Claude，回复会经过 schema 验证。
• 不存储任何 GitHub 令牌。
• MCP 访问令牌绑定到 PUBLIC_URL/mcp（RFC 8707）。PKCE 为强制要求，授权码只能使用一次，刷新令牌会轮换；两者均仅以哈希形式存储。/mcp 端点会根据 Host 标头检查 DNS 重绑定。

许可证

MIT