unraidclaw 0.1.14 → 0.1.16

package/README.md

@@ -1,6 +1,6 @@
 # unraidclaw
 
-> OpenClaw plugin to manage your Unraid server through AI agents — Docker, VMs, array, shares, system, notifications, and more, with permission control.
+> OpenClaw plugin to manage your Unraid server through AI agents: Docker, VMs, array, shares, system, notifications, and more, with permission control.
 
 [![npm](https://img.shields.io/npm/v/unraidclaw)](https://www.npmjs.com/package/unraidclaw)
 
@@ -8,22 +8,30 @@ This is the [OpenClaw](https://github.com/openclaw/openclaw) plugin for **[Unrai
 
 ## Prerequisites
 
-1. **The UnraidClaw plugin installed on your Unraid server** — install it from the Unraid Community Apps store, or see the [main repo](https://github.com/emaspa/unraidclaw). It runs the gateway on port `9876` (HTTPS).
-2. **An UnraidClaw API key** — generate one on the **Settings → UnraidClaw** page in the Unraid WebGUI.
+1. **The UnraidClaw plugin installed on your Unraid server.** Install it from the Unraid Community Apps store, or see the [main repo](https://github.com/emaspa/unraidclaw). It runs the gateway on port `9876` (HTTPS) by default.
+2. **An UnraidClaw API key.** Generate one on the **Settings > UnraidClaw** page in the Unraid WebGUI.
 3. **OpenClaw** installed (`openclaw --version`).
 
 ## Install
 
 ```bash
-npm pack unraidclaw && openclaw plugins install unraidclaw-*.tgz && rm unraidclaw-*.tgz
+openclaw plugins install clawhub:unraidclaw --accept-capabilities
+```
+
+The same package is on npm. OpenClaw asks you to confirm installs from outside ClawHub, so installing from npm needs `--force`:
+
+```bash
+openclaw plugins install unraidclaw --force --accept-capabilities
 ```
 
 To update to the latest version:
 
 ```bash
-rm -rf ~/.openclaw/extensions/unraidclaw && npm pack unraidclaw && openclaw plugins install unraidclaw-*.tgz && rm unraidclaw-*.tgz
+openclaw plugins update unraidclaw --accept-capabilities
 ```
 
+Then restart the gateway with `openclaw gateway restart` so it loads the new version.
+
 ## Configure
 
 Edit `~/.openclaw/openclaw.json`.
@@ -57,8 +65,8 @@ Edit `~/.openclaw/openclaw.json`.
       "unraidclaw": {
         "config": {
           "servers": [
-            { "name": "home", "serverUrl": "https://192.168.1.100:9876", "apiKey": "...", "tlsSkipVerify": true, "default": true },
-            { "name": "work", "serverUrl": "https://10.0.0.50:9876", "apiKey": "..." }
+            { "name": "home", "serverUrl": "https://<home-server>:9876", "apiKey": "<api-key>", "tlsSkipVerify": true, "default": true },
+            { "name": "work", "serverUrl": "https://<work-server>:9876", "apiKey": "<api-key>" }
           ]
         }
       }
@@ -67,21 +75,21 @@ Edit `~/.openclaw/openclaw.json`.
 }
 ```
 
-With multi-server config, every tool accepts an optional `server` parameter (e.g. `unraid_docker_list(server: "work")`); the default server is used when it's omitted.
+With multi-server config, every tool accepts an optional `server` parameter (e.g. `unraid_docker_list(server: "work")`); the first server marked `default` is used when it's omitted, or the first configured server if none is marked.
 
-Set `tlsSkipVerify: true` when using UnraidClaw's auto-generated self-signed certificate.
+Set `tlsSkipVerify: true` to accept the gateway's self-signed certificate. The plugin does not verify the certificate in that mode, so regenerating the certificate on the server does not affect it. The repository README's [TLS certificate](https://github.com/emaspa/unraidclaw#tls-certificate) section explains what the certificate contains and how strict clients can trust it.
 
 ### Keeping the API key out of the config file
 
 You don't have to hard-code the key in `openclaw.json`. Two options:
 
-**Environment variable** — OpenClaw expands `${VAR}` references at config-load time:
+**Environment variable.** OpenClaw expands `${VAR}` references at config-load time:
 
 ```json
 "apiKey": "${UNRAID_API_KEY}"
 ```
 
-**Provider-backed secret (`SecretRef`)** — point `apiKey` at one of your configured secret providers; OpenClaw resolves it before the plugin loads, so the plugin only ever sees the resolved string:
+**Provider-backed secret (`SecretRef`).** Point `apiKey` at one of your configured secret providers; OpenClaw resolves it before the plugin loads, so the plugin only ever sees the resolved string:
 
 ```json
 "apiKey": { "source": "file", "provider": "default", "id": "/unraidclaw_key" }
@@ -91,7 +99,7 @@ You don't have to hard-code the key in `openclaw.json`. Two options:
 
 ## Usage
 
-Once installed and configured, just ask your agent:
+Once installed and configured, ask your agent:
 
 - "List all running Docker containers"
 - "Stop the plex container"
@@ -127,9 +135,11 @@ Once installed and configured, just ask your agent:
 
 `unraid_ca_update` and `unraid_ca_remove` act on an installed app, so their `name` is the container's name from the Docker tab, not the app's name in the catalog. Update keeps the configuration saved on the server and restores the running or stopped state; remove deletes the container and leaves appdata, volumes, the image and the template alone. Both take `dryRun`.
 
+`unraid_docker_create` takes `image` plus optional `name`, `ports`, `volumes`, `env`, `restart` and `network`, and the advanced settings of Unraid's container form: `extraArgs` (Extra Parameters, docker run options such as `--gpus all` or `--memory=8g`), `postArgs` (Post Arguments, the container command), `staticIp` (a fixed IPv4 or IPv6 address, which needs a macvlan, ipvlan or custom bridge network), `privileged`, `cpuset` and `devices`. Each is saved to the matching field of the container's template. The two free-form fields accept only letters, digits, `: . , / + = _ -` and single spaces, because Unraid passes them to the shell unescaped when it rebuilds a container. A container created with any of these settings in effect cannot be rebuilt by `unraid_ca_update`, which refuses settings it does not reproduce exactly; use the Docker tab for it.
+
 The six plugin tools manage Unraid `.plg` plugins through Unraid's own plugin manager. Installing one runs vendor code as root, checking for an update downloads a plugin file and stages it, and removing one runs the plugin's removal script, which may take its data with it. All four mutating tools take `dryRun`.
 
-Every tool is gated by a 30-key `resource:action` permission matrix configured from the Unraid WebGUI, so you control exactly what agents can do.
+Tools use the gateway's 30-key `resource:action` permission matrix configured from the Unraid WebGUI. Health requires no permission.
 
 ## Links
 
@@ -137,6 +147,10 @@ Every tool is gated by a 30-key `resource:action` permission matrix configured f
 - [Issues](https://github.com/emaspa/unraidclaw/issues)
 - [Unraid Community Apps](https://unraid.net/community/apps)
 
+## Gateway MCP mode
+
+The gateway has an optional MCP endpoint at `/mcp` that serves the same 55 tools to MCP clients. It is off by default and is switched on with **Enable MCP** in the gateway's Settings tab. This plugin does not use it: OpenClaw keeps calling `/api/*` whether MCP is on or off. The tool definitions in this package are shared with the gateway through the `unraidclaw/tools` export, so OpenClaw, MCP and the standalone CLI use the same tools and the `READ_ONLY` set exported by `src/registry.ts`. The CLI, command `unraidclaw`, is published to npm as `unraidclaw-cli` and attached to each [GitHub release](https://github.com/emaspa/unraidclaw/releases/latest) as `unraidclaw-cli-<version>.tar.gz`; see the [CLI guide](https://github.com/emaspa/unraidclaw/blob/main/packages/cli/README.md). See the [repository README](https://github.com/emaspa/unraidclaw#mcp) for MCP client setup.
+
 ## License
 
 MIT

package/dist/index.js

@@ -109,9 +109,12 @@ var UnraidClient = class {
 function textResult(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
+var failures = /* @__PURE__ */ new WeakSet();
 function errorResult(err) {
   const message = err instanceof Error ? err.message : String(err);
-  return { content: [{ type: "text", text: `Error: ${message}` }] };
+  const result = { content: [{ type: "text", text: `Error: ${message}` }] };
+  failures.add(result);
+  return result;
 }
 function checkParams(params, allowed) {
   for (const key of Object.keys(params)) {
@@ -194,7 +197,7 @@ function registerDockerTools(api, getClient) {
       type: "object",
       properties: {
         id: { type: "string", description: "Container ID or name" },
-        tail: { type: "number", description: "Number of lines from the end (default: 100)" },
+        tail: { type: "integer", minimum: 1, maximum: 1e4, description: "Number of lines from the end (default: 100)" },
         since: { type: "string", description: "Show logs since timestamp (e.g., 2024-01-01T00:00:00Z)" },
         server: { type: "string", description: "Target server name (optional, uses default server)" }
       },
@@ -261,7 +264,7 @@ function registerDockerTools(api, getClient) {
   });
   api.registerTool({
     name: "unraid_docker_create",
-    description: "Create and start a new Docker container on the Unraid server. Specify image, optional name, port mappings, volume mounts, environment variables, restart policy, and network.",
+    description: "Create and start a new Docker container on the Unraid server. Specify image, optional name, port mappings, volume mounts, environment variables, restart policy, network, and Unraid's advanced settings: extra docker run options, post arguments, a fixed IP on a custom network, privileged mode, CPU pinning and host devices.",
     parameters: {
       type: "object",
       properties: {
@@ -288,6 +291,25 @@ function registerDockerTools(api, getClient) {
           description: "Restart policy (default: unless-stopped)"
         },
         network: { type: "string", description: "Network to attach the container to" },
+        extraArgs: {
+          type: "string",
+          description: "Extra docker run options, space separated, as Unraid's Extra Parameters field (e.g. '--gpus all', '--cap-add=SYS_ADMIN --memory=8g', '--hostname=media'). Must start with an option. Only letters, digits, : . , / + = _ - and single spaces; no quotes or shell characters."
+        },
+        postArgs: {
+          type: "string",
+          description: "Arguments appended after the image as the container command, space separated, as Unraid's Post Arguments field (e.g. '--config /config/app.yml'). Same character rules as extraArgs."
+        },
+        staticIp: {
+          type: "string",
+          description: "Fixed IPv4 or IPv6 address for the container (Unraid's Fixed IP field). Needs a user-defined network such as a macvlan, ipvlan or custom bridge; docker refuses it on bridge, host and none."
+        },
+        privileged: { type: "boolean", description: "Run the container privileged, with full host access (default: false)" },
+        cpuset: { type: "string", description: "CPUs the container may run on, as docker --cpuset-cpus reads it (e.g. '0-3,8')" },
+        devices: {
+          type: "array",
+          items: { type: "string" },
+          description: "Host devices to pass through, as docker --device reads them (e.g. ['/dev/dri', '/dev/ttyUSB0:/dev/ttyUSB0:rwm'])"
+        },
         server: { type: "string", description: "Target server name (optional, uses default server)" }
       },
       required: ["image"]
@@ -1078,7 +1100,7 @@ function registerNotificationTools(api, getClient) {
         title: { type: "string", description: "Notification title" },
         subject: { type: "string", description: "Notification subject" },
         description: { type: "string", description: "Notification body text" },
-        importance: { type: "string", description: "Importance level: alert, warning, or normal" },
+        importance: { type: "string", enum: ["normal", "warning", "alert"], description: "Importance level: alert, warning, or normal" },
         server: { type: "string", description: "Target server name (optional, uses default server)" }
       },
       required: ["title", "subject", "description"]
@@ -1206,6 +1228,23 @@ function registerLogTools(api, getClient) {
   });
 }
 
+// src/registry.ts
+function registerTools(api, getClient) {
+  registerHealthTools(api, getClient);
+  registerDockerTools(api, getClient);
+  registerCaTools(api, getClient);
+  registerPluginTools(api, getClient);
+  registerVMTools(api, getClient);
+  registerArrayTools(api, getClient);
+  registerDiskTools(api, getClient);
+  registerShareTools(api, getClient);
+  registerSystemTools(api, getClient);
+  registerNotificationTools(api, getClient);
+  registerNetworkTools(api, getClient);
+  registerUserTools(api, getClient);
+  registerLogTools(api, getClient);
+}
+
 // src/index.ts
 function resolveServers(api) {
   const raw = api.config?.servers ?? api.pluginConfig?.servers ?? api.config?.plugins?.entries?.unraidclaw?.config?.servers;
@@ -1235,19 +1274,7 @@ function register(api) {
     }
     return client;
   }
-  registerHealthTools(api, getClient);
-  registerDockerTools(api, getClient);
-  registerCaTools(api, getClient);
-  registerPluginTools(api, getClient);
-  registerVMTools(api, getClient);
-  registerArrayTools(api, getClient);
-  registerDiskTools(api, getClient);
-  registerShareTools(api, getClient);
-  registerSystemTools(api, getClient);
-  registerNotificationTools(api, getClient);
-  registerNetworkTools(api, getClient);
-  registerUserTools(api, getClient);
-  registerLogTools(api, getClient);
+  registerTools(api, getClient);
   const servers = resolveServers(api);
   if (servers.length > 1) {
     log.info(`UnraidClaw: registered tools for ${servers.length} servers: ${servers.map((s) => s.name).join(", ")}`);

package/dist/registry.d.ts

@@ -0,0 +1,38 @@
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: JsonSchema;
+    execute: (id: string, params: Record<string, unknown>) => Promise<ToolResult>;
+}
+interface ToolOptions {
+    optional?: boolean;
+}
+interface JsonSchema {
+    type: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    additionalProperties?: boolean;
+}
+interface ToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}
+
+declare function isErrorResult(result: ToolResult): boolean;
+
+/** The tools depend only on this transport, not on an HTTP client or host. */
+interface ToolClient {
+    get<T>(path: string, query?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+type ClientResolver = (serverName?: string) => ToolClient;
+declare function registerTools(api: {
+    registerTool(tool: ToolDefinition, options?: ToolOptions): void;
+}, getClient: ClientResolver): void;
+declare const READ_ONLY: Set<string>;
+
+export { type ClientResolver, READ_ONLY, type ToolClient, type ToolDefinition, type ToolOptions, type ToolResult, isErrorResult, registerTools };