{
  "markdown": "# arcane-rmcp\n\nArcane Docker and Compose management over MCP and CLI with authenticated stdio and HTTP.\n\nIt exposes one MCP tool, `arcane`, plus the `rarcane` CLI. Agents can inspect\nArcane environments, manage compose projects, containers, images, networks,\nvolumes, registries, GitOps syncs, image updates, vulnerability findings, and\nsystem operations through stdio MCP, Streamable HTTP MCP, or direct shell\ncommands.\n\n**30-second path:** set `RARCANE_API_URL` and `RARCANE_API_KEY`, then run\n`npx -y @dinglebear/rarcane status` -> start loopback HTTP with\n`RARCANE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rarcane serve` -> call `tools/call` with\n`{\"action\":\"status\"}`.\n\n**Status:** operational RMCP upstream-client server. Write-capable; destructive\nDocker and Arcane operations require explicit confirmation. HTTP MCP supports\nloopback dev mode, static bearer tokens, and Google OAuth through `lab-auth`.\n\n**Not for:** replacing Arcane, bypassing Docker or Arcane authorization,\nrunning arbitrary shell commands, storing registry or Git credentials,\nmulti-tenant isolation, or passing Arcane API keys through MCP tool arguments.\n\n## Contents\n\n- [Naming](#naming)\n- [Capabilities And Boundaries](#capabilities-and-boundaries)\n- [Install](#install)\n- [Quickstart](#quickstart)\n- [Client Configuration](#client-configuration)\n- [Runtime Surfaces](#runtime-surfaces)\n- [MCP Tool Reference](#mcp-tool-reference)\n- [CLI Reference](#cli-reference)\n- [Configuration](#configuration)\n- [Authentication](#authentication)\n- [Safety And Trust Model](#safety-and-trust-model)\n- [Architecture](#architecture)\n- [Distribution Contract](#distribution-contract)\n- [Development](#development)\n- [Verification](#verification)\n- [Deployment](#deployment)\n- [Troubleshooting](#troubleshooting)\n- [Related Servers](#related-servers)\n- [Documentation](#documentation)\n- [License](#license)\n\n## Naming\n\n| Surface | This repo |\n|---|---|\n| Repository | `arcane-rmcp` |\n| Rust crate | `rarcane` |\n| Binary / CLI | `rarcane` |\n| npm package | `@dinglebear/rarcane` |\n| npm binary alias | `rarcane` |\n| MCP server name | `rarcane` in bundled plugin/client config |\n| MCP tool | `arcane` |\n| Config home | `~/.rarcane` on hosts, `/data` in containers |\n| Env prefixes | `RARCANE_*`, `RARCANE_MCP_*`, `RARCANE_RMCP_*` for npm launcher controls |\n\nThe repo and npm package use the upstream service name, while the shipped\nbinary keeps the historical Rust CLI name `rarcane`. The MCP server may be\nregistered as `rarcane`, but the tool clients call is `arcane`.\n\n## Capabilities And Boundaries\n\n- Read Arcane status plus Docker environment, project, container, image,\n  network, volume, registry, GitOps, update, vulnerability, and system state.\n- Create, update, start, stop, restart, delete, prune, deploy, sync, scan, and\n  back up supported Arcane resources through action/subaction dispatch.\n- Enforce action scopes and destructive-operation confirmation before forwarding\n  write operations to Arcane.\n- Expose the `quick_start` prompt and `rarcane://schema/mcp-tool` resource for\n  client-side discovery.\n- Provide setup, doctor, and watch commands for local plugin/runtime checks.\n\n| This repo owns | Arcane owns | Explicitly out of scope |\n|---|---|---|\n| MCP/CLI projection, request validation, auth policy, response shaping, setup checks, schema/resource exposure, and destructive gates. | Docker state, Arcane projects and environments, upstream authorization, registry credentials, GitOps secrets, vulnerability scanner output, and API semantics. | Direct Docker socket access, shell execution, credential storage, generic REST proxy behavior, multi-tenant sandboxing, scheduler behavior, and replacing the Arcane UI/API. |\n\n## Install\n\n| Path | Command | Best for | Notes |\n|---|---|---|---|\n| npm / npx | `npx -y @dinglebear/rarcane --help` | Local MCP clients and quick trials. | Downloads the matching `rarcane` binary from GitHub Releases. |\n| Release installer | `curl -fsSL https://raw.githubusercontent.com/dinglebear-ai/rarcane/main/scripts/install.sh \\| bash` | Host installs without Node. | Installs `rarcane` for the current Linux host. |\n| Docker / Compose | `docker compose up -d` | Shared HTTP MCP deployments. | Reads `.env` and exposes container port `40110`. |\n| Build from source | `cargo build --release` | Development and audits. | Produces `target/release/rarcane`. |\n| Plugin | `claude plugin install plugins/rarcane` | Claude Code local plugin setup from this checkout. | Uses the packaged skill and monitor metadata. The plugin ships no lifecycle hooks — run `rarcane setup repair` once after install. |\n\n### npm / npx\n\nRun the stdio MCP server or CLI without a manual binary install:\n\n```bash\nnpx -y @dinglebear/rarcane --help\nnpx -y @dinglebear/rarcane mcp\nnpx -y @dinglebear/rarcane status\n```\n\nThe npm package downloads `rarcane` during `postinstall`. Override download\nbehavior only when testing packaging:\n\n| Variable | Purpose |\n|---|---|\n| `RARCANE_RMCP_SKIP_DOWNLOAD=1` | Skip postinstall binary download. |\n| `RARCANE_RMCP_VERSION` or `RARCANE_RMCP_BINARY_VERSION` | Select the GitHub Release tag. |\n| `RARCANE_RMCP_REPO` | Select the GitHub repo used for release downloads. |\n| `RARCANE_RMCP_RELEASE_BASE_URL` | Select a custom release base URL. |\n\n### Build From Source\n\n```bash\ngit clone https://github.com/dinglebear-ai/rarcane\ncd rarcane\ncargo build --release\n./target/release/rarcane --help\n```\n\nMinimum supported Rust version: 1.90.\n\n## Quickstart\n\n### 1. Configure Arcane\n\nPoint the bridge at an existing Arcane API server:\n\n```bash\nexport RARCANE_API_URL=https://arcane.example.com\nexport RARCANE_API_KEY=...\n```\n\nThe API key is read from env or config only. Do not pass it in MCP tool\narguments or CLI `--params-json`.\n\n### 2. Run A Safe CLI Call\n\n```bash\nnpx -y @dinglebear/rarcane status\n```\n\n### 3. Start Loopback HTTP MCP\n\n```bash\nRARCANE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rarcane serve\n```\n\nIn another shell:\n\n```bash\ncurl -sf http://127.0.0.1:40110/health\n```\n\n### 4. Make A First MCP Call\n\n```bash\ncurl -s -X POST http://127.0.0.1:40110/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json, text/event-stream\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"arcane\",\"arguments\":{\"action\":\"status\"}}}'\n```\n\n## Client Configuration\n\n### Claude Code Stdio\n\n```json\n{\n  \"mcpServers\": {\n    \"rarcane\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"arcane-rmcp\", \"mcp\"],\n      \"env\": {\n        \"RARCANE_API_URL\": \"https://arcane.example.com\",\n        \"RARCANE_API_KEY\": \"...\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code HTTP\n\n```json\n{\n  \"mcpServers\": {\n    \"rarcane\": {\n      \"type\": \"http\",\n      \"url\": \"http://127.0.0.1:40110/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${RARCANE_MCP_TOKEN}\"\n      }\n    }\n  }\n}\n```\n\n### Codex / Labby Gateway\n\nRegister Arcane through Labby as an HTTP upstream when sharing one long-running\nserver, or run it directly as stdio for local-only use.\n\n```toml\n[mcp_servers.rarcane]\ncommand = \"npx\"\nargs = [\"-y\", \"arcane-rmcp\", \"mcp\"]\n```\n\n### Generic MCP JSON\n\n```json\n{\n  \"command\": \"rarcane\",\n  \"args\": [\"mcp\"],\n  \"env\": {\n    \"RARCANE_API_URL\": \"https://arcane.example.com\"\n  }\n}\n```\n\nDo not put `RARCANE_API_KEY`, registry credentials, Git credentials, OAuth\nsecrets, SSH keys, passwords, or upstream bearer tokens in MCP tool arguments.\nUse env, config files, or the MCP client's secret storage.\nMCP callers never provide credentials, tokens, keys, or secrets as action\narguments.\n\n## Runtime Surfaces\n\n| Surface | Status | Entry point | Purpose |\n|---|---:|---|---|\n| MCP stdio | Supported | `rarcane mcp`, `npx -y @dinglebear/rarcane mcp` | Local child-process MCP clients. |\n| MCP HTTP | Supported | `rarcane serve`, `POST /mcp` | Streamable HTTP MCP for local or shared server deployments. |\n| CLI | Supported | `rarcane <command>` | Scriptable parity and debugging. |\n| Prompt | Supported | `quick_start` | Guides a client through `status` and public `help`. |\n| Resource | Supported | `rarcane://schema/mcp-tool` | JSON schema for the `arcane` tool. |\n| REST API | Not shipped | N/A | Arcane already owns the REST API. |\n| Web UI | Not shipped | N/A | Arcane already owns the web UI. |\n\n## MCP Tool Reference\n\nOne MCP tool is exposed: `arcane`. Pass the required `action` argument and, for\nmost domains, a required `subaction`.\n\n| Action | Common subactions | Scope |\n|---|---|---|\n| `help` | action reference or domain-specific help | public |\n| `status` | local bridge and Arcane config status | `rarcane:read` |\n| `elicit_name` | MCP elicitation demonstration | `rarcane:read` |\n| `scaffold_intent` | side-effect-free scaffold planning handoff | `rarcane:read` |\n| `environment` | `list`, `get`, `create`, `update`, `delete`, `test` | read/write |\n| `project` | `list`, `get`, `create`, `update`, `up`, `down`, `restart`, `pull`, `destroy`, `redeploy`, `build` | read/write |\n| `container` | `list`, `get`, `create`, `start`, `stop`, `restart`, `update`, `delete`, `stats` | read/write |\n| `image` | `list`, `get`, `pull`, `delete`, `prune`, `scan` | read/write |\n| `network` | `list`, `get`, `create`, `delete`, `prune` | read/write |\n| `volume` | `list`, `get`, `create`, `delete`, `prune`, `browse`, `list-backups`, `create-backup`, `delete-backup`, `restore`, `restore-files` | read/write |\n| `system` | `docker-info`, `prune`, `start-all`, `stop-all`, `convert` | read/write |\n| `image-update` | `check-all`, `check`, `check-batch`, `summary` | read |\n| `vulnerability` | `summary`, `list`, `scanner-status`, `ignore`, `unignore`, `list-ignored` | read/write |\n| `registry` | `list`, `get`, `create`, `update`, `delete`, `test` | read/write |\n| `gitops` | `list`, `get`, `create`, `update`, `delete`, `sync`, `status`, `browse` | read/write |\n\nAction specs in `src/actions.rs` and the generated schema notes in\n`docs/MCP_SCHEMA.md` are the source of truth for required parameters.\n\nExample read-only tool arguments:\n\n```json\n{\n  \"action\": \"container\",\n  \"subaction\": \"list\",\n  \"envId\": \"default\"\n}\n```\n\nExample destructive operation:\n\n```json\n{\n  \"action\": \"container\",\n  \"subaction\": \"stop\",\n  \"envId\": \"default\",\n  \"id\": \"my-container\",\n  \"params\": {\n    \"confirm\": true\n  }\n}\n```\n\n## CLI Reference\n\n`rarcane` exposes the same service layer as the MCP tool:\n\n```bash\nrarcane status\nrarcane help --domain container\nrarcane call --action container --subaction list --env-id default\nrarcane call --action system --subaction docker-info --env-id default\nrarcane call --action container --subaction stop --env-id default --id my-container --confirm\nrarcane doctor --json\nrarcane watch --url http://127.0.0.1:40110\nrarcane setup check\nrarcane setup repair\n```\n\n`--params-json` accepts action-specific JSON payloads. Do not use it to pass\ncredentials.\n\n## Configuration\n\nHost installs read `~/.rarcane/.env`, `~/.rarcane/config.toml`, and process env.\nContainers read `/data/.env`, `/data/config.toml`, and process env.\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `RARCANE_API_URL` | unset | Arcane API base URL. |\n| `RARCANE_API_KEY` | unset | Arcane API key or bearer token. |\n| `RARCANE_MCP_HOST` | `127.0.0.1` | HTTP bind host. |\n| `RARCANE_MCP_PORT` | `40110` | HTTP bind port. |\n| `RARCANE_MCP_SERVER_NAME` | `arcane-rmcp` | Advertised MCP server name. |\n| `RARCANE_MCP_TOKEN` | unset | Static bearer token for HTTP MCP. |\n| `RARCANE_MCP_NO_AUTH` | `false` | Disable auth only for loopback development. |\n| `RARCANE_NOAUTH` | `false` | Trust an upstream gateway to enforce auth. |\n| `RARCANE_MCP_ALLOWED_HOSTS` | unset | Extra accepted Host header values. |\n| `RARCANE_MCP_ALLOWED_ORIGINS` | unset | Extra accepted CORS origins. |\n| `RARCANE_MCP_PUBLIC_URL` | unset | Public base URL for OAuth issuer metadata. |\n| `RARCANE_MCP_AUTH_MODE` | `bearer` | `bearer` or `oauth`. |\n| `RARCANE_MCP_ALLOW_DESTRUCTIVE` | `false` | Bypass the per-call destructive confirmation gate. Do not set in shared deployments. |\n| `RARCANE_HOME` | `~/.rarcane` | Config/appdata root override. |\n| `RUST_LOG` | `info` | Log filter. |\n\n## Authentication\n\nStdio MCP runs as a local trusted child process and does not use HTTP auth.\n\nHTTP MCP auth policy:\n\n| State | Condition | Behavior |\n|---|---|---|\n| Loopback dev | Bound to `127.0.0.1`, `localhost`, or `[::1]` | Local unauthenticated development is allowed. |\n| Mounted bearer | Non-loopback with `RARCANE_MCP_TOKEN` | Requires `Authorization: Bearer <token>` and action scopes. |\n| Mounted OAuth | `RARCANE_MCP_AUTH_MODE=oauth` | Uses Google OAuth/JWT through `lab-auth`; static bearer remains supported. |\n| Trusted gateway | `RARCANE_NOAUTH=true` | Assumes a reverse proxy or gateway already enforced auth. |\n\nOAuth mode uses the `RARCANE_MCP_*` Google OAuth variables documented in\n`docs/CONFIG.md`.\n\nOAuth mode is single-replica: client/session state and signing keys are local to\none host. Do not run multiple OAuth replicas until those stores are externalized\nor safely shared.\n\n## Safety And Trust Model\n\n- Arcane API credentials are loaded from config/env only.\n- MCP callers select actions and payloads, not upstream credentials.\n- Destructive subactions reject unless `params.confirm=true` or CLI\n  `--confirm` is present.\n- Unknown actions, unknown subactions, missing environment IDs, missing IDs, and\n  unsafe volume paths are rejected before upstream calls.\n- Non-loopback HTTP deployments must use bearer auth, OAuth, or a trusted\n  authenticated gateway.\n- This bridge does not sandbox Arcane itself. Arcane remains responsible for\n  Docker authorization and the effects of Docker operations.\n\n## Architecture\n\n```text\nArcaneClient  (src/arcane.rs)      HTTP transport and redacted errors\n      |\nArcaneService (src/app.rs)         action validation, confirmation, response normalization\n      |\nMCP shim      (src/mcp/tools.rs)   JSON args -> service -> Value\nCLI shim      (src/cli.rs)         argv -> service -> stdout\n```\n\n## Distribution Contract\n\n- `Cargo.toml`, `Cargo.lock`, `packages/arcane-rmcp/package.json`,\n  `.release-please-manifest.json`, and `server.json` must agree on the released\n  version.\n- GitHub Releases publish the `rarcane` binary consumed by the npm launcher.\n- The npm package name is `@dinglebear/rarcane`; the installed binary alias is\n  `rarcane`.\n- Docker/OCI metadata uses `ghcr.io/dinglebear-ai/rarcane:<version>`.\n- `plugins/rarcane/.mcp.json` must launch `npx -y @dinglebear/rarcane mcp` so stdio\n  clients start the MCP transport rather than the HTTP server.\n- The root README is curated. Generated or source-of-truth details live in\n  `src/actions.rs`, `docs/MCP_SCHEMA.md`, and the package/registry manifests.\n\n## Development\n\n```bash\ncargo fmt --check\ncargo test\ncargo clippy -- -D warnings\ncargo build --release\nnpm --prefix packages/arcane-rmcp run check\n```\n\n## Verification\n\n```bash\njust verify                 # fmt-check → lint → check → test\njust template-check         # patterns, plugin layout, schema docs, scaffold contract\nnpm --prefix packages/arcane-rmcp run check\ngit diff --check\n```\n\nRuntime smoke:\n\n```bash\nRARCANE_API_URL=https://arcane.example.com \\\nRARCANE_API_KEY=... \\\nrarcane status\n```\n\nHTTP smoke:\n\n```bash\nRARCANE_MCP_HOST=127.0.0.1 rarcane serve\ncurl -sf http://127.0.0.1:40110/health\n```\n\n## Deployment\n\nUse loopback for local development:\n\n```bash\nRARCANE_MCP_HOST=127.0.0.1 rarcane serve\n```\n\nUse Docker Compose for shared HTTP deployment:\n\n```bash\ncp .env.example .env\ndocker compose up -d\n```\n\nWhen binding to a non-loopback address, configure `RARCANE_MCP_TOKEN`,\n`RARCANE_MCP_AUTH_MODE=oauth`, or `RARCANE_NOAUTH=true` behind an authenticated\ngateway.\n\n## Troubleshooting\n\n| Symptom | Check |\n|---|---|\n| `RARCANE_API_URL is required` | Set `RARCANE_API_URL` in env or `~/.rarcane/.env`. |\n| Arcane calls return unauthorized | Refresh `RARCANE_API_KEY` in Arcane and restart the bridge. |\n| HTTP `/mcp` returns unauthorized | Set `RARCANE_MCP_TOKEN` and send `Authorization: Bearer <token>`. |\n| Stdio client hangs or logs JSON errors | Ensure client config runs `arcane-rmcp mcp`, not the default HTTP server mode. |\n| Destructive action is rejected | Add CLI `--confirm` or MCP `params.confirm=true` after verifying the target. |\n| Port conflict | Set `RARCANE_MCP_PORT` or stop the process already using `40110`. |\n\n## Related Servers\n\n- [soma](https://github.com/dinglebear-ai/soma) - RMCP runtime for provider-backed MCP servers.\n- [unifi-rmcp](https://github.com/dinglebear-ai/runifi) - UniFi controller REST API bridge.\n- [tailscale-rmcp](https://github.com/dinglebear-ai/rtailscale) - Tailscale API bridge for devices, users, and tailnet operations.\n- [unraid](https://github.com/dinglebear-ai/unraid) - Unraid GraphQL bridge for NAS and server management.\n- [apprise-rmcp](https://github.com/dinglebear-ai/rapprise) - Apprise notification fan-out bridge for many delivery backends.\n- [gotify-rmcp](https://github.com/dinglebear-ai/rgotify) - Gotify push notification bridge for sends, messages, apps, and clients.\n- [yarr](https://github.com/dinglebear-ai/yarr) - Media-stack bridge for Sonarr, Radarr, Prowlarr, Plex, and related services.\n- [ytdl-rmcp](https://github.com/dinglebear-ai/rytdl) - Media download and metadata workflow server.\n- [synapse-rmcp](https://github.com/dinglebear-ai/synapse) - Local Synapse workflow server for scout and flux actions.\n- [cortex](https://github.com/dinglebear-ai/cortex) - Syslog and homelab log aggregation MCP server.\n- [axon](https://github.com/dinglebear-ai/axon) - RAG, crawl, scrape, extract, and semantic search project.\n- [labby](https://github.com/dinglebear-ai/labby) - Homelab control plane and MCP gateway project.\n- [lumen](https://github.com/dinglebear-ai/lumen) - Local semantic code search MCP server.\n\n## Documentation\n\n- `docs/API.md` is the curated action-contract overview.\n- `docs/CONFIG.md` is the curated configuration and auth reference.\n- `docs/QUICKSTART.md` is the curated smoke-test guide.\n- `docs/MCP_SCHEMA.md` is the generated/schema-drift contract for actions,\n  resources, prompts, and validation rules.\n- `plugins/rarcane/skills/rarcane/SKILL.md` is the agent usage guide.\n\n## License\n\nOriginal Dinglebear-authored portions of this project are licensed under [AGPL-3.0-only](LICENSE). Separate commercial licensing is available for organizations that need terms outside the AGPL. Third-party material remains under its original license. See [LICENSING.md](https://github.com/dinglebear-ai/rarcane/blob/main/LICENSING.md).\n",
  "bytes": 18486,
  "sha": "b83ef09f21e10dcb1234d5b77d89fa70224fad22eb07920f40dc5b49902628ef",
  "repo_slug": "jmagar/arcane-rmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_dinglebear_arcane_rmcp_95cacc5c/readme"
}