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：1 回のインストールで任意の数のリポジトリを接続でき、個人アクセストークンは不要です（ADR 002）。
• マルチテナント：各行はインストールに紐付きます。ユーザーの認可は、GitHub がアクセス可能と示すインストールに基づいて行われ、アンインストールすると、そのテナントのデータが削除されます。
• Postgres + pg-boss：Webhook はすぐに 202 を返し、別のワーカーがリトライとバックオフを使ってダイジェストを送信します（ADR 003）。
• 同意機能を組み込み：ダブルオプトインによる確認、署名付きのワンクリック配信停止（RFC 8058）、POST でのみ状態が変更される確認・配信停止ページを備えています。
• コスト管理：Claude が作成するダイジェストには、インストールごとの月間上限があります（上限を超えると通常のダイジェストを使用）。トークン使用量の追跡機能と、CLAUDE_ENABLEDによる緊急停止スイッチも備えています。
• 仕様優先：OpenAPI 3.1 と JSON Schema のコントラクトを、実行時と CI で検証します。
• OAuth 2.1 対応のリモート MCP サーバー：Claude Code、Claude Desktop、VS Code または Cursor に URL を 1 つ追加して、GitHub でサインインすると、チャットを通じて Relay を管理できます（docs/mcp.md、ADR 004、ADR 005）。
• ダッシュボード：MCP を使わない方向けに、/dashboardで小規模なサーバーサイドレンダリングの UI を提供します。
• より詳細な要約（オプトイン）：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

Webhook とサインインのために、GitHub からマシンにアクセスできる必要があります。そのため、トンネル（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を実行します。

デプロイ

1 つのイメージ、2 つのプロセス（web、worker）、1 つの Postgres で構成されています。ホストされたインスタンスは Fly.io（1 台の Web マシンと 1 台のワーカーマシン）で動作し、Supabase Postgres を使用します。マイグレーションは各デプロイ前に Fly のリリースコマンドとして実行されます。詳しくはdocs/deploy.mdを参照してください。タグに基づいてリリースされます。v*はバックエンドをデプロイして MCP Registry のエントリーを更新し、ext-v*は VS Code 拡張機能を公開します。

設定

すべての設定項目は環境変数です。各項目の一覧と説明は .env.example をご覧ください。必須の値が不足している場合、Web プロセスとワーカープロセスは起動を拒否します。

変数	必須	用途
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 サーバー

リモート：MCP クライアントに https://relay-vishnu.fly.dev/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 に対して実行されます。各テストファイルには独自のスキーマが割り当てられるため、テストスイートを並列実行できます。docker compose up -d db を実行すると、relay_test データベースが作成されます。

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

CI では Postgres サービスコンテナを使い、Node 22 と 24 で同じ手順を実行します。また、カバレッジが低下すると失敗します（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 に渡され、応答はスキーマ検証されます。
• GitHub トークンは保存されません。
• MCP アクセストークンは PUBLIC_URL/mcp に紐付けられます（RFC 8707）。PKCE が必須で、認可コードは一度だけ使用できます。リフレッシュトークンはローテーションされ、どちらもハッシュとしてのみ保存されます。/mcp エンドポイントは、DNS リバインディング対策として Host ヘッダーを検証します。

ライセンス

MIT