papermc-ai-ops

Manage PaperMC Minecraft servers through safe, controlled interfaces. Use for server lifecycle management, backups, plugin operations, and health monitoring with backup-first safety policy.

Safety Notice

This listing is from the official public ClawHub registry. Review SKILL.md and referenced scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "papermc-ai-ops" with this command: npx skills add yanxi1024-git/papermc-ai-ops

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
  • Intelligent plugin upgrades with risk assessment (NEW in v2.0)

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>

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.0

# Scan for upgrade candidates (Method 2)
python3 plugin_upgrade_framework.py --method 2 --scan-limit 20

# Run examples
python3 upgrade_examples.py

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

Plugin 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 PluginUpgradeFramework

framework = 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 LevelVersion JumpAction
LowPatch update (x.x.1 → x.x.2)Recommended upgrade
MediumMinor update (x.1.x → x.2.x)Test before production
HighMajor 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:

  • Proxy issue resolution
  • Risk assessment validation
  • Complete upgrade process
  • Lessons learned

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

  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

  • ≥ 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
├── 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 <new_plugin_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 20

# Upgrade specific plugin with risk assessment
python3 plugin_upgrade_framework.py --plugin ViaVersion --version 5.8.0 --auto-restart

# Run batch upgrade planning
python3 upgrade_examples.py

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."

See Also

  • docs/architecture.md - System architecture
  • docs/changelog.md - Version history
  • docs/Turret_Plugin_User_Manual.md - Complete Turret plugin guide
  • scripts/health_check.sh - Health monitoring script
  • manage_server.py - Main control script
  • plugin_manager.py - Plugin operations
  • update_paper.py - PaperMC updates
  • plugin_upgrade_framework.py - Intelligent plugin upgrade framework
  • upgrade_examples.py - Upgrade usage examples
  • viaversion_upgrade_report.json - ViaVersion upgrade experience

License

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

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open Registry RecordOpen in ClawHub

Related Skills

Related by shared tags or category signals.

Automation

Duplicati Backup Manager

Manage Duplicati backups on the server using secure Bearer tokens.

Registry SourceRecently Updated
1.8K3Profile unavailable
Coding

workspace-backup-github

Backup AI Agent workspace to GitHub - One-click backup for OpenClaw, Claude Code, Cursor, and other AI Agent workspaces to a private GitHub repository. Suppo...

Registry SourceRecently Updated
2780Profile unavailable
Coding

alfred-github-backup

GitHub 仓库备份技能 - 将 OpenClaw 工作空间备份到 GitHub 私有仓库。 支持两种模式：(1) 自动模式 - 定时自动备份 (2) 手动模式 - 交互式配置向导。 自动引导用户完成：GitHub Token 配置 → 仓库创建 → 初始化备份 → 设置定时任务。 用途：(1) 首次设置 (2...

Registry SourceRecently Updated
2720Profile unavailable
Automation

OpenClaw Backup

Backup OpenClaw workspace, config, and state using the built-in `openclaw backup create` command. Also handles cleanup of old backups and health verification...

Registry SourceRecently Updated
500Profile unavailable