yarr

yarr 用于媒体自动化舰队的 Rust MCP 和 CLI 服务器：Sonarr、、Prowlarr、Tautulli、Overseerr、Bazarr、Tracearr、SABnzbd、qBittorrent、Plex 和 Jellyfin。 如果您在自托管的媒体栈上运行 Claude Code、Codex 或 Gemini CLI，`yarr` 为代理提供了一种一致的方式来查询和控制所有这些服务，而不是使用 11 种不同的临时集成。它是一个上游客户端 MCP 服务器：它不会替换这些应用程序或将每个 REST 端点镜像为 Web UI。是为代理和操作员提供一个一致的工具表面和一个等效的 CLI 表面。 **不适用于：** 通用 REST 网关到任意服务，或调度/自动化引擎。`yarr` 只与它知道的服务类型通信，并且只执行您或您的代理要求它执行的操作。 ## 目录 - [命名](#命名) - [功能和边界](#功能和边界) - [安装](#安装) - [快速入门](#快速入门) - [客户端配置](#客户端配置) - [运行时界面](#运行时界面) - [MCP 工具参考](#mcp-工具参考) - [CLI 参考](#cli-参考) - [配置](#配置) - [身份验证](#身份验证) - [安全性和信任模型](#安全性和信任模型) - [架构](#架构) - [分发合约](#分发合约) - [开发](#开发) - [验证](#验证) - [部署](#部署) - [故障排除](#故障排除) - [相关服务器](#相关服务器) - [文档](#文档) - [许可证](#许可证) ## 命名 该存储库发布在 `github.com/jmagar/yarr`。 Rust 包和安装的二进制文件都是 `yarr`。npm 启动器包是 `yarr-mcp`，因为较短的 `yarr` 名称在 npm 上被占用；安装启动器仍然为您提供 `yarr` 命令。MCP 注册表 `ai.dinglebear/yarr-mcp`，镜像使用 `ghcr.io/jmagar/yarr`。生产 Compose 部署通过不可变清单摘要选择该镜像。 插件命名故意拆分： - `y完整的 MCP 服务器插件。它启动与存储库yarr-mcp` npm 包，跨 stdio，并包括每个服务回退技能；它不提交平台的二进制文件。 - `sonarr`、`radarr`、`prow、`overseerr`、`sabnzbd`、`qbittorrent`、`plex`、`jellyfintautulli`、`tracearr` 和 `bazarr` 是仅限技能的插件，没有 MCP 服务器和捆绑二进制文件。 ## 功能和边界 `yarr` 通过一个动作调度服务层包装一个配置的媒体自动化舰队。相同的实现支持 MCP 和 CLI 调用，因此行为在“代理使用工具”和“操作员运行命令”之间不会偏移： - 跨配置服务进行舰队状态检查。 - 已知服务类型的凭证上游 API 直通。 - Sonarr、Radarr、Prowlarr、Overseerr、Jellyfin 和 Plex 的表驱动 OpenAPI 操作元数据器保留声明的参数、请求媒体和成功的响应传输契约；不支持的行被排除并在生成的[功能矩阵](docs/TOOLS_ACTIONS_ENDPOINTS.md#generated-operations-spec-backed-services)中列出。 - SABnzbd、qBittorrent、Tautulli、Bazarr 和 Tracearr 的精选命令，其上游不提供可用的机器可读规范。 - 跨 MCP 的 Code Mode，用于多步骤媒体自动化脚本。 - 可重复使用的 Code Mode 工作流的片段存储和执行。 - 每个服务的技能直接 HTTP 插件回退。 边界： - `yarr` 不会自行存储或调度媒体作业。 - 它不会公开本地 REST 操作 API 或嵌入式 Web UI。 - 它不接受任意未知的服务类型。 - MCP 调用者永远不会提供凭证、令牌、密钥或机密作为操作参数。凭证来自环境变量、配置文件或严格的每个服务插件配置 JSON。 ## 安装 推荐的安装路径是 Node 启动器包： ```bash # 在不永久安装的情况下运行 stdio MCP 服务器。 npx -y yarr-mcp mcp # 或全局安装启动器。 npm i -g yarr-mcp yarr --yarr mcpnpm 包在安装期间下载匹配的 GitHub Release 二进制文件，并将 `y 添加到`。它不留命令别名。 npm 的使用发布安装程序： ```bash curl -fsSL https://rawmagar/yarr/main/install.sh |``` 该脚本将 `yarr` 安装到/.local/bin`。 快速入门 第一个屏幕 30 秒路径是： ```bash YARR_SERVICES=sonarr export YONARR_URL=http://127.0.0.1:8989 YARR_SONARR_API_KEY=... npx -y yarr-mcp sonarr status npx -y yarr-mcp mcp ``` 然后将 MCP 客户端指向 stdio 命令： ```json { "mcpServers": { "yarr": { "command": "npx", " ["-y", "yarr-mcp", "mcp"], "env": { "YARR_SERVICES": "sonarr", "YARR_SONARR_URL": "http://127.0.0.1:8989", "YARR_S_API_KEY": "${YARR_SONARR_API_KEY}" } } } } ``` 对于 Claude Code 插件安装，在 Claude Code 聊天会话中使用市场命令，而不是在 shell 中： ```text /plugin marketplace add jmagar/yarr /plugin install yarr@yarr ``` 安装一个仅限技能的插件，当您想要直接服务脚本而无需 MCP 服务器时： ```text /plugin install sonarr@yarr /plugin install plex@yarr ``` ## 客户端配置 ### stdio stdio 是的本地 MCP 传输。它按需启动 `yarr mcp`，无需绑定本地 HTTP 端口。 ```json { "mcpServers": { "yarr": { "command": "yarr "args": ["mcp"], " "RUST_LOG": "info,yarr=debug" } } ``` ### 可流式 HTTP 运行一个持久的服务器，以便多个客户端或机器应该共享一个 MCP 端点： ```bash YARR_MCP_TOKEN=change-me yarr serve ``` ```json { "mcpServers": { "yarr": { "url": "http://127.0.0.1:40070/mcp", "headers": { ": "Bearer ${YARR_MCP_TOKEN}" } } } } ``` HTTP MCP 烟雾测试： ```bash curl -s http://127.0.1:40070/mcp \ -H "Authorization: Bearer $YARR_MCP_TOKEN" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"yarr","arguments":{"code":"async () => await sonarr.get_system_status()"}}}' ``` ## 运行时界面 | 界面 | 状态 | 目的 | | --- | ---: | --- | | MCP | 必需 | 整个舰队的默认 `yarr` Code Mode 工具 | | CLI | 必需 | 用于调试和自动化的可脚本化奇偶校验表面 | | REST | 不提供 | 上游客户端服务器不公开本地 REST 操作 API | | Web | 不提供 | 上游客户端服务器不提供嵌入式 Web UI | 设置 `YARR_MCP_TOOL_MODE=flat` 以宣传每个配置服务的单独操作调度工具，而不是单个 Code Mode 工具。在 Labby 等网关后面，此模式很有用，Labby 已经提供了自己的发现和沙盒层。`codemode` 是默认选择，适用于独立的 MCP 客户端。 ## MCP 工具参考 默认情况下，MCP 公开一个名为 `yarr` 的工具。 | 字段 | 类型 | 必需 | 备注 | | --- | --- | ---: | --- | | `code` | 字符串 | 是 | 在进程内 Code Mode 沙盒中执行的 JavaScript 异步箭头函数 | 在 Code Mode 中，脚本可以使用： - 每项服务的可调用函数，如 `sonarr.get_series()`、`radarr.post_movie({ body })`、`prowlarr.get_indexer()` 和 `plex.get_sessions()`。 - 精选命令，如 `qbittorrent.download_queue()` 和 `tautulli.stats_activity()`。 - 原始直通助手 `api.<service>.get/post/put/delete(path, body)`。 - `callTool(action, params)` 用于底层操作调度逃生口。 - `codemode.search(query)` 和 `codemode.describe(path)` 用于发现。 - `codemode.run(name, input)`、`codemode.snippets()` 和 `writeArtifact(...)` 用于可重复使用的脚本和工件。 生成的可调用函数来自元数据表。它们保留方法/路径、所需路径参数、已知查询名称、JSON 正文存在和有界单文件 multipart 转义舱口。它们不强制执行每个所需查询、标头/cookie 参数、样式/爆炸规则、表单类型或响应架构。请在依赖生成的操作用于非 JSON 或序列化点之前参阅 `docs/API.md`。 ```js => { const queue = await radarr.get_queue(); await radarr.post_command({ body: { name: "MoviesIds: [456] } }); return { queued: queue.records?.length }; } ``` ### 通用操作 这些操作适用于每种配置类型： | 操作 | 范围 | CLI | | --- | --- | --- | --- | | `service_status` | `yarr:read` | `yarr <service> status` | 获取上游服务状态端点 | | `api_get` | `yarr:write` | `yarr <service> get --path <path>` | 代理一个认证的 GET 请求 | | `api_post` | `yarr:write` | `yservice> post --path <path> --body <json>` | 代理一个 POST 请求 | |_put` | `yarr:write`yarr <service> put --path <path> --body <json>` | 代理一个 PUT 请求 | | `api_delete` | `yarr:write` | `yarr delete --path <path>` | DELETE 请求 | | `help` | 公共 | `yarr help` | 返回操作参考 | ### Code Mode 操作 | 操作 | 范围 | 界面 | 描述 | | --- | --- | --- | --- | | `codemode` | `yarr:write` | `yarr` 工具 / `yarr codemode --code <JS>` | 在舰队上运行一个 JS 箭头函数 | ` | `yarr:write` | `<service>.<operation>()yarr <service> op <name>`度一个生成的 OpenAPI 操作 | | `snippet_list` | `yarr:read` | `yarr snippet list` / `codemode.snippets()` | 列出已保存的片段 | | `snippet_save` | `yarr:write` | `yarr snippet save` | 保存一个可重复使用的片段 | | `snippet_run` | `yarr:write` | `yarr snippet run` / `codemode.run(name, input)` | 运行一个已保存的片段 | | `snippet_delete` | `yarr:write` | `yarr | 删除一个的片段 | 没有` 参数。CLI 破坏性命令立即MCP 直接和嵌套 Code Mode 破坏性调用需要诱导，如果对等方无法诱导或未授予批准。 ## CLI 参考 CLI 按服务分组： ```bash y yarr radarr status yarr get --path /api/v3/system/status radarr post --path /api/v3body '{"name":""}' yarr sonarr put --path /api/v3/series/editor --body '{"seriesIds":[1],"qualityProfileId":4}' yarr delete --path /api/v3/movie/12 # 为支持规范的服务生成操作。 sonarr op get_series yarr radarr op post_command --body":{"name":"MoviesSearch","movieIds":[456]}}' # 为仅限文档的服务提供精选命令。 yarr qbittorrent queue yarr tautulli activity # Code Mode 和片段。 yarr codemode --code 'async () => sonarr.get_system_status()' snippet list ``` 没有 `--service` 标志。诸如 `help`、`codemode` 和 `snippet` 之类的基础设施命令是无服务的。 ## 配置 复制 `.env.example` 或使用 `config.example.toml` 作为起点。常见的环境变量： ```bash YARR_MCP_HOST=127.0.0.1 YARR_MCP_PORT=40070 YARR_MCP_TOKEN=change-me YARR_SERVICES=sonarr,radarr,prowlarr,tautulli,overseerr,bazarr,tracearr,sabnzbd,,plex,jellyfin YARR_SONARR_URL=http://sonarr:8989 _SONARR_API_KEY=... YARR_RADARR_URL=http://radarr:7878 YARR_RADARR_API_KEY=... YARR_QBITTORRENT_URL=http://qbittorrent:8080 YARR_QBITTORRENT_USERNAMEYARR_QBITTORRENT_PASSWORD=... YARR_PLEX_URL=http://plex:32400 YARR_PLEX_TOKEN=... ``` 支持的服务类型有 `sonarr`、`radarr`、`prowlarr`、`tautulli`erseerr`、`bazarr`、`tracearr`、`sab、`qbittorrent`、`plex` 和 `jellyfin`。 `*_API_KEY` 涵盖大多数 Arr 式服务。qBittorrent 使用用户名/密码登录。Plex 和 Jellyfin 令牌标头分别处理YARR_MCP_TOOL_MODE=codemode` 是默认的。只有当网关应该看到单独的每个服务工具时，才使用 `YARR_MCP_TOOL_MODE=flat`。 ## 身份验证 `YARR_MCP_TOKEN` 认证 `/mcp` 并接收只读 `yarr:read` 范围。在 `127.0.0 或 `localhost` 上，如果没有显式，则身份验证被绕过，以进行本地开发。设置一个真实的令牌，或在将此令牌暴露在网络上之前设置 `YARR_MCP_AUTH_MODE= 以进行 Google身份验证状态： | 状态 | 条件 | 行为 | | --- | --- | --- | | `Dev` | 环回绑定或显式环回无身份验证 | 无身份验证，无范围 | | `TrustedGatewayUnscoped` | 受信任的后面的 `YARR_NOAUTH=true` | 无本地身份验证或范围 | |` 持有 非环回，带有 `YCP_TOKEN`持有者身份验证，范围检查只读 | | | `Mounted` OAuth | `YARR_MCP_AUTH_MODE=oauth` | OAuth/JWT 身份验证和范围检查 | 未经身份健康检查端 `/health `ready`、`status` 和 `/metrics`。`/status` 会抹去机密；`/metrics` 公开 HTTP 和有界域度量标准，当需要时网络。 ## 安全性和信任模型 机密保留在服务器端。MCP 客户端提供操作参数，而非上游令牌。查询字符串机密（例如 `apikey=`、`token=` 和 `X-Plex-Token`）被路径验证拒绝` 在操作层面上是公开的，但已安装的 HTTP 需要持有者或 OAuth 传输身份验证。`service_status` 需要 `yarr:read`。凭证直通、生成的操作、精选的和 Code Modeyarr:；写入满足生成的 DELETE 操作、``、`download_remove`、`stats_delete` 和 `trace_terminate_stream` 是破坏性的。CLI 命令它们。M者在实际调度交互式诱导提示，包括 Code Mode 内部的提示，没有调用参数或嵌套的 `callTool` 路径过它。 响应在返回给 MCP 客户端之前由共享的令牌限制层限制。 架构 ```MCP shim (src/mcp/tools.rs) CLI shim (src/cli.rs) JSON args -> dispatch argv -> dispatch \ / execute_service_action (src/actions/dispatch.rs) + curated-command dispatch | Ysrc/app src/app/*. validation, service lookup, response shaping | YarrClient (src/yarr.rs) network calls and auth headers ``` `src/mcp.rs` 和 `src/cli.rs` 是薄薄的 facade，重新导出它们自己的子模块。`execute_service_action` 使 CLI 到 MCP 的奇偶校验结构更为结构化，而不是通过手动保持同步。 服务层拥有： - 支持的服务目录和配置查找 - 安全路径验证 - 凭证隐藏 qBittorrent 登录- 响应规范化 ## 分发合约 发布的是 `Cargo.toml`、``、`xtask/Cargo.tomlrelease-please-manifest.jsonpackages/yarr-mcp/package.json` 和 `server.json` 共享的版本。 生成的代码和文档必须从提交的源输入重新生成，而不是手动修补： - 生成的 OpenAPI 操作位于 `src/openapi/generated/` 下，来自 `/` 中的供应商规格。 - 精选操作位于手工编写的操作注册文档中。 - 插件清单保持无版本；市场从 git 派生插件版本。 包版本和 GitHub 发布匹配。 - `server.json` 必须命名确切的 `yarr-mcp` npm 版本和 stdio 启动合约下的 `ai.dinglebear/yarr-mcp` 注册表身份。 - Docker 镜像路径是 `ghcr.io/jmagar/yarr`；生产部署使用提升的不可变 `@sha256=` 摘要。 ## 开发bash cargo run -- help cargo fmt --check cargo test cargo clippy -- -D warnings cargo build --release ``` 当更改生成的操作时： cargo xtask gen-openapi ask tool-docs cargo test --test parity ``` 当更改插件打包时： ```bash cargo test --test plugin_contract cargo test --test template_invariants ``` ## 验证 在着陆文档更改之前，使用 README 指南检查器： ```bash python3 /home/jmagar/workspace/soma/scripts/check-readme-guide.py README.md ``` 对于分发敏感的工作，使用和 Rust 检查： ```bash npm --prefix packages/ycp run check cargo fmt --check cargo check cargo test git diff --check对于实时安装验证，请使用三个公共安装路径： ```bash curl -fsSL https://raw.githubusercontent.com/jmagarr/main/install.sh | bash npm i -g yarr npx -y yarr mcp ``` 部署 作为持久的 HTTP MCP 服务器运行： ```bash YARR_MCP_HOST0.0 \ YARR_PORT=40070ARR_MCP_TOKEN= \ yarr serve Compose 部署由 `docker`、`docker-compose.prod.ymldocs/DOCKER.md` 和/DEPLOYMENT.md涵盖。生产部署应yarr` 置于受反向代理或 MCP 网，当其暴露在环回之外## 故障排除 - 来自 HTTP MCP 的 `401``：确认 `YARR_TOKEN`、OAuth 模式关标头。 - ``：确认服务在 `YICES` 中列出并的 `YARR_<SERVICE>_。 - 上游 `401确认服务器环境中的服务特定密钥或令牌，而不是在工具- `query-string secret rejected`：从 `--path` 中牌并将其放入配置中。 插件技能无法访问服务：钩子或重新，以便在 `~/.configservice>/config.json` 下刷新其每个服务配置 JSON。 Mode 找不到可调用函数 `codemode.search(...)` 和 `codemode.describe(...)`；生成的规范化后的上游 Open ID。 ## 相关服务器 - [soma](https://github.com/jmagar/soma) - 提供商支持的MCP服务器的RMCP运行时。 - [unifi-rmcp](https://github.com/jmagar/unifi-rmcp) - UniFi控制器REST API桥接器。 - [tailscale-rmcp](https://github.com/jmagar/tailscale-rmcp) - 设备、用户和尾网操作的Tailscale API桥接器。 - [unraid-rmcp](https://github.com/jmagar/unraid-rmcp) - 用于NAS和服务器管理的Unraid GraphQL桥接器。 - [apprise-rmcp](https://github.com/jmagar/apprise-rmcp) - 多个投递后端的大通知分发桥接器。 - [gotify-rmcp](https://github.com/jmagar/gotify-rmcp) - 用于发送、消息、应用程序和客户端的Gotify推送通知桥接器。 - [arcane-rmcp](https://github.com/jmagar/arcane-rmcp) - 用于容器和相关资源的Arcane Docker管理桥接器。 - [ytdl-rmcp](https://github.com/jmagar/ytdl-rmcp) - 媒体下载和元数据工作流服务器。 - [synapse-rmcp](https://github.com/jmagar/synapse-rmcp) - 用于侦察和通量操作的本地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/API.md` - 操作合约和代码模式调用形状。 - `docs/CONFIG.md` - 环境变量、身份验证状态和工具模式。 - `docs/QUICKSTART.md` - 本地烟雾测试。 - `docs/MCP_SCHEMA.md` - 模式漂移规则。 - `docs/AUTH.md` - 持有者和OAuth身份验证。 - `docs/DEPLOYMENT.md` 和 `docs/DOCKER.md` - 生产运行时。 - `docs/PATTERNS.md` - RMCP服务器家族中共享的约定。 - `docs/PLUGINS.md` - 市场插件打包。 - `plugins/README.md` - `yarr`包与每个服务插件布局的比较。 - `plugins/yarr/README.md` 和 `plugins/yarr/skills/yarr/SKILL.md` - 完整的插件包。 - `CLAUDE.md` - 仓库本地代理内存和“如何添加操作”的检查清单。 ## 许可证 [MIT](LICENSE)