github-webhook-mcp 0.2.1 → 0.3.0

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": "0.3",
   "name": "github-webhook-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Browse pending GitHub webhook events. Pairs with a webhook receiver that writes events.json.",
   "author": {
     "name": "Liplus Project"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-webhook-mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "MCP server for browsing GitHub webhook events",
   "type": "module",
   "bin": {

package/server/event-store.js

@@ -1,152 +1,181 @@
-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"];
-
-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);
-}
-
-// ── 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();
-  for (const event of events) {
-    if (event.id === eventId) {
-      event.processed = true;
-      save(events);
-      return true;
-    }
-  }
-  return false;
-}
+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 };
+}

package/server/index.js

@@ -1,107 +1,215 @@
-#!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import {
-  getPendingStatus,
-  getPendingSummaries,
-  getEvent,
-  getPending,
-  markDone,
-} from "./event-store.js";
-
-const server = new McpServer({
-  name: "github-webhook-mcp",
-  version: "0.2.0",
-});
-
-// ── Tools ───────────────────────────────────────────────────────────────────
-
-server.tool(
-  "get_pending_status",
-  "Get a lightweight snapshot of pending GitHub webhook events. Use this for periodic polling before requesting details.",
-  {},
-  async () => {
-    const status = getPendingStatus();
-    return {
-      content: [{ type: "text", text: JSON.stringify(status, null, 2) }],
-    };
-  }
-);
-
-server.tool(
-  "list_pending_events",
-  "List lightweight summaries for pending GitHub webhook events. Returns metadata only, without full payloads.",
-  {
-    limit: z
-      .number()
-      .int()
-      .min(1)
-      .max(100)
-      .default(20)
-      .describe("Maximum number of pending events to return"),
-  },
-  async ({ limit }) => {
-    const summaries = getPendingSummaries(limit);
-    return {
-      content: [{ type: "text", text: JSON.stringify(summaries, null, 2) }],
-    };
-  }
-);
-
-server.tool(
-  "get_event",
-  "Get the full payload for a single webhook event by ID.",
-  {
-    event_id: z.string().describe("The event ID to retrieve"),
-  },
-  async ({ event_id }) => {
-    const event = getEvent(event_id);
-    if (event === null) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({ error: "not_found", event_id }),
-          },
-        ],
-      };
-    }
-    return {
-      content: [{ type: "text", text: JSON.stringify(event, null, 2) }],
-    };
-  }
-);
-
-server.tool(
-  "get_webhook_events",
-  "Get pending (unprocessed) GitHub webhook events with full payloads. Prefer get_pending_status or list_pending_events for polling.",
-  {},
-  async () => {
-    const events = getPending();
-    return {
-      content: [{ type: "text", text: JSON.stringify(events, null, 2) }],
-    };
-  }
-);
-
-server.tool(
-  "mark_processed",
-  "Mark a webhook event as processed so it won't appear again.",
-  {
-    event_id: z.string().describe("The event ID to mark as processed"),
-  },
-  async ({ event_id }) => {
-    const success = markDone(event_id);
-    return {
-      content: [
-        { type: "text", text: JSON.stringify({ success, event_id }) },
-      ],
-    };
-  }
-);
-
-// ── Start ───────────────────────────────────────────────────────────────────
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
+#!/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);
+  }
+}