unraid-mcp/docs/DESTRUCTIVE_ACTIONS.md

Destructive Actions Inventory

This file lists all destructive actions across the unraid-mcp tools. Fill in the "Testing Strategy" column to specify how each should be tested in the mcporter integration test suite.

Last Updated: 2026-02-15

---

Summary

• Total Destructive Actions: 8 (after removing 4 array operations)
• Tools with Destructive Actions: 6
• Environment Variable Gates: 6 (one per tool)

---

Destructive Actions by Tool

1. Docker (1 action)

Action	Description	Risk Level	Env Var Gate	Testing Strategy
remove	Permanently delete a Docker container	HIGH - Data loss, irreversible	UNRAID_ALLOW_DOCKER_DESTRUCTIVE	TODO: Specify testing approach

Notes:

• Container must be stopped first
• Removes container config and any non-volume data
• Cannot be undone

---

2. Virtual Machines (2 actions)

Action	Description	Risk Level	Env Var Gate	Testing Strategy
force_stop	Forcefully power off a running VM (equivalent to pulling power cord)	MEDIUM - Severe but recoverable, risk of data corruption	UNRAID_ALLOW_VM_DESTRUCTIVE	TODO: Specify testing approach
reset	Hard reset a VM (power cycle without graceful shutdown)	MEDIUM - Severe but recoverable, risk of data corruption	UNRAID_ALLOW_VM_DESTRUCTIVE	TODO: Specify testing approach

Notes:

• Both bypass graceful shutdown procedures
• May corrupt VM filesystem if used during write operations
• Use stop action instead for graceful shutdown

---

3. Notifications (2 actions)

Action	Description	Risk Level	Env Var Gate	Testing Strategy
delete	Permanently delete a notification	HIGH - Data loss, irreversible	UNRAID_ALLOW_NOTIFICATIONS_DESTRUCTIVE	TODO: Specify testing approach
delete_archived	Permanently delete all archived notifications	HIGH - Bulk data loss, irreversible	UNRAID_ALLOW_NOTIFICATIONS_DESTRUCTIVE	TODO: Specify testing approach

Notes:

• Cannot recover deleted notifications
• delete_archived affects ALL archived notifications (bulk operation)

---

4. Rclone (1 action)

Action	Description	Risk Level	Env Var Gate	Testing Strategy
delete_remote	Permanently delete an rclone remote configuration	HIGH - Data loss, irreversible	UNRAID_ALLOW_RCLONE_DESTRUCTIVE	TODO: Specify testing approach

Notes:

• Removes cloud storage connection configuration
• Does NOT delete data in the remote storage
• Must reconfigure remote from scratch if deleted

---

5. Users (1 action)

Action	Description	Risk Level	Env Var Gate	Testing Strategy
delete	Permanently delete a user account	HIGH - Data loss, irreversible	UNRAID_ALLOW_USERS_DESTRUCTIVE	TODO: Specify testing approach

Notes:

• Removes user account and permissions
• Cannot delete the root user
• User's data may remain but become orphaned

---

6. API Keys (1 action)

Action	Description	Risk Level	Env Var Gate	Testing Strategy
delete	Permanently delete an API key	HIGH - Data loss, irreversible, breaks integrations	UNRAID_ALLOW_KEYS_DESTRUCTIVE	TODO: Specify testing approach

Notes:

• Immediately revokes API key access
• Will break any integrations using the deleted key
• Cannot be undone - must create new key

---

Removed Actions (No Longer Exposed)

These actions were previously marked as destructive but have been removed from the array tool per the implementation plan:

Action	Former Risk Level	Reason for Removal
start	CRITICAL	System-wide impact - should not be exposed via MCP
stop	CRITICAL	System-wide impact - should not be exposed via MCP
shutdown	CRITICAL	System-wide impact - could cause data loss
reboot	CRITICAL	System-wide impact - disrupts all services

---

Testing Strategy Options

Choose one of the following for each action in the "Testing Strategy" column:

Option 1: Mock/Validation Only

• Test parameter validation
• Test confirm=True requirement
• Test env var gate requirement
• DO NOT execute the actual action

Option 2: Dry-Run Testing

• Test with confirm=false to verify rejection
• Test without env var to verify gate
• DO NOT execute with both gates passed

Option 3: Test Server Execution

• Execute on a dedicated test Unraid server (e.g., shart)
• Requires pre-created test resources (containers, VMs, notifications)
• Verify action succeeds and state changes as expected
• Clean up after test

Option 4: Manual Test Checklist

• Document manual verification steps
• Do not automate in mcporter suite
• Requires human operator to execute and verify

Option 5: Skip Testing

• Too dangerous to automate
• Rely on unit tests only
• Document why testing is skipped

---

Example Testing Strategies

Safe approach (recommended for most):

Option 1: Mock/Validation Only
- Verify action requires UNRAID_ALLOW_DOCKER_DESTRUCTIVE=true
- Verify action requires confirm=True
- Do not execute actual deletion

Comprehensive approach (for test server only):

Option 3: Test Server Execution on 'shart'
- Create test container 'mcporter-test-container'
- Execute remove with gates enabled
- Verify container is deleted
- Clean up not needed (container already removed)

Hybrid approach:

Option 1 + Option 4: Mock validation + Manual checklist
- Automated: Test gate requirements
- Manual: Human operator verifies on test server

---

Usage in mcporter Tests

Each tool test script will check the testing strategy:

# Example from test_docker.sh
test_remove_action() {
    local strategy="TODO: Specify testing approach"  # From this file

    case "$strategy" in
        *"Option 1"*|*"Mock"*)
            # Mock/validation testing
            test_remove_requires_env_var
            test_remove_requires_confirm
            ;;
        *"Option 3"*|*"Test Server"*)
            # Real execution on test server
            if [[ "$UNRAID_TEST_SERVER" != "unraid-shart" ]]; then
                echo "SKIP: Destructive test only runs on test server"
                return 2
            fi
            test_remove_real_execution
            ;;
        *"Option 5"*|*"Skip"*)
            echo "SKIP: Testing disabled for this action"
            return 2
            ;;
    esac
}

---

Security Model

Two-tier security for destructive actions:

1. Environment Variable Gate (first line of defense)

   • Must be explicitly enabled per tool
   • Defaults to disabled (safe)
   • Prevents accidental execution

2. Runtime Confirmation (second line of defense)

   • Must pass confirm=True in each call
   • Forces explicit acknowledgment per operation
   • Cannot be cached or preset

Both must pass for execution.

---

Next Steps

1. Fill in Testing Strategy column for each action above
2. Create test fixtures if using Option 3 (test containers, VMs, etc.)
3. Implement tool test scripts following the specified strategies
4. Document any special setup required for destructive testing

---

Questions to Consider

For each action, ask:

• Is this safe to automate on a test server?
• Do we have test fixtures/resources available?
• What cleanup is required after testing?
• What's the blast radius if something goes wrong?
• Can we verify the action worked without side effects?