github-webhook-mcp 0.2.0

package/manifest.json

@@ -0,0 +1,60 @@
+{
+  "manifest_version": "0.3",
+  "name": "github-webhook-mcp",
+  "version": "0.2.0",
+  "description": "Browse pending GitHub webhook events. Pairs with a webhook receiver that writes events.json.",
+  "author": {
+    "name": "Liplus Project"
+  },
+  "license": "MIT",
+  "server": {
+    "type": "node",
+    "entry_point": "server/index.js",
+    "mcp_config": {
+      "command": "node",
+      "args": [
+        "${__dirname}/server/index.js"
+      ],
+      "env": {
+        "EVENTS_JSON_PATH": "${user_config.events_json_path}"
+      }
+    }
+  },
+  "user_config": {
+    "events_json_path": {
+      "description": "Absolute path to the events.json file written by the webhook receiver.",
+      "type": "string",
+      "required": true,
+      "title": "Events JSON Path"
+    }
+  },
+  "tools": [
+    {
+      "name": "get_pending_status",
+      "description": "Get a lightweight snapshot of pending GitHub webhook events."
+    },
+    {
+      "name": "list_pending_events",
+      "description": "List lightweight summaries for pending GitHub webhook events."
+    },
+    {
+      "name": "get_event",
+      "description": "Get the full payload for a single webhook event by ID."
+    },
+    {
+      "name": "get_webhook_events",
+      "description": "Get pending (unprocessed) GitHub webhook events with full payloads."
+    },
+    {
+      "name": "mark_processed",
+      "description": "Mark a webhook event as processed so it won't appear again."
+    }
+  ],
+  "compatibility": {
+    "platforms": [
+      "win32",
+      "darwin",
+      "linux"
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "github-webhook-mcp",
+  "version": "0.2.0",
+  "description": "MCP server for browsing GitHub webhook events",
+  "type": "module",
+  "bin": {
+    "github-webhook-mcp": "server/index.js"
+  },
+  "main": "./server/index.js",
+  "files": [
+    "server/",
+    "manifest.json"
+  ],
+  "scripts": {
+    "start": "node server/index.js",
+    "test": "node --test test/",
+    "pack:mcpb": "mcpb pack"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "iconv-lite": "^0.6.3",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@anthropic-ai/mcpb": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "github",
+    "webhook"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Liplus-Project/github-webhook-mcp.git"
+  }
+}

package/server/event-store.js

@@ -0,0 +1,152 @@
+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;
+}

package/server/index.js

@@ -0,0 +1,107 @@
+#!/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);