github-webhook-mcp 0.2.1 → 0.4.1

package/manifest.json

@@ -1,11 +1,21 @@
 {
   "manifest_version": "0.3",
   "name": "github-webhook-mcp",
-  "version": "0.2.0",
+  "display_name": "GitHub Webhook MCP",
+  "version": "0.4.1",
   "description": "Browse pending GitHub webhook events. Pairs with a webhook receiver that writes events.json.",
+  "long_description": "GitHub Webhook MCP helps Claude review and react to GitHub notifications from a local event store. It surfaces lightweight pending-event summaries, exposes full webhook payloads on demand, and lets users mark handled events as processed without exposing the event file directly.",
   "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",
@@ -51,10 +61,24 @@
     }
   ],
   "compatibility": {
+    "claude_desktop": ">=0.11.0",
     "platforms": [
       "win32",
       "darwin",
       "linux"
-    ]
-  }
+    ],
+    "runtimes": {
+      "node": ">=18.0.0"
+    }
+  },
+  "keywords": [
+    "github",
+    "webhook",
+    "notifications",
+    "mcp",
+    "claude"
+  ],
+  "privacy_policies": [
+    "https://smgjp.com/privacy-policy-github-webhook-mcp/"
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-webhook-mcp",
-  "version": "0.2.1",
+  "version": "0.4.1",
   "description": "MCP server for browsing GitHub webhook events",
   "type": "module",
   "bin": {
@@ -13,7 +13,7 @@
   ],
   "scripts": {
     "start": "node server/index.js",
-    "test": "node --test test/",
+    "test": "node --check server/index.js && node --check server/event-store.js",
     "pack:mcpb": "mcpb pack"
   },
   "dependencies": {

package/server/event-store.js

@@ -7,8 +7,18 @@ 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 dataFilePath() {
+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;
 }
 
@@ -51,6 +61,21 @@ export function save(events) {
   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() {
@@ -141,12 +166,16 @@ export function getPendingSummaries(limit = 20) {
 
 export function markDone(eventId) {
   const events = load();
+  let found = false;
   for (const event of events) {
     if (event.id === eventId) {
       event.processed = true;
-      save(events);
-      return true;
+      found = true;
+      break;
     }
   }
-  return false;
+  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,240 @@
 #!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
+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 server = new McpServer({
-  name: "github-webhook-mcp",
-  version: "0.2.0",
-});
-
-// ── Tools ───────────────────────────────────────────────────────────────────
+const CHANNEL_ENABLED = process.env.WEBHOOK_CHANNEL !== "0";
 
-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) }],
-    };
-  }
-);
+const capabilities = {
+  tools: {},
+};
+if (CHANNEL_ENABLED) {
+  capabilities.experimental = { "claude/channel": {} };
+}
 
-server.tool(
-  "list_pending_events",
-  "List lightweight summaries for pending GitHub webhook events. Returns metadata only, without full payloads.",
+const server = new Server(
+  { name: "github-webhook-mcp", version: "0.4.1" },
   {
-    limit: z
-      .number()
-      .int()
-      .min(1)
-      .max(100)
-      .default(20)
-      .describe("Maximum number of pending events to return"),
+    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,
   },
-  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.",
+// ── Tools ───────────────────────────────────────────────────────────────────
+
+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,
+    },
+  },
   {
-    event_id: z.string().describe("The event ID to retrieve"),
+    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,
+    },
   },
-  async ({ event_id }) => {
-    const event = getEvent(event_id);
-    if (event === null) {
+  {
+    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;
+
+  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({ error: "not_found", event_id }),
+            text: JSON.stringify({
+              success: result.success,
+              event_id: args.event_id,
+              purged: result.purged,
+            }),
           },
         ],
       };
     }
-    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 }) },
-      ],
-    };
+    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);
+  }
+}