unraidclaw 0.1.13 → 0.1.15

package/README.md

@@ -1,29 +1,37 @@
 # 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)
 
-This is the [OpenClaw](https://github.com/openclaw/openclaw) plugin for **[UnraidClaw](https://github.com/emaspa/unraidclaw)**. It exposes **44 tools** to any AI agent running on OpenClaw, letting it monitor and manage your Unraid server. The plugin talks to the UnraidClaw gateway (a permission-enforcing REST API) running on your Unraid box.
+This is the [OpenClaw](https://github.com/openclaw/openclaw) plugin for **[UnraidClaw](https://github.com/emaspa/unraidclaw)**. It exposes **55 tools** to any AI agent running on OpenClaw, letting it monitor and manage your Unraid server. The plugin talks to the UnraidClaw gateway (a permission-enforcing REST API) running on your Unraid box.
 
 ## 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,24 +99,30 @@ 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"
 - "What's the array status?"
 - "Show me disk temperatures"
 - "Create a new nginx container with port 8080"
+- "Find me a Community Applications backup tool"
+- "Install Jellyfin from Community Applications, media on /mnt/user/media"
+- "Update the jellyfin container to the latest image"
+- "Which of my Unraid plugins have updates?"
 - "Check parity status"
 - "Reboot the server"
 
 ## Tools
 
-44 tools across 11 categories:
+55 tools across 13 categories:
 
 | Category | Tools |
 |----------|-------|
 | Health | `unraid_health_check` |
 | Docker | `unraid_docker_list`, `unraid_docker_inspect`, `unraid_docker_logs`, `unraid_docker_create`, `unraid_docker_start`, `unraid_docker_stop`, `unraid_docker_restart`, `unraid_docker_pause`, `unraid_docker_unpause`, `unraid_docker_remove` |
+| Community Apps | `unraid_ca_search`, `unraid_ca_app`, `unraid_ca_install`, `unraid_ca_update`, `unraid_ca_remove` |
+| Plugins | `unraid_plugins_list`, `unraid_plugin_info`, `unraid_plugin_install`, `unraid_plugin_check_updates`, `unraid_plugin_update`, `unraid_plugin_remove` |
 | VMs | `unraid_vm_list`, `unraid_vm_inspect`, `unraid_vm_start`, `unraid_vm_stop`, `unraid_vm_pause`, `unraid_vm_resume`, `unraid_vm_force_stop`, `unraid_vm_reboot` |
 | Array | `unraid_array_status`, `unraid_array_start`, `unraid_array_stop`, `unraid_parity_status`, `unraid_parity_start`, `unraid_parity_pause`, `unraid_parity_resume`, `unraid_parity_cancel` |
 | Disks | `unraid_disk_list`, `unraid_disk_details` |
@@ -119,7 +133,11 @@ Once installed and configured, just ask your agent:
 | Users | `unraid_user_me` |
 | Logs | `unraid_syslog` |
 
-Every tool is gated by a 22-key `resource:action` permission matrix configured from the Unraid WebGUI, so you control exactly what agents can do.
+`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`.
+
+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`.
+
+Tools use the gateway's 30-key `resource:action` permission matrix configured from the Unraid WebGUI. Health requires no permission.
 
 ## Links
 
@@ -127,6 +145,10 @@ Every tool is gated by a 22-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,26 @@ 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)) {
+    if (allowed.includes(key)) continue;
+    const near = allowed.find((a) => a.toLowerCase() === key.toLowerCase());
+    throw new Error(
+      near ? `Unknown parameter "${key}". Did you mean "${near}"? Nothing was sent to the server.` : `Unknown parameter "${key}". Allowed parameters are: ${allowed.join(", ")}. Nothing was sent to the server.`
+    );
+  }
+  if (params.dryRun !== void 0 && typeof params.dryRun !== "boolean") {
+    throw new Error(
+      `"dryRun" must be true or false, not ${JSON.stringify(params.dryRun)}. Nothing was sent to the server.`
+    );
+  }
 }
 
 // src/tools/health.ts
@@ -180,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)" }
       },
@@ -289,6 +306,359 @@ function registerDockerTools(api, getClient) {
   });
 }
 
+// src/tools/ca.ts
+function registerCaTools(api, getClient) {
+  api.registerTool({
+    name: "unraid_ca_search",
+    description: "Search the Unraid Community Applications catalog by name, description, Docker image or maintainer. Returns matching apps with their icon, categories and whether UnraidClaw can install them. Use this to find an app before calling unraid_ca_app or unraid_ca_install.",
+    parameters: {
+      type: "object",
+      properties: {
+        q: { type: "string", description: "Search text, e.g. 'plex' or 'backup tool'. All words must match." },
+        limit: { type: "number", description: "Maximum results to return (1-100, default: 25)" },
+        includeDeprecated: { type: "boolean", description: "Include templates the maintainer deprecated (default: false)" },
+        includePlugins: { type: "boolean", description: "Include Unraid plugin (.plg) entries, which are not containers (default: false)" },
+        server: { type: "string", description: "Target server name (optional, uses default server)" }
+      },
+      required: ["q"]
+    },
+    execute: async (_id, params) => {
+      try {
+        const query = { q: String(params.q ?? "") };
+        if (params.limit) query.limit = String(params.limit);
+        if (params.includeDeprecated) query.includeDeprecated = "true";
+        if (params.includePlugins) query.includePlugins = "true";
+        return textResult(await getClient(params.server).get("/api/ca/search", query));
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  });
+  api.registerTool({
+    name: "unraid_ca_app",
+    description: "Get the full Community Applications template for one app: its Docker image, icon, WebUI, network mode, and every configurable port, volume and environment variable with its default. Also reports which required fields have no default and any reason the app cannot be installed. Several apps share a name; pass repo to disambiguate when the call reports an ambiguity.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "App name exactly as it appears in the catalog, e.g. 'Jellyfin'" },
+        repo: { type: "string", description: `Owning repository, e.g. "linuxserver's Repository". Required when several templates share the name.` },
+        server: { type: "string", description: "Target server name (optional, uses default server)" }
+      },
+      required: ["name"]
+    },
+    execute: async (_id, params) => {
+      try {
+        const query = {};
+        if (params.repo) query.repo = String(params.repo);
+        return textResult(
+          await getClient(params.server).get(
+            `/api/ca/app/${encodeURIComponent(String(params.name))}`,
+            query
+          )
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  });
+  api.registerTool({
+    name: "unraid_ca_install",
+    description: "Install a Community Applications app on the Unraid server using its template defaults. Writes an Unraid docker-manager template and has Unraid create and start the container, so it appears on the Docker tab like any other app. Required fields with no default must be supplied in overrides; call unraid_ca_app first to see them. Pass dryRun=true to get the resolved template and a preview of the docker command without changing anything. Refuses apps whose templates need unsupported or unsafe options rather than installing something different from the template.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "App name exactly as it appears in the catalog, e.g. 'Jellyfin'" },
+        repo: { type: "string", description: "Owning repository. Required when several templates share the name." },
+        containerName: {
+          type: "string",
+          description: "Name for the new container. Defaults to the app name. Letters, digits, dot, dash and underscore only."
+        },
+        overrides: {
+          type: "object",
+          additionalProperties: { type: "string" },
+          description: "Values for template fields, keyed by the field's name or its container-side target, e.g. {'/data/tvshows': '/mnt/user/media/tv', 'PUID': '99'}. An unknown key is an error."
+        },
+        dryRun: {
+          type: "boolean",
+          description: "Resolve and validate everything and return the plan without installing (default: false)"
+        },
+        server: { type: "string", description: "Target server name (optional, uses default server)" }
+      },
+      required: ["name"],
+      additionalProperties: false
+    },
+    execute: async (_id, params) => {
+      try {
+        checkParams(params, ["name", "repo", "containerName", "overrides", "dryRun", "server"]);
+        const body = {};
+        if (params.repo) body.repo = params.repo;
+        if (params.containerName) body.name = params.containerName;
+        if (params.overrides) body.overrides = params.overrides;
+        if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+        return textResult(
+          await getClient(params.server).post(
+            `/api/ca/app/${encodeURIComponent(String(params.name))}/install`,
+            body
+          )
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  }, { optional: true });
+  api.registerTool({
+    name: "unraid_ca_update",
+    description: "Update an app that is already installed on the Unraid server: pulls the newest image for the tag it runs and recreates the container from the template saved on the server, keeping its ports, paths, variables and its running or stopped state. The name is the INSTALLED CONTAINER NAME as shown on the Docker tab, not the app's name in the Community Applications catalog; call unraid_docker_list to find it and never guess it from a catalog name. Nothing is refreshed from the catalog, so values the user changed are kept. A failed pull leaves the running app untouched, the previous image is never deleted, and no appdata is removed. Pass dryRun=true to see the resolved configuration and the exact docker command without changing anything.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Installed container name, e.g. 'jellyfin'. Not the catalog app name." },
+        dryRun: {
+          type: "boolean",
+          description: "Check everything and report what would happen without pulling or recreating anything (default: false)"
+        },
+        server: { type: "string", description: "Target server name (optional, uses default server)" }
+      },
+      required: ["name"],
+      additionalProperties: false
+    },
+    execute: async (_id, params) => {
+      try {
+        checkParams(params, ["name", "dryRun", "server"]);
+        const body = {};
+        if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+        return textResult(
+          await getClient(params.server).post(
+            `/api/ca/app/${encodeURIComponent(String(params.name))}/update`,
+            body
+          )
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  }, { optional: true });
+  api.registerTool({
+    name: "unraid_ca_remove",
+    description: "Remove an installed app's Docker container from the Unraid server. The name is the INSTALLED CONTAINER NAME as shown on the Docker tab, not the app's name in the Community Applications catalog; call unraid_docker_list to find it and never guess it from a catalog name. Only the container is removed: its appdata, its Docker volumes, its image and the saved template all stay, so the app can be recreated with the same configuration. Pass dryRun=true to see exactly what would be removed and what would be kept.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Installed container name, e.g. 'jellyfin'. Not the catalog app name." },
+        dryRun: {
+          type: "boolean",
+          description: "Report what would be removed and what would be kept, without removing anything (default: false)"
+        },
+        server: { type: "string", description: "Target server name (optional, uses default server)" }
+      },
+      required: ["name"],
+      additionalProperties: false
+    },
+    execute: async (_id, params) => {
+      try {
+        checkParams(params, ["name", "dryRun", "server"]);
+        const body = {};
+        if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+        return textResult(
+          await getClient(params.server).post(
+            `/api/ca/app/${encodeURIComponent(String(params.name))}/remove`,
+            body
+          )
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  }, { optional: true });
+}
+
+// src/tools/plugins.ts
+function registerPluginTools(api, getClient) {
+  api.registerTool({
+    name: "unraid_plugins_list",
+    description: "List the Unraid plugins (.plg) installed on the server, with author, version, update URL and whether an update is already staged. Unraid plugins are not Docker containers and not Community Applications: they install files and run scripts on the server itself. Plugins marked builtin belong to Unraid OS and cannot be changed through UnraidClaw.",
+    parameters: {
+      type: "object",
+      properties: {
+        server: { type: "string", description: "Target server name (optional, uses default server)" }
+      }
+    },
+    execute: async (_id, params) => {
+      try {
+        return textResult(await getClient(params.server).get("/api/plugins"));
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  });
+  api.registerTool({
+    name: "unraid_plugin_info",
+    description: "Show one installed Unraid plugin in full: its metadata, support link, Unraid version requirements, changelog text and the structure of the files it installs. Inline scripts inside the plugin are described but never returned or executed.",
+    parameters: {
+      type: "object",
+      properties: {
+        plugin: {
+          type: "string",
+          description: "Plugin file name, e.g. 'unassigned.devices.plg'. The .plg suffix is optional."
+        },
+        server: { type: "string", description: "Target server name (optional, uses default server)" }
+      },
+      required: ["plugin"]
+    },
+    execute: async (_id, params) => {
+      try {
+        return textResult(
+          await getClient(params.server).get(
+            `/api/plugins/${encodeURIComponent(String(params.plugin))}`
+          )
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  });
+  api.registerTool(
+    {
+      name: "unraid_plugin_install",
+      description: "Install an Unraid plugin from an explicit https URL to a .plg file. The plugin file is an installer that Unraid runs as root, so this executes code from whoever controls that URL: only use a URL the user gave you or one from a source they trust. The URL must be https, public, credential-free and end in .plg. Use dryRun first to see exactly what would happen. This is not the way to install Community Applications apps; those are Docker containers (unraid_ca_install).",
+      parameters: {
+        type: "object",
+        properties: {
+          url: {
+            type: "string",
+            description: "Direct https URL of the .plg file, e.g. 'https://example.com/myplugin.plg'"
+          },
+          dryRun: {
+            type: "boolean",
+            description: "Validate the URL and return the plan without downloading, writing or installing anything (default: false)"
+          },
+          server: { type: "string", description: "Target server name (optional, uses default server)" }
+        },
+        required: ["url"],
+        additionalProperties: false
+      },
+      execute: async (_id, params) => {
+        try {
+          checkParams(params, ["url", "dryRun", "server"]);
+          const body = { url: String(params.url ?? "") };
+          if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+          return textResult(
+            await getClient(params.server).post("/api/plugins/install", body)
+          );
+        } catch (err) {
+          return errorResult(err);
+        }
+      }
+    },
+    { optional: true }
+  );
+  api.registerTool(
+    {
+      name: "unraid_plugin_check_updates",
+      description: "Check whether a newer version of an installed Unraid plugin has been published, and stage it for installation. This is not a read-only lookup: it downloads the plugin file from the plugin's own update URL and writes it to the plugin manager's staging directory, where this tool's update call and the Unraid web UI will then offer to install it. Nothing is installed or executed by the check. Run this before unraid_plugin_update.",
+      parameters: {
+        type: "object",
+        properties: {
+          plugin: { type: "string", description: "Plugin file name, e.g. 'unassigned.devices.plg'" },
+          dryRun: {
+            type: "boolean",
+            description: "Return the plan without downloading or staging anything (default: false)"
+          },
+          server: { type: "string", description: "Target server name (optional, uses default server)" }
+        },
+        required: ["plugin"],
+        additionalProperties: false
+      },
+      execute: async (_id, params) => {
+        try {
+          checkParams(params, ["plugin", "dryRun", "server"]);
+          const body = {};
+          if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+          return textResult(
+            await getClient(params.server).post(
+              `/api/plugins/${encodeURIComponent(String(params.plugin))}/check`,
+              body
+            )
+          );
+        } catch (err) {
+          return errorResult(err);
+        }
+      }
+    },
+    { optional: true }
+  );
+  api.registerTool(
+    {
+      name: "unraid_plugin_update",
+      description: "Install the plugin version staged by unraid_plugin_check_updates. Unraid's plugin manager runs the new plugin's install scripts as root and there is no rollback. The result says whether the installed version actually changed; a plugin manager exit code alone is not treated as success.",
+      parameters: {
+        type: "object",
+        properties: {
+          plugin: { type: "string", description: "Plugin file name, e.g. 'unassigned.devices.plg'" },
+          dryRun: {
+            type: "boolean",
+            description: "Return the plan, including which version would replace which, without installing (default: false)"
+          },
+          server: { type: "string", description: "Target server name (optional, uses default server)" }
+        },
+        required: ["plugin"],
+        additionalProperties: false
+      },
+      execute: async (_id, params) => {
+        try {
+          checkParams(params, ["plugin", "dryRun", "server"]);
+          const body = {};
+          if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+          return textResult(
+            await getClient(params.server).post(
+              `/api/plugins/${encodeURIComponent(String(params.plugin))}/update`,
+              body
+            )
+          );
+        } catch (err) {
+          return errorResult(err);
+        }
+      }
+    },
+    { optional: true }
+  );
+  api.registerTool(
+    {
+      name: "unraid_plugin_remove",
+      description: "Remove an installed Unraid plugin through the plugin manager. The plugin's own removal scripts run as root and decide what they delete: some keep their configuration and data, others delete it, so removal cannot be promised to be data-preserving. Anything depending on the plugin stops working. Use dryRun first and confirm with the user before removing.",
+      parameters: {
+        type: "object",
+        properties: {
+          plugin: { type: "string", description: "Plugin file name, e.g. 'unassigned.devices.plg'" },
+          dryRun: {
+            type: "boolean",
+            description: "Return the plan and its warnings without removing anything (default: false)"
+          },
+          server: { type: "string", description: "Target server name (optional, uses default server)" }
+        },
+        required: ["plugin"],
+        additionalProperties: false
+      },
+      execute: async (_id, params) => {
+        try {
+          checkParams(params, ["plugin", "dryRun", "server"]);
+          const body = {};
+          if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+          return textResult(
+            await getClient(params.server).post(
+              `/api/plugins/${encodeURIComponent(String(params.plugin))}/remove`,
+              body
+            )
+          );
+        } catch (err) {
+          return errorResult(err);
+        }
+      }
+    },
+    { optional: true }
+  );
+}
+
 // src/tools/vms.ts
 function registerVMTools(api, getClient) {
   api.registerTool({
@@ -711,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"]
@@ -839,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;
@@ -868,17 +1255,7 @@ function register(api) {
     }
     return client;
   }
-  registerHealthTools(api, getClient);
-  registerDockerTools(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 };