claude-channel-github-webhook 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "github-webhook",
+  "version": "1.0.0",
+  "description": "GitHub Webhook events (PR reviews, CI failures, @claude mentions) as Claude Code Channel notifications",
+  "channel": {
+    "command": "npx",
+    "args": ["tsx", "src/channel.ts"]
+  },
+  "env": [
+    {
+      "name": "GITHUB_WEBHOOK_SECRET",
+      "description": "GitHub Webhook secret for HMAC signature verification",
+      "required": false
+    },
+    {
+      "name": "WEBHOOK_PORT",
+      "description": "Port for the webhook router (default: 8788)",
+      "required": false,
+      "default": "8788"
+    }
+  ]
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+      - run: npm test

package/README.md

@@ -0,0 +1,126 @@
+# claude-channel-github-webhook
+
+A Claude Code Channel plugin that delivers GitHub Webhook events as real-time notifications to your Claude Code session.
+
+Supports PR reviews, CI failures, and `@claude` mentions.
+
+## Architecture
+
+```
+GitHub Webhook
+      |
+      v  (tunnel: ngrok / cloudflared / etc.)
+[channel.ts :8788]  <- single process: MCP server + HTTP listener
+      |
+      v  (notifications/claude/channel)
+Claude Code session
+```
+
+A single process handles everything: receives GitHub Webhooks over HTTP and forwards them to Claude Code via MCP stdio. No router, no registry, no extra processes.
+
+## Notification Rules
+
+| Event | Condition |
+|---|---|
+| `pull_request_review` | All reviews |
+| `check_run` | `conclusion === "failure"` only |
+| `issue_comment` | Comment body contains `@claude` |
+
+## Setup
+
+### 1. Install
+
+```bash
+npm install claude-channel-github-webhook
+```
+
+Or clone directly:
+
+```bash
+git clone https://github.com/moeki0/claude-channel-github-webhook.git
+cd claude-channel-github-webhook
+npm install
+```
+
+### 2. Open a tunnel
+
+```bash
+ngrok http 8788
+```
+
+Any tunneling tool works (ngrok, cloudflared, Smee.io, reverse proxy, etc.).
+
+### 3. Configure the GitHub Webhook
+
+In your repository's **Settings > Webhooks > Add webhook**:
+
+- **Payload URL**: Your tunnel's public URL
+- **Content type**: `application/json`
+- **Secret**: Any string (optional but recommended)
+- **Events**: `Pull request reviews` / `Check runs` / `Issue comments`
+
+### 4. Launch with Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "github-webhook": {
+      "command": "npx",
+      "args": ["claude-channel-github-webhook"],
+      "env": {
+        "GITHUB_WEBHOOK_SECRET": "your_secret"
+      }
+    }
+  }
+}
+```
+
+Then start Claude Code:
+
+```bash
+claude --dangerously-load-development-channels server:github-webhook
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `GITHUB_WEBHOOK_SECRET` | Secret for HMAC signature verification | None (verification skipped) |
+| `WEBHOOK_PORT` | HTTP listen port | `8788` |
+
+## How It Works
+
+1. Claude Code spawns `channel.ts` as a child process
+2. The process connects to Claude Code via MCP stdio
+3. It starts an HTTP server on `127.0.0.1:8788`
+4. GitHub Webhooks arrive via tunnel, are verified (HMAC), parsed, and filtered
+5. Matching events are sent as `notifications/claude/channel` with structured `meta` attributes
+6. Claude Code receives `<channel source="github-webhook" event="check_run" ...>` tags and acts accordingly
+
+## What Claude Receives
+
+```xml
+<channel source="github-webhook" event="check_run" conclusion="failure" branch="feat/x" workflow="CI / test">
+CI failed: CI / test
+Branch: feat/x
+Details: https://github.com/org/repo/actions/runs/123
+</channel>
+```
+
+## Development
+
+```bash
+npm test        # Run tests
+npm run lint    # Type check
+npm run start   # Start channel standalone
+```
+
+## Status
+
+Claude Code Channels is in **Research Preview**.
+
+- Requires Claude Code v2.1.80+
+- Requires claude.ai login (not API key)
+- Team/Enterprise orgs must enable `channelsEnabled`

package/jest.config.js

@@ -0,0 +1,11 @@
+export default {
+  preset: "ts-jest/presets/default-esm",
+  testEnvironment: "node",
+  extensionsToTreatAsEsm: [".ts"],
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
+  transform: {
+    "^.+\\.ts$": ["ts-jest", { useESM: true }],
+  },
+};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "claude-channel-github-webhook",
+  "version": "1.0.0",
+  "description": "GitHub Webhook Channel plugin for Claude Code",
+  "type": "module",
+  "bin": "src/channel.ts",
+  "scripts": {
+    "build": "tsc",
+    "start": "tsx src/channel.ts",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "tsx": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/jest": "^29.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/channel.ts

@@ -0,0 +1,85 @@
+#!/usr/bin/env npx tsx
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import http from "node:http";
+import { buildNotification, verifySignature } from "./shared/message.js";
+
+const SECRET = process.env.GITHUB_WEBHOOK_SECRET ?? "";
+const PORT = parseInt(process.env.WEBHOOK_PORT ?? "8788");
+const MAX_BODY = 1024 * 1024; // 1MB
+
+const mcp = new Server(
+  { name: "github-webhook", version: "1.0.0" },
+  {
+    capabilities: { experimental: { "claude/channel": {} } },
+    instructions: [
+      "Events from the github-webhook channel arrive as <channel source=\"github-webhook\" ...>.",
+      "Attributes include event type, branch, PR number, etc.",
+      "On check_run failures: read the CI logs and attempt to fix the issue.",
+      "On pull_request_review: read the review comments and address the feedback.",
+      "On issue_comment with @claude: respond to the request in the comment.",
+      "These are one-way notifications — no reply mechanism is available.",
+    ].join(" "),
+  }
+);
+
+await mcp.connect(new StdioServerTransport());
+
+const httpServer = http.createServer((req, res) => {
+  if (req.method !== "POST") {
+    res.writeHead(405);
+    res.end();
+    return;
+  }
+
+  let body = "";
+  let size = 0;
+
+  req.on("data", (chunk: Buffer) => {
+    size += chunk.length;
+    if (size > MAX_BODY) {
+      res.writeHead(413);
+      res.end("payload too large");
+      req.destroy();
+      return;
+    }
+    body += chunk;
+  });
+
+  req.on("end", async () => {
+    if (size > MAX_BODY) return;
+
+    const signature = req.headers["x-hub-signature-256"] as string | undefined;
+    if (!verifySignature(body, signature, SECRET)) {
+      res.writeHead(401);
+      res.end("invalid signature");
+      return;
+    }
+
+    const event = req.headers["x-github-event"] as string;
+    let payload: Record<string, unknown>;
+    try {
+      payload = JSON.parse(body);
+    } catch {
+      res.writeHead(400);
+      res.end("invalid json");
+      return;
+    }
+
+    const notification = buildNotification(event, payload);
+    if (notification) {
+      await mcp.notification({
+        method: "notifications/claude/channel",
+        params: notification,
+      });
+      process.stderr.write(`[github-webhook] notified: ${event}\n`);
+    }
+
+    res.writeHead(200);
+    res.end("ok");
+  });
+});
+
+httpServer.listen(PORT, "127.0.0.1", () => {
+  process.stderr.write(`[github-webhook] listening on 127.0.0.1:${PORT}\n`);
+});

package/src/shared/message.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect } from "@jest/globals";
+import { buildNotification, verifySignature } from "./message.js";
+
+describe("buildNotification", () => {
+  it("pull_request_review のメッセージと meta を組み立てる", () => {
+    const payload = {
+      pull_request: {
+        title: "Add feature",
+        number: 42,
+        html_url: "https://github.com/org/repo/pull/42",
+        head: { ref: "feat/add-feature" },
+      },
+      review: {
+        user: { login: "reviewer" },
+        state: "approved",
+        body: "LGTM",
+      },
+    };
+    const result = buildNotification("pull_request_review", payload);
+    expect(result).not.toBeNull();
+    expect(result!.content).toContain("Add feature");
+    expect(result!.content).toContain("reviewer");
+    expect(result!.content).toContain("approved");
+    expect(result!.meta.event).toBe("pull_request_review");
+    expect(result!.meta.pr_number).toBe("42");
+  });
+
+  it("check_run 失敗のメッセージを組み立てる", () => {
+    const payload = {
+      check_run: {
+        name: "CI / test",
+        conclusion: "failure",
+        html_url: "https://github.com/org/repo/actions/runs/1",
+        check_suite: { head_branch: "feat/add-feature" },
+      },
+    };
+    const result = buildNotification("check_run", payload);
+    expect(result).not.toBeNull();
+    expect(result!.content).toContain("CI / test");
+    expect(result!.meta.event).toBe("check_run");
+    expect(result!.meta.conclusion).toBe("failure");
+  });
+
+  it("check_run 成功は null を返す", () => {
+    const payload = {
+      check_run: {
+        name: "CI / test",
+        conclusion: "success",
+        html_url: "https://github.com/org/repo/actions/runs/1",
+        check_suite: { head_branch: "feat/add-feature" },
+      },
+    };
+    expect(buildNotification("check_run", payload)).toBeNull();
+  });
+
+  it("issue_comment に @claude を含む場合のみ通過する", () => {
+    const payload = {
+      issue: { title: "Bug report" },
+      comment: { body: "Hey @claude please fix this", html_url: "https://github.com/org/repo/issues/1#comment" },
+    };
+    const result = buildNotification("issue_comment", payload);
+    expect(result).not.toBeNull();
+    expect(result!.content).toContain("Bug report");
+    expect(result!.meta.event).toBe("issue_comment");
+  });
+
+  it("issue_comment に @claude を含まない場合は null を返す", () => {
+    const payload = {
+      issue: { title: "Bug report" },
+      comment: { body: "Just a regular comment", html_url: "https://github.com/org/repo/issues/1#comment" },
+    };
+    expect(buildNotification("issue_comment", payload)).toBeNull();
+  });
+
+  it("@claudebot のような部分一致では通過しない", () => {
+    const payload = {
+      issue: { title: "Bug report" },
+      comment: { body: "ask @claudebot", html_url: "https://github.com/org/repo/issues/1#comment" },
+    };
+    expect(buildNotification("issue_comment", payload)).toBeNull();
+  });
+
+  it("未知のイベントタイプは null を返す", () => {
+    expect(buildNotification("unknown_event", {})).toBeNull();
+  });
+});
+
+describe("verifySignature", () => {
+  it("正しい署名を検証できる", () => {
+    const body = '{"test":true}';
+    const secret = "mysecret";
+    // pre-computed: echo -n '{"test":true}' | openssl dgst -sha256 -hmac 'mysecret'
+    expect(verifySignature(body, "sha256=f269168b331c2c56aa328857bfcda87bacca5e4e1da4da687667068a21dd3c53", secret)).toBe(true);
+  });
+
+  it("不正な署名を拒否する", () => {
+    expect(verifySignature("{}", "sha256=wrong", "mysecret")).toBe(false);
+  });
+
+  it("secret が空なら検証をスキップする", () => {
+    expect(verifySignature("{}", undefined, "")).toBe(true);
+  });
+
+  it("secret があるのに署名がなければ拒否する", () => {
+    expect(verifySignature("{}", undefined, "mysecret")).toBe(false);
+  });
+});

package/src/shared/message.ts

@@ -0,0 +1,93 @@
+import crypto from "node:crypto";
+
+export interface Notification {
+  [key: string]: unknown;
+  content: string;
+  meta: Record<string, string>;
+}
+
+export function buildNotification(event: string, payload: Record<string, unknown>): Notification | null {
+  switch (event) {
+    case "pull_request_review": {
+      const pr = payload.pull_request as {
+        title: string;
+        number: number;
+        html_url: string;
+      };
+      const review = payload.review as {
+        user: { login: string };
+        state: string;
+        body?: string;
+      };
+      return {
+        content: [
+          `PR review on "${pr.title}" (#${pr.number})`,
+          `Reviewer: ${review.user.login}`,
+          `State: ${review.state}`,
+          `Comment: ${review.body ?? "(none)"}`,
+          `URL: ${pr.html_url}`,
+        ].join("\n"),
+        meta: {
+          event,
+          pr_number: String(pr.number),
+          reviewer: review.user.login,
+          state: review.state,
+        },
+      };
+    }
+
+    case "check_run": {
+      const checkRun = payload.check_run as {
+        name: string;
+        conclusion: string;
+        html_url: string;
+        check_suite: { head_branch: string };
+      };
+      if (checkRun.conclusion !== "failure") return null;
+      return {
+        content: [
+          `CI failed: ${checkRun.name}`,
+          `Branch: ${checkRun.check_suite.head_branch}`,
+          `Details: ${checkRun.html_url}`,
+        ].join("\n"),
+        meta: {
+          event,
+          conclusion: checkRun.conclusion,
+          branch: checkRun.check_suite.head_branch,
+          workflow: checkRun.name,
+        },
+      };
+    }
+
+    case "issue_comment": {
+      const issue = payload.issue as { title: string };
+      const comment = payload.comment as { body: string; html_url: string };
+      if (!/@claude\b/.test(comment.body)) return null;
+      return {
+        content: [
+          `Mentioned in: ${issue.title}`,
+          `Comment: ${comment.body}`,
+          `URL: ${comment.html_url}`,
+        ].join("\n"),
+        meta: {
+          event,
+          issue_title: issue.title,
+        },
+      };
+    }
+
+    default:
+      return null;
+  }
+}
+
+export function verifySignature(body: string, signature: string | undefined, secret: string): boolean {
+  if (!secret) return true;
+  if (!signature) return false;
+  const digest = "sha256=" + crypto.createHmac("sha256", secret).update(body).digest("hex");
+  try {
+    return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
+  } catch {
+    return false;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}