omni-notify-mcp 1.0.0

package/README.md

@@ -0,0 +1,109 @@
+# omni-notify-mcp
+
+A Model Context Protocol (MCP) server that lets AI assistants (Claude, Cursor, etc.) send notifications through multiple channels: **desktop**, **Telegram**, **WhatsApp**, **SMS**, and **email**.
+
+## Quick Start
+
+```bash
+npx omni-notify-mcp
+```
+
+Add to your MCP config (`~/.claude.json`, `.vscode/mcp.json`, or `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "notify": {
+      "command": "npx",
+      "args": ["omni-notify-mcp"]
+    }
+  }
+}
+```
+
+Then create `~/.notify-mcp/config.json` (see [Configuration](#configuration)).
+
+## Tools
+
+### `notify`
+Send a notification. Priority controls which channels fire:
+
+| Priority | Channels |
+|----------|----------|
+| `low` | email only |
+| `normal` | desktop + Telegram + email |
+| `high` | desktop + Telegram + WhatsApp + SMS + email |
+
+### `ask`
+Send a question and wait for a reply via Telegram.
+
+### `poll`
+Check the inbox for pending messages from the user.
+
+## Configuration
+
+Create `~/.notify-mcp/config.json`:
+
+```json
+{
+  "desktop": {
+    "enabled": true
+  },
+  "telegram": {
+    "enabled": true,
+    "token": "YOUR_BOT_TOKEN",
+    "chatId": "YOUR_CHAT_ID"
+  },
+  "whatsapp": {
+    "enabled": false,
+    "instanceId": "YOUR_GREEN_API_INSTANCE_ID",
+    "apiToken": "YOUR_GREEN_API_TOKEN",
+    "phone": "+1234567890"
+  },
+  "sms": {
+    "enabled": false,
+    "accountSid": "YOUR_TWILIO_ACCOUNT_SID",
+    "authToken": "YOUR_TWILIO_AUTH_TOKEN",
+    "from": "+1YOUR_TWILIO_NUMBER",
+    "to": "+1YOUR_PERSONAL_NUMBER"
+  },
+  "email": {
+    "enabled": true,
+    "host": "smtp.gmail.com",
+    "port": 587,
+    "secure": false,
+    "user": "your-email@gmail.com",
+    "pass": "YOUR_GMAIL_APP_PASSWORD",
+    "to": "your-email@gmail.com"
+  }
+}
+```
+
+Only enable the channels you need — disabled channels are silently skipped.
+
+### Channel Setup
+
+**Desktop** — works out of the box on macOS, Windows, and Linux.
+
+**Telegram**
+1. Create a bot via [@BotFather](https://t.me/botfather) → get a token
+2. Message your bot, then get your chat ID:
+   ```
+   https://api.telegram.org/bot<TOKEN>/getUpdates
+   ```
+
+**WhatsApp** — uses [Green API](https://green-api.com). Create a free instance and paste the `instanceId` and `apiToken`.
+
+**SMS** — uses [Twilio](https://twilio.com). Requires an account SID, auth token, and a Twilio phone number.
+
+**Email (SMTP)** — works with any SMTP provider. For Gmail, use an [App Password](https://myaccount.google.com/apppasswords).
+
+**Email (Gmail OAuth)** — run the built-in config UI for OAuth setup:
+```bash
+npx omni-notify-mcp ui
+```
+Then open http://localhost:3737.
+
+## License
+
+MIT

package/config.example.json

@@ -0,0 +1,26 @@
+{
+  "desktop": {
+    "enabled": true
+  },
+  "whatsapp": {
+    "enabled": true,
+    "phone": "+1234567890",
+    "apikey": "YOUR_CALLMEBOT_APIKEY"
+  },
+  "sms": {
+    "enabled": true,
+    "accountSid": "YOUR_TWILIO_ACCOUNT_SID",
+    "authToken": "YOUR_TWILIO_AUTH_TOKEN",
+    "from": "+1YOUR_TWILIO_NUMBER",
+    "to": "+1YOUR_PERSONAL_NUMBER"
+  },
+  "email": {
+    "enabled": true,
+    "host": "smtp.gmail.com",
+    "port": 587,
+    "secure": false,
+    "user": "your-email@gmail.com",
+    "pass": "YOUR_GMAIL_APP_PASSWORD",
+    "to": "your-email@gmail.com"
+  }
+}

package/dist/channels/desktop.js

@@ -0,0 +1,13 @@
+import notifier from "node-notifier";
+export async function sendDesktop(config, message) {
+    if (!config.enabled)
+        return;
+    await new Promise((resolve, reject) => {
+        notifier.notify({ title: "Claude", message, sound: true }, (err) => {
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+    });
+}

package/dist/channels/email.js

@@ -0,0 +1,29 @@
+import nodemailer from "nodemailer";
+export async function sendEmail(config, message) {
+    if (!config.enabled)
+        return;
+    const transport = config.refreshToken && config.clientId && config.clientSecret
+        ? nodemailer.createTransport({
+            service: "gmail",
+            auth: {
+                type: "OAuth2",
+                user: config.connectedEmail ?? config.to,
+                clientId: config.clientId,
+                clientSecret: config.clientSecret,
+                refreshToken: config.refreshToken,
+                accessToken: config.accessToken,
+            },
+        })
+        : nodemailer.createTransport({
+            host: config.host,
+            port: config.port ?? 587,
+            secure: config.secure ?? false,
+            auth: { user: config.user, pass: config.pass },
+        });
+    await transport.sendMail({
+        from: config.from ?? config.connectedEmail ?? config.user,
+        to: config.to,
+        subject: "Claude notification",
+        text: message,
+    });
+}

package/dist/channels/sms.js

@@ -0,0 +1,7 @@
+import twilio from "twilio";
+export async function sendSms(config, message) {
+    if (!config.enabled)
+        return;
+    const client = twilio(config.accountSid, config.authToken);
+    await client.messages.create({ body: message, from: config.from, to: config.to });
+}

package/dist/channels/telegram.js

@@ -0,0 +1,11 @@
+export async function sendTelegram(config, message) {
+    if (!config.enabled)
+        return;
+    const res = await fetch(`https://api.telegram.org/bot${config.token}/sendMessage`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ chat_id: config.chatId, text: message }),
+    });
+    if (!res.ok)
+        throw new Error(`Telegram error ${res.status}: ${await res.text()}`);
+}

package/dist/channels/whatsapp.js

@@ -0,0 +1,11 @@
+export async function sendWhatsApp(config, message) {
+    if (!config.enabled)
+        return;
+    const res = await fetch(`https://api.green-api.com/waInstance${config.instanceId}/sendMessage/${config.apiToken}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ chatId: `${config.phone}@c.us`, message }),
+    });
+    if (!res.ok)
+        throw new Error(`Green API error ${res.status}: ${await res.text()}`);
+}

package/dist/config.js

@@ -0,0 +1,16 @@
+import { readFileSync, existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+const CONFIG_PATHS = [
+    join(process.cwd(), "config.json"),
+    join(homedir(), ".notify-mcp", "config.json"),
+];
+export function loadConfig() {
+    for (const path of CONFIG_PATHS) {
+        if (existsSync(path)) {
+            const raw = readFileSync(path, "utf-8");
+            return JSON.parse(raw);
+        }
+    }
+    throw new Error(`No config.json found. Run: npm run ui  (then configure at http://localhost:3737)`);
+}

package/dist/index.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { randomUUID } from "crypto";
+import { z } from "zod";
+import { loadConfig } from "./config.js";
+import { sendDesktop } from "./channels/desktop.js";
+import { sendTelegram } from "./channels/telegram.js";
+import { sendWhatsApp } from "./channels/whatsapp.js";
+import { sendSms } from "./channels/sms.js";
+import { sendEmail } from "./channels/email.js";
+const config = loadConfig();
+// ── Telegram listener ─────────────────────────────────────────────────────────
+const pendingAsks = new Map();
+const inboxQueue = [];
+let tgPollOffset = -1;
+async function initTgOffset(token) {
+    const r = await fetch(`https://api.telegram.org/bot${token}/getUpdates?offset=-1&timeout=0`);
+    const json = await r.json();
+    const results = json.result ?? [];
+    return results.length > 0 ? results[results.length - 1].update_id + 1 : 0;
+}
+async function startTelegramListener() {
+    while (true) {
+        try {
+            const cfg = loadConfig();
+            const { token, chatId } = cfg.telegram ?? {};
+            if (!token || !chatId || !cfg.telegram?.enabled) {
+                await new Promise(r => setTimeout(r, 5000));
+                continue;
+            }
+            if (tgPollOffset < 0) {
+                tgPollOffset = await initTgOffset(token);
+            }
+            const r = await fetch(`https://api.telegram.org/bot${token}/getUpdates?offset=${tgPollOffset}&timeout=10`);
+            const json = await r.json();
+            for (const update of json.result ?? []) {
+                tgPollOffset = update.update_id + 1;
+                const msg = update.message;
+                if (msg?.chat?.id?.toString() === chatId && msg.text) {
+                    const first = [...pendingAsks.entries()][0];
+                    if (first) {
+                        const [id, pending] = first;
+                        clearTimeout(pending.timer);
+                        pendingAsks.delete(id);
+                        pending.resolve(msg.text);
+                    }
+                    else {
+                        inboxQueue.push({ text: msg.text, ts: new Date().toISOString() });
+                    }
+                }
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!msg.includes("terminated") && !msg.includes("aborted")) {
+                await new Promise(r => setTimeout(r, 2000));
+            }
+        }
+    }
+}
+startTelegramListener();
+// ── MCP server ────────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "omni-notify-mcp",
+    version: "1.0.0",
+});
+server.tool("notify", "Send a notification through configured channels (desktop, Telegram, WhatsApp, SMS, email). " +
+    "Priority: low=email only; normal=desktop+telegram+email; high=all channels. " +
+    "Use for: task milestones, questions needing user input, catastrophic findings, long task completion.", {
+    message: z.string().max(500).describe("Notification message, max 500 chars"),
+    priority: z
+        .enum(["low", "normal", "high"])
+        .default("normal")
+        .describe("low=email only; normal=desktop+telegram+email; high=desktop+telegram+whatsapp+sms+email"),
+}, async ({ message, priority }) => {
+    const results = [];
+    const errors = [];
+    const send = async (name, fn) => {
+        try {
+            await fn();
+            results.push(name);
+        }
+        catch (err) {
+            errors.push(`${name}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    if (priority === "normal" || priority === "high") {
+        await send("desktop", () => sendDesktop(config.desktop, message));
+        await send("telegram", () => sendTelegram(config.telegram, message));
+    }
+    if (priority === "high") {
+        await send("whatsapp", () => sendWhatsApp(config.whatsapp, message));
+        await send("sms", () => sendSms(config.sms, message));
+    }
+    await send("email", () => sendEmail(config.email, message));
+    const summary = [
+        results.length > 0 ? `Sent via: ${results.join(", ")}` : null,
+        errors.length > 0 ? `Errors: ${errors.join("; ")}` : null,
+    ].filter(Boolean).join(" | ");
+    return { content: [{ type: "text", text: summary || "No channels delivered" }] };
+});
+server.tool("ask", "Send a question to the user via Telegram and wait for their reply. " +
+    "Use when a decision is needed before continuing — e.g. 'Should I delete these files?'", {
+    question: z.string().max(500).describe("The question to ask the user"),
+    timeout_seconds: z.number().min(30).max(3600).default(300)
+        .describe("How long to wait for a reply in seconds (default 5 min)"),
+}, async ({ question, timeout_seconds = 300 }) => {
+    const cfg = loadConfig();
+    if (!cfg.telegram?.enabled || !cfg.telegram.token || !cfg.telegram.chatId) {
+        return { content: [{ type: "text", text: "Error: Telegram not configured. Enable it in ~/.notify-mcp/config.json" }] };
+    }
+    await fetch(`https://api.telegram.org/bot${cfg.telegram.token}/sendMessage`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            chat_id: cfg.telegram.chatId,
+            text: `❓ ${question}\n\nReply to this message with your answer.`,
+        }),
+    });
+    const token = randomUUID();
+    const reply = await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            pendingAsks.delete(token);
+            reject(new Error(`No reply received within ${timeout_seconds}s`));
+        }, timeout_seconds * 1000);
+        pendingAsks.set(token, { resolve, timer });
+    });
+    return { content: [{ type: "text", text: reply }] };
+});
+server.tool("poll", "Check for unsolicited messages the user sent on Telegram (not in response to an ask). " +
+    "Returns queued messages and clears the queue. Returns 'inbox:empty' if nothing pending. " +
+    "Call this at the start of each work cycle.", {}, async () => {
+    if (inboxQueue.length === 0) {
+        return { content: [{ type: "text", text: "inbox:empty" }] };
+    }
+    const messages = inboxQueue.splice(0);
+    return {
+        content: [{
+                type: "text",
+                text: messages.map(m => `[${m.ts}] ${m.text}`).join("\n"),
+            }],
+    };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);