chore: enhance project metadata, tooling, and documentation

**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. Co-authored-by: Claude <noreply@anthropic.com>
2026-03-02 00:04:45 -08:00 · 2026-02-15 15:32:09 -05:00
parent eb9b01d044
commit 2697c269a3
39 changed files with 8978 additions and 155 deletions
--- a/docs/research/unraid-api-research.md
+++ b/docs/research/unraid-api-research.md
@@ -0,0 +1,819 @@
+# Unraid API Research Findings
+
+**Date:** 2026-02-07
+**Research Topic:** Unraid GraphQL API, Connect Cloud Service, MCP Integration
+**Specialist:** NotebookLM Deep Research
+**Notebook ID:** 4e217d5d-d68b-4bfa-881a-42f7c01d3e44
+
+## Research Summary
+
+- **Deep research mode:** deep (47 web sources discovered)
+- **Sources indexed:** 51 ready / 77 total (26 error)
+- **Q&A questions asked:** 23 comprehensive questions with follow-ups
+- **Deep research status:** completed
+- **Key source categories:** Official Unraid docs, GitHub repos, community forums, GraphQL references, third-party integrations
+
+---
+
+## Table of Contents
+
+1. [Unraid API Overview](#1-unraid-api-overview)
+2. [Architecture and Deployment](#2-architecture-and-deployment)
+3. [Authentication and Security](#3-authentication-and-security)
+4. [GraphQL Schema and Endpoints](#4-graphql-schema-and-endpoints)
+5. [WebSocket Subscriptions](#5-websocket-subscriptions)
+6. [Unraid Connect Cloud Service](#6-unraid-connect-cloud-service)
+7. [Version History and API Changes](#7-version-history-and-api-changes)
+8. [Community Integrations](#8-community-integrations)
+9. [Known Issues and Limitations](#9-known-issues-and-limitations)
+10. [API Roadmap and Future Features](#10-api-roadmap-and-future-features)
+11. [Recommendations for unraid-mcp](#11-recommendations-for-unraid-mcp)
+12. [Source Bibliography](#12-source-bibliography)
+
+---
+
+## 1. Unraid API Overview
+
+The **Unraid API** is a programmatic interface that provides automation, monitoring, and integration capabilities for Unraid servers. It uses a **GraphQL** interface, offering a modern, strongly-typed method for developers and third-party applications to interact directly with the Unraid operating system.
+
+### Key Facts
+
+- **Protocol:** GraphQL (queries, mutations, subscriptions)
+- **Endpoint:** `http(s)://[SERVER_IP]/graphql`
+- **Authentication:** API Keys, Session Cookies, SSO/OIDC
+- **Native since:** Unraid 7.2 (no plugin required)
+- **Pre-7.2:** Requires Unraid Connect plugin installation
+
+The API exposes nearly all management functions available in the Unraid WebGUI, including server management, storage operations, Docker/VM lifecycle, remote access, and backup capabilities.
+
+**Sources:**
+- [Welcome to Unraid API | Unraid Docs](https://docs.unraid.net/API/) -- Official API landing page [Tier: Primary]
+- [Using the Unraid API](https://docs.unraid.net/API/how-to-use-the-api/) -- Official usage guide [Tier: Primary]
+
+---
+
+## 2. Architecture and Deployment
+
+### Monorepo Structure
+
+The Unraid API is developed in the [unraid/api](https://github.com/unraid/api) monorepo which houses:
+
+| Directory | Purpose |
+|-----------|---------|
+| `api/` | GraphQL backend server (TypeScript/Node.js) |
+| `web/` | Frontend interface (Nuxt/Vue.js) |
+| `plugin/` | Unraid plugin packaging (.plg format) |
+| `packages/` | Shared internal libraries |
+| `unraid-ui/` | UI component library |
+| `scripts/` | Build and maintenance utilities |
+
+### Technology Stack
+
+| Component | Technology |
+|-----------|------------|
+| Primary language | TypeScript (77.4%) |
+| Frontend | Vue.js (11.8%) via Nuxt |
+| Runtime | Node.js v22 |
+| Package manager | pnpm v9.0+ |
+| API protocol | GraphQL |
+| Dev environment | Nix (optional), Docker |
+| Build tool | Justfile |
+
+### Deployment Modes
+
+1. **Native (Unraid 7.2+):** API is built into the OS, starts automatically with the system. Managed via **Settings > Management Access > API**.
+2. **Plugin (Pre-7.2):** Requires installing the Unraid Connect plugin from Community Applications. Installing the plugin on 7.2+ provides access to newer API features before they are merged into the stable OS release.
+3. **Development:** Supports local Docker builds (`pnpm run docker:build-and-run` on port 5858), direct deployment to a running server (`pnpm unraid:deploy <SERVER_IP>`), and hot-reloading dev servers (API port 3001, Web port 3000).
+
+### Integration with Nginx
+
+The API integrates with Unraid's Nginx web server. Nginx acts as a reverse proxy, handling external requests on standard web ports (80/443) and routing `/graphql` traffic to the internal API backend. This means the API shares the same IP and port as the WebGUI.
+
+**Sources:**
+- [GitHub - unraid/api: Unraid API / Connect / UI Monorepo](https://github.com/unraid/api) [Tier: Official]
+- [api/api/docs/developer/development.md](https://github.com/unraid/api/blob/main/api/docs/developer/development.md) [Tier: Official]
+
+---
+
+## 3. Authentication and Security
+
+### Authentication Methods
+
+The Unraid API supports three primary authentication mechanisms:
+
+1. **API Keys** -- Standard method for programmatic access
+   - Created via WebGUI: **Settings > Management Access > API Keys**
+   - Created via CLI: `unraid-api apikey --create --name "mykey" --roles ADMIN --json`
+   - Sent in HTTP header: `x-api-key: YOUR_API_KEY`
+   - Displayed only once upon creation
+
+2. **Session Cookies** -- Used for browser-based WebGUI access
+   - Automatic when logged into WebGUI
+   - Used internally by the GraphQL Sandbox
+
+3. **SSO / OIDC (OpenID Connect)** -- Enterprise identity management
+   - Added in API v4.0.0
+   - Supports external identity providers
+
+### API Key Authorization Flow (OAuth-like)
+
+For third-party applications, Unraid provides an OAuth-like authorization flow:
+
+1. App redirects user to: `https://[server]/ApiKeyAuthorize?name=MyApp&scopes=docker:read,vm:*&redirect_uri=https://myapp.com/callback&state=abc123`
+2. User authenticates (if not already logged in)
+3. User sees consent screen with requested permissions
+4. Upon approval, API key is created and shown to user once
+5. If `redirect_uri` provided, user is redirected with `?api_key=xxx&state=abc123`
+
+**Query Parameters:**
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `name` | Yes | Application name |
+| `scopes` | Yes | Comma-separated permissions (e.g., `docker:read,vm:*`) |
+| `redirect_uri` | No | HTTPS callback URL (localhost allowed for dev) |
+| `state` | No | CSRF prevention token |
+
+### Programmatic API Key Management (CLI)
+
+```bash
+# Create a key with admin role
+unraid-api apikey --create --name "workflow key" --roles ADMIN --json
+
+# Create a key with specific permissions
+unraid-api apikey --create --name "monitor" --permissions "DOCKER:READ_ANY,ARRAY:READ_ANY" --json
+
+# Overwrite existing key
+unraid-api apikey --create --name "workflow key" --roles ADMIN --overwrite --json
+
+# Delete a key
+unraid-api apikey --delete --name "workflow key"
+```
+
+### Roles and Permissions
+
+**Roles (pre-defined access levels):**
+
+| Role | Description |
+|------|-------------|
+| `ADMIN` | Full system access (all permissions) |
+| `VIEWER` | Read-only access |
+| `GUEST` | Limited access |
+| `CONNECT` | Unraid Connect cloud features |
+
+**Permission Scope Format:** `RESOURCE:ACTION`
+
+**Available Resources:**
+- Core: `ACTIVATION_CODE`, `API_KEY`, `CONFIG`, `CUSTOMIZATIONS`, `INFO`, `LOGS`, `OS`, `REGISTRATION`, `VARS`, `WELCOME`
+- Storage: `ARRAY`, `DISK`, `FLASH`
+- Services: `DOCKER`, `VMS`, `SERVICES`, `NETWORK`
+- Management: `DASHBOARD`, `DISPLAY`, `ME`, `NOTIFICATIONS`, `OWNER`, `PERMISSION`, `SHARE`, `USER`
+- Cloud: `CLOUD`, `CONNECT`, `CONNECT__REMOTE_ACCESS`, `ONLINE`, `SERVERS`
+
+**Available Actions:**
+- `CREATE_ANY`, `CREATE_OWN`
+- `READ_ANY`, `READ_OWN`
+- `UPDATE_ANY`, `UPDATE_OWN`
+- `DELETE_ANY`, `DELETE_OWN`
+- `*` (wildcard for all actions)
+
+### SSL/TLS Certificate Handling
+
+| Scenario | Recommendation |
+|----------|---------------|
+| Self-signed cert (local IP) | Either trust the specific CA or disable SSL verification (dev only) |
+| `myunraid.net` cert (Let's Encrypt) | SSL verification works normally; use the `myunraid.net` URL |
+| Strict SSL mode | Enforces HTTPS for all connections including local |
+
+For self-signed certs in client code:
+```bash
+curl -k "https://your-unraid-server/graphql" -H "x-api-key: YOUR_KEY"
+```
+
+**Sources:**
+- [API key authorization flow | Unraid Docs](https://docs.unraid.net/API/api-key-app-developer-authorization-flow/) [Tier: Primary]
+- [Programmatic API key management | Unraid Docs](https://docs.unraid.net/API/programmatic-api-key-management/) [Tier: Primary]
+
+---
+
+## 4. GraphQL Schema and Endpoints
+
+### Endpoint URLs
+
+| Purpose | URL |
+|---------|-----|
+| GraphQL API | `http(s)://[SERVER_IP]/graphql` |
+| GraphQL Sandbox | `http(s)://[SERVER_IP]/graphql` (must be enabled) |
+| WebSocket (subscriptions) | `ws(s)://[SERVER_IP]/graphql` |
+| Internal dev API | `http://localhost:3001/graphql` |
+
+### Enabling the GraphQL Sandbox
+
+Two methods:
+1. **WebGUI:** Settings > Management Access > Developer Options > Toggle GraphQL Sandbox to "On"
+2. **CLI:** `unraid-api developer --sandbox true`
+
+Then access at `http://YOUR_SERVER_IP/graphql` to explore the schema via Apollo Sandbox.
+
+### Query Types
+
+#### System Information (`info`)
+```graphql
+query {
+  info {
+    os { platform distro release uptime hostname arch kernel }
+    cpu { manufacturer brand cores threads }
+    memory { layout { bank type clockSpeed manufacturer } }
+    baseboard { manufacturer model version serial }
+    system { manufacturer model version serial uuid }
+    versions { kernel docker unraid node }
+    apps { installed started }
+    machineId
+    time
+  }
+}
+```
+
+#### Array Status (`array`)
+```graphql
+query {
+  array {
+    id
+    state
+    capacity {
+      kilobytes { free used total }
+      disks { free used total }
+    }
+    boot { id name device size status temp fsType }
+    parities { id name device size status temp numErrors }
+    disks { id name device size status temp numReads numWrites numErrors }
+    caches { id name device size status temp }
+  }
+}
+```
+
+#### Docker Containers (`docker`)
+```graphql
+query {
+  docker {
+    containers(skipCache: false) {
+      id names image state status autoStart
+      ports { ip privatePort publicPort type }
+      labels
+      networkSettings
+      mounts
+    }
+  }
+}
+```
+
+#### Virtual Machines (`vms`)
+```graphql
+query {
+  vms {
+    id
+    domains {
+      id name state uuid
+    }
+  }
+}
+```
+
+#### Network (`network`)
+```graphql
+query {
+  network {
+    id
+    accessUrls { type name ipv4 ipv6 }
+  }
+}
+```
+
+#### Registration (`registration`)
+```graphql
+query {
+  registration {
+    id type state expiration updateExpiration
+    keyFile { location contents }
+  }
+}
+```
+
+#### Settings (`settings`)
+```graphql
+query {
+  settings {
+    unified { values }
+  }
+}
+```
+
+#### System Variables (`vars`)
+```graphql
+query {
+  vars {
+    id version name timeZone security workgroup
+    useSsl port portssl
+    shareSmbEnabled shareNfsEnabled
+    mdState mdVersion
+    csrfToken
+    # Many more fields available -- some have Int overflow issues
+  }
+}
+```
+
+#### RClone Remotes (`rclone`)
+```graphql
+query {
+  rclone {
+    remotes { name type parameters config }
+    configForm(formOptions: { providerType: "s3" }) {
+      id dataSchema uiSchema
+    }
+  }
+}
+```
+
+#### Notifications
+```graphql
+query {
+  notifications {
+    id subject message importance unread
+  }
+}
+```
+
+#### Shares
+```graphql
+query {
+  shares {
+    name comment free used
+  }
+}
+```
+
+### Mutation Types
+
+#### Docker Container Management
+```graphql
+mutation {
+  docker {
+    start(id: $id) { id names state status }
+    stop(id: $id) { id names state status }
+  }
+}
+```
+- Uses `PrefixedID` type for container identification
+- Mutations are idempotent (starting an already-running container returns success)
+
+#### VM Management
+```graphql
+mutation {
+  vm {
+    start(id: $id)    # Returns Boolean
+    stop(id: $id)
+    pause(id: $id)
+    resume(id: $id)
+    forceStop(id: $id)
+    reboot(id: $id)
+    reset(id: $id)
+  }
+}
+```
+
+#### RClone Remote Management
+```graphql
+mutation {
+  rclone {
+    createRCloneRemote(input: { name: "...", type: "s3", config: {...} }) {
+      name type parameters
+    }
+    deleteRCloneRemote(input: { name: "..." })
+  }
+}
+```
+
+#### System Operations (via API)
+The following operations are confirmed available through the API (exact mutation names should be discovered via introspection):
+- Array start/stop
+- Parity check trigger
+- Server reboot/shutdown
+- Flash backup trigger
+- Notification management
+
+### The `PrefixedID` Type
+
+The API uses a `PrefixedID` custom scalar type for global object identification. This follows the GraphQL `Node` interface pattern, combining the object type and its internal ID (e.g., `DockerContainer:abc123`). Client libraries must handle this as a string.
+
+### The `Long` Scalar Type
+
+The API defines a custom `Long` scalar type for 64-bit integers to handle values that exceed the standard GraphQL `Int` (32-bit signed). This is used for:
+- Disk/array capacity values (size, free, used, total)
+- Memory values (total, free)
+- Disk operation counters (numReads, numWrites)
+
+These are typically serialized as strings in JSON responses.
+
+**Sources:**
+- [Welcome to Unraid API | Unraid Docs](https://docs.unraid.net/API/) [Tier: Primary]
+- [Using the Unraid API](https://docs.unraid.net/API/how-to-use-the-api/) [Tier: Primary]
+- [GitHub - jmagar/unraid-mcp](https://github.com/jmagar/unraid-mcp) [Tier: Official]
+
+---
+
+## 5. WebSocket Subscriptions
+
+### Protocol
+
+The Unraid API uses the **`graphql-transport-ws`** protocol (the modern standard, superseding the older `subscriptions-transport-ws`).
+
+### Connection Flow
+
+1. Client connects to `ws(s)://[SERVER_IP]/graphql`
+2. Client sends `connection_init` with auth payload:
+   ```json
+   {
+     "type": "connection_init",
+     "payload": {
+       "x-api-key": "YOUR_API_KEY"
+     }
+   }
+   ```
+3. Server responds with `connection_ack`
+4. Client sends `subscribe` message with GraphQL subscription query
+5. Server streams `next` messages with data as events occur
+6. Server sends `complete` when subscription ends
+
+### Known Subscription Types
+
+| Subscription | Purpose |
+|-------------|---------|
+| `syslog` / `logFile` | Real-time system log streaming |
+| Array events | State changes, parity check progress |
+| Docker events | Container state changes |
+| Notifications | Real-time alert streaming |
+
+### Authentication for WebSockets
+
+Since standard WebSocket APIs in browsers cannot set custom headers, the API key is passed in the `connectionParams` payload of the `connection_init` message. Alternatively, session cookies work automatically for WebGUI-based tools.
+
+### Infrastructure Notes
+
+- Unraid uses **Nchan** (Nginx module) for WebSocket connections internally
+- Unraid 7.0.1 fixed Nchan memory leaks affecting subscription stability
+- Unraid 7.1.0 added automatic Nchan shared memory recovery (restarts Nginx when memory runs out)
+- A setting was added in 7.1.0 to disable real-time updates on inactive browsers to prevent memory issues
+
+**Sources:**
+- [Subscriptions - GraphQL](https://graphql.org/learn/subscriptions/) [Tier: Primary]
+- [Subscriptions - Apollo GraphQL Docs](https://www.apollographql.com/docs/react/data/subscriptions) [Tier: Official]
+
+---
+
+## 6. Unraid Connect Cloud Service
+
+### Overview
+
+**Unraid Connect** is a cloud-enabled companion service that functions as a centralized "remote command center" for Unraid servers. It provides:
+
+- **Centralized Dashboard:** View status, uptime, storage, and license details for multiple servers
+- **Remote Management:** Start/stop arrays, manage Docker/VMs, reboot servers
+- **Flash Backup:** Automated cloud-based backups of USB flash drive configuration
+- **Deep Linking:** Jump directly from cloud dashboard to local WebGUI pages
+
+### Relationship to Local API
+
+- Pre-7.2: The Unraid Connect plugin provides both cloud features AND the local GraphQL API
+- Post-7.2: The API is native to the OS; the Connect plugin adds cloud features
+- The cloud dashboard communicates through a secure tunnel to execute commands locally
+
+### Data Transmitted to Cloud
+
+The local server transmits to `Unraid.net`:
+- Server hostname and keyfile details
+- Local/remote IP addresses
+- Array usage statistics (numbers only, no file names)
+- Container and VM counts
+
+**Privacy:** The service explicitly does NOT collect or share user content, file details, or personal information beyond necessary metadata.
+
+### Remote Access Mechanisms
+
+1. **Dynamic Remote Access (Recommended):**
+   - On-demand; WebGUI closed to internet by default
+   - Uses UPnP for automatic port forwarding (or manual rules)
+   - Port lease expires after inactivity (~10 minutes)
+
+2. **Static Remote Access:**
+   - Always-on; WebGUI continuously accessible
+   - Requires forwarding WAN port (high random number >1000) to HTTPS port
+
+3. **VPN Alternatives:**
+   - WireGuard (built-in)
+   - Tailscale (native since Unraid 7.0+)
+
+### Flash Backup Details
+
+- Configuration files are encrypted and uploaded
+- Excludes sensitive data: passwords, WireGuard keys
+- Retained as latest backup only; older/inactive backups are purged
+- Can be triggered and monitored via the API
+
+**Sources:**
+- [Unraid Connect overview & setup | Unraid Docs](https://docs.unraid.net/connect/about/) [Tier: Primary]
+- [Remote access | Unraid Docs](https://docs.unraid.net/connect/remote-access/) [Tier: Primary]
+- [Automated flash backup | Unraid Docs](https://docs.unraid.net/connect/flash-backup/) [Tier: Primary]
+
+---
+
+## 7. Version History and API Changes
+
+### Unraid 7.0.0 (2025-01-09)
+
+**Developer & System Capabilities:**
+- Notification agents stored as individual XML files (easier programmatic management)
+- `Content-Security-Policy frame-ancestors` support (iframe embedding for dashboards)
+- JavaScript console logging restored
+- VM Manager inline XML mode (read-only libvirt XML view)
+- Docker PID limits (default 2048)
+- Full ZFS support (hybrid pools, subpools, encryption)
+- Native Tailscale integration
+- File Manager merged into core OS
+- QEMU snapshots and clones for VMs
+
+**Note:** API was still plugin-based (Unraid Connect plugin required).
+
+### Unraid 7.0.1 (2025-02-25)
+
+- **Nchan memory leak fix** -- Critical for WebSocket subscription stability
+- Tailscale integration security restrictions for Host-network containers
+
+### Unraid 7.1.0 (2025-05-05)
+
+- **Nchan shared memory recovery** -- Automatic Nginx restart on memory exhaustion
+- **Real-time updates toggle** -- Disable updates on inactive browsers
+- Native WiFi support (`wlan0`) -- New network interface data
+- User VM templates (create, export, import)
+- CSS rework for WebGUI
+
+### Unraid 7.2.0 (Stable Release)
+
+**Major Milestone: API becomes native to the OS.**
+
+- No plugin required for local API access
+- API starts automatically with system
+- Deep system integration
+- Settings accessible at **Settings > Management Access > API**
+- OIDC/SSO support added
+- Permissions system rewritten (API v4.0.0)
+- Built-in GraphQL Sandbox
+- CLI key management (`unraid-api apikey`)
+- Open-sourced API code
+
+**Sources:**
+- [Version 7.0.0 | Unraid Docs](https://docs.unraid.net/unraid-os/release-notes/7.0.0/) [Tier: Primary]
+- [Version 7.0.1 | Unraid Docs](https://docs.unraid.net/unraid-os/release-notes/7.0.1/) [Tier: Primary]
+- [Version 7.1.0 | Unraid Docs](https://docs.unraid.net/unraid-os/release-notes/7.1.0/) [Tier: Primary]
+- [Unraid 7.2.0 Blog Post](https://unraid.net/blog/unraid-7-2-0) [Tier: Official]
+
+---
+
+## 8. Community Integrations
+
+### Third-Party Projects Using the Unraid API
+
+#### 1. unraid-mcp (Python MCP Server) -- This Project
+- **Interface:** Official Unraid GraphQL API via HTTP/HTTPS + WebSockets
+- **Auth:** `UNRAID_API_URL` + `UNRAID_API_KEY` environment variables
+- **Transport:** HTTP header `X-API-Key` for queries; WebSocket `connection_init` payload for subscriptions
+- **Tools:** 26+ MCP tools for Docker, VM, storage, system management
+
+#### 2. PSUnraid (PowerShell Module)
+- **Developer:** Community member "Jagula"
+- **Status:** Alpha / proof of concept
+- **Interface:** Official Unraid GraphQL API
+- **Install:** `Install-Module PSUnraid`
+- **Capabilities:** Server/array/disk status, Docker/VM start/stop/restart, notifications
+- **Requires:** Unraid 7.2.2+ for full feature support
+- **Key insight:** Remote-only (no SSH needed), converts JSON to PowerShell objects
+
+#### 3. unraid-management-agent (Go Plugin)
+- **Interface:** **NOT** the official GraphQL API -- independent REST API + WebSocket
+- **Port:** Default 8043
+- **Architecture:** Standalone Go binary, collects data via native libraries
+- **Endpoints:** 50+ REST endpoints, `/metrics` for Prometheus, WebSocket at `/api/v1/ws`
+- **Integrations:** Prometheus (41 metrics), MQTT, Home Assistant (auto-discovery), MCP (54 tools)
+- **Key insight:** Provides data the official API lacks (SMART data, container logs, process monitoring, GPU stats, UPS data)
+
+#### 4. unraid-ssh-mcp
+- **Interface:** SSH (explicitly chose NOT to use GraphQL API)
+- **Reason:** API lacked container logs, SMART data, real-time CPU load, process monitoring
+- **Advantage:** Works on any Unraid version, no rate limits
+
+#### Other Projects
+- **U-Manager:** Android app for remote Unraid management
+- **Unraid Deck:** Native iOS client (SwiftUI)
+- **hass-unraid:** Home Assistant integration with SMART attribute notifications
+
+**Sources:**
+- [PSUnraid Reddit Thread](https://www.reddit.com/r/unRAID/comments/1ph08wi/psunraid_powershell_m) [Tier: Community]
+- [unraid-management-agent GitHub](https://github.com/ruaan-deysel/unraid-management-agent) [Tier: Official]
+- [Unraid MCP Reddit Thread](https://www.reddit.com/r/unRAID/comments/1pl4s4j/unraid_mcp_server_que) [Tier: Community]
+
+---
+
+## 9. Known Issues and Limitations
+
+### GraphQL Schema Issues (Discovered in unraid-mcp Development)
+
+Based on the existing unraid-mcp codebase, the following issues have been encountered:
+
+1. **Int Overflow on Large Values:** Memory size fields (total, used, free) and some disk operation counters can overflow GraphQL's standard 32-bit `Int` type. The API uses a custom `Long` scalar but some fields still return problematic values.
+
+2. **NaN Values:** Certain fields in the `vars` query (e.g., `sysArraySlots`, `sysCacheSlots`, `cacheNumDevices`, `cacheSbNumDisks`) can return NaN, causing type errors. The existing codebase works around this by querying a curated subset of fields.
+
+3. **Non-nullable Fields Returning Null:** The `info.devices` section has non-nullable fields that may be null in practice. The codebase avoids querying this section entirely.
+
+4. **Memory Layout Size Missing:** Individual memory stick `size` values are not returned by the API, preventing total memory calculation from layout data.
+
+### API Coverage Gaps
+
+According to the unraid-ssh-mcp developer, the GraphQL API currently lacks:
+- Docker container logs
+- Detailed SMART data for drives
+- Real-time CPU load averages
+- Process monitoring capabilities
+- Some system-level metrics available via `/proc` and `/sys`
+
+### General Limitations
+
+- **Rate Limiting:** The API implements rate limiting (specific limits not documented publicly)
+- **Version Dependency:** Full API requires Unraid 7.2+; pre-7.2 versions need the Connect plugin
+- **Self-Signed Certificates:** Client must handle SSL verification for local IP access
+- **Schema Volatility:** The API schema is still evolving; field names and types may change between versions
+
+---
+
+## 10. API Roadmap and Future Features
+
+### Completed (as of 7.2)
+- API native to Unraid OS
+- Separated from Connect Plugin
+- Open-sourced
+- OIDC/SSO support
+- Permissions system rewrite (v4.0.0)
+
+### Q1 2025
+- New Connect Settings Interface
+
+### Q2 2025
+- New modernized Settings Pages
+- Storage Pool Creation Interface (simplified)
+- Storage Pool Status Interface (real-time)
+- Developer Tools for Plugins
+- Custom Theme Creator (start)
+
+### Q3 2025
+- Custom Theme Creator (completion)
+- New Docker Status Interface
+- Docker Container Setup Interface (streamlined)
+- New Plugins Interface (redesigned)
+
+### TBD (Planned but Unscheduled)
+- **Native Docker Compose support** -- Highly anticipated
+- Plugin Development SDK and tooling
+- Advanced Plugin Management interface
+- Storage Share Creation & Settings interfaces
+- Storage Share Management Dashboard
+
+### In Development
+- User Interface Component Library (security components)
+
+**Sources:**
+- [Roadmap & Features | Unraid Docs](https://docs.unraid.net/API/upcoming-features/) [Tier: Primary]
+
+---
+
+## 11. Recommendations for unraid-mcp
+
+Based on this research, the following improvements are recommended for the unraid-mcp project:
+
+### High Priority
+
+1. **ZFS/Pool Management Tools**
+   - Add `get_pool_status` for ZFS/BTRFS storage pools
+   - Current `get_array_status` insufficient for multi-pool setups introduced in Unraid 7.0
+
+2. **Scope-Based Tool Filtering**
+   - Before registering tools with MCP, verify the API key has appropriate permissions
+   - Prevent exposing tools the key cannot use (avoid hallucinated capabilities)
+   - Query current key permissions at startup
+
+3. **Improved Error Handling**
+   - Implement exponential backoff for rate limit errors (HTTP 429)
+   - Better handling of `Long` scalar type values
+   - Graceful degradation for unavailable schema fields
+
+4. **API Key Authorization Flow**
+   - Consider implementing the OAuth-like flow (`/ApiKeyAuthorize`) for user-friendly key generation
+   - Enables scope-based consent before key creation
+
+### Medium Priority
+
+5. **Real-Time Notification Streaming**
+   - Add WebSocket subscription for notifications
+   - Allows proactive alerting (e.g., "Disk 5 is overheating") without user request
+
+6. **File Manager Integration**
+   - Add `list_files`, `read_file` tools using the native File Manager API (merged in 7.0)
+   - Enables LLM to organize media or clean up `appdata`
+
+7. **Pagination for Large Queries**
+   - Implement `limit` and `offset` for log listings and file browsing
+   - Prevent timeouts from massive result sets
+
+8. **Flash Backup Trigger**
+   - Add tool to trigger flash backup via API mutation
+   - Monitor backup status
+
+### Low Priority
+
+9. **VM Snapshot Management**
+   - Add `create_vm_snapshot`, `revert_to_snapshot`, `clone_vm`
+   - Leverages QEMU snapshot support from Unraid 7.0
+
+10. **Tailscale/VPN Status**
+    - Query network schemas for Tailnet IPs and VPN connection status
+    - Useful for remote management diagnostics
+
+11. **Query Complexity Optimization**
+    - Separate list queries (lightweight) from detail queries (heavy)
+    - `list_docker_containers` should fetch only id/names/state
+    - Detail queries should be on-demand
+
+### Implementation Notes
+
+- **GraphQL Sandbox Discovery:** Use the built-in sandbox at `http://SERVER/graphql` to discover exact mutation names and field types for any new tools
+- **Version Compatibility:** Consider checking the Unraid API version at startup and adjusting available tools accordingly
+- **SSL Configuration:** The `UNRAID_VERIFY_SSL` environment variable is already implemented -- ensure documentation guides users toward `myunraid.net` certificates for proper SSL
+- **PrefixedID Handling:** Container and VM IDs use the `PrefixedID` custom scalar -- ensure all ID-based operations handle this string type correctly
+
+---
+
+## 12. Source Bibliography
+
+### Primary Sources (Official Documentation)
+- [Welcome to Unraid API | Unraid Docs](https://docs.unraid.net/API/)
+- [Using the Unraid API](https://docs.unraid.net/API/how-to-use-the-api/)
+- [API key authorization flow | Unraid Docs](https://docs.unraid.net/API/api-key-app-developer-authorization-flow/)
+- [Programmatic API key management | Unraid Docs](https://docs.unraid.net/API/programmatic-api-key-management/)
+- [Roadmap & Features | Unraid Docs](https://docs.unraid.net/API/upcoming-features/)
+- [Unraid Connect overview & setup | Unraid Docs](https://docs.unraid.net/connect/about/)
+- [Remote access | Unraid Docs](https://docs.unraid.net/connect/remote-access/)
+- [Automated flash backup | Unraid Docs](https://docs.unraid.net/connect/flash-backup/)
+- [Version 7.0.0 Release Notes](https://docs.unraid.net/unraid-os/release-notes/7.0.0/)
+- [Version 7.0.1 Release Notes](https://docs.unraid.net/unraid-os/release-notes/7.0.1/)
+- [Version 7.1.0 Release Notes](https://docs.unraid.net/unraid-os/release-notes/7.1.0/)
+
+### Official / GitHub Sources
+- [GitHub - unraid/api: Unraid API / Connect / UI Monorepo](https://github.com/unraid/api)
+- [GitHub - jmagar/unraid-mcp](https://github.com/jmagar/unraid-mcp)
+- [api/docs/developer/development.md](https://github.com/unraid/api/blob/main/api/docs/developer/development.md)
+- [Unraid OS 7.2.0 Blog Post](https://unraid.net/blog/unraid-7-2-0)
+
+### Community Sources
+- [PSUnraid PowerShell Module (Reddit)](https://www.reddit.com/r/unRAID/comments/1ph08wi/psunraid_powershell_m)
+- [Unraid MCP Server (Reddit)](https://www.reddit.com/r/unRAID/comments/1pl4s4j/unraid_mcp_server_que)
+- [unraid-management-agent (GitHub)](https://github.com/ruaan-deysel/unraid-management-agent)
+- [Unraid API Discussion (Reddit)](https://www.reddit.com/r/unRAID/comments/1h7xkjr/unraid_api/)
+- [API Key Location Question (Reddit)](https://www.reddit.com/r/unRAID/comments/1nk2jjk/i_couldnt_find_the_ap)
+
+### Reference Sources
+- [GraphQL Specification](https://spec.graphql.org/)
+- [Learn GraphQL](https://graphql.org/learn/)
+- [GraphQL Subscriptions](https://graphql.org/learn/subscriptions/)
+- [Apollo GraphQL Sandbox](https://www.apollographql.com/docs/graphos/platform/sandbox)
+- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)
+
+---
+
+## Cross-Source Analysis
+
+### Where Sources Agree
+- The API is GraphQL-based with queries, mutations, and subscriptions
+- Unraid 7.2 is the version where API became native
+- API Keys are the primary authentication method for programmatic access
+- The endpoint is at `/graphql` on the server
+- The API supports Docker/VM lifecycle management
+- The monorepo is TypeScript/Node.js based
+
+### Where Sources Disagree or Have Gaps
+- **Exact mutation names** are not documented publicly -- must use GraphQL Sandbox introspection
+- **Rate limit specifics** (thresholds, headers) are not publicly documented
+- **Container logs** -- the unraid-ssh-mcp developer claims they're unavailable via API, but this may have changed in newer versions
+- **Schema type issues** (Int overflow, NaN) are documented only in the unraid-mcp codebase, not in official docs
+
+### Notable Insights
+1. The unraid-management-agent project provides capabilities the official API lacks, suggesting areas for API expansion
+2. PSUnraid confirms the API schema includes mutations for Docker/VM lifecycle with boolean return types
+3. The OAuth-like authorization flow is a sophisticated feature not commonly found in self-hosted server APIs
+4. The `Long` scalar type and `PrefixedID` type are custom additions critical for proper client implementation