@applogico/blipr-mcp 0.1.0 → 0.1.3

package/README.md

@@ -1,5 +1,10 @@
 # @applogico/blipr-mcp
 
+[![npm version](https://img.shields.io/npm/v/@applogico/blipr-mcp)](https://www.npmjs.com/package/@applogico/blipr-mcp)
+[![CI](https://github.com/applogico/blipr-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/applogico/blipr-mcp/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/npm/l/@applogico/blipr-mcp)](./LICENSE)
+[![Node](https://img.shields.io/node/v/@applogico/blipr-mcp)](https://nodejs.org)
+
 An [MCP](https://modelcontextprotocol.io) server that lets AI agents send
 **[Blipr](https://blipr.dev)** push alerts to your phone. Your agent finishes a
 long task, breaks a build, needs approval, or gets stuck — and it pages you.
@@ -78,14 +83,15 @@ it's delivered as time-sensitive.
 > "Run the migration, and `send_alert` me when it's done — priority 4 if it
 > fails."
 
-> "You're about to delete production data — `send_critical` me for approval
-> first."
+> "If the nightly backup fails, `send_critical` me with the error — that one
+> can't wait."
 
 ## Develop
 
 ```bash
 npm install
 npm run build      # → dist/index.js
+npm test           # vitest: unit (publish) + in-memory MCP integration
 BLIPR_URL=https://blipr.dev BLIPR_TOPIC=demo node dist/index.js   # stdio
 ```
 

package/dist/index.js

@@ -1,104 +1,21 @@
 #!/usr/bin/env node
 /**
- * Blipr MCP server (stdio).
+ * Blipr MCP server (stdio entrypoint).
  *
- * A thin client that lets an MCP-capable AI agent (Claude Code, Cursor, …) send
- * push notifications to a phone via a Blipr instance. The agent calls a tool;
- * this process POSTs to `${BLIPR_URL}/api/notify/<topic>`. No inbound socket —
- * stdio in, outbound HTTPS out.
+ * Lets an MCP-capable AI agent (Claude Code, Cursor, …) send push notifications
+ * to a phone via a Blipr instance. stdio in, outbound HTTPS out — no socket.
  *
  * Config (env):
  *   BLIPR_URL    Base URL of the Blipr server. Default: https://blipr.dev
  *   BLIPR_TOPIC  Default topic when a tool call omits one. Optional.
  */
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-const BLIPR_URL = (process.env.BLIPR_URL ?? "https://blipr.dev").replace(/\/+$/, "");
-const DEFAULT_TOPIC = process.env.BLIPR_TOPIC?.trim() || undefined;
-/** POST a message to a Blipr topic; returns the resolved topic on success. */
-async function publish(opts) {
-    const topic = (opts.topic ?? DEFAULT_TOPIC ?? "").trim();
-    if (!topic) {
-        throw new Error("No topic given and BLIPR_TOPIC is not set. Pass `topic`, or set the BLIPR_TOPIC env var.");
-    }
-    const headers = { "Content-Type": "text/plain" };
-    if (opts.title)
-        headers["X-Title"] = opts.title;
-    if (opts.priority)
-        headers["X-Priority"] = String(opts.priority);
-    if (opts.tags?.length)
-        headers["X-Tags"] = opts.tags.join(",");
-    if (opts.click)
-        headers["X-Click"] = opts.click;
-    let res;
-    try {
-        res = await fetch(`${BLIPR_URL}/api/notify/${encodeURIComponent(topic)}`, {
-            method: "POST",
-            headers,
-            body: opts.message,
-        });
-    }
-    catch (e) {
-        throw new Error(`Could not reach Blipr at ${BLIPR_URL}: ${e.message}`);
-    }
-    if (!res.ok) {
-        const body = await res.text().catch(() => "");
-        throw new Error(`Blipr returned ${res.status} ${res.statusText}${body ? ` — ${body}` : ""}`);
-    }
-    return topic;
-}
-const server = new McpServer({ name: "blipr", version: "0.1.0" });
-server.registerTool("send_alert", {
-    title: "Send a Blipr alert",
-    description: "Send a push notification to the user's phone via Blipr. Use this to reach the human: a long task finished, a build broke, you need approval, or you're blocked and need input. Priority 1 (silent) to 5 (critical); defaults to 3.",
-    inputSchema: {
-        message: z.string().describe("The alert body — what happened or what you need."),
-        title: z.string().optional().describe("Short title, shown bold above the message."),
-        topic: z
-            .string()
-            .optional()
-            .describe("Topic to publish to. Defaults to the BLIPR_TOPIC env var."),
-        priority: z
-            .number()
-            .int()
-            .min(1)
-            .max(5)
-            .optional()
-            .describe("1=min/silent, 2=low, 3=default, 4=time-sensitive (breaks Focus), 5=critical."),
-        tags: z
-            .array(z.string())
-            .optional()
-            .describe('Tags / emoji shortcodes, e.g. ["warning", "rocket"].'),
-        click: z.string().url().optional().describe("URL opened when the notification is tapped."),
-    },
-}, async ({ message, title, topic, priority, tags, click }) => {
-    try {
-        const sent = await publish({ message, title, topic, priority, tags, click });
-        return { content: [{ type: "text", text: `Sent to "${sent}" (priority ${priority ?? 3}).` }] };
-    }
-    catch (e) {
-        return { content: [{ type: "text", text: e.message }], isError: true };
-    }
-});
-server.registerTool("send_critical", {
-    title: "Page the user (critical)",
-    description: "Send a priority-5 critical page. Use ONLY for things that genuinely cannot wait (production down, urgent approval, safety). Bypasses silent/Focus when the Blipr app has Apple's Critical Alerts entitlement enabled; otherwise it is delivered as time-sensitive.",
-    inputSchema: {
-        message: z.string().describe("What is wrong or what you need, urgently."),
-        title: z.string().optional().describe("Short title."),
-        topic: z.string().optional().describe("Topic. Defaults to BLIPR_TOPIC."),
-    },
-}, async ({ message, title, topic }) => {
-    try {
-        const sent = await publish({ message, title, topic, priority: 5, tags: ["rotating_light"] });
-        return { content: [{ type: "text", text: `Paged "${sent}" (priority 5 / critical).` }] };
-    }
-    catch (e) {
-        return { content: [{ type: "text", text: e.message }], isError: true };
-    }
-});
-const transport = new StdioServerTransport();
-await server.connect(transport);
+import { createServer } from "./server.js";
+const cfg = {
+    bliprUrl: (process.env.BLIPR_URL ?? "https://blipr.dev").replace(/\/+$/, ""),
+    defaultTopic: process.env.BLIPR_TOPIC?.trim() || undefined,
+};
+const server = createServer(cfg);
+await server.connect(new StdioServerTransport());
 // stderr is safe for logs; stdout is the MCP channel and must stay clean.
-console.error(`blipr-mcp ready → ${BLIPR_URL}${DEFAULT_TOPIC ? ` (default topic: ${DEFAULT_TOPIC})` : ""}`);
+console.error(`blipr-mcp ready → ${cfg.bliprUrl}${cfg.defaultTopic ? ` (default topic: ${cfg.defaultTopic})` : ""}`);

package/dist/publish.js

@@ -0,0 +1,40 @@
+/** Blipr publish client — the one piece of real logic, kept pure for testing. */
+/**
+ * Publish a message to a Blipr topic. Returns the resolved topic on success.
+ *
+ * Uses the JSON publish endpoint (`POST /api/notify`) rather than the
+ * header-based one. The JSON body is UTF-8, so titles/messages with emoji or
+ * accents work — HTTP headers are Latin-1 only and would corrupt or reject them.
+ */
+export async function publish(opts, cfg) {
+    const topic = (opts.topic ?? cfg.defaultTopic ?? "").trim();
+    if (!topic) {
+        throw new Error("No topic given and BLIPR_TOPIC is not set. Pass `topic`, or set the BLIPR_TOPIC env var.");
+    }
+    const payload = { topic, message: opts.message };
+    if (opts.title)
+        payload.title = opts.title;
+    if (opts.priority)
+        payload.priority = opts.priority;
+    if (opts.tags?.length)
+        payload.tags = opts.tags;
+    if (opts.click)
+        payload.click = opts.click;
+    const base = cfg.bliprUrl.replace(/\/+$/, "");
+    let res;
+    try {
+        res = await fetch(`${base}/api/notify`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(payload),
+        });
+    }
+    catch (e) {
+        throw new Error(`Could not reach Blipr at ${base}: ${e.message}`);
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`Blipr returned ${res.status} ${res.statusText}${body ? ` — ${body}` : ""}`);
+    }
+    return topic;
+}

package/dist/server.js

@@ -0,0 +1,57 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { publish } from "./publish.js";
+/** Build a configured Blipr MCP server with its tools registered. */
+export function createServer(cfg) {
+    const server = new McpServer({ name: "blipr", version: "0.1.0" });
+    server.registerTool("send_alert", {
+        title: "Send a Blipr alert",
+        description: "Send a push notification to the user's phone via Blipr. Use this to reach the human: a long task finished, a build broke, you need approval, or you're blocked and need input. Priority 1 (silent) to 5 (critical); defaults to 3.",
+        inputSchema: {
+            message: z.string().describe("The alert body — what happened or what you need."),
+            title: z.string().optional().describe("Short title, shown bold above the message."),
+            topic: z
+                .string()
+                .optional()
+                .describe("Topic to publish to. Defaults to the BLIPR_TOPIC env var."),
+            priority: z
+                .number()
+                .int()
+                .min(1)
+                .max(5)
+                .optional()
+                .describe("1=min/silent, 2=low, 3=default, 4=time-sensitive (breaks Focus), 5=critical."),
+            tags: z
+                .array(z.string())
+                .optional()
+                .describe('Tags / emoji shortcodes, e.g. ["warning", "rocket"].'),
+            click: z.string().url().optional().describe("URL opened when the notification is tapped."),
+        },
+    }, async ({ message, title, topic, priority, tags, click }) => {
+        try {
+            const sent = await publish({ message, title, topic, priority, tags, click }, cfg);
+            return { content: [{ type: "text", text: `Sent to "${sent}" (priority ${priority ?? 3}).` }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: e.message }], isError: true };
+        }
+    });
+    server.registerTool("send_critical", {
+        title: "Page the user (critical)",
+        description: "Send a priority-5 critical page. Use ONLY for things that genuinely cannot wait (production down, urgent approval, safety). Bypasses silent/Focus when the Blipr app has Apple's Critical Alerts entitlement enabled; otherwise it is delivered as time-sensitive.",
+        inputSchema: {
+            message: z.string().describe("What is wrong or what you need, urgently."),
+            title: z.string().optional().describe("Short title."),
+            topic: z.string().optional().describe("Topic. Defaults to BLIPR_TOPIC."),
+        },
+    }, async ({ message, title, topic }) => {
+        try {
+            const sent = await publish({ message, title, topic, priority: 5, tags: ["rotating_light"] }, cfg);
+            return { content: [{ type: "text", text: `Paged "${sent}" (priority 5 / critical).` }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: e.message }], isError: true };
+        }
+    });
+    return server;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applogico/blipr-mcp",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "MCP server that lets AI agents send Blipr push alerts to your phone — your agent can page you.",
   "type": "module",
   "bin": {
@@ -14,6 +14,8 @@
   },
   "scripts": {
     "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepare": "npm run build",
     "start": "node dist/index.js"
   },
@@ -30,6 +32,13 @@
   ],
   "author": "Applogico LLC",
   "homepage": "https://blipr.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/applogico/blipr-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/applogico/blipr-mcp/issues"
+  },
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -40,6 +49,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.9"
   }
 }