omni-notify-mcp 1.0.1 → 1.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 menih
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,14 +1,47 @@
-# omni-notify-mcp
+<p align="center">
+  <img src="assets/logo.svg" width="128" height="128" alt="omni-notify-mcp">
+</p>
 
-A Model Context Protocol (MCP) server that lets AI assistants (Claude, Cursor, etc.) send notifications through multiple channels: **desktop**, **Telegram**, **WhatsApp**, **SMS**, and **email**.
+<h1 align="center">omni-notify-mcp</h1>
 
-## Quick Start
+<p align="center">
+  <em>Reach me on any channel. Ask me anything. Get out of my way when I'm busy.</em><br>
+  An MCP server that gives AI agents (Claude, Cursor, etc.) a single
+  <code>notify</code> / <code>ask</code> interface — desktop, Telegram, SMS, email —
+  with two-way replies, idle gating, and Do Not Disturb.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/omni-notify-mcp"><img src="https://img.shields.io/npm/v/omni-notify-mcp.svg" alt="npm"></a>
+  <a href="https://marketplace.visualstudio.com/items?itemName=MeniHillel.omni-notify-mcp"><img src="https://img.shields.io/visual-studio-marketplace/v/MeniHillel.omni-notify-mcp?label=marketplace" alt="VS Code Marketplace"></a>
+  <img src="https://img.shields.io/badge/license-MIT-4ea3ff.svg" alt="MIT license">
+  <img src="https://img.shields.io/badge/MCP-compatible-4ea3ff.svg" alt="MCP compatible">
+</p>
+
+<p align="center">
+  <img src="assets/screenshots/main-ui.png" width="900" alt="omni-notify-mcp config UI — channels and policies side by side, with live activity log">
+</p>
+
+---
+
+## Why
+
+You step away from your machine and the AI is still working. **It needs to**:
+
+- tell you something important happened (`notify`)
+- ask you a question and wait for your answer (`ask`)
+- check whether you've sent it an unsolicited message (`poll`, or live SSE)
+- **not buzz your phone every 90 seconds** while you're sitting at the keyboard
+
+`omni-notify-mcp` is the one MCP server that does all of that, on whatever channels you've configured, with the right level of "shut up" built in.
+
+## Quick start
 
 ```bash
 npx omni-notify-mcp
 ```
 
-Add to your MCP config (`~/.claude.json`, `.vscode/mcp.json`, or `claude_desktop_config.json`):
+Add to your MCP config (`~/.claude.json`, `.vscode/mcp.json`, `claude_desktop_config.json`, etc.):
 
 ```json
 {
@@ -21,89 +54,138 @@ Add to your MCP config (`~/.claude.json`, `.vscode/mcp.json`, or `claude_desktop
 }
 ```
 
-Then create `~/.notify-mcp/config.json` (see [Configuration](#configuration)).
+Then run the config UI to wire up your channels:
 
-## Tools
+```bash
+npx omni-notify-mcp ui
+```
 
-### `notify`
-Send a notification. Priority controls which channels fire:
+Open <http://localhost:3737>, toggle the channels you want, and hit Save. The MCP server picks up changes immediately — no restart.
+
+## What the agent gets
+
+Six tools, all server-configured (the agent never names a channel):
+
+| Tool | What it does |
+|---|---|
+| **`notify`** | Send a message to the user. Priority controls fan-out (see below). |
+| **`ask`** | Send a question and **wait** for the user's reply (Telegram, or web link via email). |
+| **`poll`** | Drain any unsolicited messages the user sent. |
+| **`get_idle_seconds`** | Seconds since last keyboard/mouse input. -1 if unsupported. |
+| **`get_idle_config`** | The server's idle-gating policy `{ enabled, thresholdSeconds }`. |
+| **`get_dnd_status`** | Current DND state `{ active, reason }`. |
+
+Priority routing for `notify`:
 
 | Priority | Channels |
-|----------|----------|
-| `low` | email only |
+|---|---|
+| `low`    | email only |
 | `normal` | desktop + Telegram + email |
-| `high` | desktop + Telegram + WhatsApp + SMS + email |
+| `high`   | desktop + Telegram + SMS + email — **bypasses DND and idle gating** |
+
+## Features
+
+### Channels
+- **Desktop** — native `node-notifier` (macOS/Windows/Linux). Per-channel **system-sound toggle**.
+- **Telegram** — bidirectional. The bot **replies in-thread** to user messages and acknowledges every inbound message so the user knows it landed.
+- **SMS** — Twilio.
+- **Email** — Gmail App Password (one click) or any SMTP. `ask` over email sends a reply link the user clicks to answer.
+
+### Two-way (`ask`)
+The agent calls `ask`, the question goes out on Telegram and email, and the call **blocks until the user replies** (or times out). Reply on Telegram → agent gets the text. Click the email reply link → agent gets the text. No glue code, no polling loop.
+
+### Real-time inbox push (SSE)
+Subscribe to `GET /api/inbox/stream` (text/event-stream) to receive unsolicited user messages **the moment they arrive** — no polling. Ideal for an always-on agent that wants to react instantly. Per-session tag filtering supported (`?tag=alphawave`). Falls back gracefully to `poll` for clients without SSE.
+
+### Multi-session tagging
+Run multiple agents against the same notify server (e.g. one Claude session in `repo-a`, another in `repo-b`). Each connects with `?tag=<name>` and the user can route a Telegram message to a specific agent by prefixing `@<name>`. Untagged messages broadcast to every session.
+
+### Do Not Disturb
+- **Manual toggle** — flip it on, all `priority < high` notifs drop on the floor.
+- **Scheduled quiet hours** — e.g. 22:00 → 08:00, configurable per-day.
+- `priority='high'` always punches through.
+- Agents can pre-flight with `get_dnd_status` to skip the round-trip when DND is on.
 
-### `ask`
-Send a question and wait for a reply via Telegram.
+### Idle gating (anti-buzz)
+The server publishes a policy `{ enabled, thresholdSeconds }`. Agents are **instructed** (via the MCP `instructions` field, surfaced to every connecting client) to call `get_idle_seconds` first, and **skip** sending a notification if you're actively at the keyboard. They can already see what they'd send. Only fire when you've stepped away. `priority='high'` always fires.
 
-### `poll`
-Check the inbox for pending messages from the user.
+Cross-platform idle detection: Windows (PowerShell + `GetLastInputInfo`), macOS (`ioreg`), Linux (`xprintidle`).
+
+### Web config UI
+One page, dark theme, live activity log streaming over SSE, one-click test buttons per channel, secrets masked at rest. Plus a copy-paste help page that walks any AI client through registration in 30 seconds:
+
+<p align="center">
+  <img src="assets/screenshots/help-page.png" width="800" alt="Help page — copy-paste snippets for Claude Code, Cursor, VS Code, Claude Desktop, Windsurf, Zed">
+</p>
+
+### Activity log
+Every notify, ask, reply, and inbox event is logged with timestamp, direction (`→` `←` `·`), channel, and (color-coded) client/session id. Visible live in the UI; last 500 entries replayed on connect.
+
+### Behavioral rules baked in
+The MCP server ships with `instructions` that tell every connecting client:
+1. Pre-flight with `get_idle_seconds` and skip if user is active.
+2. Echo the message in chat too — don't trust the user is checking their phone.
+3. Use channel-agnostic wording ("notif", not "Telegram").
+4. Reply to inbox messages **through `notify`**, not just in chat.
+5. `priority='high'` is for blockers, not noise.
+
+This means well-behaved agents get the right behavior automatically — no per-prompt nagging required.
 
 ## Configuration
 
-Create `~/.notify-mcp/config.json`:
+Default location: `~/.notify-mcp/config.json`. The web UI manages this file for you, but the schema is straightforward:
 
 ```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"
-  },
+  "desktop": { "enabled": true, "sound": true },
+  "telegram": { "enabled": true, "token": "BOT_TOKEN", "chatId": "CHAT_ID" },
   "sms": {
     "enabled": false,
-    "accountSid": "YOUR_TWILIO_ACCOUNT_SID",
-    "authToken": "YOUR_TWILIO_AUTH_TOKEN",
-    "from": "+1YOUR_TWILIO_NUMBER",
-    "to": "+1YOUR_PERSONAL_NUMBER"
+    "accountSid": "ACxxxx",
+    "authToken": "...",
+    "from": "+15550000000",
+    "to": "+15550000001"
   },
   "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"
-  }
+    "host": "smtp.gmail.com", "port": 587, "secure": false,
+    "user": "you@gmail.com", "pass": "GMAIL_APP_PASSWORD",
+    "to": "you@gmail.com"
+  },
+  "dnd": {
+    "enabled": false,
+    "schedule": {
+      "enabled": false,
+      "quietStart": "22:00", "quietEnd": "08:00",
+      "days": [0, 1, 2, 3, 4, 5, 6]
+    }
+  },
+  "idle": { "enabled": true, "thresholdSeconds": 120 }
 }
 ```
 
-Only enable the channels you need — disabled channels are silently skipped.
+Disabled channels are silently skipped. Secrets are masked when read back via the API.
 
-### Channel Setup
+### Channel setup
 
-**Desktop** — works out of the box on macOS, Windows, and Linux.
+- **Desktop** — works out of the box. Toggle `sound` to mute the system chime.
+- **Telegram** — create a bot via [@BotFather](https://t.me/botfather), then click **Detect** in the UI to auto-fill the chat ID.
+- **SMS** — Twilio account SID + auth token + a Twilio number.
+- **Email** — Gmail [App Password](https://myaccount.google.com/apppasswords) (the UI walks you through it) or any SMTP host/user/pass.
 
-**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
-   ```
+## Endpoints (for power users)
 
-**WhatsApp** — uses [Green API](https://green-api.com). Create a free instance and paste the `instanceId` and `apiToken`.
+The UI server (default `:3737`) also exposes:
 
-**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.
+| Path | Purpose |
+|---|---|
+| `POST /mcp[?tag=<name>]` | StreamableHTTP MCP transport. Optional session tag. |
+| `GET  /api/inbox/stream[?tag=<name>]` | SSE push of unsolicited user messages. |
+| `GET  /api/logs` | SSE stream of the activity log. |
+| `GET/POST /api/config` | Read/write the config (secrets masked on read). |
+| `POST /api/test/<channel>` | One-shot test send for desktop/telegram/sms/email. |
+| `GET  /reply/:token` | Web reply page for `ask` over email. |
 
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE).

package/assets/logo.svg

@@ -0,0 +1,111 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256" role="img" aria-label="omni-notify-mcp">
+  <title>omni-notify-mcp</title>
+  <defs>
+    <!-- Deep slate → bright blue, matches the UI accent -->
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%"  stop-color="#1a3550"/>
+      <stop offset="55%" stop-color="#1f5a96"/>
+      <stop offset="100%" stop-color="#4ea3ff"/>
+    </linearGradient>
+    <linearGradient id="bell" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%"  stop-color="#ffffff"/>
+      <stop offset="100%" stop-color="#dbe8ff"/>
+    </linearGradient>
+    <!-- Sweep wedge: bright leading edge fading to transparent -->
+    <linearGradient id="sweep" x1="1" y1="0" x2="0" y2="1">
+      <stop offset="0%"   stop-color="#a7ffb6" stop-opacity="0.95"/>
+      <stop offset="55%"  stop-color="#34d399" stop-opacity="0.45"/>
+      <stop offset="100%" stop-color="#34d399" stop-opacity="0"/>
+    </linearGradient>
+    <radialGradient id="glow" cx="0.5" cy="0.4" r="0.6">
+      <stop offset="0%"  stop-color="#ffffff" stop-opacity="0.18"/>
+      <stop offset="100%" stop-color="#ffffff" stop-opacity="0"/>
+    </radialGradient>
+
+    <!-- Clip the sweep wedge so it stays inside the outer radar ring -->
+    <clipPath id="radarClip">
+      <circle cx="128" cy="128" r="118"/>
+    </clipPath>
+  </defs>
+
+  <!-- Background fills the entire canvas (was inset 8px before — wasted space) -->
+  <rect x="0" y="0" width="256" height="256" rx="48" fill="url(#bg)"/>
+  <rect x="0" y="0" width="256" height="256" rx="48" fill="url(#glow)"/>
+
+  <!-- ── RADAR (full concentric range rings + sweep wedge) ───────────────── -->
+  <g>
+    <!-- Three full range rings — bigger, stronger -->
+    <circle cx="128" cy="128" r="118" fill="none" stroke="#ffffff" stroke-opacity="0.32" stroke-width="3"/>
+    <circle cx="128" cy="128" r="86"  fill="none" stroke="#ffffff" stroke-opacity="0.42" stroke-width="3"/>
+    <circle cx="128" cy="128" r="54"  fill="none" stroke="#ffffff" stroke-opacity="0.55" stroke-width="3"/>
+
+    <!-- Crosshair lines through center, edge-to-edge -->
+    <line x1="10"  y1="128" x2="246" y2="128" stroke="#ffffff" stroke-opacity="0.22" stroke-width="1.8"/>
+    <line x1="128" y1="10"  x2="128" y2="246" stroke="#ffffff" stroke-opacity="0.22" stroke-width="1.8"/>
+
+    <!-- Sweep wedge: 60° pie slice from center, leading edge to upper-right -->
+    <g clip-path="url(#radarClip)">
+      <path d="M128 128 L128 10 A118 118 0 0 1 230 69 Z"
+            fill="url(#sweep)"/>
+    </g>
+
+    <!-- Bright leading edge so the rotation reads -->
+    <line x1="128" y1="128" x2="230" y2="69"
+          stroke="#a7ffb6" stroke-width="3" stroke-opacity="0.95" stroke-linecap="round"/>
+
+    <!-- Center "ping" dot -->
+    <circle cx="128" cy="128" r="4" fill="#a7ffb6"/>
+  </g>
+
+  <!-- ── BELL (foreground icon, bigger — fills ~50% of the canvas) ──────── -->
+  <g>
+    <!-- Soft drop shadow -->
+    <path d="M128 56
+             C 96 56, 80 80, 80 116
+             L 80 152
+             C 80 162, 72 170, 66 178
+             L 190 178
+             C 184 170, 176 162, 176 152
+             L 176 116
+             C 176 80, 160 56, 128 56 Z"
+          fill="#0a1426" opacity="0.40" transform="translate(0,4)"/>
+    <!-- Bell body -->
+    <path d="M128 56
+             C 96 56, 80 80, 80 116
+             L 80 152
+             C 80 162, 72 170, 66 178
+             L 190 178
+             C 184 170, 176 162, 176 152
+             L 176 116
+             C 176 80, 160 56, 128 56 Z"
+          fill="url(#bell)" stroke="#1a3550" stroke-width="2.5"/>
+    <!-- Bell top stud -->
+    <circle cx="128" cy="48" r="8" fill="url(#bell)" stroke="#1a3550" stroke-width="2.5"/>
+    <!-- Bell clapper -->
+    <path d="M118 188
+             C 118 200, 138 200, 138 188 Z"
+          fill="url(#bell)" stroke="#1a3550" stroke-width="2.5"/>
+  </g>
+
+  <!-- ── CHAT BUBBLE (lower-right, bigger — denotes bidirectional ask/reply) -->
+  <g>
+    <path d="M158 154
+             h 50
+             a 16 16 0 0 1 16 16
+             v 32
+             a 16 16 0 0 1 -16 16
+             h -26
+             l -16 16
+             v -16
+             h -8
+             a 16 16 0 0 1 -16 -16
+             v -32
+             a 16 16 0 0 1 16 -16 Z"
+          fill="#0a1426" stroke="#ffffff" stroke-width="3.5" stroke-linejoin="round"/>
+    <!-- Three bubble dots = "typing / message" -->
+    <circle cx="170" cy="186" r="3.8" fill="#ffffff"/>
+    <circle cx="186" cy="186" r="3.8" fill="#ffffff"/>
+    <circle cx="202" cy="186" r="3.8" fill="#ffffff"/>
+  </g>
+</svg>

package/config.example.json

@@ -1,26 +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"
-  }
-}
+{
+  "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

@@ -1,13 +1,18 @@
 import notifier from "node-notifier";
+import { spawn } from "child_process";
 export async function sendDesktop(config, message) {
     if (!config.enabled)
         return;
+    const wantSound = config.sound !== false;
+    // On Windows, SnoreToast's per-app sound is often muted in Windows settings.
+    // Fire a PowerShell beep alongside the toast so audio is reliable.
+    if (wantSound && process.platform === "win32") {
+        spawn("powershell", [
+            "-NoProfile", "-Command",
+            "[console]::beep(880,180); Start-Sleep -Milliseconds 60; [console]::beep(660,180)",
+        ], { windowsHide: true, stdio: "ignore" });
+    }
     await new Promise((resolve, reject) => {
-        notifier.notify({ title: "Claude", message, sound: true }, (err) => {
-            if (err)
-                reject(err);
-            else
-                resolve();
-        });
+        notifier.notify({ title: "Claude", message, sound: wantSound && process.platform !== "win32" }, (err) => err ? reject(err) : resolve());
     });
 }