diff --git a/.claude-plugin/README.md b/.claude-plugin/README.md index 65d7fb1..58abdd6 100644 --- a/.claude-plugin/README.md +++ b/.claude-plugin/README.md @@ -1,73 +1,239 @@ -# Unraid MCP Marketplace +# Unraid MCP Plugin -This directory contains the Claude Code marketplace configuration for the Unraid MCP server and skills. +Query, monitor, and manage Unraid servers via GraphQL API using a single consolidated `unraid` tool with action+subaction routing. + +**Version:** 1.1.3 | **Category:** Infrastructure | **Tags:** unraid, homelab, graphql, docker, virtualization + +--- ## Installation -### From GitHub (Recommended) - ```bash -# Add the marketplace /plugin marketplace add jmagar/unraid-mcp - -# Install the Unraid skill /plugin install unraid @unraid-mcp ``` -### From Local Path (Development) - -```bash -# Add local marketplace -/plugin marketplace add /path/to/unraid-mcp - -# Install the plugin -/plugin install unraid @unraid-mcp -``` - -## Available Plugins - -### unraid - -Query and monitor Unraid servers via GraphQL API - array status, disk health, containers, VMs, system monitoring. - -**Features:** -- 1 consolidated `unraid` tool with ~108 actions across 15 domains -- Real-time live subscriptions (CPU, memory, logs, array state, UPS) -- Disk health and temperature monitoring -- Docker container management -- VM status and control -- Log file access -- Network share information -- Notification management -- Plugin, rclone, API key, and OIDC management - -**Version:** 1.1.2 -**Category:** Infrastructure -**Tags:** unraid, monitoring, homelab, graphql, docker, virtualization - -## Configuration - -After installation, run setup to configure credentials interactively: +After install, configure credentials: ```python unraid(action="health", subaction="setup") ``` -Credentials are stored at `~/.unraid-mcp/.env` automatically. +Credentials are stored at `~/.unraid-mcp/.env`. Get an API key from **Unraid WebUI → Settings → Management Access → API Keys**. -**Getting an API Key:** -1. Open Unraid WebUI -2. Go to Settings → Management Access → API Keys -3. Click "Create" and select "Viewer" role (or appropriate roles for mutations) -4. Copy the generated API key +--- -## Documentation +## Tools -- **Plugin Documentation:** See `skills/unraid/README.md` -- **MCP Server Documentation:** See root `README.md` -- **API Reference:** See `skills/unraid/references/` +### `unraid` — Primary Tool (107 subactions, 15 domains) + +Call as `unraid(action="", subaction="", [params])`. + +#### `system` — Server Information (18 subactions) +| Subaction | Description | +|-----------|-------------| +| `overview` | Complete system summary (recommended starting point) | +| `server` | Hostname, version, uptime | +| `servers` | All known Unraid servers | +| `array` | Array status and disk list | +| `network` | Network interfaces and config | +| `registration` | License and registration status | +| `variables` | Environment variables | +| `metrics` | Real-time CPU, memory, I/O usage | +| `services` | Running services status | +| `display` | Display settings | +| `config` | System configuration | +| `online` | Quick online status check | +| `owner` | Server owner information | +| `settings` | User settings and preferences | +| `flash` | USB flash drive details | +| `ups_devices` | List all UPS devices | +| `ups_device` | Single UPS device (requires `device_id`) | +| `ups_config` | UPS configuration | + +#### `health` — Diagnostics (4 subactions) +| Subaction | Description | +|-----------|-------------| +| `check` | Comprehensive health check — connectivity, array, disks, containers, VMs, resources | +| `test_connection` | Test API connectivity and authentication | +| `diagnose` | Detailed diagnostic report with troubleshooting recommendations | +| `setup` | Configure credentials interactively (stores to `~/.unraid-mcp/.env`) | + +#### `array` — Array & Parity (13 subactions) +| Subaction | Description | +|-----------|-------------| +| `parity_status` | Current parity check progress and status | +| `parity_history` | Historical parity check results | +| `parity_start` | Start a parity check (requires `correct`) | +| `parity_pause` | Pause a running parity check | +| `parity_resume` | Resume a paused parity check | +| `parity_cancel` | Cancel a running parity check | +| `start_array` | Start the array | +| `stop_array` | ⚠️ Stop the array (requires `confirm=True`) | +| `add_disk` | Add a disk to the array (requires `slot`, `id`) | +| `remove_disk` | ⚠️ Remove a disk (requires `slot`, `confirm=True`) | +| `mount_disk` | Mount a disk | +| `unmount_disk` | Unmount a disk | +| `clear_disk_stats` | ⚠️ Clear disk statistics (requires `confirm=True`) | + +#### `disk` — Storage & Logs (6 subactions) +| Subaction | Description | +|-----------|-------------| +| `shares` | List network shares | +| `disks` | All physical disks with health and temperatures | +| `disk_details` | Detailed info for a specific disk (requires `disk_id`) | +| `log_files` | List available log files | +| `logs` | Read log content (requires `log_path`; optional `tail_lines`) | +| `flash_backup` | ⚠️ Trigger a flash backup (requires `confirm=True`) | + +#### `docker` — Containers (7 subactions) +| Subaction | Description | +|-----------|-------------| +| `list` | All containers with status, image, state | +| `details` | Single container details (requires container identifier) | +| `start` | Start a container (requires container identifier) | +| `stop` | Stop a container (requires container identifier) | +| `restart` | Restart a container (requires container identifier) | +| `networks` | List Docker networks | +| `network_details` | Details for a specific network (requires `network_id`) | + +Container identification: name, ID, or partial name (fuzzy match). + +#### `vm` — Virtual Machines (9 subactions) +| Subaction | Description | +|-----------|-------------| +| `list` | All VMs with state | +| `details` | Single VM details (requires `vm_id`) | +| `start` | Start a VM (requires `vm_id`) | +| `stop` | Gracefully stop a VM (requires `vm_id`) | +| `pause` | Pause a VM (requires `vm_id`) | +| `resume` | Resume a paused VM (requires `vm_id`) | +| `reboot` | Reboot a VM (requires `vm_id`) | +| `force_stop` | ⚠️ Force stop a VM (requires `vm_id`, `confirm=True`) | +| `reset` | ⚠️ Hard reset a VM (requires `vm_id`, `confirm=True`) | + +#### `notification` — Notifications (12 subactions) +| Subaction | Description | +|-----------|-------------| +| `overview` | Notification counts (unread, archived by type) | +| `list` | List notifications (optional `filter`, `limit`, `offset`) | +| `create` | Create a notification (requires `title`, `subject`, `description`, `importance`) | +| `archive` | Archive a notification (requires `notification_id`) | +| `mark_unread` | Mark a notification as unread (requires `notification_id`) | +| `recalculate` | Recalculate notification counts | +| `archive_all` | Archive all unread notifications | +| `archive_many` | Archive multiple (requires `ids` list) | +| `unarchive_many` | Unarchive multiple (requires `ids` list) | +| `unarchive_all` | Unarchive all archived notifications | +| `delete` | ⚠️ Delete a notification (requires `notification_id`, `notification_type`, `confirm=True`) | +| `delete_archived` | ⚠️ Delete all archived (requires `confirm=True`) | + +#### `key` — API Keys (7 subactions) +| Subaction | Description | +|-----------|-------------| +| `list` | All API keys | +| `get` | Single key details (requires `key_id`) | +| `create` | Create a new key (requires `name`; optional `roles`, `permissions`) | +| `update` | Update a key (requires `key_id`) | +| `delete` | ⚠️ Delete a key (requires `key_id`, `confirm=True`) | +| `add_role` | Add roles to a key (requires `key_id`, `roles`) | +| `remove_role` | Remove roles from a key (requires `key_id`, `roles`) | + +#### `plugin` — Plugins (3 subactions) +| Subaction | Description | +|-----------|-------------| +| `list` | All installed plugins | +| `add` | Install plugins (requires `names` list) | +| `remove` | ⚠️ Uninstall plugins (requires `names` list, `confirm=True`) | + +#### `rclone` — Cloud Storage (4 subactions) +| Subaction | Description | +|-----------|-------------| +| `list_remotes` | List configured rclone remotes | +| `config_form` | Get configuration form for a remote type | +| `create_remote` | Create a new remote (requires `name`, `provider_type`, `config_data`) | +| `delete_remote` | ⚠️ Delete a remote (requires `name`, `confirm=True`) | + +#### `setting` — System Settings (2 subactions) +| Subaction | Description | +|-----------|-------------| +| `update` | Update system settings (requires `settings_input` object) | +| `configure_ups` | ⚠️ Configure UPS settings (requires `confirm=True`) | + +#### `customization` — Theme & Appearance (5 subactions) +| Subaction | Description | +|-----------|-------------| +| `theme` | Current theme settings | +| `public_theme` | Public-facing theme | +| `is_initial_setup` | Check if initial setup is complete | +| `sso_enabled` | Check SSO status | +| `set_theme` | Update theme (requires theme parameters) | + +#### `oidc` — SSO / OpenID Connect (5 subactions) +| Subaction | Description | +|-----------|-------------| +| `providers` | List configured OIDC providers | +| `provider` | Single provider details (requires `provider_id`) | +| `configuration` | OIDC configuration | +| `public_providers` | Public-facing provider list | +| `validate_session` | Validate current SSO session (requires `token`) | + +#### `user` — Current User (1 subaction) +| Subaction | Description | +|-----------|-------------| +| `me` | Current authenticated user info | + +#### `live` — Real-Time Subscriptions (11 subactions) +Persistent WebSocket connections. Returns `{"status": "connecting"}` on first call — retry momentarily. + +| Subaction | Description | +|-----------|-------------| +| `cpu` | Live CPU utilization | +| `memory` | Live memory usage | +| `cpu_telemetry` | Detailed CPU telemetry | +| `array_state` | Live array state changes | +| `parity_progress` | Live parity check progress | +| `ups_status` | Live UPS status | +| `notifications_overview` | Live notification counts | +| `owner` | Live owner info | +| `server_status` | Live server status | +| `log_tail` | Live log tail stream (requires `path`) | +| `notification_feed` | Live notification feed | + +--- + +### `diagnose_subscriptions` — Subscription Diagnostics + +Inspect WebSocket subscription connection states, errors, and URLs. No parameters required. + +--- + +### `test_subscription_query` — Subscription Query Tester + +Test a specific GraphQL subscription query against the live Unraid API. Uses an allowlisted set of safe fields only. + +--- + +## Destructive Actions + +All require `confirm=True`. Without it, the action is blocked. + +| Domain | Subaction | +|--------|-----------| +| `array` | `stop_array`, `remove_disk`, `clear_disk_stats` | +| `vm` | `force_stop`, `reset` | +| `notification` | `delete`, `delete_archived` | +| `rclone` | `delete_remote` | +| `key` | `delete` | +| `disk` | `flash_backup` | +| `setting` | `configure_ups` | +| `plugin` | `remove` | + +--- ## Support - **Issues:** https://github.com/jmagar/unraid-mcp/issues - **Repository:** https://github.com/jmagar/unraid-mcp +- **Skill docs:** `skills/unraid/SKILL.md` +- **API reference:** `skills/unraid/references/` diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 534760c..2ecc363 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -5,7 +5,7 @@ "email": "jmagar@users.noreply.github.com" }, "metadata": { - "description": "Comprehensive Unraid server management and monitoring via a single consolidated MCP tool (~108 actions across 15 domains)", + "description": "Unraid server management via 3 MCP tools: `unraid` (107 subactions across 15 domains), `diagnose_subscriptions`, and `test_subscription_query`", "version": "1.1.3", "homepage": "https://github.com/jmagar/unraid-mcp", "repository": "https://github.com/jmagar/unraid-mcp"