内容
# apprise-rmcp
`apprise-rmcp` 是一个用 Rust 编写的 MCP 服务器和 CLI，用于通过 [Apprise API](https://github.com/caronc/apprise-api) 服务器发送通知。
它提供了一个 MCP 工具 `apprise` 和 `rapprise` CLI。代理可以发送带有标签的通知，通过预配置的 Apprise 服务器运行一次性 Apprise URL 发送，并通过 stdio MCP、Streamable HTTP MCP 或直接 shell 命令检查上游健康状况。
**30 秒路径：** 运行 `npx -y apprise-rmcp health --json` -> 使用 `APPRISE_MCP_HOST=127.0.0.1 npx -y apprise-rmcp serve` 启动回环 HTTP -> 调用 `tools/call` 并传入 `{"action":"health"}`。
**状态：** 运营中的 RMCP 上游客户端服务器。可写入；通知发送是有意为之的副作用。HTTP MCP 支持回环开发模式、静态持有者令牌和通过 `lab-auth` 的 Google OAuth。
**不适用于：** 替换 Apprise API、在此仓库中存储通知目标、安排提醒、构建通用 webhook 继电器、多租户隔离或通过 MCP 工具参数传递上游 Apprise 持有者令牌。
## 目录
- [命名](#命名)
- [功能和边界](#功能和边界)
- [安装](#安装)
- [快速入门](#快速入门)
- [客户端配置](#客户端配置)
- [运行时界面](#运行时界面)
- [MCP 工具参考](#mcp-工具参考)
- [CLI 参考](#cli参考)
- [配置](#配置)
- [身份验证](#身份验证)
- [安全性和信任模型](#安全性和信任模型)
- [架构](#架构)
- [分发合约](#分发合约)
- [开发](#开发)
- [验证](#验证)
- [部署](#部署)
- [故障排除](#故障排除)
- [相关服务器](#相关服务器)
- [文档](#文档)
- [许可证](#许可证)
## 命名
| 界面 | 本仓库 |
|---|---|
| 仓库 | `apprise-rmcp` |
| Rust 包 | `apprise-mcp` |
| 二进制文件 / CLI | `rapprise` |
| npm 包 | `apprise-rmcp` |
| npm 二进制文件别名 | `apprise-rmcp`, `rapprise` |
| MCP 工具 | `apprise` |
| 配置首页 | 主机上的 `~/.apprise`，容器中的 `/data` |
| 环境前缀 | `APPRISE_*`，`APPRISE_MCP_*`，`APPRISE_RMCP_*` 用于 npm 启动器控制 |
该仓库和 npm 包使用 RMCP 家族名称，而已发布的二进制文件使用简短的 Rust CLI 名称 `rapprise`。
## 功能和边界
- 通过上游 Apprise API 服务器中配置的标签发送通知。
- 使用 `notify_url` 向 Apprise URL 模式发送一次性通知。
- 检查上游 Apprise API 健康状况。
- 暴露 `send_alert` 提示用于关键警报工作流。
- 提供本地插件/运行时检查的设置和医生命令。
| 本仓库拥有 | Apprise 拥有 | 明确超出范围 |
|---|---|---|
| MCP/CLI 投影、请求验证、身份验证策略、响应塑形、设置检查和传输连接。 | 通知传递、配置的目标、标签、传递后端凭证、上游 API 语义。 | 目标存储、调度、超出上游行为的重试策略、多租户沙盒、任意 webhook 继电器行为。 |
## 安装
| 路径 | 命令 | 最适合 | 备注 |
|---|---|---|---|
| npm / npx | `npx -y apprise-rmcp --help` | Linux/Windows x86_64 客户端。 | 在原子安装前验证发布存档 SHA-256。 |
| 发布安装程序 | [验证的安装程序过程](#验证发布安装程序) | 无 Node 的 Linux x86_64。 | 在执行安装程序代码之前验证校验和和离线出处。 |
| Docker / Compose | `docker compose up -d` | 共享的 HTTP MCP 部署。 | 读取 `.env` 并公开容器端口 `40050`。 |
| 从源代码构建 | `cargo build --release` | 开发和审计。 | 生成 `target/release/rapprise`。 |
| 插件 | `just build-plugin && claude plugin install ./plugins/apprise` | 此签出的 Claude 代码。 | 捆绑的 `rapprise` stdio 插件。 |
发布会公布 SHA-256 文件和离线 GitHub 构建出处包。安装程序验证校验和和出处身份与 GitHub CLI 2.68+。
### npm / npx
在不手动安装二进制文件的情况下运行 stdio MCP 服务器或 CLI：
```bash
npx -y apprise-rmcp --help
npx -y apprise-rmcp mcp
npx -y apprise-rmcp health --json
```
npm 包在 `postinstall` 期间下载 `rapprise`。仅在测试打包时覆盖下载行为：
| 变量 | 目的 |
|---|---|
| `APPRISE_RMCP_SKIP_DOWNLOAD=1` | 跳过安装后二进制下载。 |
| `APPRISE_RMCP_VERSION` 或 `APPRISE_RMCP_BINARY_VERSION` | 选择 GitHub 发布标签。 |
| `APPRISE_RMCP_REPO` | 选择用于发布下载的 GitHub 仓库。 |
| `APPRISE_RMCP_RELEASE_BASE_URL` | 选择自定义发布基准 URL。 |
验证的二进制安装是故障安全的，并固定仓库、发布工作流和源标签。在使用 npm 或发布安装程序之前安装 `gh` 2.68 或更高版本。
### 验证发布安装程序
下载安装程序及其验证材料而不执行它，然后在运行它之前验证完整性和出处：
```bash
version=v0.1.3
base="https://github.com/jmagar/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 jmagar/rapprise \
--bundle rapprise-installer.sh.sigstore.json \
--signer-workflow jmagar/rapprise/.github/workflows/release.yml \
--source-ref "refs/tags/${version}" \
--deny-self-hosted-runners
APPRISE_RMCP_VERSION="$version" bash rapprise-installer.sh
```
npm 启动器仅在安装了 GitHub CLI 2.68+ 且 `gh.exe` 可用的情况下支持 Windows x86_64；出处验证不会被跳过。
### 从源代码构建
```bash
git clone https://github.com/jmagar/rapprise
cd apprise-rmcp
cargo build --release
./target/release/rapprise --help
```
最低支持的 Rust 版本：1.90。
## 快速入门
### 1. 启动或指向 Apprise API
默认上游是 `http://localhost:8000`。
```bash
docker run --rm -p 8000:8000 caronc/apprise:latest
```
在 API 服务器位于其他位置时使用 `APPRISE_URL`：
```bash
export APPRISE_URL=http://100.120.242.29:8766
```
仅当您的 Apprise API 服务器需要持有者身份验证时，才设置 `APPRISE_TOKEN`：
```bash
export APPRISE_TOKEN=...
```
### 2. 运行安全 CLI 调用
```bash
npx -y apprise-rmcp health --json
```
### 3. 启动回环 HTTP MCP
```bash
APPRISE_MCP_HOST=127.0.0.1 npx -y apprise-rmcp serve
```
在另一个 shell 中：
```bash
curl -sf http://127.0.0.1:40050/health
```
### 4. 进行首次 MCP 调用
```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"}}}'
```
## 客户端配置
### 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
通过 Labby 将 Apprise 注册为 HTTP 上游，以共享一个长期运行的服务器，或直接作为 stdio 运行仅限本地使用。
```toml
[mcp_servers.apprise]
command = "npx"
args = ["-y", "apprise-rmcp", "mcp"]
```
### 通用 MCP JSON
```json
{
"command": "rapprise",
"args": ["mcp"],
"env": {
"APPRISE_URL": "http://localhost:8000"
}
}
```
不要在 MCP 工具参数中放置 `APPRISE_TOKEN`、OAuth 机密、SSH 密钥、密码或上游持有者令牌。使用环境变量、配置文件或 MCP 客户端的秘密存储。
## 运行时界面
| 界面 | 状态 | 入口点 | 目的 |
|---|---:|---|---|
| MCP stdio | 支持 | `rapprise mcp`, `npx -y apprise-rmcp mcp` | 本地子进程 MCP 客户端。 |
| MCP HTTP | 支持 | `rapprise serve`, `POST /mcp` | 可流式 HTTP MCP，用于本地或共享服务器部署。 |
| CLI | 支持 | `rapprise <command>` | 可脚本化的对等性和调试。 |
| 提示 | 支持 | `send_alert` | 可重用的关键警报工作流。 |
| REST API | 未发布 | N/A | Apprise API 已经拥有 REST API。 |
| Web UI | 未发布 | N/A | Apprise API 已经拥有 Web UI。 |
## MCP 工具参考
公开一个 MCP 工具：`apprise`。传递所需的 `action` 参数以选择操作。
### 读取操作
| 操作 | 描述 | 必需参数 | 可选参数 |
|---|---|---|---|
| `health` | 检查 Apprise API 服务器健康状况。 | 无 | 无 |
| `status` | 返回身份验证的部署和运行时状态。 | 无 | 无 |
| `help` | 返回内置的 Markdown 工具帮助。 | 无 | 无 |
### 写入操作
| 操作 | 描述 | 必需参数 | 可选参数 |
|---|---|---|---|
| `notify` | 发送到配置的 Apprise 标签，或当省略 `tag` 时发送到所有配置的服务。 | `body` | `tag`, `title`, `type` |
| `notify_url` | 向一个或多个 Apprise URL 模式发送无状态的一次性通知。 | `urls`, `body` | `title`, `type` |
### 通知类型
| 类型 | 含义 |
|---|---|
| `info` | 信息通知。 |
| `success` | 成功操作。 |
| `warning` | 非关键警告。 |
| `failure` | 关键故障或错误。 |
### MCP 调用示例
```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"}}}'
```
```json
{
"name": "apprise",
"arguments": {
"action": "notify",
"body": "部署成功",
"tag": "ops",
"title": "部署完成",
"type": "success"
}
}
```
精选的操作摘要位于此处。`docs/INVENTORY.md` 是完整参数的当前源，直到添加生成的 `docs/MCP_SCHEMA.md` 为止。
## CLI 参考
CLI 调用与 MCP 工具相同的服务方法。
```bash
rapprise health [--json]
rapprise notify <body> [--tag TAG] [--title T] [--type info|success|warning|failure] [--json]
rapprise notify-url <urls> <body> [--title T] [--type info|success|warning|failure] [--json]
rapprise serve
rapprise serve mcp
rapprise mcp
rapprise doctor [--json]
rapprise setup check
rapprise setup repair
rapprise setup plugin-hook [--no-repair]
```
## 配置
当存在时，从 `config.toml` 加载配置，然后环境变量覆盖这些值。在启动时，它在主机上加载 `${APPRISE_HOME:-~/.apprise}/.env` 或在容器中加载 `/data/.env`。参见 [完整清单](docs/INVENTORY.md)。
### 上游变量
| 变量 | 必需 | 描述 |
|---|---:|---|
| `APPRISE_URL` | 否 | Apprise API 服务器基准 URL。默认为 `http://localhost:8000`。 |
| `APPRISE_TOKEN` | 仅限受保护的上游 | 可选的上游 Apprise API 持有者令牌。 |
### 运行时变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `APPRISE_MCP_HOST` | `0.0.0.0` | HTTP MCP 绑定主机。 |
| `APPRISE_MCP_PORT` | `40050` | HTTP MCP 绑定端口。 |
| `APPRISE_MCP_TOKEN` | 空 | HTTP MCP 的静态持有者令牌（当不在回环开发模式下）。 |
| `APPRISE_MCP_NO_AUTH` | `false` | 禁用 HTTP MCP 身份验证。仅在回环或受信任网关后使用。 |
| `APPRISE_MCP_AUTH_MODE` | `bearer` | 通过 `lab-auth` 设置为 Google OAuth。 |
| `APPRISE_MCP_PUBLIC_URL` | 空 | OAuth 元数据和受保护资源发现的公共 URL。 |
| `APPRISE_MCP_GOOGLE_CLIENT_ID` | 空 | Google OAuth 客户端 ID。 |
| `APPRISE_MCP_GOOGLE_CLIENT_SECRET` | 空 | Google OAuth 客户端密钥。 |
| `APPRISE_MCP_AUTH_ADMIN_EMAIL` | 空 | 初始/管理员 OAuth 电子邮件。 |
| `APPRISE_MCP_ALLOWED_HOSTS` | 空 | 其他接受的 HTTP 主机头值。 |
| `APPRISE_MCP_ALLOWED_ORIGINS` | 空 | HTTP MCP 的其他 CORS 来源。 |
| `APPRISE_MCP_AUTH_ALLOWED_REDIRECT_URIS` | 空 | OAuth 客户端重定向 URI。 |
| `RUST_LOG` | `info` | Rust 日志过滤器。Stdio 日志必须保持在 stdout 关闭状态。 |
## 身份验证
| 策略 | 何时 | 效果 |
|---|---|---|
| Stdio | `rapprise mcp` | 本地进程信任；HTTP 身份验证不适用。 |
| 回环开发 | 回环加无身份验证 | 允许未经身份验证的本地 HTTP。 |
| 非回环无身份验证 | 非回环加无身份验证 | 无效；启动必须拒绝它。 |
| 静态持有者 | 持有者加 `APPRISE_MCP_TOKEN` | 需要确切的持有者令牌。 |
| OAuth | 颁发者/客户端/管理员设置 | 需要 OAuth/JWT。 |
| OAuth 静态控制 | 禁用静态令牌 | 静态令牌不能绕过 OAuth。 |
MCP 范围为 `apprise:notify` 和 `apprise:admin`。在分派 MCP 调用之前检查 OAuth 令牌。
## 安全性和信任模型
- MCP 调用者从不提供 `APPRISE_TOKEN`、OAuth 机密、静态持有者令牌、密码、SSH 密钥或 API 密钥作为工具参数。
- 上游 Apprise 凭证仅从环境/配置加载。
- `notify` 是首选路径，因为目标在上游按标签配置。
- `notify_url` 故意在 MCP 参数中接受 Apprise URL 模式，以进行一次性发送。 将这些 URL 视为敏感有效载荷，避免在有可用的上游目标标签时使用它们。
- Apprise API 是目标配置的持久源；该服务器是对该 API 的薄投影。
- HTTP 模式不应在没有持有者或 OAuth 身份验证以及上游反向代理的 TLS 的情况下暴露在回环之外。
## 架构
```text
MCP 客户端 / CLI
|
v
rapprise
|
+-- MCP 垫片：JSON 参数 -> AppriseService -> 结构化结果
+-- CLI 垫片：argv -> AppriseService -> stdout
|
v
AppriseService
|
v
AppriseClient
|
v
Apprise API 服务器
|
v
通知后端
```
| 路径 | 角色 |
|---|---|
| `src/app.rs` | 业务服务层、响应塑形、计数器和通知调用。 |
| `src/apprise.rs` | Apprise API REST 客户端。 |
| `src/mcp/` | RMCP 工具、提示、模式、路由和身份验证检查。 |
| `src/cli.rs` | CLI 解析器、医生/设置助手和输出格式化。 |
| `src/config.rs` | 环境/配置加载和默认值。 |
| `packages/apprise-rmcp/` | npm 启动器和发布二进制下载器。 |
通知命令和 MCP 在 `AppriseService` 上汇聚。CLI 还拥有设置、医生、自我安装、文件系统和输出编排。
## 分发合约
| 工件 | 文件 | 必须与 |
|---|---|---|
| Rust 包/二进制文件 | `Cargo.toml`, `Cargo.lock` | Git 标签、发布资产、CLI 文档、安装脚本。 |
| npm 启动器 | `packages/apprise-rmcp/package.json`, `bin/rapprise.js`, `lib/platform.js`, `scripts/install.js` | GitHub 发布标签和资产，命名为 `rapprise-x86_64.tar.gz` 和 `rapprise-windows-x86_64.tar.gz`。 |
| GitHub 发布 | `.github/workflows/*`, `scripts/install.sh`, `install.sh` | 包版本、二进制名称、校验和、支持的平台。 |
| Docker / Compose | `Dockerfile`, `docker-compose*.yml` | 公开端口 `40050`、健康检查 `/health`、环境文件合约。 |
| MCP 注册表 | `server.json` | 身份 `ai.dinglebear/apprise-rmcp`、stdio 包、版本。 |
| 插件 | `plugins/apprise` | 捆绑的 `rapprise` stdio 和直接设置钩。 |
| 文档 | `README.md`, `docs/INVENTORY.md`, `docs/QUICKSTART.md` | 当前二进制名称、默认端口、操作列表和环境名称。 |
发布不变式：npm、crate、注册表/服务器元数据、清单、GitHub 标签和本机资产一起移动。Release Please 拥有这些更新。
## 开发
```bash
cargo fmt -- --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo build --release
npm --prefix packages/apprise-rmcp run check
```
## 验证
```bash
# 二进制文件和 CLI
cargo build --release
./target/release/rapprise --version
./target/release/rapprise health --json
# HTTP 健康状况
APPRISE_MCP_HOST=127.0.0.1 ./target/release/rapprise serve
curl -sf http://127.0.0.1:40050/health
# MCP 工具调用
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"}}}'
```
对于实时通知测试，请在 Apprise API 服务器上配置至少一个目标，并使用其标签调用 `notify`。
## 部署
### Docker / Compose
```bash
cp .env.example .env
$EDITOR .env
docker compose up -d
curl -sf http://127.0.0.1:40050/health
```
容器在 `/data` 下存储应用程序数据，通常从 `${HOME}/.apprise` 挂载。
### 反向代理
仅公开 `/mcp` 和 `/health`。保留可流式 HTTP 头部，要求 TLS，并配置持有者或 OAuth 身份验证，然后将服务器暴露在回环之外。
### 插件
```bash
claude plugin install plugins/apprise
rapprise setup check
```
## 故障排除
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
| 从 `/mcp` 获取 `401` 状态码 | 缺失或错误的 bearer/OAuth token。 | 检查 `APPRISE_MCP_TOKEN` 和客户端头部信息，或在本地使用循环开发模式。 |
| CLI 健康检查失败 | Apprise API 无法访问。 | 检查 `APPRISE_URL` 和上游 Apprise API 服务器。 |
| `notify` 无处发送 | 没有与标签匹配的上游目标。 | 检查在 Apprise API 中配置的标签，或省略 `tag` 以发送到所有已配置的服务。 |
| `notify_url` 失败 | 无效的 Apprise URL 模式或目标后端被阻止。 | 直接使用 Apprise API 测试 URL，并优先使用已配置的标签进行重复使用。 |
| 标准输出 MCP JSON 解析错误 | 日志输出到了标准输出。 | 关闭标准输出的协议日志，并根据需要降低 `RUST_LOG` 日志级别。 |
| npm 启动器无法找到二进制文件 | 发布资产下载失败或被跳过。 | 重新安装，检查 `APPRISE_RMCP_VERSION`，或从源代码构建 `rapprise`。 |
## 相关服务器
- [soma](https://github.com/jmagar/soma) - 提供商支持的 MCP 服务器运行时。
- [unifi-rmcp](https://github.com/jmagar/runifi) - UniFi 控制器 REST API 桥接。
- [tailscale-rmcp](https://github.com/jmagar/rtailscale) - Tailscale 设备、用户和 tailnet 操作的 API 桥接。
- [unraid-rmcp](https://github.com/jmagar/runraid) - Unraid 图形化查询语言桥接，用于 NAS 和服务器管理。
- [gotify-rmcp](https://github.com/jmagar/rgotify) - Gotify 发送、消息、应用和客户端的推送通知桥接。
- [arcane-rmcp](https://github.com/jmagar/rarcane) - Arcane 容器和相关资源的 Docker 管理桥接。
- [yarr](https://github.com/jmagar/yarr) - 面向 Sonarr、Radarr、Prowlarr、Plex 和相关服务的媒体栈桥接。
- [ytdl-rmcp](https://github.com/jmagar/rytdl) - 媒体下载和元数据工作流服务器。
- [synapse-rmcp](https://github.com/jmagar/synapse) - 本地 Synapse 工作流服务器，用于 scout 和 flux 操作。
- [cortex](https://github.com/jmagar/cortex) - Syslog 和家庭实验室日志聚合 MCP 服务器。
- [axon](https://github.com/jmagar/axon) - RAG、爬取、抓取、提取和语义搜索项目。
- [labby](https://github.com/jmagar/labby) - 家庭实验室控制平面和 MCP 网关项目。
- [lumen](https://github.com/jmagar/lumen) - 本地语义代码搜索 MCP 服务器。
## 文档
从这里开始：
- [`docs/QUICKSTART.md`](docs/QUICKSTART.md) - 安装流程。
- [`docs/INVENTORY.md`](docs/INVENTORY.md) - 动作、CLI 命令、环境变量和端点的组件清单。
- [`docs/README.md`](docs/README.md) - 文档索引。
- [`server.json`](server.json) - MCP 注册表元数据。
- [`packages/apprise-rmcp/README.md`](packages/apprise-rmcp/README.md) - npm 包启动器说明。
本 README 被精心整理。生成的或详尽的目录应在其各自的文件中刷新，并被视为当前分支详情的真实来源。
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器