feat: add 28 GraphQL mutations across storage, info, docker, and new settings tool

- storage: flash_backup mutation (initiates rclone flash backup, destructive)
- info: update_server and update_ssh mutations
- docker: 11 organizer mutations (create_folder, set_folder_children,
  delete_entries, move_to_folder, move_to_position, rename_folder,
  create_folder_with_items, update_view_prefs, sync_templates,
  reset_template_mappings, refresh_digests); delete_entries and
  reset_template_mappings added to DESTRUCTIVE_ACTIONS
- settings: new unraid_settings tool with 9 mutations (update,
  update_temperature, update_time, configure_ups, update_api,
  connect_sign_in, connect_sign_out, setup_remote_access,
  enable_dynamic_remote_access); registered in server.py
- tests: 82 new tests (28 settings, 23 docker organizer, 7 info, 6 storage
  + 18 existing fixes for notification regex and safety audit list)
- bump version 0.3.0 → 0.4.0 (11 tools, ~104 actions)

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Jacob Magar
2026-03-13 03:03:37 -04:00
parent 4af1e74b4a
commit 9aee3a2448
11 changed files with 994 additions and 7 deletions

View File

@@ -41,7 +41,7 @@ KNOWN_DESTRUCTIVE: dict[str, dict[str, set[str]]] = {
"module": "unraid_mcp.tools.docker",
"register_fn": "register_docker_tool",
"tool_name": "unraid_docker",
"actions": {"remove", "update_all"},
"actions": {"remove", "update_all", "delete_entries", "reset_template_mappings"},
"runtime_set": DOCKER_DESTRUCTIVE,
},
"vm": {

View File

@@ -342,3 +342,111 @@ class TestDockerNetworkErrors:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="Invalid JSON"):
await tool_fn(action="list")
_ORGANIZER_RESPONSE = {"version": 1.0, "views": [{"id": "default", "name": "Default", "rootId": "root", "flatEntries": []}]}
class TestDockerOrganizerMutations:
async def test_create_folder_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"createDockerFolder": _ORGANIZER_RESPONSE}
result = await _make_tool()(action="create_folder", folder_name="Media")
assert result["success"] is True
async def test_create_folder_requires_name(self, _mock_graphql: AsyncMock) -> None:
with pytest.raises(ToolError, match="folder_name"):
await _make_tool()(action="create_folder")
async def test_set_folder_children_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"setDockerFolderChildren": _ORGANIZER_RESPONSE}
result = await _make_tool()(action="set_folder_children", children_ids=["c1"])
assert result["success"] is True
async def test_set_folder_children_requires_children(self, _mock_graphql: AsyncMock) -> None:
with pytest.raises(ToolError, match="children_ids"):
await _make_tool()(action="set_folder_children")
async def test_delete_entries_requires_confirm(self, _mock_graphql: AsyncMock) -> None:
with pytest.raises(ToolError, match="destructive"):
await _make_tool()(action="delete_entries", entry_ids=["e1"])
async def test_delete_entries_requires_ids(self, _mock_graphql: AsyncMock) -> None:
with pytest.raises(ToolError, match="entry_ids"):
await _make_tool()(action="delete_entries", confirm=True)
async def test_delete_entries_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"deleteDockerEntries": _ORGANIZER_RESPONSE}
result = await _make_tool()(action="delete_entries", entry_ids=["e1"], confirm=True)
assert result["success"] is True
async def test_move_to_folder_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"moveDockerEntriesToFolder": _ORGANIZER_RESPONSE}
result = await _make_tool()(action="move_to_folder", source_entry_ids=["e1"], destination_folder_id="f1")
assert result["success"] is True
async def test_move_to_folder_requires_source_ids(self, _mock_graphql: AsyncMock) -> None:
with pytest.raises(ToolError, match="source_entry_ids"):
await _make_tool()(action="move_to_folder", destination_folder_id="f1")
async def test_move_to_folder_requires_destination(self, _mock_graphql: AsyncMock) -> None:
with pytest.raises(ToolError, match="destination_folder_id"):
await _make_tool()(action="move_to_folder", source_entry_ids=["e1"])
async def test_move_to_position_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"moveDockerItemsToPosition": _ORGANIZER_RESPONSE}
result = await _make_tool()(action="move_to_position", source_entry_ids=["e1"], destination_folder_id="f1", position=2.0)
assert result["success"] is True
async def test_move_to_position_requires_position(self, _mock_graphql: AsyncMock) -> None:
with pytest.raises(ToolError, match="position"):
await _make_tool()(action="move_to_position", source_entry_ids=["e1"], destination_folder_id="f1")
async def test_rename_folder_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"renameDockerFolder": _ORGANIZER_RESPONSE}
result = await _make_tool()(action="rename_folder", folder_id="f1", new_folder_name="New")
assert result["success"] is True
async def test_rename_folder_requires_folder_id(self, _mock_graphql: AsyncMock) -> None:
with pytest.raises(ToolError, match="folder_id"):
await _make_tool()(action="rename_folder", new_folder_name="New")
async def test_rename_folder_requires_new_name(self, _mock_graphql: AsyncMock) -> None:
with pytest.raises(ToolError, match="new_folder_name"):
await _make_tool()(action="rename_folder", folder_id="f1")
async def test_create_folder_with_items_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"createDockerFolderWithItems": _ORGANIZER_RESPONSE}
result = await _make_tool()(action="create_folder_with_items", folder_name="New")
assert result["success"] is True
async def test_create_folder_with_items_requires_name(self, _mock_graphql: AsyncMock) -> None:
with pytest.raises(ToolError, match="folder_name"):
await _make_tool()(action="create_folder_with_items")
async def test_update_view_prefs_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"updateDockerViewPreferences": _ORGANIZER_RESPONSE}
result = await _make_tool()(action="update_view_prefs", view_prefs={"sort": "name"})
assert result["success"] is True
async def test_update_view_prefs_requires_prefs(self, _mock_graphql: AsyncMock) -> None:
with pytest.raises(ToolError, match="view_prefs"):
await _make_tool()(action="update_view_prefs")
async def test_sync_templates_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"syncDockerTemplatePaths": {"scanned": 5, "matched": 4, "skipped": 1, "errors": []}}
result = await _make_tool()(action="sync_templates")
assert result["success"] is True
async def test_reset_template_mappings_requires_confirm(self, _mock_graphql: AsyncMock) -> None:
with pytest.raises(ToolError, match="destructive"):
await _make_tool()(action="reset_template_mappings")
async def test_reset_template_mappings_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"resetDockerTemplateMappings": True}
result = await _make_tool()(action="reset_template_mappings", confirm=True)
assert result["success"] is True
async def test_refresh_digests_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"refreshDockerDigests": True}
result = await _make_tool()(action="refresh_digests")
assert result["success"] is True

View File

@@ -282,3 +282,46 @@ class TestInfoNetworkErrors:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="Invalid JSON"):
await tool_fn(action="network")
class TestInfoMutations:
async def test_update_server_requires_name(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="server_name"):
await tool_fn(action="update_server")
async def test_update_server_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"updateServerIdentity": {"id": "s:1", "name": "tootie", "comment": None, "status": "online"}}
tool_fn = _make_tool()
result = await tool_fn(action="update_server", server_name="tootie")
assert result["success"] is True
assert result["data"]["name"] == "tootie"
async def test_update_server_passes_optional_fields(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"updateServerIdentity": {"id": "s:1", "name": "x", "comment": None, "status": "online"}}
tool_fn = _make_tool()
await tool_fn(action="update_server", server_name="x", sys_model="custom")
assert _mock_graphql.call_args[0][1]["sysModel"] == "custom"
async def test_update_ssh_requires_enabled(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="ssh_enabled"):
await tool_fn(action="update_ssh", ssh_port=22)
async def test_update_ssh_requires_port(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="ssh_port"):
await tool_fn(action="update_ssh", ssh_enabled=True)
async def test_update_ssh_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"updateSshSettings": {"id": "s:1", "useSsh": True, "portssh": 22}}
tool_fn = _make_tool()
result = await tool_fn(action="update_ssh", ssh_enabled=True, ssh_port=22)
assert result["success"] is True
assert result["data"]["useSsh"] is True
async def test_update_ssh_passes_correct_input(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"updateSshSettings": {"id": "s:1", "useSsh": False, "portssh": 2222}}
tool_fn = _make_tool()
await tool_fn(action="update_ssh", ssh_enabled=False, ssh_port=2222)
assert _mock_graphql.call_args[0][1] == {"input": {"enabled": False, "port": 2222}}

View File

@@ -171,7 +171,7 @@ class TestNotificationsCreateValidation:
async def test_invalid_importance_rejected(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="importance must be one of"):
with pytest.raises(ToolError, match="Invalid importance"):
await tool_fn(
action="create",
title="T",
@@ -183,7 +183,7 @@ class TestNotificationsCreateValidation:
async def test_normal_importance_rejected(self, _mock_graphql: AsyncMock) -> None:
"""NORMAL is not a valid GraphQL NotificationImportance value (INFO/WARNING/ALERT are)."""
tool_fn = _make_tool()
with pytest.raises(ToolError, match="importance must be one of"):
with pytest.raises(ToolError, match="Invalid importance"):
await tool_fn(
action="create",
title="T",

266
tests/test_settings.py Normal file
View File

@@ -0,0 +1,266 @@
"""Tests for the unraid_settings tool."""
from __future__ import annotations
from collections.abc import Generator
from unittest.mock import AsyncMock, patch
import pytest
from fastmcp import FastMCP
from unraid_mcp.core.exceptions import ToolError
from unraid_mcp.tools.settings import register_settings_tool
@pytest.fixture
def _mock_graphql() -> Generator[AsyncMock, None, None]:
with patch("unraid_mcp.tools.settings.make_graphql_request", new_callable=AsyncMock) as mock:
yield mock
def _make_tool() -> AsyncMock:
test_mcp = FastMCP("test")
register_settings_tool(test_mcp)
return test_mcp._tool_manager._tools["unraid_settings"].fn # type: ignore[union-attr]
class TestSettingsValidation:
"""Tests for action validation and destructive guard."""
async def test_invalid_action(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="Invalid action"):
await tool_fn(action="nonexistent_action")
async def test_destructive_configure_ups_requires_confirm(
self, _mock_graphql: AsyncMock
) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="confirm=True"):
await tool_fn(action="configure_ups", ups_config={"mode": "slave"})
async def test_destructive_setup_remote_access_requires_confirm(
self, _mock_graphql: AsyncMock
) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="confirm=True"):
await tool_fn(action="setup_remote_access", access_type="STATIC")
async def test_destructive_enable_dynamic_remote_access_requires_confirm(
self, _mock_graphql: AsyncMock
) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="confirm=True"):
await tool_fn(
action="enable_dynamic_remote_access", access_url_type="WAN", dynamic_enabled=True
)
class TestSettingsUpdate:
"""Tests for update action."""
async def test_update_requires_settings_input(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="settings_input is required"):
await tool_fn(action="update")
async def test_update_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {
"updateSettings": {"restartRequired": False, "values": {}, "warnings": []}
}
tool_fn = _make_tool()
result = await tool_fn(action="update", settings_input={"shareCount": 5})
assert result["success"] is True
assert result["action"] == "update"
async def test_update_temperature_requires_config(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="temperature_config is required"):
await tool_fn(action="update_temperature")
async def test_update_temperature_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"updateTemperatureConfig": True}
tool_fn = _make_tool()
result = await tool_fn(action="update_temperature", temperature_config={"unit": "C"})
assert result["success"] is True
assert result["action"] == "update_temperature"
class TestSystemTime:
"""Tests for update_time action."""
async def test_update_time_requires_at_least_one_field(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="update_time requires"):
await tool_fn(action="update_time")
async def test_update_time_with_timezone(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {
"updateSystemTime": {
"currentTime": "2026-03-13T00:00:00Z",
"timeZone": "America/New_York",
"useNtp": True,
"ntpServers": [],
}
}
tool_fn = _make_tool()
result = await tool_fn(action="update_time", time_zone="America/New_York")
assert result["success"] is True
assert result["action"] == "update_time"
async def test_update_time_with_ntp(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {
"updateSystemTime": {"useNtp": True, "ntpServers": ["0.pool.ntp.org"]}
}
tool_fn = _make_tool()
result = await tool_fn(action="update_time", use_ntp=True, ntp_servers=["0.pool.ntp.org"])
assert result["success"] is True
async def test_update_time_manual(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"updateSystemTime": {"currentTime": "2026-03-13T12:00:00Z"}}
tool_fn = _make_tool()
result = await tool_fn(action="update_time", manual_datetime="2026-03-13T12:00:00Z")
assert result["success"] is True
class TestUpsConfig:
"""Tests for configure_ups action."""
async def test_configure_ups_requires_ups_config(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="ups_config is required"):
await tool_fn(action="configure_ups", confirm=True)
async def test_configure_ups_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"configureUps": True}
tool_fn = _make_tool()
result = await tool_fn(
action="configure_ups", confirm=True, ups_config={"mode": "master", "cable": "usb"}
)
assert result["success"] is True
assert result["action"] == "configure_ups"
class TestApiSettings:
"""Tests for update_api action."""
async def test_update_api_requires_at_least_one_field(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="update_api requires"):
await tool_fn(action="update_api")
async def test_update_api_with_port(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {
"updateApiSettings": {"accessType": "STATIC", "forwardType": "NONE", "port": 8080}
}
tool_fn = _make_tool()
result = await tool_fn(action="update_api", port=8080)
assert result["success"] is True
assert result["action"] == "update_api"
async def test_update_api_with_access_type(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"updateApiSettings": {"accessType": "STATIC"}}
tool_fn = _make_tool()
result = await tool_fn(action="update_api", access_type="STATIC")
assert result["success"] is True
class TestConnectActions:
"""Tests for connect_sign_in and connect_sign_out actions."""
async def test_connect_sign_in_requires_api_key(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="api_key is required"):
await tool_fn(action="connect_sign_in")
async def test_connect_sign_in_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"connectSignIn": True}
tool_fn = _make_tool()
result = await tool_fn(action="connect_sign_in", api_key="test-api-key-abc123")
assert result["success"] is True
assert result["action"] == "connect_sign_in"
async def test_connect_sign_in_with_user_info(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"connectSignIn": True}
tool_fn = _make_tool()
result = await tool_fn(
action="connect_sign_in",
api_key="test-api-key",
username="testuser",
email="test@example.com",
avatar="https://example.com/avatar.png",
)
assert result["success"] is True
async def test_connect_sign_out_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"connectSignOut": True}
tool_fn = _make_tool()
result = await tool_fn(action="connect_sign_out")
assert result["success"] is True
assert result["action"] == "connect_sign_out"
class TestRemoteAccess:
"""Tests for setup_remote_access and enable_dynamic_remote_access actions."""
async def test_setup_remote_access_requires_access_type(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="access_type is required"):
await tool_fn(action="setup_remote_access", confirm=True)
async def test_setup_remote_access_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"setupRemoteAccess": True}
tool_fn = _make_tool()
result = await tool_fn(action="setup_remote_access", confirm=True, access_type="STATIC")
assert result["success"] is True
assert result["action"] == "setup_remote_access"
async def test_setup_remote_access_with_port(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"setupRemoteAccess": True}
tool_fn = _make_tool()
result = await tool_fn(
action="setup_remote_access",
confirm=True,
access_type="STATIC",
forward_type="UPNP",
port=9999,
)
assert result["success"] is True
async def test_enable_dynamic_requires_url_type(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="access_url_type is required"):
await tool_fn(action="enable_dynamic_remote_access", confirm=True, dynamic_enabled=True)
async def test_enable_dynamic_requires_dynamic_enabled(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="dynamic_enabled is required"):
await tool_fn(
action="enable_dynamic_remote_access", confirm=True, access_url_type="WAN"
)
async def test_enable_dynamic_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"enableDynamicRemoteAccess": True}
tool_fn = _make_tool()
result = await tool_fn(
action="enable_dynamic_remote_access",
confirm=True,
access_url_type="WAN",
dynamic_enabled=True,
)
assert result["success"] is True
assert result["action"] == "enable_dynamic_remote_access"
async def test_enable_dynamic_with_optional_fields(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"enableDynamicRemoteAccess": True}
tool_fn = _make_tool()
result = await tool_fn(
action="enable_dynamic_remote_access",
confirm=True,
access_url_type="WAN",
dynamic_enabled=False,
access_url_name="myserver",
access_url_ipv4="1.2.3.4",
access_url_ipv6="::1",
)
assert result["success"] is True

View File

@@ -283,3 +283,38 @@ class TestStorageNetworkErrors:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="HTTP error 500"):
await tool_fn(action="disks")
class TestStorageFlashBackup:
async def test_flash_backup_requires_confirm(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="destructive"):
await tool_fn(action="flash_backup", remote_name="r", source_path="/boot", destination_path="r:b")
async def test_flash_backup_requires_remote_name(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="remote_name"):
await tool_fn(action="flash_backup", confirm=True)
async def test_flash_backup_requires_source_path(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="source_path"):
await tool_fn(action="flash_backup", confirm=True, remote_name="r")
async def test_flash_backup_requires_destination_path(self, _mock_graphql: AsyncMock) -> None:
tool_fn = _make_tool()
with pytest.raises(ToolError, match="destination_path"):
await tool_fn(action="flash_backup", confirm=True, remote_name="r", source_path="/boot")
async def test_flash_backup_success(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"initiateFlashBackup": {"status": "started", "jobId": "j:1"}}
tool_fn = _make_tool()
result = await tool_fn(action="flash_backup", confirm=True, remote_name="r", source_path="/boot", destination_path="r:b")
assert result["success"] is True
assert result["data"]["status"] == "started"
async def test_flash_backup_passes_options(self, _mock_graphql: AsyncMock) -> None:
_mock_graphql.return_value = {"initiateFlashBackup": {"status": "started", "jobId": "j:2"}}
tool_fn = _make_tool()
await tool_fn(action="flash_backup", confirm=True, remote_name="r", source_path="/boot", destination_path="r:b", backup_options={"dryRun": True})
assert _mock_graphql.call_args[0][1]["input"]["options"] == {"dryRun": True}