内容
# 秘术-rmcp
`arcane-rmcp` 是一个用 Rust 编写的 MCP 服务器和 CLI，用于通过 [Arcane](https://github.com/ofkm/arcane) API 服务器管理 Docker。
它暴露了一个 MCP 工具 `arcane`，以及 `rarcane` CLI。代理可以通过 stdio MCP、Streamable HTTP MCP 或直接 shell 命令检查 Arcane 环境、管理 compose 项目、容器、镜像、网络、卷、注册表、GitOps 同步、镜像更新、漏洞发现和系统操作。
**30 秒路径：** 设置 `RARCANE_API_URL` 和 `RARCANE_API_KEY`，然后运行 `npx -y arcane-rmcp status` -> 使用 `RARCANE_MCP_HOST=127.0.0.1 npx -y arcane-rmcp serve` 启动回环 HTTP -> 调用 `tools/call`，传递 `{"action":"status"}`。
**状态：** 操作的 RMCP 上游客户端服务器。可写入；破坏性 Docker 和 Arcane 操作需要显式确认。HTTP MCP 支持回环开发模式、静态持有者令牌和通过 `lab-auth` 的 Google OAuth。
**不适用于：** 替换 Arcane、绕过 Docker 或 Arcane 授权、运行任意 shell 命令、存储注册表或 Git 凭证、多租户隔离或通过 MCP 工具参数传递 Arcane API 密钥。
## 目录
- [命名](#命名)
- [功能和边界](#功能和边界)
- [安装](#安装)
- [快速入门](#快速入门)
- [客户端配置](#客户端配置)
- [运行时界面](#运行时界面)
- [MCP 工具参考](#mcp-工具参考)
- [CLI 参考](#cli-参考)
- [配置](#配置)
- [身份验证](#身份验证)
- [安全性和信任模型](#安全性和信任模型)
- [架构](#架构)
- [分发合约](#分)
- [开发](#开发)
- [验证](#验证)
- [部署](#部署)
- [故障排除](#故障排除)
- [相关服务器](#相关服务器)
- [文档](#文档)
- [许可证](#许可证)
## 命名
| 界面 | 此仓库 |
|---|---|
| 仓库 | `arcane-rmcp` |
| Rust 包 | `rar| 二进制 CLI | `rarcane` |
| npm 包 |ane-rmcp` npm 二进制文件别名 | `rarcane` MCP 服务器名称 | `rarcane` 在捆插件/客户端配置| MCP 工具 | `arcane` |
| 主 `~/.rarcane`，容器中的 `/data` |
| 环境前缀 | `RARCANE_*`RARCANE_MCP_*`，`RARCMCP_*` 启动器控件 |
和 npm 包使用上游服务名称，而已发布的二进制文件保留历史的 Rust CLI 名称 `rarcane`。MCP 服务器可能注册为 `rarcane`，但工具客户端调用的是 `arcane`。
## 功能和边界
- 读取 Arcane 状态和 Docker 环境、项目、容器、镜像、网络、卷、注册表、GitOps、更新、漏洞和系统状态。
- 通过操作/子操作调度创建、更新、启动、停止、重启、删除、清理、部署、扫描和备份受支持的 Arcane 资源。
- 在转发写入操作到 Arcane 之前强制执行操作范围和破坏性操作确认。
- 暴露 `quick_start` 提示和 `rarcane://schema/mcp-tool` 资源用于客户端发现。
- 为本地插件/运行时检查提供设置、医生和监视命令。
| 此仓库拥有 | Arcane 拥有 | 明确超出范围 |
|---|---|---|
| MCP/CLI 投影、请求验证、身份验证策略、响应塑形、设置检查、模式/资源暴露和破坏性网关。 | Docker 状态、Arcane 项目和环境、上游授权、注册表凭证、GitOps 机密、漏洞扫描器输出和 API 语义。 | 直接 Docker 套接字访问、shell 执行、凭证存储、通用 REST行为、多租户沙盒、调度器行为和替换 Arcane UI/API。 |
## 安装
| 路径 | 命令 | 最适合 | 备注 |
|---|---|---|---|
| npm / npx | `npx -y arcane-rmcp --help` | 本地 MCP 客户端和快速试用。 | 从 GitHub Releases 下载匹配的 `rarcane` 二进制文件。 |
| 发布安装程序 | `curl -fsSL https://raw.githubusercontent.com/jmagar/arcane-rmcp/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 installrarcane` | 从此检查的 Claude Code 本地插件设置。 | 使用打包的设置钩子、技能和监视器元数据。 |
### npm / npx
在不手动安装二进制文件的情况下运行 stdio MCP 服务器或 CLI：
```bash
npx -y arcane-rmcp --help
npx -y arcane-rmcp mcp
npx -y arcane-rmcp status
```
npm 包在 `postinstall` 期间下载 `rarcane`。仅在测试打包时覆盖下载行为：
| 变量 | 目的 |
|---|---|
| `RARCANE_RMCP_SKIP_DOWNLOAD=1` | 跳过安装后二进制文件下载。 |
| `RARCANE_RMCP_VERSION` 或 `RARCANE_RMCP_BINARY_VERSION` | 选择 GitHub Release 标签。 |
| `RARCANE_RMCP_REPO` | 选择用于发布下载的 GitHub 仓库。 |
| `RARCANE_RMCP_RELEASE_BASE_URL` | 选择自定义发布基准 URL。 |
### 从源代码构建
```bash
git clone https://github.com/jmagar/arcane-rmcp
cd arcane-rmcp
cargo build --release
./target/release/rarcane --help
```
最低支持的 Rust 版本：1.90。
## 快速入门
### 1. 配置 Arcane
将网桥指向现有的 Arcane API 服务器：
```bash
export RARCANE_API_URL=https://arcane.example.com
export RARCANE_API_KEY=...
```
API 密钥仅从环境或配置中读取。不要在 MCP 工具参数或 CLI `--params-json` 中传递它。
### 2. 运行安全 CLI 调用
```bash
npx -y arcane-rmcp status
```
### 3. 启动回环 HTTP MCP
```bash
RARCANE_MCP_HOST=127.0.0.1 npx -y arcane-rmcp serve
```
在另一个 shell 中：
```bash
curl -sf http://127.0.0.1:40110/health
```
### 4. 进行首次 MCP 调用
```bash
curl -s -X POST http://127.0.0.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
```json
{
"mcpServers": {
"rarcane": {
"command": "npx",
"args": ["-y", "arcane-rmcp", "mcp"],
"env": {
"RARCANE_API_URL": "https://arcane.example.com",
"RARCANE_API_KEY": "..."
}
}
}
}
```
### Claude Code HTTP
```json
{
"mcpServers": {
"rarcane": {
"type": "http",
"url": "http://127.0.0.1:40110/mcp",
"headers": {
"Authorization": "Bearer ${RARCANE_MCP_TOKEN}"
}
}
}
}
```
### Codex / Labby 网关
通过 Labby 将 Arcane 注册为 HTTP 上游，共享一个长时间运行的服务器，或直接作为 stdio 运行仅限本地使用。
```toml
[mcp_servers.rarcane]
command = "npx"
args =y", "arcane-rmcp", "mcp"]
```
### 通用 MCP JSON
```json
{
"command": "rarcane",
"args": ["mcp"],
"env": {
"RARCANE_API_URL": "https://arcane.example.com"
}
}
```
不要在 MCP 工具参数中放置 `RARCANE_API_KEY`、注册表凭证、Git 凭证、OAuth 机密、SSH 密钥、密码或上游持有者令牌。使用环境、配置文件或 MCP 客户端的秘密存储。
## 运行时界面
| 界面 | 状态 | 入口点 | 目的 |
|---|---:|| MCP stdio | 支持 | `rarcane mcp`，`npx -y arcane-rmcp 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 | 未发布 | 不适用 | Arcane 已拥有 REST API。 |
| Web UI | 未发布 | 不适用 | Arcane 已拥有 Web UI。 |
## MCP 工具参考
公开一个 MCP 工具：`arcane`。传递所需的 `action` 参数和大多数域的所需 `subaction`。
| 操作 | 常见子操作 | 范围 |
|---|---|---|
| `help` | 操作参考或特定于域的帮助 | 公共 |
| `status` |网桥和 Arcane 配置状态 | `rarcane:read` |
| `elicit_name` | MCP 诱导演示 | `rarcane` |
|caffold_intent` | 无副作用的脚手架规划交接 | `rarcane:read` |
| `environment` | `list`，`get`，`create`，`update`，`delete`，`test` | 可读/写 |
| `project` | `list`，`get`，`create`，`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` |/写 |
|` | ``getcreate`，`delete`，``，`，备份和恢复操作 | 可读/写 |
| `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` 中的生成模式注释是所需参数的真实来源。
示例只读工具参数：
```json
{
": "container",
"subaction": "list",
"envId": "default"
}
```
示例破坏性操作：
```json
{
"action": "container",
"subaction": "stop",
"envId": "default",
"id": "my-container",
"params": {
"confirm": true
}
}
```
## CLI 参考
`rarcane` 公开与 MCP 服务层：
```bash
rarcane status
rarcane help --domain container
rarcane call --action container --subaction list --env
rarcane call --action system --subaction docker-info --env-id default
rarcane call --action container --subaction stop --env-id default ---container --confirm
rarcane doctor --json
rarcane watch --url http://127.0.0.1:40110
rarcane setup check
rarcane setup```
`-- 接受特定于操作的 JSON 有效负载它来传递## 配置
主机读取 `~/./.env`、`~/.rarcane/config.toml` 和进程环境。容器读取 `/data/.env`、`/data/config.toml` 和进程环境。
| 变量 | 默认值 | 目的 |
|---|---|---|
| `RARCANE_API_URL` | 未设置 | Arcane API 基 URL。 |
| `RARCANE_API_KEY` | 未设置 | Arcane API 密钥或持有者令牌。 `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 的静态持有者令牌。 |
| `RARCANE_MCP_NO_AUTH` | `false` | 仅在回环开发中禁用身份验证。 |
| `R_NOAUTH` | `false` | 游网关验证。 |
| `RARCANE_MCP_ALLOWED_HOSTS` | 未设置 | 额外的已接受主机头值。 |
| `RARCANE_MCP_ALLOWED_ORIGINS` | 未设置 | 额外的已接受 CORS 来源。 |
| `RARCANE_MCP_AUTH_MODE` | `bearer` | `bearer` 或 `oauth`。 |
## 身份验证
HTTP MCP 身份验证策略：
| 状态 | 条件 | 行为 |
|---|---|---|
| 回环开发 | 绑定到 `127.0.0.1`、`localhost` 或1]` | 允许本地未经身份验证的开发。 |
| 安装持有者 | 非回环且具有 `RARCANE_MCP_TOKEN` | 需要 `Authorization: Bearer <token>` 和操作范围。 |
| 安装 OAuth | `RARCANE_MCP_AUTH_MODE=oauth` | 通过 `lab-auth` 使用 Google OAuth/JWT；静态持有者仍然受支持。 |
| 信任网关 | `RARCANE_NOAUTH=true` | 假设反向代理或网关已经强制执行身份验证。 |
OAuth 模式使用 `RARCANE_MCP_*` Google OAuth 变量，如 `docs/CONFIG.md` 中所述。
OAuth 模式是单副本的：客户端/会话状态和签名密钥对于一个主机是本地的。在外部化或安全共享这些存储之前，请勿运行多个 OAuth 副本。
## 安全性和信任模型
- Arcane API 凭证仅从配置/环境加载。
- MCP 调用者选择操作和有效载荷，而不是上游凭证。
- 破坏性子操作在 `params.confirm=true` 或 CLI `--confirm` 存在之前被拒绝。
- 未知操作、未知子操作、缺少环境 ID、缺少 ID 和不安全的卷路径在上游调用之前被拒绝。
- 非回环 HTTP 部署必须使用持有者身份验证、OAuth 或带有身份验证网关的受信任网关。
- 此网桥不为 Arcane 本身提供沙盒。Arcane 仍然负责 Docker 身份验证和 Docker 操作的效果。
## 架构
```text
ArcaneClient （src/arcane.rs） HTTP 传输和简化错误
|
ArcaneService （src/app.rs） 操作验证、确认、响应规范化
|
MCP shim （src/mcp/tools.rs） JSON 参数 -> 服务 -> 值
CLI shim （src/cli.rs） argv -> 服务 -> stdout
```
## 分发合约
- `Cargo.toml`、`Cargo.lock`、`packages/arcane-rmcp/package.json`、`release-please-manifest.json` 和 `server.json` 必须同意发布的版本号。
- GitHub Releases 发布 npm 启动器消耗的 `rarcane` 二进制文件。
- npm 包名称为 `arcane-rmcp`；已安装的二进制文件别名为 `rarcane`。
- Docker/OCI 元数据使用 `ghcr.io/jmagar/arcane-rmcp:<version>`。
- `plugins/rarcane/.mcp.json` 必须启动 `npx -y arcane-rmcp mcp`，以便 stdio 客户端启动 MCP 传输，而不是 HTTP 服务器模式。
- 根 README 已策划。生成的或源代码真实性详细信息位于 `src/actions.rs`、`docs/MCP_SCHEMA.md` 和包/注册表清单中。
## 开发
```bash
cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo build --release
npm --prefix packages/arcane-rmcp run check
```
##```bash
python3 /mag/soma/scripts/check-readme-guide.py README.md
npm --prefix packages/arcane-rmcp run check
cargo check
cargo test
git diff --check
```
运行时烟雾测试：
```bash
RARCANE_API_URL=https://arcane.example.com \
RARCANE_API_KEY=... \
rarcane status
```
HTTP 烟雾测试：
```bash
RARCANE_MCP_HOST=127.0.0.1 rarcane serve
curl -sf http://127.0.0.1:40110/health
```
## 部署
在本地开发中使用回环：
```bash
RARCANE_MCP_HOST=127.0.0.1 rarcane serve
```
使用 Docker Compose 进行共享 HTTP 部署：
```bash
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`，而不是默认的模式。 |
|性操作被拒绝 | 在验证添加 CLI `-- 或 MCP `params.confirm=true`。口冲突 `RARCANE_MCP_PORT`已经使用 `` 的进程。 |
## 相关服务器
- [soma://githubmagar/s 用于提供的 MCP 服务器 运行时。
- [unifi-rmhttps://github.com/jmagar/unifi-rmcp) - UniFi 控制器 REST API 网桥。
- [tailscp](https.com/jmagar/tailscale-rmcp) - 用于设备、用户和尾网操作的 Tailscale API 网桥。
- [unraid-rmcp](github.comar/unraid-rmcp) - 用于 NAS 和服务器管理的 Unraid GraphQL 网桥。
- [-rmcp](https://github.com/jmagar/apprise-rmcp) - 用于许多投递后端的 Apprise 通知扇出网桥。
- [gotify-rmcp](https://github.com/jmagar/gotify-rmcp) - 用于发送、消息、客户端的 Gotify 推送通知网桥。
- [yarr](https://github.com/jmagar/yarr) - 用于 Sonarrarr、Prowlarr、Plex 和相关服务的媒体栈网桥。
- [ytdl-rmcp](https://github.com/jmagar/ytdl-rmcp) - 媒体下载和元数据工作流服务器。
- [synapse-rmcp](https://github.com/jmagar/synapse-rmcp) - 用于侦察和通量操作的本地 Synapse 工作流服务器。
- [cortex](https://github.com/jmagar/cortex) - 系统日志和家庭实验室日志聚合 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` 是整理的动作合约概述。
-/CONFIG.md` 是整理的配置和身份验证参考。
- `docs/QUICKSTART.md` 是整理的烟雾测试指南。
- `docs/MCP_SCHEMA.md` 是动作、资源、提示和验证规则的生成/模式漂移合约。
- `plugins/rarcane/skills/rarcane/SKILL.md` 是代理使用指南。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器