内容
# gotify-rmcp
`gotify-rmcp` 是一个用 Rust 编写的 MCP 服务器和 CLI，用于将代理连接到自托管的 [Gotify](https://gotify.net/) 消息推送服务器。
它提供了一个 MCP 工具 `gotify` 和 `rgotify` CLI。代理可以通过 stdio MCP、Streamable HTTP MCP 或直接 shell 命令发送通知、检查服务器健康、列出消息和管理 Gotify 应用和客户端。
**30 秒路径：** 设置 `GOTIFY_URL`，然后运行 `npx -y gotify-rmcp health --json` -> 使用 `GOTIFY_MCP_HOST=127.0.0.1 npx -y gotify-rmcp serve` 启动循环 HTTP -> 调用 `tools/call` 并传入 `{"action":"health"}`。
**状态：** 操作 RMCP 上游客户端服务器。可写入；破坏性删除操作需要显式确认。HTTP MCP 支持循环开发模式、静态 bearer token 和通过 `lab-auth` 的 Google OAuth。
**不适用于：** 替换 Gotify、独立存储通知、通用 webhook 路由、调度提醒、多租户隔离或通过 MCP 工具参数传递 Gotify token。
## 目录
- [命名](#命名)
- [功能和边界](#功能和边界)
- [安装](#安装)
- [快速入门](#快速入门)
- [客户端配置](#客户端配置)
- [运行时界面](#运行时界面)
- [MCP 工具参考](#mcp-工具参考)
- [CLI 参考](#cli-参考)
- [配置](#配置)
- [身份验证](#身份验证)
- [安全和信任模型](#安全和信任模型)
- [架构](#架构)
- [分发合约](#分发合约)
- [开发](#开发)
- [验证](#验证)
- [部署](#部署)
- [故障排除](#故障排除)
- [相关服务器](#相关服务器)
- [文档](#文档)
- [许可证](#许可证)
## 命名
| 界面 | 本仓库 |
|---|---|
| 仓库 | `gotify-rmcp` |
| Rust crate | `gotify-rmcp` |
| 二进制 / CLI | `rgotify` |
| npm 包 | `gotify-rmcp` |
| npm 二进制别名 | `gotify-rmcp`、`rgotify` |
| MCP 工具 | `gotify` |
| 配置主页 | 主机上的 `~/.gotify`，容器中的 `/data` |
| 环境前缀 | `GOTIFY_*`、`GOTIFY_MCP_*`、`GOTIFY_RMCP_*` 用于 npm 启动器控件 |
仓库和 npm 包使用 RMCP 家族名称，而发布的二进制文件使用简短的 Rust CLI 名称 `rgotify`。
## 功能和边界
- 发送带有消息、标题、优先级和额外信息的 Gotify 消息推送通知。
- 读取服务器健康、运行时状态、服务器版本、当前用户、消息、应用程序和客户端。
- 创建或更新应用程序并创建客户端。
- 删除消息、所有消息、应用程序或客户端，仅在显式破坏性确认后。
- 为常见工作流程公开 MCP 提示和包含当前工具模式的资源。
| 本仓库拥有 | Gotify 拥有 | 明确超出范围 |
|---|---|---|
| MCP/CLI 投影、请求验证、身份验证策略、响应塑形、设置检查、破坏性门控。 | 通知存储、投递、Gotify 用户、令牌颁发、应用程序/客户端状态、上游 API 语义。 | 通知调度、独立持久性、任意 webhook 中继行为、多租户沙盒、凭证代理。 |
## 安装
| 路径 | 命令 | 最适合 | 备注 |
|---|---|---|---|
| npm / npx | `npx -y gotify-rmcp --help` | 本地 MCP 客户端和快速试验。 | 从 GitHub Releases 下载匹配的 `rgotify` 二进制文件。 |
| 发布安装程序 | `curl -fsSL https://raw.githubusercontent.com/jmagar/rgotify/main/scripts/install.sh \| bash` | 无 Node 的主机安装。 | 为当前 Linux 主机安装 `rgotify`。 |
| Docker / Compose | `docker compose up -d` | 共享 HTTP MCP 部署。 | 读取 `.env` 并公开容器端口 `40020`。 |
| 从源代码构建 | `cargo build --release` | 开发和审计。 | 生成 `target/release/rgotify`。 |
| 插件 | `claude plugin install plugins/gotify` | 从此检出安装 Claude Code 本地插件。 | 使用打包的设置钩子和本地运行时元数据。 |
### npm / npx
在没有手动二进制安装的情况下运行 stdio MCP 服务器或 CLI：
```bash
npx -y gotify-rmcp --help
npx -y gotify-rmcp mcp
npx -y gotify-rmcp health --json
```
npm 包在 `postinstall` 期间下载 `rgotify`。仅在测试包装时覆盖下载行为：
| 变量 | 目的 |
|---|---|
| `GOTIFY_RMCP_SKIP_DOWNLOAD=1` | 跳过 postinstall 二进制下载。 |
| `GOTIFY_RMCP_VERSION` 或 `GOTIFY_RMCP_BINARY_VERSION` | 选择 GitHub Release 标签。 |
| `GOTIFY_RMCP_REPO` | 选择用于发布下载的 GitHub 仓库。 |
| `GOTIFY_RMCP_RELEASE_BASE_URL` | 选择自定义发布基准 URL。 |
### 从源代码构建
```bash
git clone https://github.com/jmagar/rgotify
cd gotify-rmcp
cargo build --release
./target/release/rgotify --help
```
最低支持的 Rust 版本：1.86。
## 快速入门
### 1. 配置 Gotify
对于最安全的首次调用，仅需要 `GOTIFY_URL`：
```bash
export GOTIFY_URL=https://gotify.example.com
```
在 Gotify Web UI 中创建令牌后再使用管理或发送操作：
```bash
export GOTIFY_CLIENT_TOKEN=Cxxxxxxxxxxxxxxxx
export GOTIFY_APP_TOKEN=Axxxxxxxxxxxxxxxx
```
令牌角色：
| 令牌 | 环境变量 | 用于 |
|---|---|---|
| 客户端令牌 | `GOTIFY_CLIENT_TOKEN` | 读取和管理操作，例如消息、应用程序、客户端和当前用户。 |
| 应用程序令牌 | `GOTIFY_APP_TOKEN` | 使用 `send` 发送通知。 |
### 2. 运行安全 CLI 调用
```bash
npx -y gotify-rmcp health --json
```
### 3. 启动循环 HTTP MCP
```bash
GOTIFY_MCP_HOST=127.0.0.1 npx -y gotify-rmcp serve
```
在另一个 shell 中：
```bash
curl -sf http://127.0.0.1:40020/health
```
### 4. 进行首次 MCP 调用
```bash
curl -s -X POST http://127.0.0.1:40020/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"gotify","arguments":{"action":"health"}}}'
```
## 客户端配置
### Claude Code Stdio
```json
{
"mcpServers": {
"gotify": {
"command": "npx",
"args": ["-y", "gotify-rmcp", "mcp"],
"env": {
"GOTIFY_URL": "https://gotify.example.com",
"GOTIFY_CLIENT_TOKEN": "Cxxxxxxxxxxxxxxxx",
"GOTIFY_APP_TOKEN": "Axxxxxxxxxxxxxxxx"
}
}
}
}
```
### Claude Code HTTP
```json
{
"mcpServers": {
"gotify": {
"type": "http",
"url": "http://127.0.0.1:40020/mcp",
"headers": {
"Authorization": "Bearer ${GOTIFY_MCP_TOKEN}"
}
}
}
}
```
### Codex / Labby Gateway
在 Labby 中将 Gotify 注册为 HTTP 上游以共享一个长时间运行的服务器，或直接作为 stdio 仅用于本地使用。
```toml
[mcp_servers.gotify]
command = "npx"
args = ["-y", "gotify-rmcp", "mcp"]
```
### 通用 MCP JSON
```json
{
"command": "rgotify",
"args": ["mcp"],
"env": {
"GOTIFY_URL": "https://gotify.example.com"
}
}
```
不要将 API 密钥、密码、OAuth 机密、SSH 密钥、Gotify 客户端令牌、Gotify 应用程序令牌或上游 bearer 令牌放入 MCP 工具参数中。使用环境变量、配置文件或 MCP 客户端的秘密存储。
## 运行时界面
| 界面 | 状态 | 入口点 | 目的 |
|---|---:|---|---|
| MCP stdio | 支持 | `rgotify mcp`、`npx -y gotify-rmcp mcp` | 本地子进程 MCP 客户端。 |
| MCP HTTP | 支持 | `rgotify serve`、`POST /mcp` | 流式 HTTP MCP，用于本地或共享服务器部署。 |
| CLI | 支持 | `rgotify <command>` | 可脚本化对齐和调试。 |
| 提示 | 支持 | `send_notification`、`check_status` | 可重用代理提示。 |
| 资源 | 支持 | `gotify://schema/mcp-tool` | `gotify` 工具的 JSON 模式。 |
| REST API | 未发货 | N/A | Gotify 已经拥有 REST API。 |
| Web UI | 未发货 | N/A | Gotify 已经拥有 Web UI。 |
## MCP 工具参考
公开一个 MCP 工具：`gotify`。传递所需的 `action` 参数以选择操作。
### 读取操作
| 操作 | 描述 | 必需参数 | 可选参数 |
|---|---|---|---|
| `health` | Gotify 服务器健康检查。 | 无 | 无 |
| `version` | Gotify 服务器版本。 | 无 | 无 |
| `me` | 当前身份验证用户。 | 无 | 无 |
| `messages` | 列出消息。 | 无 | `app_id`、`limit`、`since` |
| `applications` | 列出应用程序。 | 无 | 无 |
| `clients` | 列出客户端。 | 无 | 无 |
| `status` | 返回运行时状态、配置快照和计数器。 | 无 | 无 |
### 写操作
| 操作 | 描述 | 必需参数 | 可选参数 |
|---|---|---|---|
| `send` | 发送推送通知。 | `message` | `title`、`priority`、`extras` |
| `create_application` | 创建应用程序。 | `name` | `description`、`default_priority` |
| `update_application` | 更新应用程序。 | `app_id` | `name`、`description`、`default_priority` |
| `create_client` | 创建客户端。 | `name` | 无 |
### 破坏性操作
破坏性操作需要 `confirm=true` 在 MCP 参数中、`--confirm` 在 CLI 上或 `GOTIFY_ALLOW_DESTRUCTIVE=true` 在进程环境中。
| 操作 | 描述 | 必需参数 |
|---|---|---|
| `delete_message` | 删除一条消息。 | `id`、`confirm` |
| `delete_all_messages` | 删除所有消息。 | `confirm` |
| `delete_application` | 删除应用程序及其消息。 | `app_id`、`confirm` |
| `delete_client` | 删除客户端。 | `client_id`、`confirm` |
### 元数据、提示和资源
| 原始 | 名称/URI | 目的 |
|---|---|---|
| 工具操作 | `help` | 返回内置的 markdown 工具帮助。 |
| 提示 | `send_notification` | 指导代理发送通知。 |
| 提示 | `check_status` | 检查健康状况和最近的消息。 |
| 资源 | `gotify://schema/mcp-tool` | 返回基于操作的当前 JSON 模式。 |
精选的操作摘要在此处。当前分支源代码和 `docs/INVENTORY.md` 是完整参数的源，直到添加生成的 `docs/MCP_SCHEMA.md` 为止。
## CLI 参考
CLI 调用与 MCP 工具相同的服务方法。
```bash
rgotify health [--json]
rgotify version [--json]
rgotify me [--json]
rgotify messages [--app-id N] [--limit N] [--since N] [--json]
rgotify applications [--json]
rgotify clients [--json]
rgotify send <message> [--title T] [--priority N] [--json]
rgotify create app <name> [--description D] [--priority N] [--json]
rgotify create client <name> [--json]
rgotify delete message <id> [--confirm] [--json]
rgotify delete all [--confirm] [--json]
rgotify delete app <app_id> [--confirm] [--json]
rgotify delete client <client_id> [--confirm] [--json]
rgotify serve
rgotify serve mcp
rgotify mcp
rgotify doctor [--json]
rgotify setup check [--json]
rgotify setup repair [--json]
rgotify setup plugin-hook [--no-repair] [--json]
```
已知对齐异常：MCP `action=status` 是 MCP 独有的可观察性。CLI 等效运算符检查是 `rgotify doctor --json`。
## 配置
配置从存在时从 `config.toml` 加载，然后环境变量覆盖这些值。在启动时，二进制文件还会在主机上加载 `~/.gotify/.env` 或容器中的 `/data/.env` 而不覆盖已设置的变量。
### 必需的上游变量
| 变量 | 必需 | 描述 |
|---|---:|---|
| `GOTIFY_URL` | 是 | Gotify 服务器基本 URL，例如 `https://gotify.example.com`。 |
| `GOTIFY_CLIENT_TOKEN` | 用于管理 | Gotify 客户端令牌，用于读取和管理操作。 |
| `GOTIFY_APP_TOKEN` | 用于 `send` | Gotify 应用令牌，仅用于发送通知。 |
### 运行时变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `GOTIFY_ALLOW_DESTRUCTIVE` | `false` | 跳过破坏性确认门控。 |
| `GOTIFY_MCP_HOST` | `0.0.0.0` | HTTP MCP 绑定主机。 |
| `GOTIFY_MCP_PORT` | `40020` | HTTP MCP 绑定端口。 |
| `GOTIFY_MCP_TOKEN` | 空 | HTTP MCP 的静态 bearer 令牌（不在循环开发模式下）。 |
| `GOTIFY_MCP_NO_AUTH` | `false` | 禁用 HTTP MCP 身份验证。仅在循环或受信任的网关后使用。 |
| `GOTIFY_MCP_AUTH_MODE` | `bearer` | 设置为 `oauth` 以通过 `lab-auth` 进行 Google OAuth。 |
| `GOTIFY_MCP_PUBLIC_URL` | 空 | OAuth 元数据和受保护资源发现的公共 URL。 |
| `GOTIFY_MCP_GOOGLE_CLIENT_ID` | 空 | Google OAuth 客户端 ID。 |
| `GOTIFY_MCP_GOOGLE_CLIENT_SECRET` | 空 | Google OAuth 客户端机密。 |
| `GOTIFY_MCP_AUTH_ADMIN_EMAIL` | 空 | 初始/管理员 OAuth 电子邮件。 |
| `RUST_LOG` | `info` | Rust 日志过滤器。Stdio 日志必须保留在 stdout 上。 ## 身份验证
| 策略 | 何时 | 效果 |
|---|---|---|
| 循环开发 | `GOTIFY_MCP_HOST` 以 `127.` 或 `GOTIFY_MCP_NO_AUTH=true` 开始 | 不会安装 HTTP 身份验证层。仅用于本地测试。 |
| 静态` | `false` | 禁用 HTTP MCP 身份验证。仅在循环或受信任的网关后使用。 |
| `GOTIFY_MCP_AUTH_MODE` | `bearer` | 设置为 `oauth` 以通过 `lab-auth` 进行 Google OAuth。 |
| stdio | `rgotify mcp` | 本地子进程边界是信任边界。 |
MCP 作用域为 `gotify:read` 和 `gotify:write`。静态 bearer token 授予两种作用域。OAuth token 在调度 MCP 调用之前进行检查。
## 安全性和信任模型
- MCP 调用者永远不会将 Gotify 客户端令牌、Gotify 应用令牌、OAuth 机密、静态 bearer token、密码或 API 密钥作为工具参数提供。
- 上游凭证仅从环境变量/配置加载。
- 删除操作需要 `confirm=true`、`--confirm` 或显式 `GOTIFY_ALLOW_DESTRUCTIVE=true` 进程覆盖。
- Gotify 是通知状态的持久化源；此服务器是对该 API 的薄弱投影。
- stdio 模式使用用户的本地权限运行，不会提供沙盒保护。
- HTTP 模式不应在没有 bearer 或 OAuth 身份验证以及上游反向代理的 TLS 保护的情况下暴露在 loopback 以外。
## 架构
```text
MCP 客户端 / CLI
|
v
rgotify
|
+-- MCP shim: JSON 参数 -> GotifyService -> 结构化结果
+-- CLI shim: argv -> GotifyService -> stdout
|
v
GotifyService
|
v
GotifyClient
|
v
Gotify REST API
```
| 路径 | 角色 |
|---|---|
| `src/app.rs` | 业务服务层、破坏性门控、响应塑形。 |
| `src/gotify.rs` | Gotify REST 客户端。 |
| `src/mcp/` | RMCP 工具、提示、资源、模式和身份验证检查。 |
| `src/cli/` | CLI 解析器、医生、设置帮助程序和输出格式化。 |
| `src/config.rs` | 环境变量/配置加载和默认值。 |
| `packages/gotify-rmcp/` | npm 启动器和发布二进制下载器。 |
薄薄的 shim 规则是有意的：MCP 和 CLI 解析输入，调用 `GotifyService` 并返回输出。凭证处理、破坏性门控和 Gotify API 行为保留在 MCP 和 CLI shim 之外。
## 分发合约
| 工件 | 文件（s） | 必须与以下内容对齐 |
|---|---|---|
| Rust crate/binary | `Cargo.toml`、`Cargo.lock` | Git 标签、发布资产、CLI 文档、安装脚本。 |
| npm 启动器 | `packages/gotify-rmcp/package.json`、`bin/rgotify.js`、`lib/platform.js`、`scripts/install.js` | GitHub 发布标签和资产命名为 `rgotify-x86_64.tar.gz` 和 `rgotify-windows-x86_64.tar.gz`。 |
| GitHub Releases | `.github/workflows/*`、`scripts/install.sh` | 包版本、二进制名称、校验和、支持的平台。 |
| Docker / Compose | `config/Dockerfile`、`docker-compose*.yml` | 公开的端口 `40020`、健康检查 `/health`、环境文件合约。 |
| MCP 注册表 | `server.json` | 服务器身份 `tv.tootie/gotify-rmcp`、环境变量、传输 URL、包版本。 |
| 插件 | `plugins/gotify` | 运行时命令、设置钩子、用户配置、捆绑的元数据。 |
| 文档 | `README.md`、`docs/INVENTORY.md`、`docs/QUICKSTART.md` | 当前二进制名称、默认端口、操作列表和环境变量名称。 |
发布不变式：npm 包版本、Rust crate 版本、`server.json.version`、GitHub 发布标签、发布资产名称和 README 安装示例应一起移动。README 示例必须使用规范的仓库和二进制名称，而不是旧别名。
## 开发
```bash
cargo fmt -- --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo build --release
npm --prefix packages/gotify-rmcp run check
```
## 验证
```bash
# 二进制文件和 CLI
cargo build --release
./target/release/rgotify --version
GOTIFY_URL=https://gotify.example.com ./target/release/rgotify health --json
# HTTP 健康状况
GOTIFY_URL=https://gotify.example.com GOTIFY_MCP_HOST=127.0.0.1 ./target/release/rgotify serve
curl -sf http://127.0.0.1:40020/health
# MCP 工具调用
curl -s -X POST http://127.0.0.1:40020/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"gotify","arguments":{"action":"health"}}}'
```
对于实时发送或管理测试，请添加 `GOTIFY_CLIENT_TOKEN` 和 `GOTIFY_APP_TOKEN` 来自您的 Gotify 实例。
## 部署
### Docker / Compose
```bash
cp .env.example .env
$EDITOR .env
docker compose up -d
curl -sf http://127.0.0.1:40020/health
```
容器在 `/data` 下存储应用程序数据，通常映射到 `${HOME}/.gotify`。
### 反向代理
公开 `/mcp` 和 `/health`。保留 Streamable HTTP 头部，强制 TLS，并在使用前配置 bearer 或 OAuth 身份验证以保护服务器。
### 插件
```bash
claude plugin install plugins/gotify
rgotify setup check
```
## 故障排除
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
| 从 `/mcp` 获取 `401` 状态码 | 缺少或错误的 bearer/OAuth token。 | 检查 `GOTIFY_MCP_TOKEN` 和客户端头部信息，或在本地使用循环开发模式。 |
| CLI 健康检查失败 | `GOTIFY_URL` 缺失或无法访问。 | 导出 `GOTIFY_URL` 并确认 Gotify 可以从当前主机访问。 |
| `send` 操作出现身份验证错误 | token 类型错误。 | 使用 `GOTIFY_APP_TOKEN` 进行发送，使用 `GOTIFY_CLIENT_TOKEN` 进行管理。 |
| 破坏性操作被阻止 | 确认门控功能正在工作。 | 添加 `confirm=true`、`--confirm` 或显式的 `GOTIFY_ALLOW_DESTRUCTIVE=true`。 |
| 标准输出 MCP JSON 解析错误 | 日志输出到了标准输出。 | 关闭标准输出的协议日志，并根据需要降低 `RUST_LOG` 日志级别。 |
| npm 启动器无法找到二进制文件 | 发布资产下载失败或被跳过。 | 重新安装，检查 `GOTIFY_RMCP_VERSION`，或从源代码构建 `rgotify`。 |
## 相关服务器
- [soma](https://github.com/jmagar/soma) - 提供商支持的 MCP 服务器的 RMCP 运行时。
- [unifi-rmcp](https://github.com/jmagar/runifi) - UniFi 控制器 REST API 桥接。
- [tailscale-rmcp](https://github.com/jmagar/rtailscale) - 设备、用户和 tailnet 操作的 Tailscale API 桥接。
- [unraid-rmcp](https://github.com/jmagar/runraid) - 用于 NAS 和服务器管理的 Unraid GraphQL 桥接。
- [apprise-rmcp](https://github.com/jmagar/rapprise) - 用于多个投递后端的信息通知扇出桥接。
- [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) - 用于侦察和 flux 操作的本地 Synapse 工作流服务器。
- [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/RUST.md`](docs/RUST.md) - Rust 开发笔记。
- [`docs/stack/ARCH.md`](docs/stack/ARCH.md) - 栈架构细节。
- [`server.json`](server.json) - MCP 注册表元数据。
- [`packages/gotify-rmcp/README.md`](packages/gotify-rmcp/README.md) - npm 包启动器笔记。
本 README 是精选的。生成的或详尽的目录应在其各自的文件中刷新，并视为当前分支详情的真实来源。
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器