rarcane

# arcane-rmcp

Arcane Docker and Compose management over MCP and CLI with authenticated stdio and HTTP.

It exposes one MCP tool, `arcane`, plus the `rarcane` CLI. Agents can inspect
Arcane environments, manage compose projects, containers, images, networks,
volumes, registries, GitOps syncs, image updates, vulnerability findings, and
system operations through stdio MCP, Streamable HTTP MCP, or direct shell
commands.

**30-second path:** set `RARCANE_API_URL` and `RARCANE_API_KEY`, then run
`npx -y @dinglebear/rarcane status` -> start loopback HTTP with
`RARCANE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rarcane serve` -> call `tools/call` with
`{"action":"status"}`.

**Status:** operational RMCP upstream-client server. Write-capable; destructive
Docker and Arcane operations require explicit confirmation. HTTP MCP supports
loopback dev mode, static bearer tokens, and Google OAuth through `lab-auth`.

**Not for:** replacing Arcane, bypassing Docker or Arcane authorization,
running arbitrary shell commands, storing registry or Git credentials,
multi-tenant isolation, or passing Arcane API keys through MCP tool arguments.

## Contents

- [Naming](#naming)
- [Capabilities And Boundaries](#capabilities-and-boundaries)
- [Install](#install)
- [Quickstart](#quickstart)
- [Client Configuration](#client-configuration)
- [Runtime Surfaces](#runtime-surfaces)
- [MCP Tool Reference](#mcp-tool-reference)
- [CLI Reference](#cli-reference)
- [Configuration](#configuration)
- [Authentication](#authentication)
- [Safety And Trust Model](#safety-and-trust-model)
- [Architecture](#architecture)
- [Distribution Contract](#distribution-contract)
- [Development](#development)
- [Verification](#verification)
- [Deployment](#deployment)
- [Troubleshooting](#troubleshooting)
- [Related Servers](#related-servers)
- [Documentation](#documentation)
- [License](#license)

## Naming

| Surface | This repo |
|---|---|
| Repository | `arcane-rmcp` |
| Rust crate | `rarcane` |
| Binary / CLI | `rarcane` |
| npm package | `@dinglebear/rarcane` |
| npm binary alias | `rarcane` |
| MCP server name | `rarcane` in bundled plugin/client config |
| MCP tool | `arcane` |
| Config home | `~/.rarcane` on hosts, `/data` in containers |
| Env prefixes | `RARCANE_*`, `RARCANE_MCP_*`, `RARCANE_RMCP_*` for npm launcher controls |

The repo and npm package use the upstream service name, while the shipped
binary keeps the historical Rust CLI name `rarcane`. The MCP server may be
registered as `rarcane`, but the tool clients call is `arcane`.

## Capabilities And Boundaries

- Read Arcane status plus Docker environment, project, container, image,
  network, volume, registry, GitOps, update, vulnerability, and system state.
- Create, update, start, stop, restart, delete, prune, deploy, sync, scan, and
  back up supported Arcane resources through action/subaction dispatch.
- Enforce action scopes and destructive-operation confirmation before forwarding
  write operations to Arcane.
- Expose the `quick_start` prompt and `rarcane://schema/mcp-tool` resource for
  client-side discovery.
- Provide setup, doctor, and watch commands for local plugin/runtime checks.

| This repo owns | Arcane owns | Explicitly out of scope |
|---|---|---|
| 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. |

## Install

| Path | Command | Best for | Notes |
|---|---|---|---|
| npm / npx | `npx -y @dinglebear/rarcane --help` | Local MCP clients and quick trials. | Downloads the matching `rarcane` binary from GitHub Releases. |
| 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. |
| Docker / Compose | `docker compose up -d` | Shared HTTP MCP deployments. | Reads `.env` and exposes container port `40110`. |
| Build from source | `cargo build --release` | Development and audits. | Produces `target/release/rarcane`. |
| 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. |

### npm / npx

Run the stdio MCP server or CLI without a manual binary install:

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

The npm package downloads `rarcane` during `postinstall`. Override download
behavior only when testing packaging:

| Variable | Purpose |
|---|---|
| `RARCANE_RMCP_SKIP_DOWNLOAD=1` | Skip postinstall binary download. |
| `RARCANE_RMCP_VERSION` or `RARCANE_RMCP_BINARY_VERSION` | Select the GitHub Release tag. |
| `RARCANE_RMCP_REPO` | Select the GitHub repo used for release downloads. |
| `RARCANE_RMCP_RELEASE_BASE_URL` | Select a custom release base URL. |

### Build From Source

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

Minimum supported Rust version: 1.90.

## Quickstart

### 1. Configure Arcane

Point the bridge at an existing Arcane API server:

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

The API key is read from env or config only. Do not pass it in MCP tool
arguments or CLI `--params-json`.

### 2. Run A Safe CLI Call

```bash
npx -y @dinglebear/rarcane status
```

### 3. Start Loopback HTTP MCP

```bash
RARCANE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rarcane serve
```

In another shell:

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

### 4. Make A First MCP Call

```bash
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"}}}'
```

## Client Configuration

### 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 Gateway

Register Arcane through Labby as an HTTP upstream when sharing one long-running
server, or run it directly as stdio for local-only use.

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

### Generic MCP JSON

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

Do not put `RARCANE_API_KEY`, registry credentials, Git credentials, OAuth
secrets, SSH keys, passwords, or upstream bearer tokens in MCP tool arguments.
Use env, config files, or the MCP client's secret storage.
MCP callers never provide credentials, tokens, keys, or secrets as action
arguments.

## Runtime Surfaces

| Surface | Status | Entry point | Purpose |
|---|---:|---|---|
| MCP stdio | Supported | `rarcane mcp`, `npx -y @dinglebear/rarcane mcp` | Local child-process MCP clients. |
| MCP HTTP | Supported | `rarcane serve`, `POST /mcp` | Streamable HTTP MCP for local or shared server deployments. |
| CLI | Supported | `rarcane <command>` | Scriptable parity and debugging. |
| Prompt | Supported | `quick_start` | Guides a client through `status` and public `help`. |
| Resource | Supported | `rarcane://schema/mcp-tool` | JSON schema for the `arcane` tool. |
| REST API | Not shipped | N/A | Arcane already owns the REST API. |
| Web UI | Not shipped | N/A | Arcane already owns the web UI. |

## MCP Tool Reference

One MCP tool is exposed: `arcane`. Pass the required `action` argument and, for
most domains, a required `subaction`.

| Action | Common subactions | Scope |
|---|---|---|
| `help` | action reference or domain-specific help | public |
| `status` | local bridge and Arcane config status | `rarcane:read` |
| `elicit_name` | MCP elicitation demonstration | `rarcane:read` |
| `scaffold_intent` | side-effect-free scaffold planning handoff | `rarcane:read` |
| `environment` | `list`, `get`, `create`, `update`, `delete`, `test` | read/write |
| `project` | `list`, `get`, `create`, `update`, `up`, `down`, `restart`, `pull`, `destroy`, `redeploy`, `build` | read/write |
| `container` | `list`, `get`, `create`, `start`, `stop`, `restart`, `update`, `delete`, `stats` | read/write |
| `image` | `list`, `get`, `pull`, `delete`, `prune`, `scan` | read/write |
| `network` | `list`, `get`, `create`, `delete`, `prune` | read/write |
| `volume` | `list`, `get`, `create`, `delete`, `prune`, `browse`, `list-backups`, `create-backup`, `delete-backup`, `restore`, `restore-files` | read/write |
| `system` | `docker-info`, `prune`, `start-all`, `stop-all`, `convert` | read/write |
| `image-update` | `check-all`, `check`, `check-batch`, `summary` | read |
| `vulnerability` | `summary`, `list`, `scanner-status`, `ignore`, `unignore`, `list-ignored` | read/write |
| `registry` | `list`, `get`, `create`, `update`, `delete`, `test` | read/write |
| `gitops` | `list`, `get`, `create`, `update`, `delete`, `sync`, `status`, `browse` | read/write |

Action specs in `src/actions.rs` and the generated schema notes in
`docs/MCP_SCHEMA.md` are the source of truth for required parameters.

Example read-only tool arguments:

```json
{
  "action": "container",