forked from HomeLab/unraid-mcp
37e9424a5c
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.
204 lines
5.2 KiB
Markdown
204 lines
5.2 KiB
Markdown
# 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" skill
|
|
- Categories and tags for discoverability
|
|
|
|
### 2. Plugin Manifest (`skills/unraid/.claude-plugin/plugin.json`)
|
|
The individual plugin configuration for the Unraid skill.
|
|
|
|
**Location:** `skills/unraid/.claude-plugin/plugin.json`
|
|
|
|
**Contents:**
|
|
- Plugin name, version, author
|
|
- Repository and homepage links
|
|
- Plugin-specific metadata
|
|
|
|
### 3. Documentation
|
|
- `.claude-plugin/README.md` - Marketplace installation guide
|
|
- Updated root `README.md` with plugin installation section
|
|
|
|
### 4. Validation Script
|
|
- `scripts/validate-marketplace.sh` - Automated validation of marketplace structure
|
|
|
|
## Installation Methods
|
|
|
|
### Method 1: GitHub Distribution (Recommended for Users)
|
|
|
|
Once you push this to GitHub, users can install via:
|
|
|
|
```bash
|
|
# Add your marketplace
|
|
/plugin marketplace add jmagar/unraid-mcp
|
|
|
|
# Install the Unraid skill
|
|
/plugin install unraid @unraid-mcp
|
|
```
|
|
|
|
### Method 2: Local Installation (Development)
|
|
|
|
For testing locally before publishing:
|
|
|
|
```bash
|
|
# Add local marketplace
|
|
/plugin marketplace add /home/jmagar/workspace/unraid-mcp
|
|
|
|
# Install the plugin
|
|
/plugin install unraid @unraid-mcp
|
|
```
|
|
|
|
### Method 3: Direct URL
|
|
|
|
Users can also install from a specific commit or branch:
|
|
|
|
```bash
|
|
# 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/ # Marketplace manifest
|
|
│ ├── marketplace.json
|
|
│ └── README.md
|
|
├── skills/unraid/ # Plugin directory
|
|
│ ├── .claude-plugin/ # Plugin manifest
|
|
│ │ └── plugin.json
|
|
│ ├── SKILL.md # Skill documentation
|
|
│ ├── README.md # Plugin documentation
|
|
│ ├── examples/ # Example scripts
|
|
│ ├── scripts/ # Helper scripts
|
|
│ └── references/ # API reference docs
|
|
└── 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**
|
|
```bash
|
|
./scripts/validate-marketplace.sh
|
|
```
|
|
|
|
2. **Update Version Numbers**
|
|
- Bump version in `.claude-plugin/marketplace.json`
|
|
- Bump version in `skills/unraid/.claude-plugin/plugin.json`
|
|
- Update version in `README.md` if needed
|
|
|
|
3. **Test Locally**
|
|
```bash
|
|
/plugin marketplace add .
|
|
/plugin install unraid @unraid-mcp
|
|
```
|
|
|
|
4. **Commit and Push**
|
|
```bash
|
|
git add .claude-plugin/ skills/unraid/.claude-plugin/
|
|
git commit -m "feat: add Claude Code marketplace configuration"
|
|
git push origin main
|
|
```
|
|
|
|
5. **Create Release Tag** (Optional)
|
|
```bash
|
|
git tag -a v0.2.0 -m "Release v0.2.0"
|
|
git push origin v0.2.0
|
|
```
|
|
|
|
## User Experience
|
|
|
|
After installation, users will:
|
|
|
|
1. **See the skill in their skill list**
|
|
```bash
|
|
/skill list
|
|
```
|
|
|
|
2. **Access Unraid functionality directly**
|
|
- Claude Code will automatically detect when to invoke the skill
|
|
- Users can explicitly invoke with `/unraid`
|
|
|
|
3. **Have access to all helper scripts**
|
|
- Example scripts in `examples/`
|
|
- Utility scripts in `scripts/`
|
|
- API reference in `references/`
|
|
|
|
## Maintenance
|
|
|
|
### Updating the Plugin
|
|
|
|
To release a new version:
|
|
|
|
1. Make changes to the plugin
|
|
2. Update version in `skills/unraid/.claude-plugin/plugin.json`
|
|
3. Update marketplace catalog in `.claude-plugin/marketplace.json`
|
|
4. Run validation: `./scripts/validate-marketplace.sh`
|
|
5. Commit and push
|
|
|
|
Users with the plugin installed will see the update available and can upgrade with:
|
|
```bash
|
|
/plugin update unraid
|
|
```
|
|
|
|
### Adding More Plugins
|
|
|
|
To add additional plugins to this marketplace:
|
|
|
|
1. Create new plugin directory: `skills/new-plugin/`
|
|
2. Add plugin manifest: `skills/new-plugin/.claude-plugin/plugin.json`
|
|
3. Update marketplace catalog: add entry to `.plugins[]` array in `.claude-plugin/marketplace.json`
|
|
4. Validate: `./scripts/validate-marketplace.sh`
|
|
|
|
## Support
|
|
|
|
- **Repository:** https://github.com/jmagar/unraid-mcp
|
|
- **Issues:** https://github.com/jmagar/unraid-mcp/issues
|
|
- **Documentation:** See `.claude-plugin/README.md` and `skills/unraid/README.md`
|
|
|
|
## Validation
|
|
|
|
Run the validation script anytime to ensure marketplace integrity:
|
|
|
|
```bash
|
|
./scripts/validate-marketplace.sh
|
|
```
|
|
|
|
This checks:
|
|
- Manifest file existence and validity
|
|
- JSON syntax
|
|
- Required fields
|
|
- Plugin structure
|
|
- Source path accuracy
|
|
- Documentation completeness
|
|
|
|
All 17 checks must pass before publishing.
|