mirror of
https://github.com/jmagar/unraid-mcp.git
synced 2026-03-01 16:04:24 -08:00
feat: harden API safety and expand command docs with full test coverage
This commit is contained in:
Jacob Magar
30
commands/array.md
Normal file
30
commands/array.md
Normal file
@@ -0,0 +1,30 @@
|
||||
---
|
||||
description: Manage Unraid array parity checks
|
||||
argument-hint: [action] [correct=true/false]
|
||||
---
|
||||
|
||||
Execute the `unraid_array` MCP tool with action: `$1`
|
||||
|
||||
## Available Actions (5)
|
||||
|
||||
**Parity Check Operations:**
|
||||
- `parity_start` - Start parity check/sync (optional: correct=true to fix errors)
|
||||
- `parity_pause` - Pause running parity operation
|
||||
- `parity_resume` - Resume paused parity operation
|
||||
- `parity_cancel` - Cancel running parity operation
|
||||
- `parity_status` - Get current parity check status
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
/array parity_start
|
||||
/array parity_start correct=true
|
||||
/array parity_pause
|
||||
/array parity_resume
|
||||
/array parity_cancel
|
||||
/array parity_status
|
||||
```
|
||||
|
||||
**Note:** Use `correct=true` with `parity_start` to automatically fix any parity errors found during the check.
|
||||
|
||||
Use the tool to execute the requested parity operation and report the results.
|
||||
48
commands/docker.md
Normal file
48
commands/docker.md
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
description: Manage Docker containers on Unraid
|
||||
argument-hint: [action] [additional-args]
|
||||
---
|
||||
|
||||
Execute the `unraid_docker` MCP tool with action: `$1`
|
||||
|
||||
## Available Actions (15)
|
||||
|
||||
**Query Operations:**
|
||||
- `list` - List all Docker containers with status
|
||||
- `details` - Get detailed info for a container (requires container identifier)
|
||||
- `logs` - Get container logs (requires container identifier)
|
||||
- `check_updates` - Check for available container updates
|
||||
- `port_conflicts` - Identify port conflicts
|
||||
- `networks` - List Docker networks
|
||||
- `network_details` - Get network details (requires network identifier)
|
||||
|
||||
**Container Lifecycle:**
|
||||
- `start` - Start a stopped container (requires container identifier)
|
||||
- `stop` - Stop a running container (requires container identifier)
|
||||
- `restart` - Restart a container (requires container identifier)
|
||||
- `pause` - Pause a running container (requires container identifier)
|
||||
- `unpause` - Unpause a paused container (requires container identifier)
|
||||
|
||||
**Updates & Management:**
|
||||
- `update` - Update a specific container (requires container identifier)
|
||||
- `update_all` - Update all containers with available updates
|
||||
|
||||
**⚠️ Destructive:**
|
||||
- `remove` - Permanently delete a container (requires container identifier + confirmation)
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
/unraid-docker list
|
||||
/unraid-docker details plex
|
||||
/unraid-docker logs plex
|
||||
/unraid-docker start nginx
|
||||
/unraid-docker restart sonarr
|
||||
/unraid-docker check_updates
|
||||
/unraid-docker update plex
|
||||
/unraid-docker port_conflicts
|
||||
```
|
||||
|
||||
**Container Identification:** Use container name, ID, or partial match (fuzzy search supported)
|
||||
|
||||
Use the tool to execute the requested Docker operation and report the results.
|
||||
59
commands/health.md
Normal file
59
commands/health.md
Normal file
@@ -0,0 +1,59 @@
|
||||
---
|
||||
description: Check Unraid system health and connectivity
|
||||
argument-hint: [action]
|
||||
---
|
||||
|
||||
Execute the `unraid_health` MCP tool with action: `$1`
|
||||
|
||||
## Available Actions (3)
|
||||
|
||||
**Health Monitoring:**
|
||||
- `check` - Comprehensive health check of all system components
|
||||
- `test_connection` - Test basic API connectivity
|
||||
- `diagnose` - Detailed diagnostic information for troubleshooting
|
||||
|
||||
## What Each Action Checks
|
||||
|
||||
### `check` - System Health
|
||||
- API connectivity and response time
|
||||
- Array status and disk health
|
||||
- Running services status
|
||||
- Docker container health
|
||||
- VM status
|
||||
- System resources (CPU, RAM, disk I/O)
|
||||
- Network connectivity
|
||||
- UPS status (if configured)
|
||||
|
||||
Returns: Overall health status (`HEALTHY`, `WARNING`, `CRITICAL`) with component details
|
||||
|
||||
### `test_connection` - Connectivity
|
||||
- GraphQL endpoint availability
|
||||
- Authentication validity
|
||||
- Basic query execution
|
||||
- Network latency
|
||||
|
||||
Returns: Connection status and latency metrics
|
||||
|
||||
### `diagnose` - Diagnostic Details
|
||||
- Full system configuration
|
||||
- Resource utilization trends
|
||||
- Error logs and warnings
|
||||
- Component-level diagnostics
|
||||
- Troubleshooting recommendations
|
||||
|
||||
Returns: Detailed diagnostic report
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
/unraid-health check
|
||||
/unraid-health test_connection
|
||||
/unraid-health diagnose
|
||||
```
|
||||
|
||||
**Use Cases:**
|
||||
- `check` - Quick health status (monitoring dashboards)
|
||||
- `test_connection` - Verify API access (troubleshooting)
|
||||
- `diagnose` - Deep dive debugging (issue resolution)
|
||||
|
||||
Use the tool to execute the requested health check and present results with clear severity indicators.
|
||||
50
commands/info.md
Normal file
50
commands/info.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
description: Query Unraid server information and configuration
|
||||
argument-hint: [action] [additional-args]
|
||||
---
|
||||
|
||||
Execute the `unraid_info` MCP tool with action: `$1`
|
||||
|
||||
## Available Actions (19)
|
||||
|
||||
**System Overview:**
|
||||
- `overview` - Complete system summary with all key metrics
|
||||
- `server` - Server details (hostname, version, uptime)
|
||||
- `servers` - List all known Unraid servers
|
||||
|
||||
**Array & Storage:**
|
||||
- `array` - Array status, disks, and health
|
||||
|
||||
**Network & Registration:**
|
||||
- `network` - Network configuration and interfaces
|
||||
- `registration` - Registration status and license info
|
||||
- `connect` - Connect service configuration
|
||||
- `online` - Online status check
|
||||
|
||||
**Configuration:**
|
||||
- `config` - System configuration settings
|
||||
- `settings` - User settings and preferences
|
||||
- `variables` - Environment variables
|
||||
- `display` - Display settings
|
||||
|
||||
**Services & Monitoring:**
|
||||
- `services` - Running services status
|
||||
- `metrics` - System metrics (CPU, RAM, disk I/O)
|
||||
- `ups_devices` - List all UPS devices
|
||||
- `ups_device` - Get specific UPS device details (requires device_id)
|
||||
- `ups_config` - UPS configuration
|
||||
|
||||
**Ownership:**
|
||||
- `owner` - Server owner information
|
||||
- `flash` - USB flash drive details
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
/unraid-info overview
|
||||
/unraid-info array
|
||||
/unraid-info metrics
|
||||
/unraid-info ups_device [device-id]
|
||||
```
|
||||
|
||||
Use the tool to retrieve the requested information and present it in a clear, formatted manner.
|
||||
37
commands/keys.md
Normal file
37
commands/keys.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
description: Manage Unraid API keys for authentication
|
||||
argument-hint: [action] [key-id]
|
||||
---
|
||||
|
||||
Execute the `unraid_keys` MCP tool with action: `$1`
|
||||
|
||||
## Available Actions (5)
|
||||
|
||||
**Query Operations:**
|
||||
- `list` - List all API keys with metadata
|
||||
- `get` - Get details for a specific API key (requires key_id)
|
||||
|
||||
**Management Operations:**
|
||||
- `create` - Create a new API key (requires name, optional description and expiry)
|
||||
- `update` - Update an existing API key (requires key_id, name, description)
|
||||
|
||||
**⚠️ Destructive:**
|
||||
- `delete` - Permanently revoke an API key (requires key_id + confirmation)
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
/unraid-keys list
|
||||
/unraid-keys get [key-id]
|
||||
/unraid-keys create "MCP Server Key" "Key for unraid-mcp integration"
|
||||
/unraid-keys update [key-id] "Updated Name" "Updated description"
|
||||
```
|
||||
|
||||
**Key Format:** PrefixedID (`hex64:suffix`)
|
||||
|
||||
**IMPORTANT:**
|
||||
- Deleted keys are immediately revoked and cannot be recovered
|
||||
- Store new keys securely - they're only shown once during creation
|
||||
- Set expiry dates for keys used in automation
|
||||
|
||||
Use the tool to execute the requested API key operation and report the results.
|
||||
41
commands/notifications.md
Normal file
41
commands/notifications.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
description: Manage Unraid system notifications and alerts
|
||||
argument-hint: [action] [additional-args]
|
||||
---
|
||||
|
||||
Execute the `unraid_notifications` MCP tool with action: `$1`
|
||||
|
||||
## Available Actions (9)
|
||||
|
||||
**Query Operations:**
|
||||
- `overview` - Summary of notification counts by category
|
||||
- `list` - List all notifications with details
|
||||
- `warnings` - List only warning/error notifications
|
||||
- `unread` - List unread notifications only
|
||||
|
||||
**Management Operations:**
|
||||
- `create` - Create a new notification (requires title, message, severity)
|
||||
- `archive` - Archive a specific notification (requires notification_id)
|
||||
- `archive_all` - Archive all current notifications
|
||||
|
||||
**⚠️ Destructive Operations:**
|
||||
- `delete` - Permanently delete a notification (requires notification_id + confirmation)
|
||||
- `delete_archived` - Permanently delete all archived notifications (requires confirmation)
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
/unraid-notifications overview
|
||||
/unraid-notifications list
|
||||
/unraid-notifications warnings
|
||||
/unraid-notifications unread
|
||||
/unraid-notifications create "Test Alert" "This is a test" normal
|
||||
/unraid-notifications archive [notification-id]
|
||||
/unraid-notifications archive_all
|
||||
```
|
||||
|
||||
**Severity Levels:** `normal`, `warning`, `alert`, `critical`
|
||||
|
||||
**IMPORTANT:** Delete operations are permanent and cannot be undone.
|
||||
|
||||
Use the tool to execute the requested notification operation and present results clearly.
|
||||
32
commands/rclone.md
Normal file
32
commands/rclone.md
Normal file
@@ -0,0 +1,32 @@
|
||||
---
|
||||
description: Manage Rclone cloud storage remotes on Unraid
|
||||
argument-hint: [action] [remote-name]
|
||||
---
|
||||
|
||||
Execute the `unraid_rclone` MCP tool with action: `$1`
|
||||
|
||||
## Available Actions (4)
|
||||
|
||||
**Query Operations:**
|
||||
- `list_remotes` - List all configured Rclone remotes
|
||||
- `config_form` - Get configuration form for a remote type (requires remote_type)
|
||||
|
||||
**Management Operations:**
|
||||
- `create_remote` - Create a new Rclone remote (requires remote_name, remote_type, config)
|
||||
|
||||
**⚠️ Destructive:**
|
||||
- `delete_remote` - Permanently delete a remote (requires remote_name + confirmation)
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
/unraid-rclone list_remotes
|
||||
/unraid-rclone config_form s3
|
||||
/unraid-rclone create_remote mybackup s3 {"access_key":"...","secret_key":"..."}
|
||||
```
|
||||
|
||||
**Supported Remote Types:** s3, dropbox, google-drive, onedrive, backblaze, ftp, sftp, webdav, etc.
|
||||
|
||||
**IMPORTANT:** Deleting a remote does NOT delete cloud data, only the local configuration.
|
||||
|
||||
Use the tool to execute the requested Rclone operation and report the results.
|
||||
33
commands/storage.md
Normal file
33
commands/storage.md
Normal file
@@ -0,0 +1,33 @@
|
||||
---
|
||||
description: Query Unraid storage, shares, and disk information
|
||||
argument-hint: [action] [additional-args]
|
||||
---
|
||||
|
||||
Execute the `unraid_storage` MCP tool with action: `$1`
|
||||
|
||||
## Available Actions (6)
|
||||
|
||||
**Shares & Disks:**
|
||||
- `shares` - List all user shares with sizes and allocation
|
||||
- `disks` - List all disks in the array
|
||||
- `disk_details` - Get detailed info for a specific disk (requires disk identifier)
|
||||
- `unassigned` - List unassigned devices
|
||||
|
||||
**Logs:**
|
||||
- `log_files` - List available system log files
|
||||
- `logs` - Read log file contents (requires log file path)
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
/unraid-storage shares
|
||||
/unraid-storage disks
|
||||
/unraid-storage disk_details disk1
|
||||
/unraid-storage unassigned
|
||||
/unraid-storage log_files
|
||||
/unraid-storage logs /var/log/syslog
|
||||
```
|
||||
|
||||
**Note:** Log file paths must start with `/var/log/`, `/boot/logs/`, or `/mnt/`
|
||||
|
||||
Use the tool to retrieve the requested storage information and present it clearly.
|
||||
31
commands/users.md
Normal file
31
commands/users.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
description: Query current authenticated Unraid user
|
||||
argument-hint: [action]
|
||||
---
|
||||
|
||||
Execute the `unraid_users` MCP tool with action: `$1`
|
||||
|
||||
## Available Actions (1)
|
||||
|
||||
**Query Operation:**
|
||||
- `me` - Get current authenticated user info (id, name, description, roles)
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
/users me
|
||||
```
|
||||
|
||||
## API Limitation
|
||||
|
||||
⚠️ **Note:** The Unraid GraphQL API does not support user management operations. Only the `me` query is available, which returns information about the currently authenticated user (the API key holder).
|
||||
|
||||
**Not supported:**
|
||||
- Listing all users
|
||||
- Getting other user details
|
||||
- Adding/deleting users
|
||||
- Cloud/remote access queries
|
||||
|
||||
For user management, use the Unraid web UI.
|
||||
|
||||
Use the tool to query the current authenticated user and report the results.
|
||||
41
commands/vm.md
Normal file
41
commands/vm.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
description: Manage virtual machines on Unraid
|
||||
argument-hint: [action] [vm-id]
|
||||
---
|
||||
|
||||
Execute the `unraid_vm` MCP tool with action: `$1` and vm_id: `$2`
|
||||
|
||||
## Available Actions (9)
|
||||
|
||||
**Query Operations:**
|
||||
- `list` - List all VMs with status and resource allocation
|
||||
- `details` - Get detailed info for a VM (requires vm_id)
|
||||
|
||||
**Lifecycle Operations:**
|
||||
- `start` - Start a stopped VM (requires vm_id)
|
||||
- `stop` - Gracefully stop a running VM (requires vm_id)
|
||||
- `pause` - Pause a running VM (requires vm_id)
|
||||
- `resume` - Resume a paused VM (requires vm_id)
|
||||
- `reboot` - Gracefully reboot a VM (requires vm_id)
|
||||
|
||||
**⚠️ Destructive Operations:**
|
||||
- `force_stop` - Forcefully power off VM (like pulling power cord - requires vm_id + confirmation)
|
||||
- `reset` - Hard reset VM (power cycle without graceful shutdown - requires vm_id + confirmation)
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
/unraid-vm list
|
||||
/unraid-vm details windows-10
|
||||
/unraid-vm start ubuntu-server
|
||||
/unraid-vm stop windows-10
|
||||
/unraid-vm pause debian-vm
|
||||
/unraid-vm resume debian-vm
|
||||
/unraid-vm reboot ubuntu-server
|
||||
```
|
||||
|
||||
**VM Identification:** Use VM ID (PrefixedID format: `hex64:suffix`)
|
||||
|
||||
**IMPORTANT:** `force_stop` and `reset` bypass graceful shutdown and may corrupt VM filesystem. Use `stop` instead for safe shutdowns.
|
||||
|
||||
Use the tool to execute the requested VM operation and report the results.
|
||||
Reference in New Issue
Block a user