@dinglebear/unraid 0.2.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jmagar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,515 @@
+# unraid-rmcp
+
+Rust MCP server and CLI for Unraid GraphQL operations across NAS, Docker, VM, and storage workflows.
+
+It exposes one MCP tool, `unraid`, plus the `runraid` CLI. Agents can inspect
+array health, disks, Docker containers and logs, VMs, shares, notifications,
+system metrics, UPS, logs, network settings, plugins, parity history, rclone,
+remote access, and Unraid Connect through stdio MCP, Streamable HTTP MCP, or
+direct shell commands.
+
+**30-second path:** install CRGX, set `UNRAID_API_URL` and `UNRAID_API_KEY`,
+then run `crgx unraid-rmcp -- server --json` -> start loopback HTTP with
+`UNRAID_RMCP_HOST=127.0.0.1 crgx unraid-rmcp -- serve mcp` -> call
+`tools/call` with `{"action":"server"}`.
+
+**Status:** operational RMCP upstream-client server with the full Unraid GraphQL
+query and mutation surface. Read actions require `unraid:read`; writes require
+`unraid:admin`. Destructive operations use MCP form elicitation and fail closed
+when the client cannot obtain user approval. HTTP MCP supports loopback dev mode,
+static bearer tokens, and Google OAuth through `lab-auth`. Release binaries and
+Docker images target linux/amd64 only.
+
+**Not for:** replacing the Unraid web UI, running arbitrary shell commands,
+storing API keys for callers, multi-tenant isolation, or passing Unraid 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 | `unraid` monorepo (`unraid-rs/` component) |
+| Rust crate | `unraid-rmcp` |
+| Binary / CLI | `runraid` |
+| crates.io package | `unraid-rmcp` |
+| CRGX command | `crgx unraid-rmcp -- <runraid args>` |
+| Legacy npm package | `unraid-rmcp` |
+| MCP tool | `unraid` |
+| Config home | `~/.unraid` on hosts, `/data` in containers |
+| Env prefixes | `UNRAID_*`, `UNRAID_RMCP_*` |
+
+This repo is a small naming exception in the RMCP family: MCP/server variables
+use `UNRAID_RMCP_*` rather than `UNRAID_MCP_*` for compatibility with the
+existing deployment config.
+
+## Capabilities And Boundaries
+
+- Read Unraid array state, parity status, disk health, SMART summaries, and
+  capacity.
+- Manage array, Docker, VM, notification, plugin, API-key, rclone, onboarding,
+  settings, remote-access, and Unraid Connect state through GraphQL mutations.
+- Require MCP form elicitation for destructive operations while allowing ordinary
+  writes to proceed after scope authorization.
+- Provide pagination/filtering for MCP list actions and output truncation for
+  large MCP responses.
+- Expose the `server_summary` prompt and `unraid://schema/mcp-tool` schema
+  resource.
+- Provide setup and doctor commands for local plugin/runtime checks.
+
+| This repo owns | Unraid owns | Explicitly out of scope |
+|---|---|---|
+| MCP/CLI projection, GraphQL operation selection, response shaping, pagination, auth policy, elicitation policy, setup checks, and prompt/resource metadata. | NAS state, array/docker/VM behavior, GraphQL schema, Unraid API key issuance, remote access, and Connect state. | Arbitrary shell execution, controller UI replacement, credential brokerage, background monitoring, multi-tenant sandboxing, and direct local filesystem writes. |
+
+## Install
+
+| Path | Command | Best for | Notes |
+|---|---|---|---|
+| CRGX | `crgx unraid-rmcp -- --help` | Local MCP clients and quick trials. | Resolves the crate from crates.io and downloads the matching GitHub Release binary. |
+| Cargo install | `cargo install unraid-rmcp --locked` | Persistent CLI installation. | Builds `runraid` from the crates.io source package. |
+| Release installer | `curl -fsSL https://raw.githubusercontent.com/dinglebear-ai/unraid/main/unraid-rs/scripts/install.sh \| bash` | Host installs without CRGX. | Installs `runraid` for linux/amd64. |
+| Docker / Compose | `docker compose up -d` | Shared HTTP MCP deployments. | Reads `.env` and exposes container port `40010`. |
+| Build from source | `cargo build --release` | Development and audits. | Produces `target/release/runraid`. |
+| Plugin | `claude plugin install agents/unraid-rs` | Claude Code local plugin setup from this checkout. | Ships the skill and local runtime metadata. No hooks — run `runraid setup plugin-hook` once to provision credentials. |
+
+### CRGX / crates.io
+
+Run the stdio MCP server or CLI without installing Node or compiling Rust:
+
+```bash
+crgx unraid-rmcp -- --help
+crgx unraid-rmcp -- mcp
+crgx unraid-rmcp -- server --json
+```
+
+CRGX resolves `unraid-rmcp` from crates.io, reads its cargo-binstall metadata,
+and downloads the matching `runraid` archive from the component-prefixed GitHub
+Release. Exact crate versions can be pinned with `unraid-rmcp@<version>`.
+
+The npm launcher remains available only as a compatibility path for existing
+installations; new MCP configurations should use CRGX.
+
+### Build From Source
+
+```bash
+git clone https://github.com/dinglebear-ai/unraid
+cd unraid-mcp/unraid-rs
+cargo build --release
+./target/release/runraid --help
+```
+
+Minimum supported Rust version: 1.90.
+
+## Quickstart
+
+### 1. Configure Unraid
+
+Create an Unraid API key in Settings -> API Management, then set:
+
+```bash
+export UNRAID_API_URL="https://10-1-0-2.<hash>.myunraid.net:31337/graphql"
+export UNRAID_API_KEY="your-api-key-here"
+```
+
+Set `UNRAID_API_SKIP_TLS_VERIFY=true` only when your Unraid GraphQL endpoint uses
+a certificate your host does not trust.
+
+### 2. Run A Safe CLI Call
+
+```bash
+crgx unraid-rmcp -- server --json
+```
+
+### 3. Start Loopback HTTP MCP
+
+```bash
+UNRAID_RMCP_HOST=127.0.0.1 crgx unraid-rmcp -- serve mcp
+```
+
+In another shell:
+
+```bash
+curl -sf http://127.0.0.1:40010/health
+```
+
+### 4. Make A First MCP Call
+
+```bash
+curl -s -X POST http://127.0.0.1:40010/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"unraid","arguments":{"action":"server"}}}'
+```
+
+## Client Configuration
+
+### Claude Code Stdio
+
+```json
+{
+  "mcpServers": {
+    "unraid": {
+      "command": "crgx",
+      "args": ["unraid-rmcp", "--", "mcp"],
+      "env": {
+        "UNRAID_API_URL": "https://10-1-0-2.<hash>.myunraid.net:31337/graphql",
+        "UNRAID_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code HTTP
+
+```json
+{
+  "mcpServers": {
+    "unraid": {
+      "type": "http",
+      "url": "http://127.0.0.1:40010/mcp",
+      "headers": {
+        "Authorization": "Bearer ${UNRAID_RMCP_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### Codex / Labby Gateway
+
+Register Unraid 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.unraid]
+command = "crgx"
+args = ["unraid-rmcp", "--", "mcp"]
+```
+
+### Generic MCP JSON
+
+```json
+{
+  "command": "runraid",
+  "args": ["mcp"],
+  "env": {
+    "UNRAID_API_URL": "https://10-1-0-2.<hash>.myunraid.net:31337/graphql",
+    "UNRAID_API_KEY": "your-api-key-here"
+  }
+}
+```
+
+Do not put `UNRAID_API_KEY`, OAuth secrets, passwords, SSH keys, 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 | `runraid mcp`, `crgx unraid-rmcp -- mcp` | Local child-process MCP clients. |
+| MCP HTTP | Supported | `runraid serve mcp`, `POST /mcp` | Streamable HTTP MCP for local or shared server deployments. |
+| CLI | Supported | `runraid <command>` | Scriptable parity and debugging. |
+| Prompt | Supported | `server_summary` | Guides a model to call `info` and summarize server state. |
+| Resource | Supported | `unraid://schema/mcp-tool` | JSON schema for the `unraid` tool. |
+| Health endpoint | Supported | `GET /health` | Unauthenticated liveness check. |
+| REST API | Not shipped | N/A | Unraid owns the GraphQL API. |
+| Web UI | Not shipped | N/A | Unraid owns the web UI. |
+
+## MCP Tool Reference
+
+One MCP tool is exposed: `unraid`. Pass the required `action` argument to select
+the operation.
+
+### Core Actions
+
+| Action | Description | Required params | Optional params |
+|---|---|---|---|
+| `array` | Array state, disk health, parity check status, and capacity. | none | none |
+| `disks` | Physical disks with SMART status, temperature, size, interface, and partitions. | none | `limit`, `offset`, `name` |
+| `docker` | Docker containers with state, status, ports, and update availability. | none | `limit`, `offset`, `state`, `name` |
+| `docker_logs` | Container log lines. | `id` | `tail` |
+| `vms` | Virtual machines and state. | none | `limit`, `offset`, `state`, `name` |
+| `server` | Server identity, LAN/WAN IP, local/remote URLs, GUID, and online status. | none | none |
+| `info` | OS, CPU, memory layout, Unraid version, and kernel version. | none | none |
+| `shares` | User shares with size, cache settings, and encryption state. | none | `limit`, `offset`, `name` |
+| `notifications` | Active warnings and alerts with overview counts. | none | none |
+
+### System Actions
+
+| Action | Description |
+|---|---|
+| `services` | Running system services with uptime. |
+| `network` | Network access URLs and addresses. |
+| `metrics` | Live CPU, memory, and temperature sensor data. |
+| `vars` | System configuration variables. |
+| `registration` | License type, state, and expiry. |
+| `flash` | USB flash drive details. |
+
+### Log And Storage Actions
+
+| Action | Description | Required params | Optional params |
+|---|---|---|---|
+| `log_files` | Available log files with sizes and modified times. | none | none |
+| `log_file` | Read a log file. | `path` | `lines`, `start_line` |
+| `parity_history` | Past parity check results. | none | none |
+| `rclone` | Backup remote configurations and drive names. | none | none |
+
+### UPS, Remote, Plugin, And Meta Actions
+
+| Action | Description |
+|---|---|
+| `ups` | UPS devices, charge, runtime, and load. |
+| `ups_config` | UPS monitoring configuration. |
+| `remote_access` | WAN access and port forwarding configuration. |
+| `connect` | Unraid Connect dynamic remote access state. |
+| `plugins` | Installed community plugins with versions. |
+| `status` | Server observability: version, PID, uptime, and counters. |
+| `help` | Markdown reference for all actions. |
+
+Pagination and filtering are MCP-only. List actions return a paginated envelope
+with `items`, `total`, `limit`, `offset`, `has_more`, and `next_offset`.
+
+## CLI Reference
+
+All CLI commands accept `--json` for machine-readable output.
+
+```bash
+runraid array [--json]
+runraid disks [--json]
+runraid docker [--json]
+runraid docker logs <id> [--tail N] [--json]
+runraid vms [--json]
+runraid server [--json]
+runraid info [--json]
+runraid shares [--json]
+runraid notifications [--json]
+runraid services [--json]
+runraid network [--json]
+runraid metrics [--json]
+runraid vars [--json]
+runraid registration [--json]
+runraid flash [--json]
+runraid log-files [--json]
+runraid log <path> [--lines N] [--start-line N] [--json]
+runraid parity-history [--json]
+runraid rclone [--json]
+runraid ups [--json]
+runraid ups-config [--json]
+runraid remote-access [--json]
+runraid connect [--json]
+runraid plugins [--json]
+runraid doctor [--json]
+runraid setup check [--json]
+runraid setup repair [--json]
+```
+
+`status` is MCP-only; `setup` and `doctor` are CLI-only.
+
+## Configuration
+
+Host installs read `~/.unraid/.env` before loading config. Containers read
+`/data/.env`. Process environment overrides both.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `UNRAID_API_URL` | unset | Full Unraid GraphQL endpoint URL. |
+| `UNRAID_API_KEY` | unset | API key for the `x-api-key` header. |
+| `UNRAID_API_SKIP_TLS_VERIFY` | `false` | Skip TLS certificate verification for self-signed endpoints. |
+| `UNRAID_RMCP_HOST` | `0.0.0.0` | HTTP bind host. |
+| `UNRAID_RMCP_PORT` | `40010` | HTTP bind port. |
+| `UNRAID_RMCP_SERVER_NAME` | `unraid-rmcp` | Advertised MCP server name. |
+| `UNRAID_RMCP_TOKEN` | unset | Static bearer token for HTTP MCP. |
+| `UNRAID_RMCP_NO_AUTH` | `false` | Disable auth only for loopback development. |
+| `UNRAID_RMCP_DISABLE_HTTP_AUTH` | `false` | Compatibility alias for disabling auth. |
+| `UNRAID_NOAUTH` | `false` | Trust an upstream gateway to enforce auth. |
+| `UNRAID_RMCP_ALLOWED_HOSTS` | unset | Extra accepted Host header values. |
+| `UNRAID_RMCP_ALLOWED_ORIGINS` | unset | Extra accepted CORS origins. |
+| `UNRAID_RMCP_PUBLIC_URL` | unset | Public URL for OAuth metadata. |
+| `UNRAID_RMCP_AUTH_MODE` | `bearer` | `bearer` or `oauth`. |
+| `UNRAID_RMCP_GOOGLE_CLIENT_ID` | unset | Google OAuth client ID. |
+| `UNRAID_RMCP_GOOGLE_CLIENT_SECRET` | unset | Google OAuth client secret. |
+| `UNRAID_RMCP_AUTH_ADMIN_EMAIL` | unset | Admin email for OAuth bootstrap. |
+
+## Authentication
+
+Stdio MCP runs as a local trusted child process and does not use HTTP auth.
+
+HTTP MCP auth policy:
+
+| State | Condition | Behavior |
+|---|---|---|
+| Loopback dev | `UNRAID_RMCP_HOST` starts with `127.` or auth is explicitly disabled on loopback | Local unauthenticated development is allowed. |
+| Mounted bearer | Non-loopback with `UNRAID_RMCP_TOKEN` | Requires `Authorization: Bearer <token>` and action scopes. |
+| Mounted OAuth | `UNRAID_RMCP_AUTH_MODE=oauth` | Uses Google OAuth/JWT through `lab-auth`. |
+| Trusted gateway | `UNRAID_NOAUTH=true` | Assumes a reverse proxy or gateway already enforced auth. |
+
+Read actions require `unraid:read`; mutating actions require `unraid:admin`.
+Configured static bearer tokens are operator credentials and receive admin scope.
+OAuth clients receive the scopes granted by the authorization flow.
+
+## Safety And Trust Model
+
+- Unraid API keys are loaded from config/env only.
+- MCP callers select actions and arguments, not upstream credentials.
+- Destructive actions issue an MCP form-elicitation request before dispatch. A
+  decline, cancellation, malformed response, or client without elicitation support
+  stops the operation before the GraphQL request is sent.
+- Ordinary mutations remain directly available after `unraid:admin` authorization;
+  the server does not add a second confirmation parameter or disable writes.
+- `log_file` reads through the Unraid GraphQL API, not arbitrary local files.
+- Non-loopback HTTP deployments must use bearer auth, OAuth, or a trusted
+  authenticated gateway.
+- This bridge does not sandbox Unraid itself. Unraid remains responsible for API
+  permissions and GraphQL response semantics.
+
+## Architecture
+
+```text
+GraphQL operations (src/graphql.rs)  queries + mutations
+        |
+UnraidService (src/app.rs)           action behavior and response shaping
+        |
+MCP scope + elicitation              authorization and destructive approval
+        |
+MCP shim      (src/mcp/tools.rs)     JSON args -> service -> Value
+CLI shim      (src/cli.rs)           argv -> service -> stdout
+```
+
+## Distribution Contract
+
+- `Cargo.toml`, `Cargo.lock`, both `version` and `binaryVersion` in
+  `packages/unraid-rmcp/package.json`, `.release-please-manifest.json`, agent
+  manifests, and `server.json` must agree on the released version.
+- crates.io publishes `lab-auth` first and `unraid-rmcp` second through
+  `.github/workflows/crates-publish.yml`; automatic publication stays disabled
+  until `CRATES_IO_PUBLISHING_ENABLED=true` and the `crates-io` environment holds
+  `CARGO_REGISTRY_TOKEN`.
+- GitHub Releases publish the linux/amd64 `runraid` archive consumed by CRGX and
+  cargo-binstall through the manifest metadata in `Cargo.toml`.
+- The npm package remains a compatibility surface only. Automatic npm publishing
+  is enabled only when `NPM_TRUSTED_PUBLISHING_ENABLED=true`.
+- Docker/OCI metadata uses `ghcr.io/dinglebear-ai/unraid-rmcp:<version>`.
+- `agents/unraid-rs/.mcp.json` must launch `crgx unraid-rmcp -- mcp` so stdio
+  clients resolve the crates.io package without requiring Node.
+- The root README is curated. `docs/INVENTORY.md` is the curated inventory for
+  actions, CLI commands, env vars, HTTP endpoints, and dependencies.
+
+## Development
+
+```bash
+cargo fmt --check
+cargo test
+cargo clippy -- -D warnings
+cargo build --release
+npm --prefix packages/unraid-rmcp run check
+```
+
+## Verification
+
+```bash
+python3 /home/jmagar/workspace/soma/scripts/check-readme-guide.py README.md
+npm --prefix packages/unraid-rmcp run check
+cargo check
+cargo test
+git diff --check
+```
+
+Runtime smoke:
+
+```bash
+UNRAID_API_URL=https://10-1-0-2.<hash>.myunraid.net:31337/graphql \
+UNRAID_API_KEY=... \
+runraid server --json
+```
+
+HTTP smoke:
+
+```bash
+UNRAID_RMCP_HOST=127.0.0.1 runraid serve mcp
+curl -sf http://127.0.0.1:40010/health
+```
+
+## Deployment
+
+Use loopback for local development:
+
+```bash
+UNRAID_RMCP_HOST=127.0.0.1 runraid serve mcp
+```
+
+Use Docker Compose for shared HTTP deployment:
+
+```bash
+cp .env.example .env
+docker compose up -d
+```
+
+When binding to a non-loopback address, configure `UNRAID_RMCP_TOKEN`,
+`UNRAID_RMCP_AUTH_MODE=oauth`, or `UNRAID_NOAUTH=true` behind an authenticated
+gateway.
+
+## Troubleshooting
+
+| Symptom | Check |
+|---|---|
+| `UNRAID_API_URL` or `UNRAID_API_KEY` is missing | Set it in env or `~/.unraid/.env`. |
+| TLS errors against Unraid | Set `UNRAID_API_SKIP_TLS_VERIFY=true` only for self-signed endpoints. |
+| HTTP `/mcp` returns unauthorized | Set `UNRAID_RMCP_TOKEN` and send `Authorization: Bearer <token>`. |
+| Stdio client hangs or logs JSON errors | Ensure client config runs `unraid-rmcp mcp`, not the default HTTP server mode. |
+| Large list response is truncated | Use `limit`, `offset`, `name`, or `state` filters on MCP list actions. |
+| `docker_logs` fails | Pass a valid container `id` and optional `tail`. |
+
+## Related Servers
+
+- [soma](https://github.com/jmagar/soma) - RMCP runtime for provider-backed MCP servers.
+- [unifi-rmcp](https://github.com/jmagar/runifi) - UniFi controller REST API bridge.
+- [tailscale-rmcp](https://github.com/jmagar/rtailscale) - Tailscale API bridge for devices, users, and tailnet operations.
+- [apprise-rmcp](https://github.com/jmagar/rapprise) - Apprise notification fan-out bridge for many delivery backends.
+- [gotify-rmcp](https://github.com/jmagar/rgotify) - Gotify push notification bridge for sends, messages, apps, and clients.
+- [arcane-rmcp](https://github.com/jmagar/rarcane) - Arcane Docker management bridge for containers and related resources.
+- [yarr](https://github.com/jmagar/yarr) - Media-stack bridge for Sonarr, Radarr, Prowlarr, Plex, and related services.
+- [ytdl-rmcp](https://github.com/jmagar/rytdl) - Media download and metadata workflow server.
+- [synapse-rmcp](https://github.com/jmagar/synapse) - Local Synapse workflow server for scout and flux actions.
+- [cortex](https://github.com/jmagar/cortex) - Syslog and homelab log aggregation MCP server.
+- [axon](https://github.com/jmagar/axon) - RAG, crawl, scrape, extract, and semantic search project.
+- [labby](https://github.com/jmagar/labby) - Homelab control plane and MCP gateway project.
+- [lumen](https://github.com/jmagar/lumen) - Local semantic code search MCP server.
+
+## Documentation
+
+- `CLAUDE.md` is the curated local operating guide for contributors and agents.
+- `docs/INVENTORY.md` is the curated/generated inventory for actions, CLI
+  commands, env vars, HTTP endpoints, and dependencies.
+- `docs/stack/ARCH.md` is the curated architecture guide.
+- `agents/unraid-rs/skills/unraid/SKILL.md` is the agent usage guide.
+- `src/` is the source of truth for current GraphQL queries, config defaults,
+  auth behavior, and CLI parsing.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/bin/runraid.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+"use strict";
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { binaryPath } = require("../lib/platform");
+function fail(message) { process.stderr.write(`unraid-rmcp: ${message}\n`); process.exit(1); }
+const binary = binaryPath();
+if (!fs.existsSync(binary)) {
+  const installer = path.resolve(__dirname, "..", "scripts", "install.js");
+  const install = spawnSync(process.execPath, [installer], { stdio: "inherit" });
+  if (install.status !== 0) fail("binary is not installed; postinstall may have failed");
+}
+const child = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+if (child.error) fail(child.error.message);
+if (child.signal) process.kill(process.pid, child.signal);
+else process.exit(child.status ?? 1);

package/lib/platform.js

@@ -0,0 +1,51 @@
+"use strict";
+
+const path = require("node:path");
+
+function packageVersion() {
+  return require("../package.json").version;
+}
+
+function binaryVersion() {
+  return require("../package.json").binaryVersion || packageVersion();
+}
+
+function targetFor(platform = process.platform, arch = process.arch) {
+  if (platform === "linux" && arch === "x64") {
+    return { asset: "runraid-x86_64.tar.gz", binary: "runraid" };
+  }
+  throw new Error(`Unsupported platform ${platform}/${arch}. Supported target: linux/x64.`);
+}
+
+// Release tags in the unraid-mcp monorepo are component-prefixed: the Rust
+// server publishes `unraid-rs-v<semver>` (see .github/workflows/rust-release.yml),
+// while bare `v<semver>` tags belong to the Python server. Accept a bare or
+// v-prefixed version for backwards compatibility and normalise to the tag the
+// monorepo actually creates.
+const RELEASE_TAG_PREFIX = "unraid-rs-v";
+
+function releaseVersion(env = process.env) {
+  const raw = env.UNRAID_RMCP_BINARY_VERSION || env.UNRAID_RMCP_VERSION || binaryVersion();
+  if (raw.startsWith(RELEASE_TAG_PREFIX)) return raw;
+  return `${RELEASE_TAG_PREFIX}${raw.startsWith("v") ? raw.slice(1) : raw}`;
+}
+
+function releaseBaseUrl(env = process.env) {
+  const repo = env.UNRAID_RMCP_REPO || "dinglebear-ai/unraid";
+  return env.UNRAID_RMCP_RELEASE_BASE_URL || `https://github.com/${repo}/releases/download`;
+}
+
+function downloadUrl(target, env = process.env) {
+  return `${releaseBaseUrl(env)}/${releaseVersion(env)}/${target.asset}`;
+}
+
+function installRoot() {
+  return path.resolve(__dirname, "..", "vendor");
+}
+
+function binaryPath(platform = process.platform, arch = process.arch) {
+  const target = targetFor(platform, arch);
+  return path.join(installRoot(), target.binary);
+}
+
+module.exports = { binaryPath, binaryVersion, downloadUrl, releaseBaseUrl, installRoot, packageVersion, releaseVersion, targetFor };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@dinglebear/unraid",
+  "version": "0.2.5",
+  "description": "Rust MCP server and CLI for Unraid GraphQL operations across NAS, Docker, VM, and storage workflows.",
+  "license": "MIT",
+  "homepage": "https://github.com/dinglebear-ai/unraid#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dinglebear-ai/unraid.git",
+    "directory": "unraid-rs/packages/unraid-rmcp"
+  },
+  "bugs": {
+    "url": "https://github.com/dinglebear-ai/unraid/issues"
+  },
+  "bin": {
+    "unraid-rmcp": "bin/runraid.js",
+    "runraid": "bin/runraid.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/",
+    "README.md",
+    "LICENSE*",
+    "package.json"
+  ],
+  "scripts": {
+    "prepack": "node scripts/sync-readme.js",
+    "postinstall": "node scripts/install.js",
+    "test": "node --test",
+    "check": "node --check bin/runraid.js && node --check scripts/install.js && node --check lib/platform.js && node --check scripts/sync-readme.js && node --check scripts/check-package.js && node scripts/check-package.js",
+    "prepublishOnly": "node scripts/check-package.js --release"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "rmcp",
+    "rust",
+    "unraid",
+    "nas",
+    "graphql",
+    "storage",
+    "docker",
+    "virtualization",
+    "homelab",
+    "cli",
+    "claude-code",
+    "codex",
+    "gemini",
+    "automation",
+    "oauth"
+  ],
+  "mcpName": "ai.dinglebear/unraid",
+  "binaryVersion": "0.2.5",
+  "author": {
+    "name": "dinglebear.ai",
+    "url": "https://dinglebear.ai"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/check-package.js

@@ -0,0 +1,490 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const https = require("node:https");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const packageRoot = path.resolve(__dirname, "..");
+const repoRoot = path.resolve(packageRoot, "..", "..");
+// Canonical home of this package after the monorepo consolidation.
+const CANONICAL_REPO = "dinglebear-ai/unraid";
+const REPOSITORY_DIRECTORY = "unraid-rs/packages/unraid-rmcp";
+const packageJsonPath = path.join(packageRoot, "package.json");
+const packageJson = readJson(packageJsonPath);
+const expectedPackageName = "@dinglebear/unraid";
+const releaseMode = process.argv.includes("--release");
+const skipReleaseAssets = process.argv.includes("--skip-release-assets");
+
+const failures = [];
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function fail(message) {
+  failures.push(message);
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    fail(message);
+  }
+}
+
+function normalizeRepoUrl(url) {
+  return String(url || "")
+    .replace(/^git\+/, "")
+    .replace(/#readme$/, "")
+    .replace(/\.git$/, "")
+    .replace(/\/$/, "");
+}
+
+function normalizeHomepage(url) {
+  return String(url || "").replace(/#readme$/, "").replace(/\/$/, "");
+}
+
+function repoLicenseFiles() {
+  return fs
+    .readdirSync(repoRoot)
+    .filter((entry) => /^licen[cs]e/i.test(entry))
+    .filter((entry) => fs.statSync(path.join(repoRoot, entry)).isFile())
+    .sort();
+}
+
+function compareFiles(left, right) {
+  if (!fs.existsSync(left) || !fs.existsSync(right)) {
+    return false;
+  }
+
+  return fs.readFileSync(left).equals(fs.readFileSync(right));
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd || packageRoot,
+    env: options.env || process.env,
+    encoding: "utf8",
+    stdio: options.stdio || ["ignore", "pipe", "pipe"],
+  });
+
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || `${command} ${args.join(" ")} failed`).trim();
+    throw new Error(detail);
+  }
+
+  return result;
+}
+
+function checkSyncedFiles() {
+  assert(
+    compareFiles(path.join(repoRoot, "README.md"), path.join(packageRoot, "README.md")),
+    "package README.md must be byte-identical to the repo README.md; run npm pack or scripts/sync-readme.js",
+  );
+
+  const licenses = repoLicenseFiles();
+  assert(licenses.length > 0, "repo must have at least one LICENSE file to sync into the npm package");
+
+  for (const license of licenses) {
+    assert(
+      compareFiles(path.join(repoRoot, license), path.join(packageRoot, license)),
+      `package ${license} must be byte-identical to repo ${license}; run npm pack or scripts/sync-readme.js`,
+    );
+  }
+}
+
+function findNpmPackage(serverJson) {
+  return (serverJson.packages || []).find(
+    (entry) => entry.registryType === "npm" || entry.identifier === packageJson.name,
+  );
+}
+
+function checkMetadata() {
+  const serverPath = path.join(repoRoot, "server.json");
+  assert(fs.existsSync(serverPath), "repo must contain server.json for package metadata checks");
+
+  if (!fs.existsSync(serverPath)) {
+    return;
+  }
+
+  const serverJson = readJson(serverPath);
+  const npmPackage = findNpmPackage(serverJson);
+  const repoUrl = normalizeRepoUrl(packageJson.repository && packageJson.repository.url);
+  const serverRepoUrl = normalizeRepoUrl(serverJson.repository && serverJson.repository.url);
+  const homepage = normalizeHomepage(packageJson.homepage);
+  const serverWebsite = normalizeHomepage(serverJson.websiteUrl);
+
+  assert(packageJson.name, "package.json must include name");
+  assert(
+    packageJson.name === expectedPackageName,
+    "package.json name must match the dinglebear organization package",
+  );
+  assert(
+    packageJson.publishConfig && packageJson.publishConfig.access === "public",
+    "scoped npm package must publish with public access",
+  );
+  assert(packageJson.version, "package.json must include version");
+  assert(packageJson.description, "package.json must include description");
+  assert(packageJson.license, "package.json must include license");
+  assert(packageJson.author && packageJson.author.name === "dinglebear.ai", "package.json author must be dinglebear.ai");
+  assert(packageJson.engines && packageJson.engines.node, "package.json must declare engines.node");
+  assert(packageJson.repository && packageJson.repository.type === "git", "package.json repository.type must be git");
+  assert(packageJson.repository && packageJson.repository.directory, "package.json repository.directory must point at this package");
+  assert(
+    packageJson.repository && packageJson.repository.directory === REPOSITORY_DIRECTORY,
+    "package.json repository.directory must match its monorepo path",
+  );
+  assert(packageJson.bugs && packageJson.bugs.url, "package.json must include bugs.url");
+  assert(packageJson.mcpName === serverJson.name, "package.json mcpName must match server.json name");
+  assert(
+    packageJson.description === serverJson.description,
+    "package.json description must match server.json description",
+  );
+  assert(repoUrl === serverRepoUrl, `package repository ${repoUrl} must match server.json repository ${serverRepoUrl}`);
+  assert(homepage === serverWebsite, `package homepage ${homepage} must match server.json websiteUrl ${serverWebsite}`);
+  // Anchor the URLs to the canonical monorepo. Asserting only that package.json
+  // and server.json agree with EACH OTHER let both drift to the pre-consolidation
+  // repo (jmagar/runraid) while CI stayed green.
+  for (const [label, value] of [["package repository", repoUrl], ["server.json repository", serverRepoUrl], ["package homepage", homepage], ["server.json websiteUrl", serverWebsite]]) {
+    assert(
+      typeof value === "string" && value.includes(`/${CANONICAL_REPO}`),
+      `${label} must point at ${CANONICAL_REPO} (got ${value})`,
+    );
+  }
+  assert(serverJson.version === packageJson.version, `package version ${packageJson.version} must match server.json version ${serverJson.version}`);
+
+  if (npmPackage) {
+    assert(npmPackage.identifier === packageJson.name, "server.json npm package identifier must match package name");
+    assert(npmPackage.version === packageJson.version, "server.json npm package version must match package version");
+  } else {
+    fail("server.json must include an npm package entry");
+  }
+
+  const publisherMeta = serverJson._meta && serverJson._meta["io.modelcontextprotocol.registry/publisher-provided"];
+  const distribution = publisherMeta && publisherMeta.distribution;
+  if (distribution) {
+    if (distribution.npm) {
+      assert(
+        distribution.npm === `${packageJson.name}@${packageJson.version}`,
+        `server.json distribution.npm must be ${packageJson.name}@${packageJson.version}`,
+      );
+    }
+    if (distribution.nodePackage) {
+      assert(distribution.nodePackage === packageJson.name, "server.json distribution.nodePackage must match package name");
+    }
+  }
+
+  for (const keyword of ["mcp", "mcp-server", "model-context-protocol"]) {
+    assert(Array.isArray(packageJson.keywords) && packageJson.keywords.includes(keyword), `package keywords must include ${keyword}`);
+  }
+
+  for (const field of ["bin/", "scripts/", "README.md", "LICENSE*", "package.json"]) {
+    assert(Array.isArray(packageJson.files) && packageJson.files.includes(field), `package files must include ${field}`);
+  }
+
+  assert(packageJson.scripts && packageJson.scripts.prepack === "node scripts/sync-readme.js", "package prepack must sync README/LICENSE files");
+  assert(packageJson.scripts && packageJson.scripts.prepublishOnly === "node scripts/check-package.js --release", "package prepublishOnly must run the release gate");
+  assert(packageJson.scripts && packageJson.scripts.check && packageJson.scripts.check.includes("node scripts/check-package.js"), "package check must run the package verifier");
+}
+
+function assertRuntimeScriptsDoNotEscapePackage() {
+  const runtimeScripts = [packageJson.scripts && packageJson.scripts.postinstall].filter(Boolean);
+  for (const script of runtimeScripts) {
+    assert(!script.includes("../"), `runtime npm script must not reference files outside the package: ${script}`);
+  }
+
+  const runtimeFiles = [];
+  if (packageJson.bin) {
+    for (const relative of Object.values(packageJson.bin)) {
+      runtimeFiles.push(relative);
+    }
+  }
+  for (const relative of ["scripts/install.js", "lib/platform.js"]) {
+    const absolute = path.join(packageRoot, relative);
+    if (fs.existsSync(absolute)) {
+      runtimeFiles.push(relative);
+    }
+  }
+
+  for (const relative of new Set(runtimeFiles)) {
+    const text = fs.readFileSync(path.join(packageRoot, relative), "utf8");
+    assert(!text.includes('"..", ".."'), `${relative} must not resolve paths outside the package at runtime`);
+    assert(!text.includes("'..', '..'"), `${relative} must not resolve paths outside the package at runtime`);
+  }
+
+  const installer = path.join(packageRoot, "scripts", "install.js");
+  if (fs.existsSync(installer)) {
+    const text = fs.readFileSync(installer, "utf8");
+    assert(text.includes("verifyChecksum"), "postinstall downloader must verify release checksums");
+    assert(text.includes("sha256"), "postinstall downloader must validate SHA-256 checksums");
+  }
+}
+
+function packTarball(tempDir) {
+  run("npm", ["pack", packageRoot, "--pack-destination", tempDir], { cwd: packageRoot });
+  const tarballs = fs.readdirSync(tempDir).filter((entry) => entry.endsWith(".tgz"));
+  assert(tarballs.length === 1, "npm pack must produce exactly one tarball");
+  return path.join(tempDir, tarballs[0]);
+}
+
+function tarList(tarball) {
+  return run("tar", ["-tzf", tarball]).stdout.trim().split(/\n+/).filter(Boolean);
+}
+
+function tarExtract(tarball, entry) {
+  return run("tar", ["-xOzf", tarball, entry]).stdout;
+}
+
+function checkPacklist(tarball) {
+  const entries = tarList(tarball);
+  const allowedPrefixes = ["package/bin/", "package/lib/", "package/scripts/"];
+  const allowedExact = new Set(["package/package.json", "package/README.md"]);
+
+  for (const license of repoLicenseFiles()) {
+    allowedExact.add(`package/${license}`);
+  }
+
+  for (const required of allowedExact) {
+    assert(entries.includes(required), `packed tarball missing ${required}`);
+  }
+
+  const forbiddenFragments = [
+    "node_modules",
+    "vendor/",
+    "test/",
+    ".env",
+    "Cargo.",
+    "target/",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    ".tgz",
+  ];
+
+  for (const entry of entries) {
+    const allowed = allowedExact.has(entry) || allowedPrefixes.some((prefix) => entry.startsWith(prefix));
+    assert(allowed, `packed tarball contains unexpected file ${entry}`);
+    for (const fragment of forbiddenFragments) {
+      assert(!entry.includes(fragment), `packed tarball must not contain ${entry}`);
+    }
+  }
+
+  assert(
+    Buffer.from(tarExtract(tarball, "package/README.md")).equals(fs.readFileSync(path.join(repoRoot, "README.md"))),
+    "packed README.md must match repo README.md",
+  );
+
+  for (const license of repoLicenseFiles()) {
+    assert(
+      Buffer.from(tarExtract(tarball, `package/${license}`)).equals(fs.readFileSync(path.join(repoRoot, license))),
+      `packed ${license} must match repo ${license}`,
+    );
+  }
+}
+
+function writeSmokeBinary(destination) {
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.writeFileSync(
+    destination,
+    "#!/usr/bin/env node\nprocess.stdout.write(`package-smoke-ok ${process.argv.slice(2).join(\" \")}\\n`);\n",
+    { mode: 0o755 },
+  );
+  fs.chmodSync(destination, 0o755);
+}
+
+function checkInstalledBins(installRoot) {
+  const installedPackageRoot = path.join(installRoot, "node_modules", packageJson.name);
+  assert(fs.existsSync(installedPackageRoot), "tarball install must create package under node_modules");
+
+  const env = { ...process.env };
+  if (packageJson.name === "soma-rmcp") {
+    const fakeBinary = path.join(installRoot, "fake-soma");
+    writeSmokeBinary(fakeBinary);
+    env.SOMA_BIN = fakeBinary;
+  } else {
+    const platformPath = path.join(installedPackageRoot, "lib", "platform.js");
+    assert(fs.existsSync(platformPath), "downloaded-binary packages must include lib/platform.js");
+    if (fs.existsSync(platformPath)) {
+      const platform = require(platformPath);
+      writeSmokeBinary(platform.binaryPath());
+    }
+  }
+
+  for (const [name, relative] of Object.entries(packageJson.bin || {})) {
+    const binPath = path.join(installedPackageRoot, relative);
+    const result = spawnSync(process.execPath, [binPath, "--package-smoke"], {
+      cwd: installRoot,
+      env,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const output = `${result.stdout || ""}${result.stderr || ""}`;
+    assert(result.status === 0, `${name} bin smoke exited ${result.status}: ${output.trim()}`);
+    assert(output.includes("package-smoke-ok --package-smoke"), `${name} bin smoke did not invoke the installed binary`);
+  }
+}
+
+function checkTarballInstallSmoke(tarball, tempDir) {
+  const installRoot = path.join(tempDir, "consumer");
+  fs.mkdirSync(installRoot, { recursive: true });
+  run("npm", ["install", "--ignore-scripts", "--prefix", installRoot, tarball], { cwd: tempDir });
+  checkInstalledBins(installRoot);
+}
+
+function supportedTargets(platform) {
+  const tuples = [
+    ["linux", "x64"],
+    ["win32", "x64"],
+    ["darwin", "x64"],
+    ["darwin", "arm64"],
+  ];
+  const targets = [];
+  for (const [osName, arch] of tuples) {
+    try {
+      const target = platform.targetFor(osName, arch);
+      targets.push({ osName, arch, target });
+    } catch (_) {
+      // Unsupported target; ignore.
+    }
+  }
+  return targets;
+}
+
+function requestHead(url, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    const request = https.request(url, { method: "HEAD" }, (response) => {
+      if ([301, 302, 303, 307, 308].includes(response.statusCode) && response.headers.location) {
+        response.resume();
+        if (redirects > 8) {
+          reject(new Error(`too many redirects for ${url}`));
+          return;
+        }
+        requestHead(new URL(response.headers.location, url).toString(), redirects + 1).then(resolve, reject);
+        return;
+      }
+
+      response.resume();
+      resolve(response.statusCode);
+    });
+
+    request.setTimeout(15000, () => {
+      request.destroy(new Error(`timeout checking ${url}`));
+    });
+    request.on("error", reject);
+    request.end();
+  });
+}
+
+function requestText(url, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, (response) => {
+        if ([301, 302, 303, 307, 308].includes(response.statusCode) && response.headers.location) {
+          response.resume();
+          if (redirects > 8) {
+            reject(new Error(`too many redirects for ${url}`));
+            return;
+          }
+          requestText(new URL(response.headers.location, url).toString(), redirects + 1).then(resolve, reject);
+          return;
+        }
+
+        if (response.statusCode < 200 || response.statusCode >= 300) {
+          response.resume();
+          reject(new Error(`${url} returned ${response.statusCode}`));
+          return;
+        }
+
+        let body = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          body += chunk;
+        });
+        response.on("end", () => resolve(body));
+      })
+      .on("error", reject)
+      .setTimeout(15000, function onTimeout() {
+        this.destroy(new Error(`timeout checking ${url}`));
+      });
+  });
+}
+
+function checksumManifestUrl(assetUrl) {
+  return assetUrl.replace(/\/[^/]+$/, "/SHA256SUMS");
+}
+
+async function hasChecksumFor(url, asset) {
+  const sidecarStatus = await requestHead(`${url}.sha256`);
+  if (sidecarStatus >= 200 && sidecarStatus < 300) {
+    return true;
+  }
+
+  const manifestUrl = checksumManifestUrl(url);
+  const manifest = await requestText(manifestUrl);
+  return manifest
+    .trim()
+    .split(/\r?\n/)
+    .some((line) => {
+      const parts = line.trim().split(/\s+/);
+      const hash = parts[0] && parts[0].toLowerCase();
+      const name = parts.slice(1).join(" ").replace(/^\*/, "");
+      return /^[a-f0-9]{64}$/.test(hash) && path.basename(name) === asset;
+    });
+}
+
+async function checkReleaseAssets() {
+  if (skipReleaseAssets || !releaseMode) {
+    return;
+  }
+
+  const platformPath = path.join(packageRoot, "lib", "platform.js");
+  if (!fs.existsSync(platformPath)) {
+    return;
+  }
+
+  const platform = require(platformPath);
+  if (typeof platform.downloadUrl !== "function" || typeof platform.targetFor !== "function") {
+    return;
+  }
+
+  for (const { osName, arch, target } of supportedTargets(platform)) {
+    const url = platform.downloadUrl(target);
+    const status = await requestHead(url);
+    assert(status >= 200 && status < 300, `release asset missing for ${osName}/${arch}: ${url} returned ${status}`);
+    assert(await hasChecksumFor(url, target.asset), `release checksum missing for ${osName}/${arch}: ${target.asset}`);
+  }
+}
+
+async function main() {
+  checkSyncedFiles();
+  checkMetadata();
+  assertRuntimeScriptsDoNotEscapePackage();
+
+  const packageTempLabel = packageJson.name.replace(/[^A-Za-z0-9._-]/g, "-");
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `${packageTempLabel}-package-check-`));
+  try {
+    const tarball = packTarball(tempDir);
+    checkPacklist(tarball);
+    checkTarballInstallSmoke(tarball, tempDir);
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+
+  await checkReleaseAssets();
+
+  if (failures.length > 0) {
+    for (const failure of failures) {
+      process.stderr.write(`package-check: ${failure}\n`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  process.stdout.write(`package-check: ${packageJson.name} ok\n`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`package-check: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/scripts/install.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+"use strict";
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const http = require("node:http");
+const https = require("node:https");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { binaryPath, downloadUrl, installRoot, releaseVersion, targetFor } = require("../lib/platform");
+function log(message) { process.stderr.write(`unraid-rmcp: ${message}\n`); }
+function download(url, destination) {
+  return new Promise((resolve, reject) => {
+    const client = url.startsWith("http:") ? http : https;
+    const request = client.get(url, (response) => {
+      if ([301, 302, 303, 307, 308].includes(response.statusCode)) { response.resume(); download(response.headers.location, destination).then(resolve, reject); return; }
+      if (response.statusCode !== 200) { response.resume(); reject(new Error(`download failed (${response.statusCode}) from ${url}`)); return; }
+      const file = fs.createWriteStream(destination, { mode: 0o600 });
+      response.pipe(file);
+      file.on("finish", () => file.close(resolve));
+      file.on("error", reject);
+    });
+    request.on("error", reject);
+  });
+}
+function sha256(file) {
+  const hash = crypto.createHash("sha256");
+  hash.update(fs.readFileSync(file));
+  return hash.digest("hex");
+}
+
+function checksumFromText(text, asset) {
+  const lines = text.trim().split(/\r?\n/).filter(Boolean);
+  for (const line of lines) {
+    const parts = line.trim().split(/\s+/);
+    const hash = parts[0] && parts[0].toLowerCase();
+    const name = parts.slice(1).join(" ").replace(/^\*/, "");
+    if (/^[a-f0-9]{64}$/.test(hash) && (!asset || !name || path.basename(name) === asset)) {
+      return hash;
+    }
+  }
+  throw new Error("checksum file does not contain a SHA-256 entry for " + asset);
+}
+
+async function verifyChecksum(url, archive) {
+  const asset = path.basename(archive);
+  const sidecarFile = archive + ".sha256";
+  let expected;
+
+  try {
+    await download(url + ".sha256", sidecarFile);
+    expected = checksumFromText(fs.readFileSync(sidecarFile, "utf8"), asset);
+  } catch (sidecarError) {
+    const manifestUrl = url.replace(/\/[^/]+$/, "/SHA256SUMS");
+    const manifestFile = archive + ".SHA256SUMS";
+    await download(manifestUrl, manifestFile);
+    expected = checksumFromText(fs.readFileSync(manifestFile, "utf8"), asset);
+  }
+
+  const actual = sha256(archive);
+  if (actual !== expected) {
+    throw new Error("checksum mismatch for " + asset + ": expected " + expected + ", got " + actual);
+  }
+
+  log("verified checksum for " + asset);
+}
+
+function extract(archive, destination) {
+  fs.rmSync(destination, { recursive: true, force: true });
+  fs.mkdirSync(destination, { recursive: true });
+  const result = spawnSync("tar", ["-xzf", archive, "-C", destination], { encoding: "utf8" });
+  if (result.status !== 0) throw new Error((result.stderr || result.stdout || "tar extraction failed").trim());
+}
+async function main() {
+  if (process.env.UNRAID_RMCP_SKIP_DOWNLOAD === "1") { log("skipping binary download because UNRAID_RMCP_SKIP_DOWNLOAD=1"); return; }
+  const target = targetFor();
+  const destination = binaryPath();
+  if (fs.existsSync(destination)) { log(`${path.basename(destination)} already installed for ${releaseVersion()}`); return; }
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "unraid-rmcp-install-"));
+  const archive = path.join(tempDir, target.asset);
+  try {
+    const url = downloadUrl(target);
+    log(`downloading ${url}`);
+    await download(url, archive);
+    await verifyChecksum(url, archive);
+    extract(archive, installRoot());
+    fs.chmodSync(destination, 0o755);
+    log(`installed ${destination}`);
+  } finally { fs.rmSync(tempDir, { recursive: true, force: true }); }
+}
+main().catch((error) => { log(error.message); process.exitCode = 1; });

package/scripts/sync-readme.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const packageReadme = path.resolve(__dirname, "..", "README.md");
+const repoReadme = path.resolve(__dirname, "..", "..", "..", "README.md");
+const packageRoot = path.resolve(__dirname, "..");
+const repoRoot = path.resolve(__dirname, "..", "..", "..");
+
+if (fs.existsSync(packageReadme) && fs.lstatSync(packageReadme).isSymbolicLink()) {
+  fs.unlinkSync(packageReadme);
+}
+
+fs.copyFileSync(repoReadme, packageReadme);
+
+for (const entry of fs.readdirSync(repoRoot)) {
+  const source = path.join(repoRoot, entry);
+  if (/^licen[cs]e/i.test(entry) && fs.statSync(source).isFile()) {
+    const destination = path.join(packageRoot, entry);
+    if (fs.existsSync(destination) && fs.lstatSync(destination).isSymbolicLink()) {
+      fs.unlinkSync(destination);
+    }
+    fs.copyFileSync(source, destination);
+  }
+}