agent-notify-chime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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

@@ -0,0 +1,158 @@
+# Agent Notify Chime MCP Server
+
+A lightweight Model Context Protocol (MCP) server that sends push notifications through [ntfy](https://ntfy.sh). It mirrors the feature set from `simple-ntfy-mcp` and adds clear setup guides for Codex, VS Code, and Windsurf clients.
+
+## Features
+
+- Zero-setup usage via `npx` or local install
+- Sends notifications to any ntfy topic
+- Optional title, priority, tags, click actions, and action buttons
+- Works with STDIO MCP clients (Codex CLI/IDE, VS Code extensions, Windsurf)
+
+## Requirements
+
+- Node.js 18+
+- An ntfy topic name (and optional ntfy credentials if you self-host)
+
+## Quickstart (local)
+
+```bash
+npm install
+npm run start
+```
+
+This runs the MCP server on stdio. Use the client configuration examples below to connect.
+
+## Environment variables
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `NTFY_DEFAULT_TOPIC` | Default topic to send notifications to | required |
+| `NTFY_BASE_URL` | Base URL of the ntfy server | `https://ntfy.sh` |
+| `NTFY_AUTH_TOKEN` | Bearer token for ntfy auth (optional) | empty |
+| `NTFY_USERNAME` | Username for Basic auth (optional) | empty |
+| `NTFY_PASSWORD` | Password for Basic auth (optional) | empty |
+| `NTFY_REQUEST_TIMEOUT_MS` | Request timeout in ms | `10000` |
+
+## Tool: `send_ntfy`
+
+Send a push notification to your configured ntfy topic.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `message` | string | yes | The notification message |
+| `topic` | string | no | Topic to send to (uses default if not specified) |
+| `title` | string | no | Notification title |
+| `priority` | number | no | Priority level 1-5 (default 3) |
+| `tags` | string[] | no | Array of tags/emojis |
+| `click` | string | no | URL to open when clicked |
+| `actions` | object[] | no | Action buttons per ntfy docs |
+
+### Example tool call
+
+```json
+{
+  "message": "Build finished successfully",
+  "title": "CI",
+  "priority": 4,
+  "tags": ["white_check_mark", "rocket"],
+  "click": "https://example.com/builds/123"
+}
+```
+
+## Client setup
+
+Use the published package command below:
+
+- **Published package**: `command = "npx"`, `args = ["-y", "agent-notify-chime"]`
+
+### Codex (CLI + IDE extension)
+
+Codex reads MCP servers from `~/.codex/config.toml` and shares this config with the IDE extension (VS Code, Cursor, Windsurf).
+
+**Option A: CLI command**
+
+```bash
+codex mcp add agent-notify-chime \
+  --env NTFY_DEFAULT_TOPIC=your-topic \
+  -- npx -y agent-notify-chime
+```
+
+**Option B: Edit `config.toml`**
+
+```toml
+[mcp_servers.agent-notify-chime]
+command = "npx"
+args = ["-y", "agent-notify-chime"]
+
+[mcp_servers.agent-notify-chime.env]
+NTFY_DEFAULT_TOPIC = "your-topic"
+```
+
+### VS Code (Cline extension)
+
+Cline is a popular MCP client for VS Code. It stores MCP settings in `cline_mcp_settings.json` (open it via the MCP Servers panel).
+
+```json
+{
+  "mcpServers": {
+    "agent-notify-chime": {
+      "command": "npx",
+      "args": ["-y", "agent-notify-chime"],
+      "env": {
+        "NTFY_DEFAULT_TOPIC": "your-topic"
+      }
+    }
+  }
+}
+```
+
+After editing, restart the server from the MCP Servers panel.
+
+### Windsurf (Cascade)
+
+Windsurf reads MCP settings from `~/.codeium/windsurf/mcp_config.json`.
+
+```json
+{
+  "mcpServers": {
+    "agent-notify-chime": {
+      "command": "npx",
+      "args": ["-y", "agent-notify-chime"],
+      "env": {
+        "NTFY_DEFAULT_TOPIC": "your-topic"
+      }
+    }
+  }
+}
+```
+
+Restart Cascade or toggle the server to apply changes.
+
+## Implementation notes
+
+- This server uses the MCP SDK over stdio and publishes a single tool: `send_ntfy`.
+- Notifications are sent by POSTing to `NTFY_BASE_URL/<topic>` with ntfy headers.
+- Auth is optional (Bearer token or Basic auth) for self-hosted ntfy servers.
+
+## Future improvements (recommended)
+
+- Add attachment support (files, images) via ntfy `X-Attach`.
+- Add retry/backoff for transient HTTP failures.
+- Provide a small CLI to validate config/env variables before launching.
+- Support ntfy message templating (predefined titles/tags).
+- Optional metrics or structured logging for observability.
+
+## Publish to npm
+
+1. Ensure you are logged in: `npm login`
+2. Update the version if needed: `npm version patch` (or `minor`/`major`)
+3. Publish: `npm publish --access public`
+
+If you are publishing for the first time, make sure the package name `agent-notify-chime` is available on npm.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const NTFY_BASE_URL = (process.env.NTFY_BASE_URL || "https://ntfy.sh").replace(
+  /\/+$/,
+  ""
+);
+const DEFAULT_TOPIC = process.env.NTFY_DEFAULT_TOPIC || "";
+const AUTH_TOKEN = process.env.NTFY_AUTH_TOKEN || "";
+const NTFY_USERNAME = process.env.NTFY_USERNAME || "";
+const NTFY_PASSWORD = process.env.NTFY_PASSWORD || "";
+const REQUEST_TIMEOUT_MS = Number.parseInt(
+  process.env.NTFY_REQUEST_TIMEOUT_MS || "10000",
+  10
+);
+
+const server = new Server(
+  {
+    name: "agent-notify-chime",
+    version: "0.1.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+function getAuthHeader() {
+  if (AUTH_TOKEN) {
+    return `Bearer ${AUTH_TOKEN}`;
+  }
+
+  if (NTFY_USERNAME && NTFY_PASSWORD) {
+    const encoded = Buffer.from(`${NTFY_USERNAME}:${NTFY_PASSWORD}`).toString(
+      "base64"
+    );
+    return `Basic ${encoded}`;
+  }
+
+  return undefined;
+}
+
+function buildActionsHeader(actions) {
+  if (!Array.isArray(actions)) {
+    return undefined;
+  }
+
+  const serialized = actions
+    .map((action) => {
+      if (!action || typeof action.action !== "string") {
+        return null;
+      }
+
+      const label = typeof action.label === "string" ? action.label : "";
+      const url = typeof action.url === "string" ? action.url : "";
+      const parts = [action.action, label, url];
+
+      if (typeof action.method === "string" && action.method) {
+        parts.push(`method=${action.method}`);
+      }
+
+      return parts.join(", ");
+    })
+    .filter(Boolean)
+    .join("; ");
+
+  return serialized || undefined;
+}
+
+function normalizeTags(tags) {
+  if (!Array.isArray(tags)) {
+    return undefined;
+  }
+
+  const filtered = tags.filter((tag) => typeof tag === "string" && tag.trim());
+  return filtered.length > 0 ? filtered : undefined;
+}
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "send_ntfy",
+        description: "Send a notification via ntfy",
+        inputSchema: {
+          type: "object",
+          properties: {
+            topic: {
+              type: "string",
+              description: "The ntfy topic to send to",
+            },
+            message: {
+              type: "string",
+              description: "The message to send",
+            },
+            title: {
+              type: "string",
+              description: "Optional notification title",
+            },
+            priority: {
+              type: "number",
+              description: "Priority level (1-5, default 3)",
+              minimum: 1,
+              maximum: 5,
+            },
+            tags: {
+              type: "array",
+              items: { type: "string" },
+              description: "Optional tags/emojis",
+            },
+            click: {
+              type: "string",
+              description: "URL to open when notification is clicked",
+            },
+            actions: {
+              type: "array",
+              description: "Action buttons",
+              items: {
+                type: "object",
+                properties: {
+                  action: { type: "string" },
+                  label: { type: "string" },
+                  url: { type: "string" },
+                  method: { type: "string" },
+                },
+              },
+            },
+          },
+          required: ["message"],
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name !== "send_ntfy") {
+    throw new Error(`Unknown tool: ${request.params.name}`);
+  }
+
+  const args = request.params.arguments ?? {};
+  const message = typeof args.message === "string" ? args.message : "";
+  const topic =
+    typeof args.topic === "string" && args.topic.trim()
+      ? args.topic.trim()
+      : DEFAULT_TOPIC;
+
+  if (!message.trim()) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              success: false,
+              error: "Message is required",
+            },
+            null,
+            2
+          ),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  if (!topic) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              success: false,
+              error: "No topic specified and no default topic configured",
+            },
+            null,
+            2
+          ),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  const url = `${NTFY_BASE_URL}/${encodeURIComponent(topic)}`;
+  const headers = {
+    "Content-Type": "text/plain",
+  };
+
+  const authHeader = getAuthHeader();
+  if (authHeader) {
+    headers.Authorization = authHeader;
+  }
+
+  if (typeof args.title === "string" && args.title) {
+    headers["X-Title"] = args.title;
+  }
+
+  if (typeof args.priority === "number") {
+    headers["X-Priority"] = String(args.priority);
+  }
+
+  const tags = normalizeTags(args.tags);
+  if (tags) {
+    headers["X-Tags"] = tags.join(",");
+  }
+
+  if (typeof args.click === "string" && args.click) {
+    headers["X-Click"] = args.click;
+  }
+
+  const actionsHeader = buildActionsHeader(args.actions);
+  if (actionsHeader) {
+    headers["X-Actions"] = actionsHeader;
+  }
+
+  const timeoutMs = Number.isFinite(REQUEST_TIMEOUT_MS)
+    ? REQUEST_TIMEOUT_MS
+    : 10000;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body: message,
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const responseText = await response.text().catch(() => "");
+      throw new Error(
+        `HTTP ${response.status}${responseText ? `: ${responseText}` : ""}`
+      );
+    }
+
+    const contentType = response.headers.get("content-type") || "";
+    const result = contentType.includes("application/json")
+      ? await response.json()
+      : { body: await response.text() };
+
+    const payload = {
+      success: true,
+      topic,
+      response: result,
+    };
+
+    if (result && typeof result === "object") {
+      if (result.id) payload.messageId = result.id;
+      if (result.time) payload.time = result.time;
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(payload, null, 2),
+        },
+      ],
+    };
+  } catch (error) {
+    const messageText =
+      error && error.name === "AbortError"
+        ? `Request timed out after ${timeoutMs}ms`
+        : error?.message || "Unknown error";
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              success: false,
+              error: messageText,
+            },
+            null,
+            2
+          ),
+        },
+      ],
+      isError: true,
+    };
+  } finally {
+    clearTimeout(timeoutId);
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Agent Notify Chime MCP Server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "agent-notify-chime",
+  "version": "0.1.0",
+  "description": "MCP server for sending ntfy notifications",
+  "type": "module",
+  "bin": {
+    "agent-notify-chime": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "ntfy",
+    "notifications",
+    "model-context-protocol",
+    "codex",
+    "vscode",
+    "windsurf"
+  ],
+  "author": "",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ace3/agent-notify-chime.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ace3/agent-notify-chime/issues"
+  },
+  "homepage": "https://github.com/ace3/agent-notify-chime#readme",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}