mamawhes/dsh-mc-server-manager

# dsh-mc-server-manager: Manage local Minecraft Paper servers within DSH

# Introduction

If you have ever run a Minecraft server at home using DSH, you have probably encountered these annoyances: manually searching directories for JAR files, modifying `server.properties` requires typing it out yourself, installing plugins depends on scripts to download from Modrinth, and remembering when to run `save-all` for backups is a hassle. Even more frustrating is when the Agent wants to help manage the server, but has no tools available and can only paste a line of command for you to execute.

The plugin introduced below, `mamawhes/dsh-mc-server-manager`, solves this problem: it adds a sidebar panel to DSH, turning operations like creating servers, starting/stopping, installing plugins, and backing up worlds into a GUI; simultaneously, it registers a set of `mc_*` Agent tools, allowing the model to execute the same operations directly in the conversation. The current version is 0.1.0, supports only Paper servers, and is maintained by mamawhes (created on GitHub on 2026-11-04, 0 stars).

## What is it

A one-sentence positioning: A DSH host plugin for managing local Minecraft Paper servers.

It does two things that previously required the shell to complete:

- Move the server lifecycle into the DSH sidebar panel. The process is hosted directly by the host plugin, and data is stored in `~/.dsh/minecraft`, keeping the workspace clean.
- Register `mc_*` tools. The Agent can create servers, start/stop, install plugins, and backup worlds directly in the conversation without the user needing to paste commands.

The target server is only Paper; Fabric / Forge / Vanilla are not implemented.

## Installation and Usage

Installation commands come from the original README, separated by profile:
```bash
dsh plugin --profile web add dsh-mc-server-manager
dsh plugin --profile desktop add dsh-mc-server-manager

After installation, you need to restart the DSH process. Open the sidebar in the browser; if the “MC Server” entry appears, it is active; if not, refresh the page once.

If not yet published on npm, install from source (as given in the README):

dsh plugin --profile desktop add github:mamawhes/dsh-mc-server-manager

Environment requirements: DSH >=0.1.7-rc.1 <0.3.0-0 (tested in 0.2.1-rc.5), Node.js >=22, Platform macOS / Linux (backup dependencies system zip / unzip). Note the Java version mapping for the server: Paper 1.20–1.21.11 requires Java 21, Paper 26.1+ requires Java 25.

Sidebar Panel: Graphical Operations¶

Opening the “MC Server” entry reveals a global panel not bound to a specific session. It includes:

• Server Lifecycle: New (auto-download JAR from PaperMC), start, stop, restart, delete.
• Java Environment Management: Scan local Java (PATH / JAVA_HOME / Homebrew / SDKMAN / JDK directories / plugin install directory), verify minimum version by Paper version, one-click download and install JDK (prioritize Amazon Corretto, fallback to Eclipse Temurin / Adoptium, supports 25/21/17/11/8), and allow fixing or auto-selecting the runtime for each server.
• Console: Pull real-time logs in increments every 1.5 seconds, support sending console commands directly.
• Plugin Management: List plugins/ (read real plugin names and versions from jar plugin.yml), enable/disable (*.jar.disabled), delete, install from URL, install from Modrinth by server version. Defaults to installing LuckPerms and EssentialsX when creating a new server; skips if they exist; fails only warn and do not block creation.
• Backup Management: List worlds and dimension directories, create zip backups (run save-off + save-all flush while running, then save-on after completion), restore (automatically keep backups/rollback-* rollback points), delete backups.
• Server Parameters: Graphical editing of server.properties, common keys with Chinese labels, validate by type, keep unknown keys as is; modification while running prompts for restart to take effect.
• Game Rules: gamerule read/modify; while running, read and re-read to confirm via console; read from world/level.dat when stopped.

Agent Tools: Operations in Conversation¶

On the overview page of the panel, there is a “Let Agent Execute” option, providing one-click actions like checking status / start / stop / backup worlds / view plugins / view parameters. Clicking sends a command with server context to the current conversation and switches to it; the Agent executes immediately; if no open session exists, a new one is created and the command is pre-filled. You can also describe your needs directly in the dialog box.

The list of tools is large; here are the common groups:

• Status & Lifecycle: mc_list_servers (call before any operation), mc_server_status, mc_start_server / mc_stop_server (graceful stop, SIGTERM/SIGKILL after 30s timeout).
• Java: mc_list_java_runtimes, mc_install_java, mc_set_server_java.
• Server & Parameters: mc_create_server, mc_get_properties / mc_set_properties, mc_get_gamerules / mc_set_gamerule.
• Plugins & Backups: mc_list_plugins / mc_install_plugin / mc_toggle_plugin / mc_remove_plugin; mc_list_worlds / mc_backup_world / mc_restore_world / mc_delete_backup.
• Console: mc_console_command.
• EULA: mc_accept_eula, only called after the user explicitly agrees to the EULA.

Data Directory¶

Server data is unified in ~/.dsh/minecraft. The general structure is as follows:

~/.dsh/minecraft/
├─ settings.json        # Default Java path
├─ java/                # JDKs installed by the plugin
└─ servers/<id>/
   ├─ server.json       # Display name, MC version, memory, EULA, Java selection
   ├─ paper.jar
   ├─ server.properties
   ├─ eula.txt
   ├─ plugins/          # Defaults include LuckPerms, EssentialsX
   ├─ backups/          # Backup zip files and rollback-*/ directories
   └─ world/ world_nether/ world_the_end/ ...

The root directory can be overridden by the environment variable DSH_MC_ROOT or config.root in the patch.

HTTP Interface¶

Behind the panel is a set of local HTTP interfaces with the prefix /mc/api. Excerpt:

GET    /mc/api/meta                         /mc/api/versions      /mc/api/java
POST   /mc/api/java/install                 /mc/api/java/select   /mc/api/java/probe
GET/POST    /mc/api/servers
GET/DELETE  /mc/api/servers/:id
POST   /mc/api/servers/:id/start|{stop,restart,eula,java,command,gamerules,backups,plugins,plugins-toggle}
GET    /mc/api/servers/:id/status|{console,players,properties,plugins,worlds,backups,latest-log}
PUT    /mc/api/servers/:id/properties
DELETE /mc/api/servers/:id/plugins/:file     /mc/api/servers/:id/backups/:name
POST   /mc/api/servers/:id/backups/:name/restore

Use Cases and Considerations¶

Who is it for: People running Paper servers on macOS / Linux using DSH Web or Desktop, who wish to hand over operations to the panel or Agent.

Before installing, confirm that you can accept what it does:

• Execute local processes: Directly spawn / kill Java processes to host the Minecraft server.
• File system writes: Create server directories under ~/.dsh/minecraft, write server.properties / eula.txt, and pack/unpack world saves.
• Downloads: Pull files from fill.papermc.io, api.modrinth.com, Corretto CDN / Adoptium / GitHub Releases.
• Local HTTP routing: /mc/api does not go through DSH /api cookie authentication. The plugin uses Origin loopback check + default localhost listening to protect itself. The README explicitly states not to expose DSH to the public internet and rely on this plugin for management.
• EULA: This is a legal agreement. The plugin will not accept it for you; the Agent tool will only set acceptEula=true after you explicitly agree.

Known limitations: Only supports Paper; Java installation depends on the network. In offline environments, you need to manually install Java and have it discovered by scanning, or manually fill in the Java path. The host restart cannot take over still-running Java processes (status shows stopped), so confirm ports are not occupied before starting. Custom HTTP routes do not go through DSH /api authentication, only do Origin loopback check.

Also, the plugin runs with the permissions of the current DSH process. It can read/write ~/.dsh/minecraft outside the workspace. It is recommended to review the source code and license (MIT, © 2026 mamawhes) before installing.

Conclusion¶

The value of this plugin lies in turning “operating a Paper server” from typing commands into a panel click or a single command; both the Agent side and the GUI cover the same capabilities. It is still relatively new (v0.1.0, only Paper), suitable for those willing to verify and fallback themselves.

• Directory page: https://www.skillhub.cn/plugins/mamawhes/dsh-mc-server-manager
• GitHub: https://github.com/mamawhes/dsh-mc-server-manager
  ```