@applogico/blipr-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Applogico LLC
+
+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,95 @@
+# @applogico/blipr-mcp
+
+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.
+
+It's a thin stdio client: your MCP host (Claude Code, Cursor, …) launches it,
+the agent calls a tool, and this process makes one outbound HTTPS `POST` to your
+Blipr server. No inbound socket, nothing to host.
+
+```
+Claude Code ──stdio──► blipr-mcp ──POST /api/notify/<topic>──► blipr.dev ──APNs──► 📱
+```
+
+## Setup
+
+No install needed — `npx` fetches it on demand. Point it at a Blipr server
+(`blipr.dev` or your own self-hosted instance) and a default topic.
+
+### Claude Code
+
+```bash
+claude mcp add blipr \
+  --env BLIPR_URL=https://blipr.dev \
+  --env BLIPR_TOPIC=agent-alerts \
+  -- npx -y @applogico/blipr-mcp
+```
+
+### Cursor / Claude Desktop / any MCP host (JSON)
+
+```jsonc
+{
+  "mcpServers": {
+    "blipr": {
+      "command": "npx",
+      "args": ["-y", "@applogico/blipr-mcp"],
+      "env": {
+        "BLIPR_URL": "https://blipr.dev",
+        "BLIPR_TOPIC": "agent-alerts"
+      }
+    }
+  }
+}
+```
+
+Then subscribe to the same topic (`agent-alerts`) in the Blipr iOS app, and
+you'll get the agent's pushes on your phone.
+
+## Configuration
+
+| Env var       | Default             | Description                                            |
+| ------------- | ------------------- | ------------------------------------------------------ |
+| `BLIPR_URL`   | `https://blipr.dev` | Base URL of your Blipr server (hosted or self-hosted). |
+| `BLIPR_TOPIC` | _(none)_            | Default topic used when a tool call omits one.         |
+
+## Tools
+
+### `send_alert`
+
+Send a push notification. Parameters:
+
+- `message` (required) — the alert body.
+- `title` — short bold title.
+- `topic` — overrides `BLIPR_TOPIC`.
+- `priority` — `1` silent · `2` low · `3` default · `4` time-sensitive (breaks
+  Focus) · `5` critical.
+- `tags` — emoji shortcodes, e.g. `["warning"]`.
+- `click` — URL opened when the notification is tapped.
+
+### `send_critical`
+
+A priority-5 page for things that genuinely can't wait. Bypasses silent/Focus
+when the Blipr app has Apple's Critical Alerts entitlement enabled; otherwise
+it's delivered as time-sensitive.
+
+## Example prompts
+
+> "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."
+
+## Develop
+
+```bash
+npm install
+npm run build      # → dist/index.js
+BLIPR_URL=https://blipr.dev BLIPR_TOPIC=demo node dist/index.js   # stdio
+```
+
+## License
+
+MIT © Applogico LLC. This is the open client adapter; the Blipr server is
+distributed as a container image.

package/dist/index.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * Blipr MCP server (stdio).
+ *
+ * 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.
+ *
+ * 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);
+// 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})` : ""}`);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@applogico/blipr-mcp",
+  "version": "0.1.0",
+  "description": "MCP server that lets AI agents send Blipr push alerts to your phone — your agent can page you.",
+  "type": "module",
+  "bin": {
+    "blipr-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "blipr",
+    "notifications",
+    "push",
+    "alerts",
+    "apns",
+    "ai-agents",
+    "claude"
+  ],
+  "author": "Applogico LLC",
+  "homepage": "https://blipr.dev",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}