unraidclaw 0.1.14 → 0.1.15

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"
@@ -129,7 +137,7 @@ Once installed and configured, just ask your agent:
 
 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 +145,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 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)" }
       },
@@ -1078,7 +1081,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 +1209,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 +1255,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 };