Skip to main content
Glama
README.md
# @blipr/mcp

[![npm version](https://img.shields.io/npm/v/@blipr/mcp)](https://www.npmjs.com/package/@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/@blipr/mcp)](./LICENSE)
[![Node](https://img.shields.io/node/v/@blipr/mcp)](https://nodejs.org)

> Previously published as `@applogico/blipr-mcp`. That package is deprecated;
> new releases ship as **`@blipr/mcp`**. Update your MCP config to
> `npx -y @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
can also **ask you a question and block until you answer**, for human-in-the-loop
approval gates.

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 /blip/<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).

### Claude Code

```bash
claude mcp add blipr \
  --env BLIPR_URL=https://blipr.dev \
  -- npx -y @blipr/mcp
```

### Cursor / Claude Desktop / any MCP host (JSON)

```jsonc
{
  "mcpServers": {
    "blipr": {
      "command": "npx",
      "args": ["-y", "@blipr/mcp"],
      "env": {
        "BLIPR_URL": "https://blipr.dev"
      }
    }
  }
}
```

### Pick a topic (per project, not global)

Every blip goes to a **topic**, and each project should use its own, so alerts
from different projects land separately on your phone. The topic for a call is
resolved in this order:

1. **`topic` tool argument** — the agent passes it on the call. Always wins.
2. **`.blipr-topic` file** — per-project default. Put the topic name on the
   first line of a `.blipr-topic` file in the project root; the server picks up
   the nearest one from its launch directory upward (`#` lines are comments).
3. **`BLIPR_TOPIC` env var** — global fallback, kept for backward
   compatibility. Avoid it when one machine hosts several projects: a global
   default makes every project ping the same topic.

```bash
echo my-project-alerts > .blipr-topic
```

Then subscribe to the same topic (`my-project-alerts`) in the Blipr iOS app,
and you'll get the agent's pushes on your phone. On blipr.dev that subscribe,
made while signed in, is also what creates the topic, so do it before the
agent's first blip: publishing to a topic that does not exist returns 404. A
self-hosted server still creates the topic on the first publish.

## Configuration

| Setting                    | Default             | Description                                                                 |
| -------------------------- | ------------------- | --------------------------------------------------------------------------- |
| `BLIPR_URL` (env)          | `https://blipr.dev` | Base URL of your Blipr server (hosted or self-hosted).                      |
| `.blipr-topic` (file)      | _(none)_            | Per-project default topic, nearest file from the launch directory upward.   |
| `BLIPR_TOPIC` (env)        | _(none)_            | Global fallback topic; lowest precedence (see "Pick a topic" above).        |

## Tools

### `send_alert`

Send a push notification. Parameters:

- `message` (required) — the alert body.
- `title` — short bold title.
- `topic` — topic to publish to; pass it explicitly (falls back to
  `.blipr-topic`, then `BLIPR_TOPIC`).
- `priority` — `1` silent · `2` low · `3` default · `4` high (plays a sound,
  respects Focus) · `5` critical (breaks Focus).
- `tags` — emoji shortcodes, e.g. `["warning"]`.
- `click` — URL opened when the notification is tapped.
- `markdown`: render the body as Markdown (bold, italics, links, code). Off by default.

### `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. Also takes `markdown`.

### `ask`: human-in-the-loop yes/no or multiple choice (blocks)

Send a **yes/no or multiple-choice question** to your phone and **block until you tap an answer**,
then return it. This is an approval gate: the agent calls it before doing
something consequential or irreversible and waits for your decision instead of
guessing.

- `message` (required): the question.
- `title` — short bold title.
- `topic` — topic to publish to; pass it explicitly (falls back to
  `.blipr-topic`, then `BLIPR_TOPIC`).
- `priority` — defaults to `4` (high) since it needs an answer.
- `tags` — emoji shortcodes, e.g. `["question"]`.
- `markdown`: render the body as Markdown (bold, italics, links, code). Off by default.
- `options`: 2 to 5 distinct choices. Makes it a multiple-choice question; omit for yes/no.
- `timeout_seconds` — how long to wait for your answer (default `120`).

Returns `{ responded, approved, value, message_id, topic }`. **Branch on
`approved`** — it is `true` **only** when you tapped Yes, and `false` on No, a
timeout, or an error, so a refusal or non-answer can never be misread as a
go-ahead. On a timeout you get
`{ responded: false, approved: false, reason: "timeout", message_id, topic }`. If
it times out (or your MCP client cancels the call), you can still answer for
~30 min — pass the returned `message_id` to `check_reply` to resume.

With `options`, it returns `{ responded, value, message_id, topic }` with no
`approved`. `value` is the option you tapped, exactly as sent.

Under the hood it publishes with `reply: "binary"` (or `reply: "choice"` with
`options`), captures the message `id`
from the publish response, then long-polls
`GET /blip/<topic>/<id>/reply?wait=…` until you answer or the timeout
budget runs out.

### `request_ack` — require acknowledgement (blocks)

Send a message that you must **acknowledge**, and **block until you tap
"Acknowledge"**. Use it when the human has to see and confirm something before
the agent continues. Same parameters as `ask` except `options`; publishes with `reply: "ack"`.

Returns `{ responded, message_id, topic }` plus `replied_at` when acked, or
`{ responded: false, reason: "timeout", … }`. As with `ask`, on a timeout you can
resume later with `check_reply` and the returned `message_id`.

### `check_reply` — resume / poll an earlier ask or request_ack

Look up whether you've replied to an earlier `ask`/`request_ack` — handy if the
blocking call timed out or your MCP client cancelled it. Pass the `message_id`
(and `topic`) it returned; non-blocking by default, or set `wait_seconds` to
briefly long-poll. Returns `{ responded, value?, replied_at? }` (`value` is
`"yes"` / `"no"` / `"ack"`, or the chosen option). Replies are kept ~30 minutes after the original
message was sent.

## Example prompts

> "Run the migration, and `send_alert` me when it's done — priority 4 if it
> fails."

> "If the nightly backup fails, `send_critical` me with the error — that one
> can't wait."

> "Before you `DROP` the production table, `ask` me to approve it — only proceed
> if I answer yes."

A concrete approval-gate flow:

```
Agent: about to delete the prod `events` table → calls
       ask("Delete prod `events` table (12M rows)? This cannot be undone.")
        … blocks; your phone buzzes …
You:   tap "No"
Agent: ask returns { responded: true, approved: false, value: "no" } → aborts the deletion.
```

## Develop

```bash
npm install
npm run build      # → dist/index.js
npm test           # vitest: unit (publish, config) + in-memory MCP integration
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.

TDQS

A4.2/5.0

Scored across 5 tools

Disambiguation4/5

Each tool maps to a distinct interaction mode: blocking question (ask), blocking acknowledgement (request_ack), non-blocking notification (send_alert), escalation (send_critical), and async polling (check_reply). The one soft overlap is send_alert vs send_critical, since send_alert at priority 5 does nearly the same job as send_critical; ask vs request_ack is clarified by their descriptions but still requires reading to distinguish.

Naming Consistency4/5

All names are lowercase snake_case and four of five follow a verb_noun shape (check_reply, request_ack, send_alert, send_critical). The bare verb `ask` is the only deviation, and it is short and unambiguous rather than genuinely inconsistent.

Tool Count5/5

Five tools is tightly scoped for a human-in-the-loop notification/approval service, and each one covers a genuinely different interaction pattern (ask, ack, notify, escalate, resume). Nothing looks like a redundant wrapper or a filler tool.

Completeness4/5

The core lifecycle — send notification, page critically, ask a question, request an ack, and resume a timed-out call — is fully covered. Minor gaps remain: no non-blocking question send (all questions block), no message listing/cancel/history, and send_alert's description doesn't state that it returns a message_id, which would make follow-up polling awkward.

Maintenance

ActivityActive
ResponsivenessLimited data