@tensakulabs/discord-mcp 0.1.2 → 0.1.4

package/README.md

@@ -17,6 +17,8 @@ Exposes 6 Discord tools via MCP (Model Context Protocol):
 | `discord_send_message` | Send a message (channel or DM) |
 | `discord_get_unread` | Get messages you haven't seen yet |
 
+A background daemon maintains a persistent WebSocket to the Discord Gateway, ingesting messages into a local SQLite database so `discord_get_unread` works even while Claude isn't running.
+
 ## Setup
 
 ### 1. Install & configure
@@ -27,8 +29,9 @@ npx @tensakulabs/discord-mcp setup
 
 This will:
 1. Show you how to extract your Discord token from the desktop app
-2. Save it securely to your OS keychain
-3. Auto-register the MCP server in Claude's config
+2. Save it securely to your OS keychain (macOS: uses built-in `security` CLI — no native module required)
+3. Start the background daemon via launchd (macOS) or systemd (Linux)
+4. Auto-register the MCP server in Claude's config
 
 ### 2. Token extraction (step shown during setup)
 
@@ -72,6 +75,69 @@ Once registered, Claude can use Discord tools directly:
 → Claude calls discord_send_message with replyToMessageId
 ```
 
+## Hooks
+
+Fire shell commands or HTTP webhooks when Discord events occur. Configure in `~/.config/discord-mcp/config.json`:
+
+```json
+{
+  "hooks": {
+    "on_mention": [
+      {
+        "type": "command",
+        "enabled": true,
+        "command": "osascript -e 'display notification \"{content}\" with title \"Mention from {author}\"'"
+      }
+    ],
+    "on_everyone": [],
+    "on_here": [],
+    "on_message": []
+  }
+}
+```
+
+### Hook types
+
+| Hook | Fires when |
+|------|-----------|
+| `on_mention` | Someone directly @username mentions you |
+| `on_everyone` | Someone uses @everyone in a server you're in |
+| `on_here` | Someone uses @here in a server you're in |
+| `on_message` | Any non-bot message (use sparingly — fires a lot) |
+
+### Hook config fields
+
+| Field | Values | Description |
+|-------|--------|-------------|
+| `type` | `"command"` \| `"http"` | Shell command or HTTP POST |
+| `enabled` | `true` \| `false` | Toggle without removing |
+| `command` | string | Shell command (type: command) |
+| `url` | string | Endpoint to POST to (type: http) |
+
+### Template variables
+
+Available in `command` strings and HTTP POST body:
+
+| Variable | Value |
+|----------|-------|
+| `{author}` | Username of message sender |
+| `{content}` | Message text |
+| `{channel}` | Channel ID |
+| `{guild}` | Guild/server ID (or `"dm"` for DMs) |
+| `{is_dm}` | `true` or `false` |
+
+### HTTP hook payload
+
+```json
+{
+  "author": "username",
+  "content": "message text",
+  "channel": "channel-id",
+  "guild": "guild-id",
+  "is_dm": false
+}
+```
+
 ## OpenClaw integration
 
 Add to OpenClaw's MCP config:
@@ -91,10 +157,9 @@ Add to OpenClaw's MCP config:
 
 ## Security
 
-- Token stored in OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Store)
-- Fallback: AES-256-CBC encrypted file at `~/.config/discord-mcp/token.enc`
+- Token stored in OS keychain (macOS: `security` CLI — no native module compilation needed; Linux: keytar; fallback: AES-256-CBC encrypted file)
 - Token never written to config files or logs
-- State (last-seen timestamps, channel modes) at `~/.config/discord-mcp/state.json`
+- Local files at `~/.config/discord-mcp/`: `messages.db`, `config.json`, `token.enc` (fallback only), `daemon.log`
 
 ## Architecture
 
@@ -103,9 +168,14 @@ discord-mcp/
 ├── src/
 │   ├── index.ts          MCP server entry — registers 6 tools
 │   ├── cli.ts            setup + status commands
-│   ├── auth.ts           keychain token storage
+│   ├── daemon.ts         Discord Gateway WebSocket → SQLite ingestion + hooks
+│   ├── auth.ts           keychain token storage (macOS security CLI / keytar / encrypted file)
+│   ├── hooks.ts          hook runner — shell commands and HTTP webhooks
+│   ├── config.ts         config loader (~/.config/discord-mcp/config.json)
+│   ├── db.ts             SQLite schema + queries
 │   ├── ratelimit.ts      429 backoff + Discord headers
-│   ├── state.ts          per-channel state (review/auto/muted + last-seen)
+│   ├── state.ts          per-channel last-seen state
+│   ├── purge.ts          scheduled message retention cleanup
 │   └── tools/
 │       ├── list_guilds.ts
 │       ├── list_channels.ts
@@ -116,3 +186,5 @@ discord-mcp/
 ```
 
 All Discord API calls go through `rateLimitedFetch` — automatic backoff on 429.
+
+The daemon runs as a launchd service (`com.discord-mcp.daemon`) on macOS, connecting to `wss://gateway.discord.gg` and storing all messages locally for fast unread queries.

package/dist/cli.js

@@ -157,4 +157,8 @@ program
         process.exit(1);
     }
 });
+// Default: no subcommand → run MCP server
+program.action(async () => {
+    await import("./index.js");
+});
 program.parse();

package/dist/config.js

@@ -10,6 +10,12 @@ const DEFAULTS = {
         mentioned: 90,
         fallback_to_api: true,
     },
+    hooks: {
+        on_mention: [],
+        on_everyone: [],
+        on_here: [],
+        on_message: [],
+    },
 };
 export function loadConfig() {
     if (!existsSync(CONFIG_FILE))
@@ -18,6 +24,12 @@ export function loadConfig() {
         const raw = JSON.parse(readFileSync(CONFIG_FILE, "utf8"));
         return {
             retention: { ...DEFAULTS.retention, ...(raw.retention ?? {}) },
+            hooks: {
+                on_mention: raw.hooks?.on_mention ?? [],
+                on_everyone: raw.hooks?.on_everyone ?? [],
+                on_here: raw.hooks?.on_here ?? [],
+                on_message: raw.hooks?.on_message ?? [],
+            },
         };
     }
     catch {

package/dist/daemon.js

@@ -8,6 +8,8 @@ import { WebSocket } from "ws";
 import { getToken } from "./auth.js";
 import { initDb, insertMessage } from "./db.js";
 import { schedulePurge } from "./purge.js";
+import { loadConfig } from "./config.js";
+import { fireHooks } from "./hooks.js";
 const GATEWAY_URL = "wss://gateway.discord.gg/?v=10&encoding=json";
 const IDENTIFY_INTENTS = (1 << 0) | (1 << 9) | (1 << 12); // GUILDS | GUILD_MESSAGES | MESSAGE_CONTENT
 let ws = null;
@@ -16,6 +18,7 @@ let sequence = null;
 let sessionId = null;
 let resumeGatewayUrl = null;
 let reconnectDelay = 1000;
+let selfId = null; // set from READY event
 const db = initDb();
 schedulePurge();
 async function connect(resume = false) {
@@ -82,14 +85,24 @@ function handleEvent(type, data) {
         case "READY":
             sessionId = data.session_id;
             resumeGatewayUrl = data.resume_gateway_url;
-            console.error(`[discord-mcp daemon] Ready.`);
+            selfId = data.user?.id ?? null;
+            console.error(`[discord-mcp daemon] Ready. (selfId: ${selfId})`);
             break;
         case "MESSAGE_CREATE": {
             const msg = data;
             if (msg.author?.bot)
                 break; // ignore bots
-            const isMention = Array.isArray(msg.mentions) &&
-                msg.mentions.some((u) => u.id === (data.self_id ?? ""));
+            // Detect mention type
+            const isDirect = selfId !== null && Array.isArray(msg.mentions) &&
+                msg.mentions.some((u) => u.id === selfId);
+            const isEveryone = msg.mention_everyone === true &&
+                msg.content.includes("@everyone");
+            const isHere = msg.mention_everyone === true &&
+                msg.content.includes("@here");
+            const mentionType = isDirect ? "direct"
+                : isEveryone ? "everyone"
+                    : isHere ? "here"
+                        : null;
             insertMessage(db, {
                 id: msg.id,
                 channel_id: msg.channel_id,
@@ -99,8 +112,25 @@ function handleEvent(type, data) {
                 content: msg.content,
                 timestamp: new Date(msg.timestamp).getTime(),
                 is_dm: msg.guild_id ? 0 : 1,
-                is_mention: isMention ? 1 : 0,
+                is_mention: mentionType !== null ? 1 : 0,
+                mention_type: mentionType,
             });
+            // Fire hooks
+            const cfg = loadConfig();
+            const ctx = {
+                author: msg.author.username,
+                content: msg.content,
+                channel: msg.channel_id,
+                guild: msg.guild_id ?? "dm",
+                is_dm: !msg.guild_id,
+            };
+            if (isDirect)
+                fireHooks(cfg.hooks.on_mention, ctx);
+            if (isEveryone)
+                fireHooks(cfg.hooks.on_everyone, ctx);
+            if (isHere)
+                fireHooks(cfg.hooks.on_here, ctx);
+            fireHooks(cfg.hooks.on_message, ctx);
             break;
         }
     }

package/dist/db.js

@@ -28,16 +28,17 @@ export function initDb() {
     db.pragma("synchronous = NORMAL");
     db.exec(`
     CREATE TABLE IF NOT EXISTS messages (
-      id          TEXT PRIMARY KEY,
-      channel_id  TEXT NOT NULL,
-      guild_id    TEXT,
-      author_id   TEXT NOT NULL,
-      author_name TEXT NOT NULL,
-      content     TEXT NOT NULL,
-      timestamp   INTEGER NOT NULL,  -- unix ms
-      is_dm       INTEGER NOT NULL DEFAULT 0,
-      is_mention  INTEGER NOT NULL DEFAULT 0,
-      seen        INTEGER NOT NULL DEFAULT 0
+      id           TEXT PRIMARY KEY,
+      channel_id   TEXT NOT NULL,
+      guild_id     TEXT,
+      author_id    TEXT NOT NULL,
+      author_name  TEXT NOT NULL,
+      content      TEXT NOT NULL,
+      timestamp    INTEGER NOT NULL,  -- unix ms
+      is_dm        INTEGER NOT NULL DEFAULT 0,
+      is_mention   INTEGER NOT NULL DEFAULT 0,
+      mention_type TEXT DEFAULT NULL, -- "direct" | "everyone" | "here" | null
+      seen         INTEGER NOT NULL DEFAULT 0
     );
 
     CREATE INDEX IF NOT EXISTS idx_channel_ts ON messages(channel_id, timestamp DESC);
@@ -55,15 +56,20 @@ export function initDb() {
       VALUES (new.rowid, new.content, new.author_name);
     END;
   `);
+    // Migration: add mention_type column if not present (existing installs)
+    const cols = db.pragma("table_info(messages)").map(c => c.name);
+    if (!cols.includes("mention_type")) {
+        db.exec("ALTER TABLE messages ADD COLUMN mention_type TEXT DEFAULT NULL");
+    }
     _db = db;
     return db;
 }
 export function insertMessage(db, msg) {
     const stmt = db.prepare(`
     INSERT OR IGNORE INTO messages
-      (id, channel_id, guild_id, author_id, author_name, content, timestamp, is_dm, is_mention, seen)
+      (id, channel_id, guild_id, author_id, author_name, content, timestamp, is_dm, is_mention, mention_type, seen)
     VALUES
-      (@id, @channel_id, @guild_id, @author_id, @author_name, @content, @timestamp, @is_dm, @is_mention, 0)
+      (@id, @channel_id, @guild_id, @author_id, @author_name, @content, @timestamp, @is_dm, @is_mention, @mention_type, 0)
   `);
     stmt.run(msg);
 }

package/dist/hooks.js

@@ -0,0 +1,34 @@
+import { exec } from "child_process";
+function substitute(template, ctx) {
+    return template
+        .replace(/\{author\}/g, ctx.author)
+        .replace(/\{content\}/g, ctx.content.replace(/"/g, '\\"'))
+        .replace(/\{channel\}/g, ctx.channel)
+        .replace(/\{guild\}/g, ctx.guild)
+        .replace(/\{is_dm\}/g, String(ctx.is_dm));
+}
+async function runHook(hook, ctx) {
+    if (!hook.enabled)
+        return;
+    if (hook.type === "command" && hook.command) {
+        const cmd = substitute(hook.command, ctx);
+        exec(cmd, (err) => {
+            if (err)
+                console.error(`[discord-mcp hooks] command failed: ${err.message}`);
+        });
+    }
+    if (hook.type === "http" && hook.url) {
+        fetch(hook.url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(ctx),
+        }).catch((err) => {
+            console.error(`[discord-mcp hooks] http failed: ${err.message}`);
+        });
+    }
+}
+export async function fireHooks(hooks, ctx) {
+    for (const hook of hooks) {
+        runHook(hook, ctx).catch(() => { }); // never block the daemon
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tensakulabs/discord-mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Discord selfbot MCP server — read & send messages via Claude",
   "license": "MIT",
   "type": "module",