@palmpush/mcp 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# @palmpush/mcp
+
+Local MCP server for sending palmpush notifications from AI agents.
+
+## Install
+
+```bash
+npm install -g @palmpush/mcp
+```
+
+You can also run it with `npx @palmpush/mcp`.
+
+## Single-listener setup
+
+Use this when every notification should go to one palmpush listener.
+
+```bash
+PALMPUSH_LISTENER_ID=abc123abc123abc123abc123abc123ab palmpush-mcp
+```
+
+The MCP server exposes one tool: `send_push_notification`.
+
+```json
+{
+  "title": "Hello",
+  "body": "world."
+}
+```
+
+## Named-listener setup
+
+Use a config file when the agent should choose between multiple palmpush
+listeners. When `PALMPUSH_CONFIG` is set, `PALMPUSH_LISTENER_ID` is ignored.
+
+```json
+{
+  "listeners": [
+    {
+      "name": "human in the loop",
+      "listenerId": "aaa123aaa123aaa123aaa123aaa123aa",
+      "description": "Use when the user needs to decide, approve, or intervene."
+    },
+    {
+      "name": "informative only",
+      "listenerId": "bbb123bbb123bbb123bbb123bbb123bb",
+      "description": "Use for status updates, completions, and non-blocking information."
+    }
+  ]
+}
+```
+
+Start the server with:
+
+```bash
+PALMPUSH_CONFIG=/path/to/palmpush-mcp.json palmpush-mcp
+```
+
+In named-listener mode, the tool requires `listenerName`:
+
+```json
+{
+  "title": "Approval needed",
+  "body": "Should I continue?",
+  "listenerName": "human in the loop"
+}
+```
+
+The MCP tool description shows listener names and descriptions, but never shows
+listener IDs.
+
+## Optional API URL
+
+By default, the server sends to the deployed palmpush API. To override it:
+
+```bash
+PALMPUSH_LISTENER_ID=abc123abc123abc123abc123abc123ab PALMPUSH_API_URL=http://127.0.0.1:5001/local/api palmpush-mcp
+```
+
+## MCP client example
+
+```json
+{
+  "mcpServers": {
+    "palmpush": {
+      "command": "npx",
+      "args": ["-y", "@palmpush/mcp"],
+      "env": {
+        "PALMPUSH_CONFIG": "/path/to/palmpush-mcp.json"
+      }
+    }
+  }
+}
+```
+
+For a single listener, use:
+
+```json
+{
+  "mcpServers": {
+    "palmpush": {
+      "command": "npx",
+      "args": ["-y", "@palmpush/mcp"],
+      "env": {
+        "PALMPUSH_LISTENER_ID": "abc123abc123abc123abc123abc123ab"
+      }
+    }
+  }
+}
+```
+
+## Security
+
+palmpush listener IDs are capability secrets. Anyone with a listener ID can send
+notifications to that listener. Keep the MCP config private, avoid committing it
+to projects, and prefer storing it outside workspaces that AI agents can read.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@palmpush/mcp",
+  "version": "0.1.0",
+  "description": "Local MCP server for sending palmpush notifications from AI agents.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://www.palmpush.com",
+  "keywords": [
+    "palmpush",
+    "mcp",
+    "model-context-protocol",
+    "push-notifications",
+    "ai-agents"
+  ],
+  "bin": {
+    "palmpush-mcp": "src/cli.js"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "palmpush": "0.2.0",
+    "zod": "^3.25.76"
+  }
+}

package/src/cli.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readPalmpushMcpConfig } from './config.js';
+import { createPalmpushMcpServer } from './server.js';
+
+const main = async () => {
+  const config = readPalmpushMcpConfig();
+  const server = createPalmpushMcpServer(config);
+  const transport = new StdioServerTransport();
+
+  await server.connect(transport);
+};
+
+main().catch((error) => {
+  const message =
+    error && typeof error.message === 'string'
+      ? error.message
+      : 'palmpush MCP server failed to start.';
+
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+});

package/src/config.js

@@ -0,0 +1,174 @@
+import { readFileSync as defaultReadFileSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+const uuidWithoutHyphensPattern = /^[0-9a-f]{32}$/;
+
+const isDefined = (value) => value !== undefined && value !== null;
+
+const readOptionalEnvString = (value) => {
+  if (!isDefined(value)) {
+    return undefined;
+  }
+
+  const normalizedValue = String(value).trim();
+
+  return normalizedValue || undefined;
+};
+
+const normalizeListenerId = (value, fieldName) => {
+  if (typeof value !== 'string') {
+    throw new Error(`${fieldName} must be a string.`);
+  }
+
+  const listenerId = value.trim().toLowerCase().replaceAll('-', '');
+
+  if (!uuidWithoutHyphensPattern.test(listenerId)) {
+    throw new Error(`${fieldName} must be a UUID with or without hyphens.`);
+  }
+
+  return listenerId;
+};
+
+const readListenerName = (value, fieldName) => {
+  if (typeof value !== 'string') {
+    throw new Error(`${fieldName} must be a string.`);
+  }
+
+  const listenerName = value.trim();
+
+  if (!listenerName) {
+    throw new Error(`${fieldName} is required.`);
+  }
+
+  if (listenerName.includes('<') || listenerName.includes('>')) {
+    throw new Error(`${fieldName} must not contain "<" or ">".`);
+  }
+
+  return listenerName;
+};
+
+const readOptionalDescription = (value, fieldName) => {
+  if (!isDefined(value)) {
+    return undefined;
+  }
+
+  if (typeof value !== 'string') {
+    throw new Error(`${fieldName} must be a string when provided.`);
+  }
+
+  const description = value.trim();
+
+  return description || undefined;
+};
+
+const resolveConfigPath = (configPath, cwd) =>
+  path.isAbsolute(configPath) ? configPath : path.resolve(cwd, configPath);
+
+const readJsonConfig = ({ configPath, cwd, readFileSync }) => {
+  const resolvedConfigPath = resolveConfigPath(configPath, cwd);
+  const configText = readFileSync(resolvedConfigPath, 'utf8');
+
+  try {
+    return {
+      config: JSON.parse(configText),
+      configPath: resolvedConfigPath,
+    };
+  } catch (error) {
+    throw new Error(
+      `PALMPUSH_CONFIG must point to valid JSON: ${error.message}`,
+    );
+  }
+};
+
+const readConfigListeners = (config) => {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error('PALMPUSH_CONFIG JSON must be an object.');
+  }
+
+  if (!Array.isArray(config.listeners)) {
+    throw new Error('PALMPUSH_CONFIG JSON must include a listeners array.');
+  }
+
+  if (config.listeners.length === 0) {
+    throw new Error(
+      'PALMPUSH_CONFIG listeners must include at least one listener.',
+    );
+  }
+
+  const seenListenerNames = new Set();
+
+  return config.listeners.map((listener, index) => {
+    const fieldPrefix = `listeners[${index}]`;
+
+    if (!listener || typeof listener !== 'object' || Array.isArray(listener)) {
+      throw new Error(`${fieldPrefix} must be an object.`);
+    }
+
+    const name = readListenerName(listener.name, `${fieldPrefix}.name`);
+
+    if (seenListenerNames.has(name)) {
+      throw new Error(`Duplicate listener name in PALMPUSH_CONFIG: "${name}".`);
+    }
+
+    seenListenerNames.add(name);
+
+    return {
+      name,
+      listenerId: normalizeListenerId(
+        listener.listenerId,
+        `${fieldPrefix}.listenerId`,
+      ),
+      description: readOptionalDescription(
+        listener.description,
+        `${fieldPrefix}.description`,
+      ),
+    };
+  });
+};
+
+/**
+ * Reads the palmpush MCP runtime configuration.
+ *
+ * Config-file mode is enabled only when `PALMPUSH_CONFIG` is set. In that mode,
+ * listener IDs come exclusively from the config file and `PALMPUSH_LISTENER_ID`
+ * is ignored.
+ *
+ * @param {{env?: Record<string, string | undefined>, cwd?: string, readFileSync?: typeof defaultReadFileSync}} [options] - Runtime inputs.
+ * @returns {{mode: 'config', apiUrl?: string, configPath: string, listeners: {name: string, listenerId: string, description?: string}[]} | {mode: 'env', apiUrl?: string, listenerId: string}} MCP runtime config.
+ */
+export const readPalmpushMcpConfig = ({
+  env = process.env,
+  cwd = process.cwd(),
+  readFileSync = defaultReadFileSync,
+} = {}) => {
+  const apiUrl = readOptionalEnvString(env.PALMPUSH_API_URL);
+  const configPath = readOptionalEnvString(env.PALMPUSH_CONFIG);
+
+  if (configPath) {
+    const { config, configPath: resolvedConfigPath } = readJsonConfig({
+      configPath,
+      cwd,
+      readFileSync,
+    });
+
+    return {
+      mode: 'config',
+      apiUrl,
+      configPath: resolvedConfigPath,
+      listeners: readConfigListeners(config),
+    };
+  }
+
+  const listenerId = readOptionalEnvString(env.PALMPUSH_LISTENER_ID);
+
+  if (!listenerId) {
+    throw new Error('Set PALMPUSH_LISTENER_ID or PALMPUSH_CONFIG.');
+  }
+
+  return {
+    mode: 'env',
+    apiUrl,
+    listenerId: normalizeListenerId(listenerId, 'PALMPUSH_LISTENER_ID'),
+  };
+};

package/src/index.js

@@ -0,0 +1,7 @@
+export { readPalmpushMcpConfig } from './config.js';
+export {
+  SEND_PUSH_TOOL_NAME,
+  SERVER_NAME,
+  SERVER_VERSION,
+  createPalmpushMcpServer,
+} from './server.js';

package/src/server.js

@@ -0,0 +1,231 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import palmpush from 'palmpush';
+import * as z from 'zod/v4';
+
+export const SERVER_NAME = '@palmpush/mcp';
+export const SERVER_VERSION = '0.1.0';
+export const SEND_PUSH_TOOL_NAME = 'send_push_notification';
+
+const redactedListenerIdPattern =
+  /\b[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}\b/gi;
+
+const redactListenerIds = (value) =>
+  String(value).replaceAll(redactedListenerIdPattern, '[listener-id-redacted]');
+
+const escapeToolDescriptionText = (value) =>
+  String(value)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+
+const getSafeErrorMessage = (error) => {
+  const message =
+    error && typeof error.message === 'string'
+      ? error.message
+      : 'palmpush failed to send the notification.';
+
+  return redactListenerIds(message);
+};
+
+const getDeliverySummary = (response) => {
+  const delivery = response?.delivery;
+
+  if (!delivery || typeof delivery !== 'object') {
+    return undefined;
+  }
+
+  const sentCount =
+    typeof delivery.sentCount === 'number' ? delivery.sentCount : undefined;
+  const failedCount =
+    typeof delivery.failedCount === 'number' ? delivery.failedCount : undefined;
+
+  if (sentCount === undefined && failedCount === undefined) {
+    return undefined;
+  }
+
+  const parts = [];
+
+  if (sentCount !== undefined) {
+    parts.push(`${sentCount} sent`);
+  }
+
+  if (failedCount !== undefined) {
+    parts.push(`${failedCount} failed`);
+  }
+
+  return parts.join(', ');
+};
+
+const formatAvailableListeners = (listeners) =>
+  listeners
+    .map((listener) => {
+      const name = escapeToolDescriptionText(listener.name);
+      const description = listener.description
+        ? escapeToolDescriptionText(listener.description)
+        : 'No description configured.';
+
+      return `- <listenerName>${name}</listenerName>: ${description}`;
+    })
+    .join('\n');
+
+const createToolDescription = (config) => {
+  if (config.mode === 'env') {
+    return [
+      'Send a palmpush notification to the single listener configured with PALMPUSH_LISTENER_ID.',
+      'Use this for notifying the user from an AI agent, automation, or local workflow.',
+    ].join('\n');
+  }
+
+  return [
+    'Send a palmpush notification to one configured listener.',
+    'You must set listenerName by copying exactly one value from the <listenerName> entries below.',
+    'Available listeners:',
+    formatAvailableListeners(config.listeners),
+  ].join('\n');
+};
+
+const createInputSchema = (config) => {
+  const baseSchema = {
+    title: z
+      .string()
+      .trim()
+      .min(1)
+      .max(120)
+      .describe('Short push notification title.'),
+    body: z
+      .string()
+      .trim()
+      .min(1)
+      .max(4096)
+      .describe('Push notification body text.'),
+  };
+
+  if (config.mode === 'env') {
+    return baseSchema;
+  }
+
+  return {
+    ...baseSchema,
+    listenerName: z
+      .string()
+      .trim()
+      .min(1)
+      .describe(
+        'Copy exactly one configured listener name from the <listenerName> entries in the tool description.',
+      ),
+  };
+};
+
+const getListenerTarget = ({ config, listenerName }) => {
+  if (config.mode === 'env') {
+    return {
+      listenerId: config.listenerId,
+    };
+  }
+
+  const listener = config.listeners.find((item) => item.name === listenerName);
+
+  if (!listener) {
+    throw new Error(
+      `Unknown listenerName "${redactListenerIds(listenerName)}". Use one of: ${config.listeners
+        .map((item) => `"${item.name}"`)
+        .join(', ')}.`,
+    );
+  }
+
+  return {
+    listenerId: listener.listenerId,
+    listenerName: listener.name,
+  };
+};
+
+const createClient = ({ apiUrl, fetchImpl, listenerId }) =>
+  palmpush({
+    apiUrl,
+    fetch: fetchImpl,
+    listenerId,
+    mode: 'strict',
+  });
+
+/**
+ * Creates the local stdio palmpush MCP server.
+ *
+ * @param {{mode: 'config', apiUrl?: string, listeners: {name: string, listenerId: string, description?: string}[]} | {mode: 'env', apiUrl?: string, listenerId: string}} config - Runtime config.
+ * @param {{fetch?: typeof fetch}} [options] - Test/runtime overrides.
+ * @returns {McpServer} Configured MCP server.
+ */
+export const createPalmpushMcpServer = (config, options = {}) => {
+  const server = new McpServer({
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+  });
+
+  server.registerTool(
+    SEND_PUSH_TOOL_NAME,
+    {
+      title: 'Send palmpush notification',
+      description: createToolDescription(config),
+      inputSchema: createInputSchema(config),
+      annotations: {
+        title: 'Send palmpush notification',
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    async ({ title, body, listenerName }) => {
+      let target;
+
+      try {
+        target = getListenerTarget({ config, listenerName });
+      } catch (error) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: 'text',
+              text: getSafeErrorMessage(error),
+            },
+          ],
+        };
+      }
+
+      try {
+        const client = createClient({
+          apiUrl: config.apiUrl,
+          fetchImpl: options.fetch,
+          listenerId: target.listenerId,
+        });
+        const response = await client.pushStrict({ title, body });
+        const deliverySummary = getDeliverySummary(response);
+        const targetSummary = target.listenerName
+          ? ` to "${target.listenerName}"`
+          : '';
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: deliverySummary
+                ? `palmpush notification sent${targetSummary}. Delivery: ${deliverySummary}.`
+                : `palmpush notification sent${targetSummary}.`,
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: 'text',
+              text: getSafeErrorMessage(error),
+            },
+          ],
+        };
+      }
+    },
+  );
+
+  return server;
+};