Changelog

(unreleased)

Fix

- Even more changes to accommodate older GraphQL schema. [Simon
  Diesenreiter]


0.0.3 (2026-02-28)
------------------

Fix

Adapt for supported GraphQL schema on 6.12.13. [Simon Diesenreiter]

Other



0.0.2 (2026-02-21)
------------------

Fix
~~~
- Set scripts as executable, refs NOISSUE. [Simon Diesenreiter]
- Initial test release. [Simon Diesenreiter]

Other

0.0.1 (2026-02-21)

Fix

- Use CLAUDE_PLUGIN_ROOT for portable MCP server configuration. [Jacob
  Magar]

  Update .mcp.json to use  environment variable
  for the --directory argument, ensuring the MCP server works correctly
  regardless of where the plugin is installed.

  This follows Claude Code plugin best practices for MCP server bundling.
- Correct marketplace.json source field format. [Jacob Magar]

  Change source from absolute GitHub URL to relative path "./"
  This follows Claude Code marketplace convention where source paths
  are relative to the cloned repository root, not external URLs.

  Matches pattern from working examples like claude-homelab marketplace.
- Upgrade fastmcp and mcp to resolve remaining security vulnerabilities.
  [Claude]

  Security Updates:
  - fastmcp 2.12.5 → 2.14.5 (fixes CVE-2025-66416, command injection, XSS, auth takeover)
  - mcp 1.16.0 → 1.26.0 (enables DNS rebinding protection, addresses CVE requirements)
  - websockets 13.1 → 16.0 (required dependency for fastmcp 2.14.5)

  Dependency Changes:
  + beartype 0.22.9
  + cachetools 7.0.1
  + cloudpickle 3.1.2
  + croniter 6.0.0
  + diskcache 5.6.3
  + fakeredis 2.34.0
  + importlib-metadata 8.7.1
  + jsonref 1.1.1
  + lupa 2.6
  + opentelemetry-api 1.39.1
  + pathvalidate 3.3.1
  + platformdirs 4.9.2
  + prometheus-client 0.24.1
  + py-key-value-aio 0.3.0
  + py-key-value-shared 0.3.0
  + pydocket 0.17.7
  + pyjwt 2.11.0
  + python-dateutil 2.9.0.post0
  + python-json-logger 4.0.0
  + redis 7.2.0
  + shellingham 1.5.4
  + sortedcontainers 2.4.0
  + typer 0.23.2
  + zipp 3.23.0

  Removed Dependencies:
  - isodate 0.7.2
  - lazy-object-proxy 1.12.0
  - markupsafe 3.0.3
  - openapi-core 0.22.0
  - openapi-schema-validator 0.6.3
  - openapi-spec-validator 0.7.2
  - rfc3339-validator 0.1.4
  - werkzeug 3.1.5

  Testing:
  - All 493 tests pass
  - Type checking passes (ty check)
  - Linting passes (ruff check)

  This completes the resolution of GitHub Dependabot security alerts.
  Addresses the remaining 5 high/medium severity vulnerabilities in fastmcp and mcp packages.
- Correct marketplace.json source field and improve async operations.
  [Jacob Magar]

  - Fix marketplace.json: change source from relative path to GitHub URL
    (was "skills/unraid", now "https://github.com/jmagar/unraid-mcp")
    This resolves the "Invalid input" schema validation error when adding
    the marketplace to Claude Code

  - Refactor subscriptions autostart to use anyio.Path for async file checks
    (replaces blocking pathlib.Path.exists() with async anyio.Path.exists())

  - Update dependencies: anyio 4.11.0→4.12.1, attrs 25.3.0→25.4.0
- Correct marketplace.json format for Claude Code compatibility.
  [Claude]

  - Rename marketplace from "unraid-mcp" to "jmagar-unraid-mcp" to match expected directory structure
  - Wrap description, version, homepage, and repository in metadata object per standard format
  - Fixes "Marketplace file not found" error when adding marketplace to Claude Code

  Resolves marketplace installation issues by aligning with format used by other Claude Code marketplaces.
- Address PR comment #38 - remove duplicate User-Agent header. [Jacob
  Magar]

  Resolves review thread PRRT_kwDOO6Hdxs5uu7z7
  - Removed redundant User-Agent header from per-request headers in make_graphql_request()
  - User-Agent is already set as default header on the shared HTTP client
  - httpx merges per-request headers with client defaults, so client-level default is sufficient
- Harden read-logs.sh against GraphQL injection and path traversal.
  [Jacob Magar]

  - Remove slashes from LOG_NAME regex to block path traversal (e.g.
    ../../etc/passwd). Only alphanumeric, dots, hyphens, underscores allowed.
  - Cap LINES to 1-10000 range to prevent resource exhaustion.
  - Add query script existence check before execution.
  - Add query failure, empty response, and invalid JSON guards.

  Resolves review thread PRRT_kwDOO6Hdxs5uvKrj
- Address 5 critical and major PR review issues. [Jacob Magar]

  - Remove set -e from validate-marketplace.sh to prevent early exit on
    check failures, allowing the summary to always be displayed (PRRT_kwDOO6Hdxs5uvKrc)
  - Fix marketplace.json source path to point to skills/unraid instead of
    ./ for correct plugin directory resolution (PRRT_kwDOO6Hdxs5uvKrg)
  - Fix misleading trap registration comment in unraid-api-crawl.md and
    add auth note to Apollo Studio URL (PRRT_kwDOO6Hdxs5uvO2t)
  - Extract duplicated cleanup-with-error-handling in main.py into
    _run_shutdown_cleanup() helper (PRRT_kwDOO6Hdxs5uvO3A)
  - Add input validation to read-logs.sh to prevent GraphQL injection
    via LOG_NAME and LINES parameters (PRRT_kwDOO6Hdxs5uvKrj)
- Address PR review comments on test suite. [Jacob Magar]

  - Rename test_start_http_401_unauthorized to test_list_http_401_unauthorized
    to match the actual action="list" being tested (threads #19, #23)
  - Use consistent PrefixedID format ("a"*64+":local") in test_start_container
    instead of "abc123def456"*4 concatenation (thread #37)
  - Refactor container_actions_require_id to use @pytest.mark.parametrize
    so each action runs independently (thread #18)
  - Fix docstring claiming ToolError for test that asserts success in
    test_stop_mutation_returns_null (thread #26)
  - Fix inaccurate comment about `in` operator checking truthiness;
    it checks key existence (thread #25)
  - Add edge case tests for temperature=0, temperature=null, and
    logFile=null in test_storage.py (thread #31)

  Resolves review threads: PRRT_kwDOO6Hdxs5uvO2-, PRRT_kwDOO6Hdxs5uvOcf,
  PRRT_kwDOO6Hdxs5uu7zx, PRRT_kwDOO6Hdxs5uvO28, PRRT_kwDOO6Hdxs5uvOcp,
  PRRT_kwDOO6Hdxs5uvOcn, PRRT_kwDOO6Hdxs5uvKr3
- Harden shell scripts with error handling and null guards. [Jacob
  Magar]

  - dashboard.sh: Add // [] jq null guard on .data.array.disks[] (L176-177)
    Resolves review thread PRRT_kwDOO6Hdxs5uvO21

  - dashboard.sh: Default NAME to server key when env var unset (L221)
    Resolves review thread PRRT_kwDOO6Hdxs5uvO22

  - unraid-query.sh: Check curl exit code, empty response, and JSON validity
    before piping to jq (L112-129)
    Resolves review thread PRRT_kwDOO6Hdxs5uvO24

  - disk-health.sh: Guard against missing query script and invalid responses
    Resolves review thread PRRT_kwDOO6Hdxs5uvKrh
- Address 54 MEDIUM/LOW priority PR review issues. [Jacob Magar]

  Comprehensive fixes across Python code, shell scripts, and documentation
  addressing all remaining MEDIUM and LOW priority review comments.

  Python Code Fixes (27 fixes):
  - tools/info.py: Simplified dispatch with lookup tables, defensive guards,
    CPU fallback formatting, !s conversion flags, module-level sync assertion
  - tools/docker.py: Case-insensitive container ID regex, keyword-only confirm,
    module-level ALL_ACTIONS constant
  - tools/virtualization.py: Normalized single-VM dict responses, unified
    list/details queries
  - core/client.py: Fixed HTTP client singleton race condition, compound key
    substring matching for sensitive data redaction
  - subscriptions/: Extracted SSL context creation to shared helper in utils.py,
    replaced deprecated ssl._create_unverified_context API
  - tools/array.py: Renamed parity_history to parity_status, hoisted ALL_ACTIONS
  - tools/storage.py: Fixed dict(None) risks, temperature 0 falsiness bug
  - tools/notifications.py, keys.py, rclone.py: Fixed dict(None) TypeError risks
  - tests/: Fixed generator type annotations, added coverage for compound keys

  Shell Script Fixes (13 fixes):
  - dashboard.sh: Dynamic server discovery, conditional debug output, null-safe
    jq, notification count guard order, removed unused variables
  - unraid-query.sh: Proper JSON escaping via jq, --ignore-errors and --insecure
    CLI flags, TLS verification now on by default
  - validate-marketplace.sh: Removed unused YELLOW variable, defensive jq,
    simplified repository URL output

  Documentation Fixes (24+ fixes):
  - Version consistency: Updated all references to v0.2.0 across pyproject.toml,
    plugin.json, marketplace.json, MARKETPLACE.md, __init__.py, README files
  - Tool count updates: Changed all "26 tools" references to "10 tools, 90 actions"
  - Markdown lint: Fixed MD022, MD031, MD047 issues across multiple files
  - Research docs: Fixed auth headers, removed web artifacts, corrected stale info
  - Skills docs: Fixed query examples, endpoint counts, env var references

  All 227 tests pass, ruff and ty checks clean.
- Update Subprotocol import and SSL handling in WebSocket modules.
  [Jacob Magar]

  - Change Subprotocol import from deprecated websockets.legacy.protocol
    to websockets.typing (canonical location in websockets 13.x)
  - Fix SSL context handling in diagnostics.py to properly build
    ssl.SSLContext objects, matching the pattern in manager.py
    (previously passed UNRAID_VERIFY_SSL directly which breaks
    when it's a CA bundle path string)
- Resolve ruff lint issues in storage tool and tests. [Jacob Magar]

  - Move _ALLOWED_LOG_PREFIXES to module level (N806: constant naming)
  - Use f-string conversion flag {e!s} instead of {str(e)} (RUF010)
  - Fix import block sorting in both files (I001)
- Address 18 CRITICAL+HIGH PR review comments. [Jacob Magar, config-
  fixer, docker-fixer, info-fixer, keys-rclone-fixer, storage-fixer,
  users-fixer, vm-fixer, websocket-fixer]

  **Critical Fixes (7 issues):**
  - Fix GraphQL schema field names in users tool (role→roles, remove email)
  - Fix GraphQL mutation signatures (addUserInput, deleteUser input)
  - Fix dict(None) TypeError guards in users tool (use `or {}` pattern)
  - Fix FastAPI version constraint (0.116.1→0.115.0)
  - Fix WebSocket SSL context handling (support CA bundles, bool, and None)
  - Fix critical disk threshold treated as warning (split counters)

  **High Priority Fixes (11 issues):**
  - Fix Docker update/remove action response field mapping
  - Fix path traversal vulnerability in log validation (normalize paths)
  - Fix deleteApiKeys validation (check response before success)
  - Fix rclone create_remote validation (check response)
  - Fix keys input_data type annotation (dict[str, Any])
  - Fix VM domain/domains fallback restoration

  **Changes by file:**
  - unraid_mcp/tools/docker.py: Response field mapping
  - unraid_mcp/tools/info.py: Split critical/warning counters
  - unraid_mcp/tools/storage.py: Path normalization for traversal protection
  - unraid_mcp/tools/users.py: GraphQL schema + null handling
  - unraid_mcp/tools/keys.py: Validation + type annotations
  - unraid_mcp/tools/rclone.py: Response validation
  - unraid_mcp/tools/virtualization.py: Domain fallback
  - unraid_mcp/subscriptions/manager.py: SSL context creation
  - pyproject.toml: FastAPI version fix
  - tests/*: New tests for all fixes

  **Review threads resolved:**
  PRRT_kwDOO6Hdxs5uu70L, PRRT_kwDOO6Hdxs5uu70O, PRRT_kwDOO6Hdxs5uu70V,
  PRRT_kwDOO6Hdxs5uu70e, PRRT_kwDOO6Hdxs5uu70i, PRRT_kwDOO6Hdxs5uu7zn,
  PRRT_kwDOO6Hdxs5uu7z_, PRRT_kwDOO6Hdxs5uu7sI, PRRT_kwDOO6Hdxs5uu7sJ,
  PRRT_kwDOO6Hdxs5uu7sK, PRRT_kwDOO6Hdxs5uu7Tk, PRRT_kwDOO6Hdxs5uu7Tn,
  PRRT_kwDOO6Hdxs5uu7Tr, PRRT_kwDOO6Hdxs5uu7Ts, PRRT_kwDOO6Hdxs5uu7Tu,
  PRRT_kwDOO6Hdxs5uu7Tv, PRRT_kwDOO6Hdxs5uu7Tw, PRRT_kwDOO6Hdxs5uu7Tx

  All tests passing.
- Add type annotation to resolve mypy Literal narrowing error. [Jacob
  Magar]

Other

Ci: add Homelab CI framework. [Simon Diesenreiter]
Refactor: move MCP server config inline to plugin.json. [Jacob Magar]

Move MCP server configuration from standalone .mcp.json to inline definition in plugin.json. This consolidates all plugin metadata in a single location.
- Add type: stdio and env fields to inline config
- Remove redundant .mcp.json file
- Maintains same functionality with cleaner structure
Feat: add MCP server configuration for Claude Code plugin integration. [Jacob Magar]

Add .mcp.json to configure the Unraid MCP server as a stdio-based MCP server for Claude Code plugin integration. This allows Claude Code to automatically start and connect to the server when the plugin is loaded.
- Type: stdio (standard input/output communication)
- Command: uv run unraid-mcp-server
- Forces stdio transport mode via UNRAID_MCP_TRANSPORT env var
Docs: fix markdown lint, broken links, stale counts, and publishing guidance. [Jacob Magar]
- Fix broken ToC anchors in competitive-analysis.md (MD051)
- Add blank lines before code blocks in api-reference.md (MD031)
- Add language identifiers to directory tree code blocks in MARKETPLACE.md and skills/unraid/README.md (MD040)
- Fix size unit guidance conflict: clarify disk sizes are KB, memory is bytes
- Update stale "90 actions" references to "76 actions" across research docs
- Fix coverage table terminology and clarify 22% coverage calculation
- Recommend PyPI Trusted Publishing (OIDC) over API token secrets in PUBLISHING.md
- Update action count in .claude-plugin/README.md
Resolves review threads: PRRT_kwDOO6Hdxs5uvO2m, PRRT_kwDOO6Hdxs5uvO2o, PRRT_kwDOO6Hdxs5uvO2r, PRRT_kwDOO6Hdxs5uvOcl, PRRT_kwDOO6Hdxs5uvOcr, PRRT_kwDOO6Hdxs5uvKrq, PRRT_kwDOO6Hdxs5uvO2u, PRRT_kwDOO6Hdxs5uvO2w, PRRT_kwDOO6Hdxs5uvO2z, PRRT_kwDOO6Hdxs5uu7zl
Feat: enhance test suite with 275 new tests across 4 validation categories. [Claude, Jacob Magar]

Add comprehensive test coverage beyond unit tests:
- Schema validation (93 tests): Validate all GraphQL queries/mutations against extracted Unraid API schema
- HTTP layer (88 tests): Test request construction, timeouts, and error handling at httpx level
- Subscriptions (55 tests): WebSocket lifecycle, reconnection, and protocol validation
- Safety audit (39 tests): Enforce destructive action confirmation requirements
Total test count increased from 210 to 485 (130% increase), all passing in 5.91s.

New dependencies:
- graphql-core>=3.2.0 for schema validation
- respx>=0.22.0 for HTTP layer mocking
Files created:
- docs/unraid-schema.graphql (150-type GraphQL schema)
- tests/schema/test_query_validation.py
- tests/http_layer/test_request_construction.py
- tests/integration/test_subscriptions.py
- tests/safety/test_destructive_guards.py
Feat: harden API safety and expand command docs with full test coverage. [Jacob Magar]
Refactor: move plugin manifest to repository root per Claude Code best practices. [Jacob Magar]
- Move plugin.json from skills/unraid/.claude-plugin/ to .claude-plugin/
- Update validation script to use correct plugin manifest path
- Add plugin structure section to root README.md
- Add installation instructions to skills/unraid/README.md
- Aligns with Claude Code's expectation for source: './' in marketplace.json
Chore: enhance project metadata, tooling, and documentation. [Claude, Jacob Magar]

Project Configuration:
- Enhance pyproject.toml with comprehensive metadata, keywords, and classifiers
- Add LICENSE file (MIT) for proper open-source distribution
- Add PUBLISHING.md with comprehensive publishing guidelines
- Update .gitignore to exclude tool artifacts (.cache, .pytest_cache, .ruff_cache, .ty_cache)
- Ignore documentation working directories (.docs, .full-review, docs/plans, docs/sessions)
Documentation:
- Add extensive Unraid API research documentation
  - API source code analysis and resolver mapping
  - Competitive analysis and feature gap assessment
  - Release notes analysis (7.0.0, 7.1.0, 7.2.0)
  - Connect platform overview and remote access documentation
- Document known API patterns, limitations, and edge cases
Testing & Code Quality:
- Expand test coverage across all tool modules
- Add destructive action confirmation tests
- Improve test assertions and error case validation
- Refine type annotations for better static analysis
Tool Improvements:
- Enhance error handling consistency across all tools
- Improve type safety with explicit type annotations
- Refine GraphQL query construction patterns
- Better handling of optional parameters and edge cases
This commit prepares the project for v0.2.0 release with improved metadata, comprehensive documentation, and enhanced code quality.
Feat: consolidate 26 tools into 10 tools with 90 actions. [Jacob Magar]

Refactor the entire tool layer to use the consolidated action pattern (action: Literal[...] with QUERIES/MUTATIONS dicts). This reduces LLM context from ~12k to ~5k tokens while adding ~60 new API capabilities.

New tools: unraid_info (19 actions), unraid_array (12), unraid_notifications (9), unraid_users (8), unraid_keys (5). Rewritten: unraid_docker (15), unraid_vm (9), unraid_storage (6), unraid_rclone (4), unraid_health (3).

Includes 129 tests across 10 test files, code review fixes for 16 issues (severity ordering, PrefixedID regex, sensitive var redaction, etc.).

Removes tools/system.py (replaced by tools/info.py). Version bumped to 0.2.0.
Chore: update .gitignore. [Jacob Magar]
Move pid and log files to /tmp directory. [Claude, Jacob Magar]
- Update dev.sh to use /tmp for LOG_DIR instead of PROJECT_DIR/logs
- Update settings.py to use /tmp for LOGS_DIR instead of PROJECT_ROOT/logs
- This change moves both pid files and log files to the temporary directory
🤖 Generated with Claude Code
Remove env_file from docker-compose and use explicit environment variables. [Claude, Jacob Magar]
- Remove env_file directive from docker-compose.yml to eliminate .env file dependency
- Add explicit environment variable declarations with default values using ${VAR:-default} syntax
- Update port mapping to use UNRAID_MCP_PORT environment variable for both host and container
- Include all 11 environment variables used by the application with proper defaults
- Update README.md Docker deployment instructions to use export commands instead of .env files
- Update manual Docker run command to use -e flags instead of --env-file
This makes Docker deployment self-contained and follows container best practices.

🤖 Generated with Claude Code
Replace log rotation with 10MB overwrite behavior. [Claude, Jacob Magar]
- Create OverwriteFileHandler class that caps log files at 10MB and overwrites instead of rotating
- Remove RotatingFileHandler dependency and backup file creation
- Add reset marker logging when file limit is reached for troubleshooting
- Update all logger configurations (main, FastMCP, and root loggers)
- Increase file size limit from 5MB to 10MB as requested
- Maintain existing Rich console formatting and error handling
🤖 Generated with Claude Code
Align documentation and Docker configuration with current implementation. [Claude, Jacob Magar]
- Fix README.md: Make Docker deployment recommended, remove duplicate installation section
- Fix Dockerfile: Copy correct source files (unraid_mcp/, uv.lock, README.md) instead of non-existent unraid_mcp_server.py
- Update docker-compose.yml: Enable build configuration and use .env instead of .env.local
- Add missing environment variables to .env.example and .env: UNRAID_AUTO_START_SUBSCRIPTIONS, UNRAID_MAX_RECONNECT_ATTEMPTS
- Fix CLAUDE.md: Correct environment hierarchy documentation (../env.local → ../.env.local)
- Remove unused unraid-schema.json file
🤖 Generated with Claude Code
Lintfree. [Jacob Magar]
Add Claude Code agent configuration and GraphQL introspection. [Claude, Jacob Magar]
- Added KFC (Kent Feature Creator) spec workflow agents for requirements, design, tasks, testing, implementation and evaluation
- Added Claude Code settings configuration for agent workflows
- Added GraphQL introspection query and schema files for Unraid API exploration
- Updated development script with additional debugging and schema inspection capabilities
- Enhanced logging configuration with structured formatting
- Updated pyproject.toml dependencies and uv.lock
🤖 Generated with Claude Code
Remove unused MCP resources and update documentation. [Claude, Jacob Magar]
- Remove array_status, system_info, notifications_overview, and parity_status resources
- Keep only logs_stream resource (unraid://logs/stream) which is working properly
- Update README.md with current resource documentation and modern docker compose syntax
- Fix import path issues that were causing subscription errors
- Update environment configuration examples
- Clean up subscription manager to only include working log streaming
🤖 Generated with Claude Code
Migrate to uv and FastMCP architecture with comprehensive tooling. [Claude, Jacob Magar]
- Replace pip/requirements.txt with uv and pyproject.toml
- Restructure as single-file MCP server using FastMCP
- Add comprehensive Unraid management tools (containers, VMs, storage, logs)
- Implement multiple transport support (streamable-http, SSE, stdio)
- Add robust error handling and timeout management
- Include project documentation and API feature tracking
- Remove outdated cline documentation structure
🤖 Generated with Claude Code
Update docker-compose.yml. [Jacob Magar]

21 KiB Raw Blame History

Changelog

(unreleased)

0.0.1 (2026-02-21)

21 KiB

Raw Blame History