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: - Manage PaperMC server lifecycle (status, logs, restart) - Create backups (world, plugins, PaperMC jar) - Install or update plugins safely - Update PaperMC server version - Monitor server health and diagnose issues

Requirements

• Linux system with systemd
• Java 21+ (Zulu JDK recommended for ARM)
• Python 3.10+
• PaperMC server installation

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 <plugin.jar>           # Backup plugin
python3 plugin_manager.py install-url <url> --filename <name>

update_paper.py

PaperMC updates:

python3 update_paper.py backup-jar                    # Backup current jar
python3 update_paper.py update-from-url <paper_jar_url>

Safety Rules

❌ Never Use Direct Commands

• kill, kill -9
• rm -rf
• systemctl stop/restart
• Direct file overwrites

✅ 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 change

Health Monitoring

bash scripts/health_check.sh

Checks: - Service status - Log errors - Plugin count - Backup age - Disk space - Memory usage

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

1. Plugin Compatibility (40 points)
2. Core plugins compatibility
3. All plugins compatible
4. Recent plugin updates

5. No critical warnings

6. Testing & Validation (20 points)

7. Test environment validation
8. Performance benchmarks

9. Functionality verification

10. Risk Management (10 points)

11. Backup readiness
12. Rollback plan tested

Upgrade Decision Matrix

• ≥ 80 points: Proceed with upgrade (low risk)
• 60-79 points: Further evaluation needed
• < 60 points: Do not upgrade (high risk)

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 backup

Emergency Rollback

Trigger conditions: - Server crash on startup - TPS consistently below 15 - Critical plugin failures - Player data corruption

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
├── backup.sh             # Backup automation
├── scripts/
│   └── health_check.sh   # Health monitoring
├── docs/
│   ├── architecture.md   # System design
│   └── changelog.md      # Change history
├── 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

python3 manage_server.py backup
python3 plugin_manager.py backup OldPlugin.jar
python3 plugin_manager.py install-url <new_plugin_url> --filename NewPlugin.jar
python3 manage_server.py restart
python3 manage_server.py status

PaperMC Update

python3 update_paper.py backup-jar
python3 update_paper.py update-from-url <paper_download_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: - All actions through controlled interfaces - Mandatory backups before changes - No destructive direct commands - Full traceability

Never bypass the script layer for "quick fixes."

License

MIT License - See LICENSE file