@topvisor/mcp-notifications - npm Package Compare versions

Comparing version 1.0.0 to 1.0.1

package.json

 {
 	"name": "@topvisor/mcp-notifications",
-	"version": "1.0.0",
+	"version": "1.0.1",
 	"type": "module",
@@ -5,0 +5,0 @@ "description": "MCP server for desktop notifications over stdio",

README.md

 # mcp-notifications
 
+[![npm version](https://img.shields.io/npm/v/@topvisor/mcp-notifications.svg)](https://www.npmjs.com/package/@topvisor/mcp-notifications)
+
 🚀 **Ship faster. Miss nothing.**
 
-`mcp-notifications` gives your MCP agent a real desktop voice: instant system notifications for completed tasks, failures, and important updates.
+`mcp-notifications` gives your MCP agent a real desktop voice: instant system notifications for completed tasks,
+failures, and important updates.
 
@@ -11,2 +14,9 @@ No more checking logs every minute.
 
+## Common problem this solves
+
+You give tasks to several AI agents, then wait and keep checking who already replied.
+
+With `mcp-notifications`, this gets simpler: the agent can notify you on desktop when it needs your input or when work
+is done.
+
 ## Why teams install this
@@ -30,3 +40,3 @@
 
-Command installed:
+Executable name (use this in MCP config):
 
@@ -37,8 +47,10 @@ ```bash
 
-## Connect to your MCP client
+`mcp-notifications` is an MCP server entrypoint (`stdio`), not a one-shot notification command.
 
+## Setup: Codex
+
 Add this to `~/.codex/config.toml`:
 
 ```toml
-[mcp_servers.notify]
+[mcp_servers.notifications]
 enabled = true
@@ -49,2 +61,61 @@ command = "mcp-notifications"
 
+Restart Codex after config update.
+
+## Setup: Claude Agent
+
+Add MCP server config to your Claude client config file:
+
+```json
+{
+  "mcpServers": {
+    "notifications": {
+      "command": "mcp-notifications",
+      "args": []
+    }
+  }
+}
+```
+
+Then restart Claude client.
+
+## AI Agent Notification Instructions
+
+There are two approaches to notifications: manual and automatic.
+
+Choose the one that works better for your workflow.
+
+### Manual
+
+In a task where you want to be notified, explicitly ask the agent. Example:
+
+```text
+Count files in the project; after the task is fully complete, notify me with sound.
+```
+
+You can also define sound, topic, and frequency rules inside a specific chat. Example:
+
+```text
+Notify me about your replies without sound, include the reply text, and use title: "Large Refactoring"
+```
+
+### Automatic
+
+Automatic notifications can be configured globally or per project.
+
+Example instruction to enable automatic notifications for agent replies:
+
+```text
+Send `send_notification` after your replies (actual task time >5 seconds or many steps); `play_sound: false`; `app_id: '{put your chat name here}'`
+```
+
+Time is a rough threshold and depends on model behavior, so adjust this instruction to your own preferences.
+
+### In Skills
+
+You can also enable notifications in specific skills. Example for a Review skill:
+
+```text
+After the review, run `send_notification` with a short summary; `play_sound: true`; `app_id: 'Reviewer {put task id here}'`
+```
+
 ## Tool
@@ -60,2 +131,3 @@
 - `icon` `string` (optional, absolute or relative path to image file)
+- `app_id` `string` (optional, Windows App User Model ID for toast source)
 
@@ -66,9 +138,46 @@ Example:
 {
-	"title": "Codex",
-	"message": "Deployment completed successfully",
-	"play_sound": true,
-	"icon": "/opt/mcp-notifications/icons/custom.png"
+  "title": "Codex",
+  "message": "Deployment completed successfully",
+  "play_sound": true,
+  "icon": "/opt/mcp-notifications/icons/custom.png",
+  "app_id": "Topvisor.Codex"
 }
 ```
 
+## app_id (Windows)
+
+- `app_id` controls the source shown in Windows toast notifications.
+- If `app_id` is not set, Windows may show `SnoreToast` as the source.
+- You can pass `app_id` in each tool call, or set `MCP_NOTIFICATIONS_APP_ID` as an environment variable for the server.
+
+## Chat Prompts To Test In Codex
+
+Use these messages directly in chat:
+
+```text
+Check send_notification
+```
+
+```text
+Send a notification without sound: title "Test", message "Check"
+```
+
+```text
+Send a notification with sound: title "Test", message "Check"
+```
+
+```text
+Send a notification with app_id "Topvisor.Codex": title "Test", message "Check"
+```
+
+```text
+Send 3 test notifications in a row without sound
+```
+
+Expected tool result in logs/response:
+
+```text
+Notification queued
+```
+
 ## Behavior
@@ -80,8 +189,1 @@
 - 🧰 Returns quickly while notifications are delivered in background queue.
-
-## Local development
-
-```bash
-npm install
-npm run start
-```

src/notifier.mjs

@@ -15,3 +15,3 @@ import notifier from 'node-notifier';
  */
-export const enqueueNotification = ({ title, message, playSound, icon }) => {
+export const enqueueNotification = ({ title, message, playSound, icon, appId }) => {
 	jobs.push({
@@ -22,2 +22,3 @@ title,
 		icon: normalizeIcon(icon),
+		appId,
 	});
@@ -42,2 +43,3 @@ processQueue();
 			icon: job.icon,
+			appID: job.appId,
 		},
@@ -44,0 +46,0 @@ (error) => {

src/server.mjs

@@ -18,5 +18,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 		icon: z.string().min(1).optional(),
+		app_id: z.string().min(1).optional(),
 	},
-	async ({ title, message, play_sound, icon }) => {
+	async ({ title, message, play_sound, icon, app_id }) => {
 		const playSound = play_sound ?? false;
+		const appId = app_id ?? process.env.MCP_NOTIFICATIONS_APP_ID;
 
@@ -28,2 +30,3 @@ enqueueNotification({
 			icon,
+			appId,
 		});
@@ -30,0 +33,0 @@

New alerts

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Improved metrics

Total package byte prevSize

86448

3.55%

Lines of code

92

5.75%

Number of lines in readme file

183

125.93%

Worsened metrics

Number of low supply chain risk alerts

1

Infinity%

No dependency changes