PaperMC AI Operations
by @yanxi1024-git
Manage PaperMC Minecraft servers through safe, controlled interfaces. Use for server lifecycle management, backups, plugin operations, and health monitoring...
clawhub install papermc-ai-opsπ About This Skill
name: papermc-ai-ops version: 2.0.1 description: Manage PaperMC Minecraft servers through safe, controlled interfaces. Use for server lifecycle management, backups, plugin operations, and health monitoring with backup-first safety policy. license: MIT
PaperMC Server AI Operations
AI-managed PaperMC Minecraft server operations with safety-first approach.
When to Use This Skill
Use this skill when you need to:
Requirements
Quick Start
1. Configure
Edit paths in the scripts:
# In manage_server.py, plugin_manager.py, update_paper.py
SERVER_DIR = Path("/path/to/your/papermc-server")
2. Check Status
python3 manage_server.py status
3. Create Backup
python3 manage_server.py backup
Core Scripts
manage_server.py
Server lifecycle management:
python3 manage_server.py status # Service status
python3 manage_server.py logs -n 50 # View logs
python3 manage_server.py backup # Backup world
python3 manage_server.py restart # Safe restart
plugin_manager.py
Plugin operations:
python3 plugin_manager.py list # List plugins
python3 plugin_manager.py backup # Backup plugin
python3 plugin_manager.py install-url --filename
update_paper.py
PaperMC updates:
python3 update_paper.py backup-jar # Backup current jar
python3 update_paper.py update-from-url
plugin_upgrade_framework.py (NEW in v2.0)
Intelligent plugin upgrade framework with risk assessment:
# Upgrade specific plugin (Method 1)
python3 plugin_upgrade_framework.py --plugin ViaVersion --version 5.8.0Scan for upgrade candidates (Method 2)
python3 plugin_upgrade_framework.py --method 2 --scan-limit 20Run examples
python3 upgrade_examples.py
Safety Rules
β Never Use Direct Commands
kill, kill -9rm -rfsystemctl stop/restartβ Always Use Scripts
All operations go through approved Python scripts.π¦ Backup-First Policy
Before ANY risky operation: 1. Run backup command 2. Verify backup created 3. Proceed with changePlugin Upgrade Framework (NEW in v2.0)
Based on ViaVersion 5.7.2 β 5.8.0 upgrade experience (2026-03-28), this skill now includes an intelligent plugin upgrade framework.
Core Upgrade Methods
#### Method 1: Specific Plugin Upgrade For upgrading a specific plugin with full automation:
from plugin_upgrade_framework import PluginUpgradeFrameworkframework = PluginUpgradeFramework()
result = framework.method1_specific_plugin_upgrade("ViaVersion", "5.8.0")
#### Method 2: Scan and Assess Upgrades For periodic maintenance and batch upgrade planning:
result = framework.method2_scan_and_assess_upgrades(limit=20)
Risk Assessment Logic
| Risk Level | Version Jump | Action | |------------|--------------|--------| | Low | Patch update (x.x.1 β x.x.2) | Recommended upgrade | | Medium | Minor update (x.1.x β x.2.x) | Test before production | | High | Major update (1.x.x β 2.x.x) | Detailed assessment needed |
Proxy Configuration for Hangar
If you have proxy issues, configure NO_PROXY:
export NO_PROXY="localhost,127.0.0.1,192.168.8.165,hangar.papermc.io,papermc.io,hangarcdn.papermc.io"
Download URL Pattern
Hangar plugin download URLs follow this pattern:
https://hangarcdn.papermc.io/plugins/{plugin}/{plugin}/versions/{version}/PAPER/{plugin}-{version}.jar
Verification Steps After Upgrade
1. Check server logs for errors 2. Verify plugin loaded message 3. Test core functionality 4. Monitor server performance 5. Have rollback plan ready
ViaVersion Upgrade Experience
See viaversion_upgrade_report.json for detailed documentation of the successful ViaVersion 5.7.2 β 5.8.0 upgrade, including:
Health Monitoring
bash scripts/health_check.sh
Checks:
Version Management Strategy
Balanced Upgrade Strategy
Adopt a balanced approach with 1-version lag for stability.Weekly Upgrade Scoring System
python3 scripts/weekly-upgrade-scorer.py
Scoring Criteria (100 points total): 1. PaperMC Stability (30 points) - Official API confirmation - Release age (>2 weeks) - Security patches included
2. Plugin Compatibility (40 points) - Core plugins compatibility - All plugins compatible - Recent plugin updates - No critical warnings
3. Testing & Validation (20 points) - Test environment validation - Performance benchmarks - Functionality verification
4. Risk Management (10 points) - Backup readiness - Rollback plan tested
Upgrade Decision Matrix
Weekly Scanning Procedure
1. Monday: Run automated scoring 2. Review: Analyze report and scores 3. Decision: Human confirmation required for β₯80 scores 4. Execution: Scheduled upgrade with full backupEmergency Rollback
Trigger conditions:Rollback steps: 1. Stop server immediately 2. Restore from latest backup 3. Revert to previous version 4. Verify and restart
Directory Structure
papermc-server/
βββ manage_server.py # Main control script
βββ plugin_manager.py # Plugin operations
βββ update_paper.py # PaperMC updates
βββ plugin_upgrade_framework.py # Intelligent plugin upgrades (NEW)
βββ upgrade_examples.py # Upgrade usage examples (NEW)
βββ viaversion_upgrade_report.json # ViaVersion experience (NEW)
βββ backup.sh # Backup automation
βββ scripts/
β βββ health_check.sh # Health monitoring
βββ docs/
β βββ architecture.md # System design
β βββ changelog.md # Change history
β βββ Turret_Plugin_User_Manual.md # Turret plugin guide (NEW)
βββ backup/ # World backups
βββ plugin_backup/ # Plugin backups
βββ jar_backup/ # PaperMC jar backups
Workflow Examples
Daily Health Check
bash scripts/health_check.sh
Before Plugin Update (Traditional)
python3 manage_server.py backup
python3 plugin_manager.py backup OldPlugin.jar
python3 plugin_manager.py install-url --filename NewPlugin.jar
python3 manage_server.py restart
python3 manage_server.py status
Intelligent Plugin Upgrade (NEW)
# Scan for upgrade candidates
python3 plugin_upgrade_framework.py --method 2 --scan-limit 20Upgrade specific plugin with risk assessment
python3 plugin_upgrade_framework.py --plugin ViaVersion --version 5.8.0 --auto-restartRun batch upgrade planning
python3 upgrade_examples.py
PaperMC Update
python3 update_paper.py backup-jar
python3 update_paper.py update-from-url
python3 manage_server.py restart
python3 manage_server.py status
Configuration
Environment Variables (.env)
SERVER_NAME=my-server
SERVER_DIR=/path/to/server
BACKUP_RETENTION=10
Troubleshooting
Service Won't Start
python3 manage_server.py logs -n 100
Check Disk Space
df -h
Verify Java
java -version
Safety First
This skill enforces operational discipline:
Never bypass the script layer for "quick fixes."
See Also
docs/architecture.md - System architecturedocs/changelog.md - Version historydocs/Turret_Plugin_User_Manual.md - Complete Turret plugin guidescripts/health_check.sh - Health monitoring scriptmanage_server.py - Main control scriptplugin_manager.py - Plugin operationsupdate_paper.py - PaperMC updatesplugin_upgrade_framework.py - Intelligent plugin upgrade frameworkupgrade_examples.py - Upgrade usage examplesviaversion_upgrade_report.json - ViaVersion upgrade experienceLicense
MIT License - See LICENSE file
Skill Version: 2.0.0 (Enhanced with Plugin Upgrade Framework) Based on: v1.0.0 release Experience Source: ViaVersion 5.7.2 β 5.8.0 Upgrade (2026-03-28) Core Value: Combines AI-managed safety-first operations with intelligent plugin upgrade capabilities based on real-world experience. ClawHub Slug: papermc-ai-ops GitHub: https://github.com/yanxi1024-git/PaperMC-Ai-Agent
π‘ Examples
1. Configure
Edit paths in the scripts:
# In manage_server.py, plugin_manager.py, update_paper.py
SERVER_DIR = Path("/path/to/your/papermc-server")
2. Check Status
python3 manage_server.py status
3. Create Backup
python3 manage_server.py backup
βοΈ Configuration
Environment Variables (.env)
SERVER_NAME=my-server
SERVER_DIR=/path/to/server
BACKUP_RETENTION=10
π Tips & Best Practices
Service Won't Start
python3 manage_server.py logs -n 100
Check Disk Space
df -h
Verify Java
java -version