unraid-mcp/docs/MARKETPLACE.md

Claude Code Marketplace Setup

This document explains the Claude Code marketplace and plugin structure for the Unraid MCP project.

What Was Created

1. Marketplace Manifest (.claude-plugin/marketplace.json)

The marketplace catalog that lists all available plugins in this repository.

Location: .claude-plugin/marketplace.json

Contents:

• Marketplace metadata (name, version, owner, repository)
• Plugin catalog with the "unraid" plugin
• Categories and tags for discoverability

2. Plugin Manifest (.claude-plugin/plugin.json)

The individual plugin configuration for the Unraid MCP server.

Location: .claude-plugin/plugin.json

Contents:

• Plugin name (unraid), version (1.1.2), author
• Repository and homepage links
• mcpServers block that configures the server to run via uv run unraid-mcp-server in stdio mode

3. Validation Script

• scripts/validate-marketplace.sh — Automated validation of marketplace structure

MCP Tools Exposed

The plugin registers 3 MCP tools:

Tool	Purpose
unraid	Primary tool — action (domain) + subaction (operation) routing, ~107 subactions across 15 domains
diagnose_subscriptions	Inspect WebSocket subscription connection states and errors
test_subscription_query	Test a specific GraphQL subscription query (allowlisted fields only)

Calling Convention

All Unraid operations go through the single unraid tool:

unraid(action="docker", subaction="list")
unraid(action="system", subaction="overview")
unraid(action="array", subaction="parity_status")
unraid(action="vm", subaction="list")
unraid(action="live", subaction="cpu")

Domains (action=)

action	example subactions
system	overview, array, network, metrics, services, ups_devices
health	check, test_connection, diagnose, setup
array	parity_status, parity_start, start_array, add_disk
disk	shares, disks, disk_details, logs
docker	list, details, start, stop, restart
vm	list, details, start, stop, pause, resume
notification	overview, list, create, archive, archive_all
key	list, get, create, update, delete
plugin	list, add, remove
rclone	list_remotes, config_form, create_remote
setting	update, configure_ups
customization	theme, set_theme, sso_enabled
oidc	providers, configuration, validate_session
user	me
live	cpu, memory, array_state, log_tail, notification_feed

Destructive subactions (e.g. stop_array, force_stop, delete) require confirm=True.

Installation Methods

Method 1: GitHub Distribution (Recommended for Users)

Once pushed to GitHub, users install via:

# Add the marketplace
/plugin marketplace add jmagar/unraid-mcp

# Install the Unraid plugin
/plugin install unraid @unraid-mcp

Method 2: Local Installation (Development)

For testing locally before publishing:

# Add local marketplace
/plugin marketplace add /home/jmagar/workspace/unraid-mcp

# Install the plugin
/plugin install unraid @unraid-mcp

Method 3: Direct URL

Install from a specific branch or commit:

# From specific branch
/plugin marketplace add jmagar/unraid-mcp#main

# From specific commit
/plugin marketplace add jmagar/unraid-mcp#abc123

Plugin Structure

unraid-mcp/
├── .claude-plugin/          # Plugin manifest + marketplace manifest
│   ├── plugin.json          # Plugin configuration (name, version, mcpServers)
│   └── marketplace.json     # Marketplace catalog
├── unraid_mcp/              # Python package (the actual MCP server)
│   ├── main.py              # Entry point
│   ├── server.py            # FastMCP server registration
│   ├── tools/unraid.py      # Consolidated tool (all 3 tools registered here)
│   ├── config/              # Settings management
│   ├── core/                # GraphQL client, exceptions, shared types
│   └── subscriptions/       # Real-time WebSocket subscription manager
└── scripts/
    └── validate-marketplace.sh  # Validation tool

Marketplace Metadata

Categories

• infrastructure — Server management and monitoring tools

Tags

• unraid — Unraid-specific functionality
• monitoring — System monitoring capabilities
• homelab — Homelab automation
• graphql — GraphQL API integration
• docker — Docker container management
• virtualization — VM management

Publishing Checklist

Before publishing to GitHub:

1. Validate Structure

   ./scripts/validate-marketplace.sh
   

2. Update Version Numbers (must be in sync)

   • pyproject.toml → version = "X.Y.Z" under [project]
   • .claude-plugin/plugin.json → "version": "X.Y.Z"
   • .claude-plugin/marketplace.json → "version" in both metadata and plugins[]

3. Test Locally

   /plugin marketplace add .
   /plugin install unraid @unraid-mcp
   

4. Commit and Push

   git add .claude-plugin/
   git commit -m "chore: bump marketplace to vX.Y.Z"
   git push origin main
   

5. Create Release Tag

   git tag -a vX.Y.Z -m "Release vX.Y.Z"
   git push origin vX.Y.Z
   

User Experience

After installation, users can:

1. Invoke Unraid operations directly in Claude Code

   unraid(action="system", subaction="overview")
   unraid(action="docker", subaction="list")
   unraid(action="health", subaction="check")
   

2. Use the credential setup tool on first run

   unraid(action="health", subaction="setup")
   

   This triggers elicitation to collect and persist credentials to ~/.unraid-mcp/.env.

3. Monitor live data via subscriptions

   unraid(action="live", subaction="cpu")
   unraid(action="live", subaction="log_tail")
   

Maintenance

Updating the Plugin

To release a new version:

1. Make changes to the plugin code
2. Update version in pyproject.toml, .claude-plugin/plugin.json, and .claude-plugin/marketplace.json
3. Run validation: ./scripts/validate-marketplace.sh
4. Commit and push

Users with the plugin installed will see the update available and can upgrade:

/plugin update unraid

Support

• Repository: https://github.com/jmagar/unraid-mcp
• Issues: https://github.com/jmagar/unraid-mcp/issues
• Destructive Actions: docs/DESTRUCTIVE_ACTIONS.md

Validation

Run the validation script anytime to ensure marketplace integrity:

./scripts/validate-marketplace.sh

This checks:

• Manifest file existence and validity
• JSON syntax
• Required fields
• Plugin structure
• Source path accuracy
• Documentation completeness