diff --git a/skills/mcp-manager/README.md b/skills/mcp-manager/README.md index f9f3348..fcd30df 100644 --- a/skills/mcp-manager/README.md +++ b/skills/mcp-manager/README.md @@ -4,43 +4,19 @@ ## Quick Start -The skill operates automatically - Jarvis will detect when you need MCPs and offer to load them. +The skill operates automatically - Claude detects when you need MCPs and offers to load them. -### Example Workflow - -**You:** "Check what tech stack reddit.com is using" - -**Jarvis:** -``` -🔍 Detected need for: httpx -Loading MCP for web stack analysis... - -✅ Enabled httpx (~300 tokens) -⚠️ Please restart Claude Code to activate, then resubmit your request. -``` - -**After restart:** -``` -[Jarvis completes the task using httpx MCP] - -Task complete! -Currently loaded MCPs: httpx (~300 tokens) -Would you like me to unload this to free context? (yes/no) -``` - -## Manual Commands - -You can also manually control MCPs: +### Manual Commands ```bash # Check what's currently loaded python3 ~/.claude/skills/mcp-manager/mcp_control.py status # Load specific MCP -python3 ~/.claude/skills/mcp-manager/mcp_control.py enable httpx +python3 ~/.claude/skills/mcp-manager/mcp_control.py enable n8n-mcp # Unload specific MCP -python3 ~/.claude/skills/mcp-manager/mcp_control.py disable httpx +python3 ~/.claude/skills/mcp-manager/mcp_control.py disable n8n-mcp # See what MCPs would help with a task python3 ~/.claude/skills/mcp-manager/mcp_control.py detect "your query here" @@ -49,81 +25,38 @@ python3 ~/.claude/skills/mcp-manager/mcp_control.py detect "your query here" python3 ~/.claude/skills/mcp-manager/mcp_control.py reset ``` -Or just ask Jarvis: -- "Load the httpx MCP" +Or just ask: +- "Load the n8n MCP" - "Unload all MCPs" - "What MCPs are currently loaded?" -- "Show MCP status" ## Available MCPs -### Security & Analysis -- **httpx** - Web server tech stack analysis (~300 tokens) -- **naabu** - Port scanning and service discovery (~300 tokens) +| MCP | Category | Description | Est. Tokens | +|-----|----------|-------------|-------------| +| `cognitive-memory` | Memory | Cognitive memory with decay scoring | Always loaded | +| `n8n-mcp` | Automation | n8n workflow management | ~1500 | +| `playwright` | Automation | Browser automation and testing | ~1000 | -### Web Scraping -- **apify** - Web scraping via Apify platform (~800 tokens) -- **brightdata** - Enterprise data extraction (~500 tokens) -- **playwright** - Browser automation (~1000 tokens) +## Configuration -### Development -- **Ref** - Documentation search (~600 tokens) -- **stripe** - Payment processing (~700 tokens) +- **Global MCPs** (always-on): `~/.claude.json` → `mcpServers` +- **Project MCPs** (on-demand): `/.mcp.json` → `mcpServers` +- **Full Registry**: `~/.claude/.mcp-full.json` (all available definitions) +- **Logs**: `~/.claude/logs/mcp-manager.log` -### Personal (Daniel Miessler) -- **content** - Content archive (~400 tokens) -- **daemon** - Personal API (~300 tokens) -- **Foundry** - PAI infrastructure (~500 tokens) - -## Context Savings - -- **All MCPs loaded**: ~5400 tokens -- **Minimal (none loaded)**: ~0 tokens -- **Savings per session**: 5000+ tokens available for actual work! - -## How Detection Works - -The skill scans your request for trigger keywords: - -- "tech stack", "what technology" → `httpx` -- "port scan", "open ports" → `naabu` -- "scrape", "crawl website" → `apify`, `brightdata` -- "browser automation" → `playwright` -- "documentation", "API docs" → `Ref` -- "stripe", "payment" → `stripe` - -## Files - -- **SKILL.md** - Main skill documentation (loaded by Jarvis) -- **mcp_control.py** - MCP management CLI tool -- **~/.claude/.mcp.json** - Active MCP configuration -- **~/.claude/.mcp-full.json** - Backup of all MCPs -- **~/.claude/.mcp.json.backup** - Previous config backup -- **~/.claude/logs/mcp-manager.log** - Change log - -## Important Notes - -⚠️ **Restart Required**: MCP changes require Claude Code restart to take effect - -🔒 **Credentials Safe**: The tool preserves all API keys and auth tokens - -💾 **Auto-Backup**: Configurations are backed up before every change - -📊 **Token Estimates**: Token counts are approximations based on MCP complexity +> **Important:** `~/.claude/.mcp.json` is NOT read by Claude Code. Global servers go in `~/.claude.json`. ## Workflow -1. **Minimal Start** - Begin each session with no MCPs loaded -2. **Auto-Detect** - Jarvis detects when MCPs are needed +1. **Minimal Start** - Begin each session with no on-demand MCPs loaded +2. **Auto-Detect** - Claude detects when MCPs are needed via trigger keywords 3. **Load on Demand** - Enable only required MCPs -4. **Complete Task** - Use the MCP for your work -5. **Unload** - Free context by removing MCPs when done -6. **Repeat** - Next task loads different MCPs as needed - -This approach keeps your context budget focused on your actual work instead of unused MCP definitions. +4. **Restart** - MCP changes require Claude Code restart +5. **Complete Task** - Use the MCP for your work +6. **Unload** - Free context by removing MCPs when done --- -**Version**: 1.0.0 -**Created**: 2025-11-09 -**Maintained by**: Jarvis (PAI System) +**Version**: 1.1.0 +**Updated**: 2026-03-05 diff --git a/skills/proxmox/SKILL.md b/skills/proxmox/SKILL.md index 74938b8..4360024 100644 --- a/skills/proxmox/SKILL.md +++ b/skills/proxmox/SKILL.md @@ -7,183 +7,78 @@ description: Proxmox VE management - VM lifecycle, creation/cloning, snapshots, **SCOPE**: Only use in claude-home or vm-management contexts. Do not activate in unrelated projects. -## When to Activate This Skill +## When to Activate - "list my VMs", "show virtual machines" - "start/stop/restart VM X" - "create a new VM", "clone VM" - "take a snapshot", "rollback to snapshot" - "check VM resources", "monitor VMs" -- "proxmox status", "hypervisor info" - "LXC containers", "manage containers" - "backup VM", "restore from backup" -- Any Proxmox VE infrastructure operations -## Quick Start +## Approach: MCP First, Python Fallback -### List All VMs +### Option 1: Proxmox MCP (Preferred) + +Load the Proxmox MCP on-demand for interactive use: +```bash +python3 ~/.claude/skills/mcp-manager/mcp_control.py enable proxmox +# Restart Claude Code to activate, then use MCP tools directly +``` + +The MCP provides direct API access without writing Python code. + +### Option 2: Python Client (Complex/Batch Operations) + +For multi-step automation, batch operations, or when MCP is unavailable: ```python from proxmox_client import ProxmoxClient client = ProxmoxClient() - -# Get all VMs with status -vms = client.get_all_vms_status() -for vm in vms: - print(f"VM {vm['vmid']}: {vm['name']} - {vm['status']}") ``` -### VM Lifecycle Operations -```python -# Start a VM -client.start_vm(100) - -# Stop a VM (graceful) -client.stop_vm(100) - -# Force stop -client.stop_vm(100, force=True) - -# Restart a VM -client.restart_vm(100) - -# Graceful shutdown with timeout -client.shutdown_vm(100, timeout=60) -``` - -### Create and Clone VMs -```python -# Create new VM -client.create_vm( - vmid=101, - name="docker-host-01", - memory=4096, - cores=2, - sockets=1 -) - -# Clone existing VM -client.clone_vm( - vmid=100, - newid=102, - name="cloned-vm", - full=True # Full clone, not linked -) -``` - -### Snapshot Management -```python -# Create snapshot -client.create_snapshot( - vmid=100, - snapname="before-upgrade", - description="Pre-system upgrade snapshot", - vmstate=True # Include RAM for running VMs -) - -# List snapshots -snapshots = client.list_snapshots(100) - -# Rollback to snapshot -client.rollback_snapshot(100, "before-upgrade") - -# Delete snapshot -client.delete_snapshot(100, "before-upgrade") -``` - -### Resource Monitoring -```python -# Get VM status and resources -status = client.get_vm_status(100) -print(f"CPU: {status['cpu']}") -print(f"Memory: {status['mem']} / {status['maxmem']}") -print(f"Uptime: {status['uptime']}s") - -# Get node resources -node_status = client.get_node_status() -print(f"Node CPU: {node_status['cpu']}") -print(f"Node Memory: {node_status['memory']}") -``` - -### Container Operations -```python -# List LXC containers -containers = client.list_containers() - -# Start/stop containers -client.start_container(200) -client.stop_container(200) -``` - -## CLI Usage - -The Python client has a CLI interface for quick operations: - +**CLI shorthand:** ```bash -# List all VMs -python3 ~/.claude/skills/proxmox/proxmox_client.py list - -# Get VM status -python3 ~/.claude/skills/proxmox/proxmox_client.py status 100 - -# Start a VM -python3 ~/.claude/skills/proxmox/proxmox_client.py start 100 - -# Stop a VM -python3 ~/.claude/skills/proxmox/proxmox_client.py stop 100 - -# List nodes -python3 ~/.claude/skills/proxmox/proxmox_client.py nodes +python3 ~/.claude/skills/proxmox/proxmox_client.py [list|status|start|stop|nodes] [vmid] ``` ## Key Capabilities -### VM Lifecycle -- ✅ List all VMs with status -- ✅ Start, stop, restart, shutdown VMs -- ✅ Create new VMs from scratch -- ✅ Clone existing VMs -- ✅ Delete VMs +- **VM Lifecycle**: list, start, stop, restart, shutdown, create, clone, delete +- **Snapshots**: create (with/without RAM), list, rollback, delete +- **Monitoring**: real-time CPU/RAM/disk, node health, storage capacity +- **LXC Containers**: list, start, stop, status +- **Backups**: create, list, job management +- **Storage**: pool listing, capacity, content +- **Tasks**: async task monitoring, wait for completion -### Snapshot Management -- ✅ Create snapshots (with/without RAM) -- ✅ List all snapshots -- ✅ Rollback to snapshot -- ✅ Delete snapshots +## Common Workflows -### Monitoring & Resources -- ✅ Real-time VM resource usage (CPU, RAM, disk) -- ✅ Node status and health -- ✅ Storage status and capacity -- ✅ Network interface information +### Deploy VM from Template +```python +upid = client.clone_vm(vmid=9000, newid=101, name="app-server-01") +client.wait_for_task(upid) +client.start_vm(101) +``` -### Container (LXC) Operations -- ✅ List containers -- ✅ Start/stop containers -- ✅ Get container status +### Pre-Upgrade Snapshot +```python +upid = client.create_snapshot(vmid=100, snapname="pre-upgrade", description="Before upgrade", vmstate=True) +client.wait_for_task(upid) +# If issues: client.rollback_snapshot(100, "pre-upgrade") +``` -### Backup & Recovery -- ✅ Create VM backups -- ✅ List available backups -- ✅ Backup job management - -### Storage Operations -- ✅ List storage pools -- ✅ Check storage capacity and usage -- ✅ Storage content listing - -### Task Management -- ✅ Monitor async task status -- ✅ Wait for task completion -- ✅ Task progress tracking +### Bulk Status Check +```python +vms = client.get_all_vms_status() +for vm in vms: + if vm['status'] != 'running': + print(f"VM {vm['vmid']} ({vm['name']}) is {vm['status']}") +``` ## Configuration -Credentials are stored in: -``` -~/.claude/secrets/proxmox.json -``` - -Format: +Credentials: `~/.claude/secrets/proxmox.json` ```json { "host": "10.10.0.11", @@ -195,115 +90,22 @@ Format: } ``` -## MCP Server Integration +## Integration -For interactive use, the Proxmox MCP server can be loaded on-demand: +- **VM docs**: `/mnt/NV2/Development/claude-home/vm-management/` +- **Network**: 10.10.0.x internal network +- **API docs**: https://pve.proxmox.com/pve-docs/api-viewer/ +- **Python lib**: https://github.com/proxmoxer/proxmoxer -```bash -# Enable Proxmox MCP -python3 ~/.claude/skills/mcp-manager/mcp_control.py enable proxmox - -# Restart Claude Code to activate -# Then use MCP tools directly -``` - -The MCP server will be automatically suggested when you use Proxmox-related keywords. - -## Common Workflows - -### 1. Deploy New VM from Template -```python -# Clone template -upid = client.clone_vm(vmid=9000, newid=101, name="app-server-01") -client.wait_for_task(upid) - -# Start the VM -client.start_vm(101) - -# Wait for boot and check status -import time -time.sleep(30) -status = client.get_vm_status(101) -print(f"VM Status: {status['status']}") -``` - -### 2. Pre-Upgrade Snapshot Workflow -```python -# Take snapshot before changes -upid = client.create_snapshot( - vmid=100, - snapname="pre-upgrade-2025-01-11", - description="Before system upgrade", - vmstate=True -) -client.wait_for_task(upid) - -# Perform upgrade operations... -# If issues occur, rollback: -# client.rollback_snapshot(100, "pre-upgrade-2025-01-11") -``` - -### 3. Bulk VM Status Check -```python -# Check status of all VMs -vms = client.get_all_vms_status() -for vm in vms: - if vm['status'] != 'running': - print(f"⚠️ VM {vm['vmid']} ({vm['name']}) is {vm['status']}") - else: - cpu_pct = vm['cpu'] * 100 - mem_pct = (vm['mem'] / vm['maxmem']) * 100 if vm['maxmem'] > 0 else 0 - print(f"✅ VM {vm['vmid']} ({vm['name']}): CPU {cpu_pct:.1f}%, MEM {mem_pct:.1f}%") -``` - -### 4. Emergency VM Operations -```python -# Force stop unresponsive VM -client.stop_vm(100, force=True) - -# Or graceful shutdown with fallback -try: - upid = client.shutdown_vm(100, timeout=120) - if not client.wait_for_task(upid, timeout=130): - print("Graceful shutdown timed out, forcing stop...") - client.stop_vm(100, force=True) -except Exception as e: - print(f"Shutdown failed: {e}") - client.stop_vm(100, force=True) -``` - -## Integration with Home Lab - -This skill integrates with Cal's home lab infrastructure: - -- **VM Management**: Documented in `/mnt/NV2/Development/claude-home/vm-management/` -- **Cloud-Init Templates**: Standard provisioning configurations -- **Networking**: 10.10.0.x internal network -- **Docker Hosts**: Automated Docker VM deployment -- **Monitoring**: Discord notifications via monitoring system - -## Supplementary Resources - -For comprehensive Proxmox API reference and advanced usage: -```bash -read ~/.claude/skills/proxmox/CLAUDE.md -``` - -For Proxmox VE API documentation: -- Official API: https://pve.proxmox.com/pve-docs/api-viewer/ -- Python Library: https://github.com/proxmoxer/proxmoxer - -## Security Notes +## Security - API token has full root privileges -- Credentials stored in `~/.claude/secrets/` (700 permissions) -- SSL verification disabled for self-signed certificates -- NEVER commit secrets to git repositories -- Token can be regenerated in Proxmox web UI if compromised +- Credentials in `~/.claude/secrets/` (700 permissions) +- SSL verification disabled (self-signed certs) +- Never commit secrets to git --- -**Created**: 2025-01-11 -**Author**: Jarvis (PAI System) **Client Library**: `~/.claude/skills/proxmox/proxmox_client.py` -**Version**: 1.0.0 +**Updated**: 2026-03-05 +**Version**: 2.0.0