github-webhook-mcp 0.3.0 → 0.6.0-rc.1

package/manifest.json

@@ -1,11 +1,21 @@
 {
   "manifest_version": "0.3",
   "name": "github-webhook-mcp",
-  "version": "0.3.0",
-  "description": "Browse pending GitHub webhook events. Pairs with a webhook receiver that writes events.json.",
+  "display_name": "GitHub Webhook MCP",
+  "version": "1.0.0",
+  "description": "Real-time GitHub webhook notifications via Cloudflare Worker + Durable Object.",
+  "long_description": "GitHub Webhook MCP bridges GitHub webhook events to Claude via a Cloudflare Worker backend. Events are stored in a Durable Object with SQLite, queried through MCP tools, and optionally pushed in real-time via SSE channel notifications. No local webhook receiver needed — just point your GitHub webhook at the Worker URL.",
   "author": {
-    "name": "Liplus Project"
+    "name": "Liplus Project",
+    "url": "https://github.com/Liplus-Project"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Liplus-Project/github-webhook-mcp.git"
+  },
+  "homepage": "https://github.com/Liplus-Project/github-webhook-mcp",
+  "documentation": "https://github.com/Liplus-Project/github-webhook-mcp#readme",
+  "support": "https://github.com/Liplus-Project/github-webhook-mcp/issues",
   "license": "MIT",
   "server": {
     "type": "node",
@@ -16,16 +26,24 @@
         "${__dirname}/server/index.js"
       ],
       "env": {
-        "EVENTS_JSON_PATH": "${user_config.events_json_path}"
+        "WEBHOOK_WORKER_URL": "${user_config.worker_url}",
+        "WEBHOOK_CHANNEL": "${user_config.channel_enabled}"
       }
     }
   },
   "user_config": {
-    "events_json_path": {
-      "description": "Absolute path to the events.json file written by the webhook receiver.",
+    "worker_url": {
+      "description": "URL of the Cloudflare Worker endpoint (e.g. https://github-webhook-mcp.example.workers.dev)",
       "type": "string",
       "required": true,
-      "title": "Events JSON Path"
+      "title": "Worker URL"
+    },
+    "channel_enabled": {
+      "description": "Enable SSE channel notifications for Claude Code CLI (set to '0' to disable, '1' to enable)",
+      "type": "string",
+      "required": false,
+      "title": "Channel Notifications",
+      "default": "0"
     }
   },
   "tools": [
@@ -51,10 +69,25 @@
     }
   ],
   "compatibility": {
+    "claude_desktop": ">=0.11.0",
     "platforms": [
       "win32",
       "darwin",
       "linux"
-    ]
-  }
+    ],
+    "runtimes": {
+      "node": ">=18.0.0"
+    }
+  },
+  "keywords": [
+    "github",
+    "webhook",
+    "notifications",
+    "cloudflare",
+    "mcp",
+    "claude"
+  ],
+  "privacy_policies": [
+    "https://smgjp.com/privacy-policy-github-webhook-mcp/"
+  ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "github-webhook-mcp",
-  "version": "0.3.0",
-  "description": "MCP server for browsing GitHub webhook events",
+  "version": "0.6.0-rc.1",
+  "description": "MCP server bridging GitHub webhooks via Cloudflare Worker",
   "type": "module",
   "bin": {
     "github-webhook-mcp": "server/index.js"
@@ -13,13 +13,12 @@
   ],
   "scripts": {
     "start": "node server/index.js",
-    "test": "node --test test/",
+    "test": "node --check server/index.js",
     "pack:mcpb": "mcpb pack"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "iconv-lite": "^0.6.3",
-    "zod": "^3.22.0"
+    "eventsource": "^2.0.2"
   },
   "devDependencies": {
     "@anthropic-ai/mcpb": "^2.1.0"
@@ -30,7 +29,8 @@
   "keywords": [
     "mcp",
     "github",
-    "webhook"
+    "webhook",
+    "cloudflare"
   ],
   "license": "MIT",
   "repository": {

package/server/index.js

@@ -1,215 +1,259 @@
-#!/usr/bin/env node
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  ListToolsRequestSchema,
-  CallToolRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
-import { watch } from "node:fs";
-import {
-  getPendingStatus,
-  getPendingSummaries,
-  getEvent,
-  getPending,
-  markDone,
-  summarizeEvent,
-  dataFilePath,
-} from "./event-store.js";
-
-const CHANNEL_ENABLED = process.env.WEBHOOK_CHANNEL !== "0";
-
-const capabilities = {
-  tools: {},
-};
-if (CHANNEL_ENABLED) {
-  capabilities.experimental = { "claude/channel": {} };
-}
-
-const server = new Server(
-  { name: "github-webhook-mcp", version: "0.3.0" },
-  {
-    capabilities,
-    instructions: CHANNEL_ENABLED
-      ? "GitHub webhook events arrive as <channel source=\"github-webhook-mcp\" ...>. They are one-way: read them and act, no reply expected."
-      : undefined,
-  },
-);
-
-// ── Tools ───────────────────────────────────────────────────────────────────
-
-const TOOLS = [
-  {
-    name: "get_pending_status",
-    description:
-      "Get a lightweight snapshot of pending GitHub webhook events. Use this for periodic polling before requesting details.",
-    inputSchema: { type: "object", properties: {} },
-  },
-  {
-    name: "list_pending_events",
-    description:
-      "List lightweight summaries for pending GitHub webhook events. Returns metadata only, without full payloads.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        limit: {
-          type: "number",
-          description: "Maximum number of pending events to return (1-100, default 20)",
-        },
-      },
-    },
-  },
-  {
-    name: "get_event",
-    description: "Get the full payload for a single webhook event by ID.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        event_id: { type: "string", description: "The event ID to retrieve" },
-      },
-      required: ["event_id"],
-    },
-  },
-  {
-    name: "get_webhook_events",
-    description:
-      "Get pending (unprocessed) GitHub webhook events with full payloads. Prefer get_pending_status or list_pending_events for polling.",
-    inputSchema: { type: "object", properties: {} },
-  },
-  {
-    name: "mark_processed",
-    description: "Mark a webhook event as processed so it won't appear again.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        event_id: {
-          type: "string",
-          description: "The event ID to mark as processed",
-        },
-      },
-      required: ["event_id"],
-    },
-  },
-];
-
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
-
-server.setRequestHandler(CallToolRequestSchema, async (req) => {
-  const { name, arguments: args } = req.params;
-
-  switch (name) {
-    case "get_pending_status": {
-      const status = getPendingStatus();
-      return {
-        content: [{ type: "text", text: JSON.stringify(status, null, 2) }],
-      };
-    }
-    case "list_pending_events": {
-      const limit = Math.max(1, Math.min(100, Number(args?.limit) || 20));
-      const summaries = getPendingSummaries(limit);
-      return {
-        content: [{ type: "text", text: JSON.stringify(summaries, null, 2) }],
-      };
-    }
-    case "get_event": {
-      const event = getEvent(args.event_id);
-      if (event === null) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({ error: "not_found", event_id: args.event_id }),
-            },
-          ],
-        };
-      }
-      return {
-        content: [{ type: "text", text: JSON.stringify(event, null, 2) }],
-      };
-    }
-    case "get_webhook_events": {
-      const events = getPending();
-      return {
-        content: [{ type: "text", text: JSON.stringify(events, null, 2) }],
-      };
-    }
-    case "mark_processed": {
-      const result = markDone(args.event_id);
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({
-              success: result.success,
-              event_id: args.event_id,
-              purged: result.purged,
-            }),
-          },
-        ],
-      };
-    }
-    default:
-      throw new Error(`unknown tool: ${name}`);
-  }
-});
-
-// ── Start ───────────────────────────────────────────────────────────────────
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
-
-// ── File watcher (after connect) ─────────────────────────────────────────────
-
-if (CHANNEL_ENABLED) {
-  const seenIds = new Set(getPending().map((e) => e.id));
-  let debounce = null;
-
-  function onFileChange() {
-    if (debounce) return;
-    debounce = setTimeout(() => {
-      debounce = null;
-      try {
-        const pending = getPending();
-        for (const event of pending) {
-          if (seenIds.has(event.id)) continue;
-          seenIds.add(event.id);
-          const summary = summarizeEvent(event);
-          const lines = [
-            `[${summary.type}] ${summary.repo ?? ""}`,
-            summary.action ? `action: ${summary.action}` : null,
-            summary.title ? `#${summary.number ?? ""} ${summary.title}` : null,
-            summary.sender ? `by ${summary.sender}` : null,
-            summary.url ?? null,
-          ].filter(Boolean);
-          server.notification({
-            method: "notifications/claude/channel",
-            params: {
-              content: lines.join("\n"),
-              meta: {
-                chat_id: "github",
-                message_id: event.id,
-                user: summary.sender ?? "github",
-                ts: summary.received_at,
-              },
-            },
-          });
-        }
-      } catch {
-        // file may be mid-write; ignore and retry on next change
-      }
-    }, 500);
-  }
-
-  try {
-    watch(dataFilePath(), onFileChange);
-  } catch {
-    // events.json may not exist yet; start polling fallback
-    const poll = setInterval(() => {
-      try {
-        watch(dataFilePath(), onFileChange);
-        clearInterval(poll);
-      } catch {
-        // keep waiting
-      }
-    }, 5000);
-  }
-}
+#!/usr/bin/env node
+/**
+ * GitHub Webhook MCP — Cloudflare Worker bridge
+ *
+ * Thin stdio MCP server that proxies tool calls to a remote
+ * Cloudflare Worker + Durable Object backend via Streamable HTTP.
+ * Optionally listens to SSE for real-time channel notifications.
+ *
+ * Discord MCP pattern: data lives in the cloud, local MCP is a thin bridge.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const WORKER_URL =
+  process.env.WEBHOOK_WORKER_URL ||
+  "https://github-webhook-mcp.liplus.workers.dev";
+const CHANNEL_ENABLED = process.env.WEBHOOK_CHANNEL !== "0";
+
+// ── Remote MCP Session (lazy, reused) ────────────────────────────────────────
+
+let _sessionId = null;
+
+async function getSessionId() {
+  if (_sessionId) return _sessionId;
+
+  const res = await fetch(`${WORKER_URL}/mcp`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream",
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      method: "initialize",
+      params: {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "local-bridge", version: "1.0.0" },
+      },
+      id: "init",
+    }),
+  });
+
+  _sessionId = res.headers.get("mcp-session-id") || "";
+  return _sessionId;
+}
+
+async function callRemoteTool(name, args) {
+  const sessionId = await getSessionId();
+
+  const res = await fetch(`${WORKER_URL}/mcp`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream",
+      "mcp-session-id": sessionId,
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      method: "tools/call",
+      params: { name, arguments: args },
+      id: crypto.randomUUID(),
+    }),
+  });
+
+  const text = await res.text();
+
+  // Streamable HTTP may return SSE format
+  const dataLine = text.split("\n").find((l) => l.startsWith("data: "));
+  const json = dataLine ? JSON.parse(dataLine.slice(6)) : JSON.parse(text);
+
+  if (json.error) {
+    // Session expired — retry once with a fresh session
+    if (json.error.code === -32600 || json.error.code === -32001) {
+      _sessionId = null;
+      return callRemoteTool(name, args);
+    }
+    return { content: [{ type: "text", text: JSON.stringify(json.error) }] };
+  }
+
+  return json.result;
+}
+
+// ── MCP Server Setup ─────────────────────────────────────────────────────────
+
+const capabilities = { tools: {} };
+if (CHANNEL_ENABLED) {
+  capabilities.experimental = { "claude/channel": {} };
+}
+
+const server = new Server(
+  { name: "github-webhook-mcp", version: "1.0.0" },
+  {
+    capabilities,
+    instructions: CHANNEL_ENABLED
+      ? 'GitHub webhook events arrive as <channel source="github-webhook-mcp" ...>. They are one-way: read them and act, no reply expected.'
+      : undefined,
+  },
+);
+
+// ── Tool Definitions ─────────────────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: "get_pending_status",
+    title: "Get Pending Status",
+    description:
+      "Get a lightweight snapshot of pending GitHub webhook events. Use this for periodic polling before requesting details.",
+    inputSchema: { type: "object", properties: {} },
+    annotations: {
+      title: "Get Pending Status",
+      readOnlyHint: true,
+    },
+  },
+  {
+    name: "list_pending_events",
+    title: "List Pending Events",
+    description:
+      "List lightweight summaries for pending GitHub webhook events. Returns metadata only, without full payloads.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "number",
+          description:
+            "Maximum number of pending events to return (1-100, default 20)",
+        },
+      },
+    },
+    annotations: {
+      title: "List Pending Events",
+      readOnlyHint: true,
+    },
+  },
+  {
+    name: "get_event",
+    title: "Get Event Payload",
+    description: "Get the full payload for a single webhook event by ID.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        event_id: { type: "string", description: "The event ID to retrieve" },
+      },
+      required: ["event_id"],
+    },
+    annotations: {
+      title: "Get Event Payload",
+      readOnlyHint: true,
+    },
+  },
+  {
+    name: "get_webhook_events",
+    title: "Get Webhook Events",
+    description:
+      "Get pending (unprocessed) GitHub webhook events with full payloads. Prefer get_pending_status or list_pending_events for polling.",
+    inputSchema: { type: "object", properties: {} },
+    annotations: {
+      title: "Get Webhook Events",
+      readOnlyHint: true,
+    },
+  },
+  {
+    name: "mark_processed",
+    title: "Mark Event Processed",
+    description:
+      "Mark a webhook event as processed so it won't appear again.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        event_id: {
+          type: "string",
+          description: "The event ID to mark as processed",
+        },
+      },
+      required: ["event_id"],
+    },
+    annotations: {
+      title: "Mark Event Processed",
+      destructiveHint: true,
+    },
+  },
+];
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+  try {
+    return await callRemoteTool(name, args ?? {});
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: `Failed to reach worker: ${err}` }],
+      isError: true,
+    };
+  }
+});
+
+// ── SSE Listener → Channel Notifications ─────────────────────────────────────
+
+async function connectSSE() {
+  let EventSourceImpl;
+  try {
+    EventSourceImpl = (await import("eventsource")).default;
+  } catch {
+    // eventsource not installed — skip SSE
+    return;
+  }
+
+  const es = new EventSourceImpl(`${WORKER_URL}/events`);
+
+  es.onmessage = (event) => {
+    try {
+      const data = JSON.parse(event.data);
+      if ("heartbeat" in data || "status" in data) return;
+      if (!data.summary) return;
+
+      const s = data.summary;
+      const lines = [
+        `[${s.type}] ${s.repo ?? ""}`,
+        s.action ? `action: ${s.action}` : null,
+        s.title ? `#${s.number ?? ""} ${s.title}` : null,
+        s.sender ? `by ${s.sender}` : null,
+        s.url ?? null,
+      ].filter(Boolean);
+
+      server.notification({
+        method: "notifications/claude/channel",
+        params: {
+          content: lines.join("\n"),
+          meta: {
+            chat_id: "github",
+            message_id: s.id,
+            user: s.sender ?? "github",
+            ts: s.received_at,
+          },
+        },
+      });
+    } catch {
+      // Ignore parse errors
+    }
+  };
+
+  es.onerror = () => {
+    // EventSource auto-reconnects
+  };
+}
+
+// ── Start ────────────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+if (CHANNEL_ENABLED) {
+  connectSSE();
+}

package/server/event-store.js

@@ -1,181 +0,0 @@
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import { resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import iconv from "iconv-lite";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const DEFAULT_DATA_FILE = resolve(__dirname, "..", "..", "events.json");
-const PRIMARY_ENCODING = "utf-8";
-const LEGACY_ENCODINGS = ["utf-8", "cp932", "shift_jis"];
-const DEFAULT_PURGE_DAYS = 1;
-
-function purgeDays() {
-  const env = process.env.PURGE_AFTER_DAYS;
-  if (env !== undefined) {
-    const n = Number(env);
-    if (Number.isFinite(n) && n >= 0) return n;
-  }
-  return DEFAULT_PURGE_DAYS;
-}
-
-export function dataFilePath() {
-  return process.env.EVENTS_JSON_PATH || DEFAULT_DATA_FILE;
-}
-
-// ── Load / Save ─────────────────────────────────────────────────────────────
-
-export function load() {
-  const filePath = dataFilePath();
-  if (!existsSync(filePath)) return [];
-
-  const raw = readFileSync(filePath);
-
-  // Try UTF-8 first (with BOM stripping)
-  try {
-    let text = raw.toString("utf-8");
-    if (text.charCodeAt(0) === 0xfeff) text = text.slice(1);
-    const events = JSON.parse(text);
-    return events;
-  } catch {
-    // fall through to legacy encodings
-  }
-
-  // Try legacy encodings
-  for (const encoding of LEGACY_ENCODINGS) {
-    try {
-      const text = iconv.decode(raw, encoding);
-      const events = JSON.parse(text);
-      // Migrate to UTF-8
-      save(events);
-      return events;
-    } catch {
-      continue;
-    }
-  }
-
-  throw new Error(`Unable to decode event store: ${filePath}`);
-}
-
-export function save(events) {
-  const filePath = dataFilePath();
-  writeFileSync(filePath, JSON.stringify(events, null, 2), PRIMARY_ENCODING);
-}
-
-// ── Purge ──────────────────────────────────────────────────────────────────
-
-export function purgeProcessed(events) {
-  const days = purgeDays();
-  if (days < 0) return { kept: events, purged: 0 };
-  const cutoff = Date.now() - days * 86_400_000;
-  const before = events.length;
-  const kept = events.filter((e) => {
-    if (!e.processed) return true;
-    const ts = Date.parse(e.received_at);
-    return Number.isNaN(ts) || ts > cutoff;
-  });
-  return { kept, purged: before - kept.length };
-}
-
-// ── Query ───────────────────────────────────────────────────────────────────
-
-export function getPending() {
-  return load().filter((e) => !e.processed);
-}
-
-export function getEvent(eventId) {
-  for (const event of load()) {
-    if (event.id === eventId) return event;
-  }
-  return null;
-}
-
-export function getPendingStatus() {
-  const pending = getPending();
-  const types = {};
-  for (const event of pending) {
-    types[event.type] = (types[event.type] || 0) + 1;
-  }
-  return {
-    pending_count: pending.length,
-    latest_received_at: pending.length > 0 ? pending[pending.length - 1].received_at : null,
-    types,
-  };
-}
-
-// ── Summary ─────────────────────────────────────────────────────────────────
-
-function eventNumber(payload) {
-  return (
-    payload.number ??
-    payload.issue?.number ??
-    payload.pull_request?.number ??
-    null
-  );
-}
-
-function eventTitle(payload) {
-  return (
-    payload.issue?.title ??
-    payload.pull_request?.title ??
-    payload.discussion?.title ??
-    payload.check_run?.name ??
-    payload.workflow_run?.name ??
-    payload.workflow_job?.name ??
-    null
-  );
-}
-
-function eventUrl(payload) {
-  return (
-    payload.issue?.html_url ??
-    payload.pull_request?.html_url ??
-    payload.discussion?.html_url ??
-    payload.check_run?.html_url ??
-    payload.workflow_run?.html_url ??
-    null
-  );
-}
-
-export function summarizeEvent(event) {
-  const payload = event.payload || {};
-  return {
-    id: event.id,
-    type: event.type,
-    received_at: event.received_at,
-    processed: event.processed,
-    trigger_status: event.trigger_status ?? null,
-    last_triggered_at: event.last_triggered_at ?? null,
-    action: payload.action ?? null,
-    repo: payload.repository?.full_name ?? null,
-    sender: payload.sender?.login ?? null,
-    number: eventNumber(payload),
-    title: eventTitle(payload),
-    url: eventUrl(payload),
-  };
-}
-
-export function getPendingSummaries(limit = 20) {
-  let pending = getPending();
-  if (limit > 0) {
-    pending = pending.slice(-limit);
-  }
-  return pending.map(summarizeEvent);
-}
-
-// ── Mutation ────────────────────────────────────────────────────────────────
-
-export function markDone(eventId) {
-  const events = load();
-  let found = false;
-  for (const event of events) {
-    if (event.id === eventId) {
-      event.processed = true;
-      found = true;
-      break;
-    }
-  }
-  if (!found) return { success: false, purged: 0 };
-  const { kept, purged } = purgeProcessed(events);
-  save(kept);
-  return { success: true, purged };
-}