Arcane RMCP

arcane-rmcp

通过 MCP 和 CLI 管理 Arcane Docker 与 Compose，支持经过身份验证的 stdio 和 HTTP。

它提供一个 MCP 工具 arcane，以及 rarcane CLI。Agent 可以通过 stdio MCP、Streamable HTTP MCP 或直接执行 shell 命令，检查 Arcane 环境，管理 Compose 项目、容器、镜像、网络、卷、注册表、GitOps 同步、镜像更新、漏洞发现结果和系统操作。

**30 秒快速上手：**设置 RARCANE_API_URL 和 RARCANE_API_KEY，然后运行 npx -y @dinglebear/rarcane status -> 启动环回 HTTP 服务： RARCANE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rarcane serve -> 使用 {"action":"status"} 调用 tools/call。

**状态：**可运行的 RMCP 上游客户端服务。支持写入；破坏性 Docker 和 Arcane 操作需要明确确认。HTTP MCP 支持环回开发模式、静态承载令牌，以及通过 lab-auth 进行 Google OAuth。

**不适用于：**替代 Arcane、绕过 Docker 或 Arcane 授权、运行任意 shell 命令、存储注册表或 Git 凭据、实现多租户隔离，或通过 MCP 工具参数传递 Arcane API 密钥。

目录

• 命名
• 功能与边界
• 安装
• 快速入门
• 客户端配置
• 运行时接口
• MCP 工具参考
• CLI 参考
• 配置
• 身份验证
• 安全与信任模型
• 架构
• 分发约定
• 开发
• 验证
• 部署
• 故障排除
• 相关服务
• 文档
• 许可证

命名

接口	本仓库
仓库	arcane-rmcp
Rust crate	rarcane
二进制文件 / CLI	rarcane
npm 包	@dinglebear/rarcane
npm 二进制别名	rarcane
MCP 服务名称	捆绑的插件 / 客户端配置中为 rarcane
MCP 工具	arcane
配置目录	主机上为 ~/.rarcane，容器中为 /data
环境变量前缀	RARCANE_*、RARCANE_MCP_*、RARCANE_RMCP_*（用于 npm 启动器控制）

仓库和 npm 包使用上游服务名称，而发布的二进制文件保留了历史 Rust CLI 名称 rarcane。MCP 服务可以注册为 rarcane，但客户端调用的工具名是 arcane。

功能与边界

• 读取 Arcane 状态，以及 Docker 环境、项目、容器、镜像、网络、卷、注册表、GitOps、更新、漏洞和系统状态。
• 通过 action/subaction 分发机制，创建、更新、启动、停止、重启、删除、清理、部署、同步、扫描和备份受支持的 Arcane 资源。
• 在将写入操作转发给 Arcane 之前，强制执行操作范围检查，并要求确认破坏性操作。
• 提供 quick_start 提示词和 rarcane://schema/mcp-tool 资源，供客户端发现。
• 提供 setup、doctor 和 watch 命令，用于本地插件 / 运行时检查。

本仓库负责	Arcane 负责	明确不在范围内
MCP/CLI 映射、请求验证、身份验证策略、响应格式化、安装检查、架构 / 资源公开，以及破坏性操作拦截。	Docker 状态、Arcane 项目和环境、上游授权、注册表凭据、GitOps 密钥、漏洞扫描器输出，以及 API 语义。	直接访问 Docker socket、执行 shell 命令、存储凭据、通用 REST 代理行为、多租户沙箱、调度器行为，以及替代 Arcane UI/API。

安装

路径	命令	适用场景	备注
npm / npx	npx -y @dinglebear/rarcane --help	本地 MCP 客户端和快速试用。	从 GitHub Releases 下载匹配的 rarcane 二进制文件。
发布版安装程序	curl -fsSL https://raw.githubusercontent.com/dinglebear-ai/rarcane/main/scripts/install.sh | bash	无需 Node 的主机安装。	为当前 Linux 主机安装 rarcane。
Docker / Compose	docker compose up -d	共享 HTTP MCP 部署。	读取 .env 并公开容器端口 40110。
从源代码构建	cargo build --release	开发和审计。	生成 target/release/rarcane。
插件	claude plugin install plugins/rarcane	从此检出版本设置 Claude Code 本地插件。	使用打包的技能和监控元数据。插件不附带生命周期钩子——安装后运行一次 rarcane setup repair。

npm / npx

无需手动安装二进制文件，即可运行 stdio MCP 服务或 CLI：

npx -y @dinglebear/rarcane --help
npx -y @dinglebear/rarcane mcp
npx -y @dinglebear/rarcane status

npm 包会在 postinstall 期间下载 rarcane。仅在测试打包时覆盖下载行为：

变量	用途
RARCANE_RMCP_SKIP_DOWNLOAD=1	跳过 postinstall 二进制文件下载。
RARCANE_RMCP_VERSION or RARCANE_RMCP_BINARY_VERSION	选择 GitHub Release 标签。
RARCANE_RMCP_REPO	选择用于下载发布版本的 GitHub 仓库。
RARCANE_RMCP_RELEASE_BASE_URL	选择自定义发布版本基础 URL。

从源代码构建

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

最低支持的 Rust 版本：1.90。

快速入门

1. 配置 Arcane

将桥接程序指向现有的 Arcane API 服务：

export RARCANE_API_URL=https://arcane.example.com
export RARCANE_API_KEY=...

API 密钥仅从环境变量或配置中读取。请勿在 MCP 工具参数或 CLI --params-json 中传入该密钥。

2. 运行安全的 CLI 调用

npx -y @dinglebear/rarcane status

3. 启动回环 HTTP MCP

RARCANE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rarcane serve

在另一个 shell 中：

curl -sf http://127.0.0.1:40110/health

4. 进行首次 MCP 调用

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

客户端配置

Claude Code Stdio

{
  "mcpServers": {
    "rarcane": {
      "command": "npx",
      "args": ["-y", "arcane-rmcp", "mcp"],
      "env": {
        "RARCANE_API_URL": "https://arcane.example.com",
        "RARCANE_API_KEY": "..."
      }
    }
  }
}

Claude Code HTTP

{
  "mcpServers": {
    "rarcane": {
      "type": "http",
      "url": "http://127.0.0.1:40110/mcp",
      "headers": {
        "Authorization": "Bearer ${RARCANE_MCP_TOKEN}"
      }
    }
  }
}

Codex / Labby 网关

需要共享一个长期运行的服务时，通过 Labby 将 Arcane 注册为 HTTP 上游；仅供本地使用时，则直接以 stdio 方式运行。

[mcp_servers.rarcane]
command = "npx"
args = ["-y", "arcane-rmcp", "mcp"]

通用 MCP JSON

{
  "command": "rarcane",
  "args": ["mcp"],
  "env": {
    "RARCANE_API_URL": "https://arcane.example.com"
  }
}

请勿将 RARCANE_API_KEY、注册表凭据、Git 凭据、OAuth 密钥、SSH 密钥、密码或上游 bearer 令牌放入 MCP 工具参数中。请使用环境变量、配置文件或 MCP 客户端的密钥存储。 MCP 调用方绝不会将凭据、令牌、密钥或机密作为操作参数提供。

运行时接口

接口	状态	入口点	用途
MCP stdio	支持	rarcane mcp、npx -y @dinglebear/rarcane mcp	本地子进程 MCP 客户端。
MCP HTTP	支持	rarcane serve、POST /mcp	面向本地或共享服务部署的可流式 HTTP MCP。
CLI	支持	rarcane <command>	可编写脚本的功能对等接口和调试工具。
提示词	支持	quick_start	引导客户端使用 status 和公开的 help。
资源	支持	rarcane://schema/mcp-tool	arcane 工具的 JSON 架构。
REST API	未提供	N/A	Arcane 已提供 REST API。
Web UI	未提供	N/A	Arcane 已提供 Web UI。

MCP 工具参考

公开了一个 MCP 工具：arcane。传入必需的 action 参数，并且对于 大多数领域，还需要传入必需的 subaction。

操作	常见子操作	范围
help	操作参考或特定领域的帮助	public
status	本地桥接和 Arcane 配置状态	rarcane:read
elicit_name	MCP 引导示例	rarcane:read
scaffold_intent	无副作用的脚手架规划移交	rarcane:read
environment	list、get、create、update、delete、test	读/写
project	list、get、create、update、up、down、restart、pull、destroy、redeploy、build	读/写
container	list、get、create、start、stop、restart、update、delete、stats	读/写
image	list、get、pull、delete、prune、scan	读/写
network	list、get、create、delete、prune	读/写
volume	list、get、create、delete、prune、browse、list-backups、create-backup、delete-backup、restore、restore-files	读/写
system	docker-info、prune、start-all、stop-all、convert	读/写
image-update	check-all、check、check-batch、summary	读
vulnerability	summary、list、scanner-status、ignore、unignore、list-ignored	读/写
registry	list、get、create、update、delete、test	读/写
gitops	list、get、create、update、delete、sync、status、browse	读/写

src/actions.rs 中的操作规范和 docs/MCP_SCHEMA.md 中生成的架构说明是必需参数的权威依据。

只读工具参数示例：

{
  "action": "container",
  "subaction": "list",
  "envId": "default"
}

破坏性操作示例：

{
  "action": "container",
  "subaction": "stop",
  "envId": "default",
  "id": "my-container",
  "params": {
    "confirm": true
  }
}

命令行参考

rarcane 暴露与 MCP 工具相同的服务层：

rarcane status
rarcane help --domain container
rarcane call --action container --subaction list --env-id default
rarcane call --action system --subaction docker-info --env-id default
rarcane call --action container --subaction stop --env-id default --id my-container --confirm
rarcane doctor --json
rarcane watch --url http://127.0.0.1:40110
rarcane setup check
rarcane setup repair

--params-json 接受特定操作的 JSON 载荷。请勿使用它传递凭据。

配置

主机安装会读取 ~/.rarcane/.env、~/.rarcane/config.toml 和进程环境变量。 容器会读取 /data/.env、/data/config.toml 和进程环境变量。

变量	默认值	用途
RARCANE_API_URL	未设置	Arcane API 基础 URL。
RARCANE_API_KEY	未设置	Arcane API 密钥或 bearer 令牌。
RARCANE_MCP_HOST	127.0.0.1	HTTP 绑定主机。
RARCANE_MCP_PORT	40110	HTTP 绑定端口。
RARCANE_MCP_SERVER_NAME	arcane-rmcp	公告的 MCP 服务名称。
RARCANE_MCP_TOKEN	未设置	用于 HTTP MCP 的静态 bearer 令牌。
RARCANE_MCP_NO_AUTH	false	仅在回环开发环境中禁用身份验证。
RARCANE_NOAUTH	false	信任上游网关执行身份验证。
RARCANE_MCP_ALLOWED_HOSTS	未设置	额外接受的 Host 标头值。
RARCANE_MCP_ALLOWED_ORIGINS	未设置	额外接受的 CORS 来源。
RARCANE_MCP_PUBLIC_URL	未设置	OAuth 颁发者元数据的公共基础 URL。
RARCANE_MCP_AUTH_MODE	bearer	bearer 或 oauth。
RARCANE_MCP_ALLOW_DESTRUCTIVE	false	绕过每次调用的破坏性操作确认门。请勿在共享部署中设置。
RARCANE_HOME	~/.rarcane	配置/应用数据根目录覆盖值。
RUST_LOG	info	日志过滤器。

身份验证

Stdio MCP 作为本地可信子进程运行，不使用 HTTP 身份验证。

HTTP MCP 身份验证策略：

状态	条件	行为
回环开发	绑定到 127.0.0.1、localhost 或 [::1]	允许本地免身份验证开发。
已挂载 Bearer	非回环地址，且设置了 RARCANE_MCP_TOKEN	需要 Authorization: Bearer <token> 和操作范围。
已挂载 OAuth	RARCANE_MCP_AUTH_MODE=oauth	通过 lab-auth 使用 Google OAuth/JWT；仍支持静态 Bearer。
可信网关	RARCANE_NOAUTH=true	假定反向代理或网关已执行身份验证。

OAuth 模式使用 docs/CONFIG.md 中说明的 RARCANE_MCP_* Google OAuth 变量。

OAuth 模式为单副本模式：客户端/会话状态和签名密钥仅存储在一台主机上。在这些存储外置或能够安全共享之前，请勿运行多个 OAuth 副本。

安全与信任模型

• Arcane API 凭据仅从配置/环境变量加载。
• MCP 调用方选择操作和负载，而非上游凭据。
• 除非存在 params.confirm=true 或 CLI --confirm，否则会拒绝破坏性子操作。
• 未知操作、未知子操作、缺少环境 ID、缺少 ID，以及不安全的卷路径，都会在调用上游之前被拒绝。
• 非回环 HTTP 部署必须使用 Bearer 身份验证、OAuth，或可信的已验证身份网关。
• 此桥接不会对 Arcane 本身进行沙箱隔离。Docker 授权和 Docker 操作的影响仍由 Arcane 负责。

架构

ArcaneClient  (src/arcane.rs)      HTTP transport and redacted errors
      |
ArcaneService (src/app.rs)         action validation, confirmation, response normalization
      |
MCP shim      (src/mcp/tools.rs)   JSON args -> service -> Value
CLI shim      (src/cli.rs)         argv -> service -> stdout

分发约定

• Cargo.toml、Cargo.lock、packages/arcane-rmcp/package.json、.release-please-manifest.json 和 server.json 中的发布版本必须一致。
• GitHub Releases 会发布供 npm 启动器使用的 rarcane 二进制文件。
• npm 包名称为 @dinglebear/rarcane；安装后的二进制别名为 rarcane。
• Docker/OCI 元数据使用 ghcr.io/dinglebear-ai/rarcane:<version>。
• plugins/rarcane/.mcp.json 必须启动 npx -y @dinglebear/rarcane mcp，以便 stdio 客户端启动 MCP 传输，而非 HTTP 服务。
• 根目录 README 经过人工整理。生成的详细信息或权威来源位于 src/actions.rs、docs/MCP_SCHEMA.md 以及包/注册表清单中。

开发

cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo build --release
npm --prefix packages/arcane-rmcp run check

验证

just verify                 # fmt-check → lint → check → test
just template-check         # patterns, plugin layout, schema docs, scaffold contract
npm --prefix packages/arcane-rmcp run check
git diff --check

运行时冒烟测试：

RARCANE_API_URL=https://arcane.example.com \
RARCANE_API_KEY=... \
rarcane status

HTTP 冒烟测试：

RARCANE_MCP_HOST=127.0.0.1 rarcane serve
curl -sf http://127.0.0.1:40110/health

部署

本地开发请使用回环地址：

RARCANE_MCP_HOST=127.0.0.1 rarcane serve

共享 HTTP 部署请使用 Docker Compose：

cp .env.example .env
docker compose up -d

绑定到非回环地址时，请配置 RARCANE_MCP_TOKEN、RARCANE_MCP_AUTH_MODE=oauth，或在已验证身份的网关之后设置 RARCANE_NOAUTH=true。

故障排除

症状	检查
RARCANE_API_URL is required	在环境变量或 ~/.rarcane/.env 中设置 RARCANE_API_URL。
Arcane 调用返回未授权	在 Arcane 中刷新 RARCANE_API_KEY，然后重启桥接程序。
HTTP /mcp 返回未授权	设置 RARCANE_MCP_TOKEN，并发送 Authorization: Bearer <token>。
Stdio 客户端挂起或记录 JSON 错误	确保客户端配置运行 arcane-rmcp mcp，而不是默认的 HTTP 服务模式。
破坏性操作被拒绝	验证目标后，添加 CLI --confirm 或 MCP params.confirm=true。
端口冲突	设置 RARCANE_MCP_PORT，或停止已占用 40110 的进程。

相关服务

• soma - 面向由提供方支持的 MCP 服务的 RMCP 运行时。
• unifi-rmcp - UniFi 控制器 REST API 桥接工具。
• tailscale-rmcp - 面向设备、用户和 tailnet 操作的 Tailscale API 桥接工具。
• unraid - 面向 NAS 和服务管理的 Unraid GraphQL 桥接工具。
• apprise-rmcp - 面向多种投递后端的 Apprise 通知分发桥接工具。
• gotify-rmcp - 面向发送通知、消息、应用和客户端的 Gotify 推送通知桥接工具。
• yarr - 面向 Sonarr、Radarr、Prowlarr、Plex 及相关服务的媒体栈桥接工具。
• ytdl-rmcp - 媒体下载和元数据工作流服务。
• synapse-rmcp - 面向 scout 和 flux 操作的本地 Synapse 工作流服务。
• cortex - Syslog 和家庭实验室日志聚合 MCP 服务。
• axon - RAG、爬取、抓取、提取和语义搜索项目。
• labby - 家庭实验室控制平面和 MCP 网关项目。
• lumen - 本地语义代码搜索 MCP 服务。

文档

• docs/API.md 是精选的操作契约概览。
• docs/CONFIG.md 是精选的配置和身份验证参考。
• docs/QUICKSTART.md 是精选的冒烟测试指南。
• docs/MCP_SCHEMA.md 是面向操作、资源、提示词和验证规则的生成式／架构漂移契约。
• plugins/rarcane/skills/rarcane/SKILL.md 是 Agent 使用指南。

许可证

本项目中由 Dinglebear 创作的部分依据 AGPL-3.0-only 许可。对于需要 AGPL 以外条款的组织，可提供单独的商业许可。第三方材料仍遵循其原始许可证。请参阅 LICENSING.md。