@topvisor/mcp-notifications 1.0.0 → 1.0.1

package/README.md

@@ -1,13 +1,23 @@
 # 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.
 
 No more checking logs every minute.  
 No more silent agent runs.  
 Just visible, reliable feedback on your desktop. 🔔
 
+## 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
 
 - ⚡ Immediate feedback from your MCP workflows.
@@ -26,23 +36,84 @@ Requirements:
 npm i -g @topvisor/mcp-notifications
 ```
 
-Command installed:
+Executable name (use this in MCP config):
 
 ```bash
 mcp-notifications
 ```
 
-## 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
 command = "mcp-notifications"
 args = []
 ```
 
+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
 
 ### `send_notification`
@@ -53,28 +124,59 @@ Input:
 - `message` `string` (required)
 - `play_sound` `boolean` (optional, default: `false`)
 - `icon` `string` (optional, absolute or relative path to image file)
+- `app_id` `string` (optional, Windows App User Model ID for toast source)
 
 Example:
 
 ```json
 {
-	"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
 
 - ✅ Uses standard system notification channels.
 - 🔊 Uses the standard system notification sound when `play_sound: true`.
 - 🤖 Uses bundled Topvisor robot image as default notification icon.
 - 🧰 Returns quickly while notifications are delivered in background queue.
-
-## Local development
-
-```bash
-npm install
-npm run start
-```

package/package.json

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

package/src/notifier.mjs

@@ -12,12 +12,13 @@ const DEFAULT_ICON_PATH = path.resolve(__dirname, '../assets/topvisor-robot.png'
  * Добавить уведомление в очередь фоновой отправки.
  * Tool-вызов не ждёт завершения системного API уведомлений.
  */
-export const enqueueNotification = ({ title, message, playSound, icon }) => {
+export const enqueueNotification = ({ title, message, playSound, icon, appId }) => {
 	jobs.push({
 		title,
 		message,
 		playSound,
 		icon: normalizeIcon(icon),
+		appId,
 	});
 	processQueue();
 };
@@ -37,6 +38,7 @@ const processQueue = () => {
 			wait: false,
 			sound: job.playSound,
 			icon: job.icon,
+			appID: job.appId,
 		},
 		(error) => {
 			isProcessing = false;
@@ -56,4 +58,4 @@ const normalizeIcon = (icon) => {
 	}
 
 	return path.resolve(icon);
-};
+};

package/src/server.mjs

@@ -15,15 +15,18 @@ server.tool(
 		message: z.string().min(1),
 		play_sound: z.boolean().optional(),
 		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;
 
 		enqueueNotification({
 			title,
 			message,
 			playSound,
 			icon,
+			appId,
 		});
 
 		return {
@@ -38,4 +41,4 @@ server.tool(
 );
 
 const transport = new StdioServerTransport();
-await server.connect(transport);
+await server.connect(transport);