rapprise

# apprise-rmcp

Apprise notifications over MCP and CLI with authenticated stdio and HTTP transports.

It exposes one MCP tool, `apprise`, plus the `rapprise` CLI. Agents can send
tagged notifications through a preconfigured Apprise server, run one-off
Apprise URL sends, and check upstream health through stdio MCP, Streamable HTTP
MCP, or direct shell commands.

**30-second path:** run `npx -y @dinglebear/rapprise health --json` -> start loopback
HTTP with `APPRISE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rapprise serve` -> call
`tools/call` with `{"action":"health"}`.

**Status:** operational RMCP upstream-client server. Write-capable; notification
sends are intentional side effects. HTTP MCP supports loopback dev mode, static
bearer tokens, and Google OAuth through `lab-auth`.

**Not for:** replacing Apprise API, storing notification destinations in this
repo, scheduling reminders, building a generic webhook relay, multi-tenant
isolation, or passing upstream Apprise bearer tokens through MCP tool arguments.

## Contents

- [Naming](#naming)
- [Capabilities And Boundaries](#capabilities-and-boundaries)
- [Install](#install)
- [Quickstart](#quickstart)
- [Client Configuration](#client-configuration)
- [Runtime Surfaces](#runtime-surfaces)
- [MCP Tool Reference](#mcp-tool-reference)
- [CLI Reference](#cli-reference)
- [Configuration](#configuration)
- [Authentication](#authentication)
- [Safety And Trust Model](#safety-and-trust-model)
- [Architecture](#architecture)
- [Distribution Contract](#distribution-contract)
- [Development](#development)
- [Verification](#verification)
- [Deployment](#deployment)
- [Troubleshooting](#troubleshooting)
- [Related Servers](#related-servers)
- [Documentation](#documentation)
- [License](#license)

## Naming

| Surface | This repo |
|---|---|
| Repository | `apprise-rmcp` |
| Rust crate | `apprise-mcp` |
| Binary / CLI | `rapprise` |
| npm package | `@dinglebear/rapprise` |
| npm binary aliases | `apprise-rmcp`, `rapprise` |
| MCP tool | `apprise` |
| Config home | `~/.apprise` on hosts, `/data` in containers |
| Env prefixes | `APPRISE_*`, `APPRISE_MCP_*`, `APPRISE_RMCP_*` for npm launcher controls |

The repo and npm package use the RMCP family name, while the shipped binary uses
the short Rust CLI name `rapprise`.

## Capabilities And Boundaries

- Send notifications through tags configured in the upstream Apprise API server.
- Send one-off notifications to Apprise URL schemas with `notify_url`.
- Check upstream Apprise API health.
- Expose the `send_alert` prompt for critical alert workflows.
- Provide setup and doctor commands for local plugin/runtime checks.

| This repo owns | Apprise owns | Explicitly out of scope |
|---|---|---|
| MCP/CLI projection, request validation, auth policy, response shaping, setup checks, and transport wiring. | Notification delivery, configured destinations, tags, delivery backend credentials, upstream API semantics. | Destination storage, scheduling, retry policy beyond upstream behavior, multi-tenant sandboxing, arbitrary webhook relay behavior. |

## Install

| Path | Command | Best for | Notes |
|---|---|---|---|
| npm / npx | `npx -y @dinglebear/rapprise --help` | Linux/Windows x86_64 clients. | Verifies the release archive SHA-256 before atomic install. |
| Release installer | [Verified installer procedure](#verified-release-installer) | Linux x86_64 without Node. | Verifies checksum and offline provenance before executing installer code. |
| Docker / Compose | `docker compose up -d` | Shared HTTP MCP deployments. | Reads `.env` and exposes container port `40050`. Needs the external network first — see [Deployment](#docker--compose). |
| Build from source | `cargo build --release` | Development and audits. | Produces `target/release/rapprise`. |
| Plugin | `just build-plugin && claude plugin install ./plugins/apprise` | Claude Code from this checkout. | Bundled `rapprise` stdio plugin. Ships no hooks. |

Releases publish SHA-256 files and offline GitHub build-provenance bundles. The
installers verify both the checksum and provenance identity with GitHub CLI 2.68+.
The npm launcher supports x86_64 Linux and Windows release assets.

### npm / npx

Run the stdio MCP server or CLI without a manual binary install:

```bash
npx -y @dinglebear/rapprise --help
npx -y @dinglebear/rapprise mcp
npx -y @dinglebear/rapprise health --json
```

The npm package downloads `rapprise` during `postinstall`. Override download
behavior only when testing packaging:

| Variable | Purpose |
|---|---|
| `APPRISE_RMCP_SKIP_DOWNLOAD=1` | Skip postinstall binary download. |
| `APPRISE_RMCP_VERSION` or `APPRISE_RMCP_BINARY_VERSION` | Select the GitHub Release tag. |
| `APPRISE_RMCP_REPO` | Select the GitHub repo used for release downloads. |
| `APPRISE_RMCP_RELEASE_BASE_URL` | Select a custom release base URL. |

Verified binary installation is fail-closed and pins the repository, release
workflow, and source tag. Install `gh` 2.68 or newer before using npm or the
release installer.

### Verified Release Installer

Download the installer and its verification material without executing it,
then verify both integrity and provenance before running it:

Replace `version` with the release tag you want; `v0.2.0` is current.

```bash
version=v0.2.0
base="https://github.com/dinglebear-ai/rapprise/releases/download/${version}/rapprise-installer.sh"
curl -fsSLO "$base"
curl -fsSLO "$base.sha256"
curl -fsSLO "$base.sigstore.json"
sha256sum --check rapprise-installer.sh.sha256
gh attestation verify rapprise-installer.sh \
  --repo dinglebear-ai/rapprise \
  --bundle rapprise-installer.sh.sigstore.json \
  --signer-workflow dinglebear-ai/rapprise/.github/workflows/release.yml \
  --source-ref "refs/tags/${version}" \
  --deny-self-hosted-runners
APPRISE_RMCP_VERSION="$version" bash rapprise-installer.sh
```

The `--repo` and `--signer-workflow` values must match the identity recorded in
the attestation at build time. Releases cut before the repository moved to the
`dinglebear-ai` org are attested as `jmagar/rapprise`; use `dinglebear-ai/rapprise`
for releases cut afterwards.

The npm launcher supports Windows x86_64 only when GitHub CLI 2.68+ is installed
and `gh.exe` is available on `PATH`; provenance verification is not skipped.

### Build From Source

```bash
git clone https://github.com/dinglebear-ai/rapprise
cd rapprise
cargo build --release
./target/release/rapprise --help
```

Minimum supported Rust version: 1.90. Rust edition 2021. The Cargo workspace has
two members: the root `apprise-mcp` package and `xtask`.

## Quickstart

### 1. Start Or Point At Apprise API

The default upstream is `http://localhost:8000`.

```bash
docker run --rm -p 8000:8000 caronc/apprise:latest
```

Use `APPRISE_URL` when the API server is elsewhere:

```bash
export APPRISE_URL=http://100.120.242.29:8766
```

Set `APPRISE_TOKEN` only when your Apprise API server requires bearer auth:

```bash
export APPRISE_TOKEN=...
```

### 2. Run A Safe CLI Call

```bash
npx -y @dinglebear/rapprise health --json
```

### 3. Start Loopback HTTP MCP

```bash
APPRISE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rapprise serve
```

In another shell:

```bash
curl -sf http://127.0.0.1:40050/health
```

### 4. Make A First MCP Call

```bash
curl -s -X POST http://127.0.0.1:40050/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"apprise","arguments":{"action":"health"}}}'
```

## Client Configuration

### Claude Code Stdio

```json
{
  "mcpServers": {
    "apprise": {
      "command": "npx",
      "args": ["-y", "apprise-rmcp", "mcp"],
      "env": {
        "APPRISE_URL": "http://localhost:8000"
      }
    }
  }
}
```

### Claude Code HTTP

```json
{
  "mcpServers": {
    "apprise": {
      "type": "http",
      "url": "http://127.0.0.1:40050/mcp",
      "headers": {
        "Authorization": "Bearer ${APPRISE_MCP_TOKEN}"
      }
    }
  }
}
```

### Codex / Labby Gateway

Register Apprise through Labby as an HTTP upstream when sharing one long-running
server, or run it directly as stdio for local-only use.

```toml
[mcp_servers.apprise]
command = "npx"
args = ["-y", "apprise-rmcp", "mcp"]
```

### Generic MCP JSON

```json
{
  "command": "rapprise",
  "args": ["mcp"],
  "env": {
    "APPRISE_URL": "http://localhost:8000"
  }
}
```

Do not put `APPRISE_TOKEN`, OAuth secrets, SSH keys, passwords, or upstream
bearer tokens in MCP tool arguments. Use env, config files, or the MCP client's
secret storage.

## Runtime Surfaces

| Surface | Status | Entry point | Purpose |
|---|---:|---|---|
| MCP stdio | Supported | `rapprise mcp`, `npx -y @dinglebear/rapprise mcp` | Local child-process MCP clients. |
| MCP HTTP | Supported | `rapprise serve`, `POST /mcp` | Streamable HTTP MCP for local or shared server deployments. |
| Liveness | Supported | `GET /health` | Always unauthenticated. |
| Readiness / status | Supported | `GET /ready`, `GET /status` | Behind the same auth layer as `/mcp`. |
| OAuth discovery | Conditional | `/mcp/.well-known/*` and `lab-auth` routes | Mounted only when `auth_mode = oauth`. |
| CLI | Supported | `rapprise <command>` | Scriptable parity and debugging. |
| Prompt | Supported | `send_alert` | Reusable critical-alert workflow. |
| REST API | Not shipped | N/A | Apprise API already owns the REST API. |
| Web UI | Not shipped | N/A | Apprise API already owns the web UI. |

## MCP Tool Reference

One MCP tool is exposed: `apprise`. Pass the required `action` argument to select
the operation.

### Read Actions

| Action | Description | Required params | Optional params |
|---|---|---|---|
| `health` | Check Apprise API server health. | none | none |
| `status` | Return authenticated deployment and runtime status. | none | none |
| `help` | Return built-in markdown tool help. | none | none |

### Write Actions

| Action | Description | Required params | Optional params |
|---|---|---|---|