dsh-mcsm-panel

Let your DSH Desktop AI operate your MCSManager Minecraft servers straight from the chat panel.

dsh-mcsm-panel is a plugin for DeepSeek Harness Desktop that connects an MCSManager 10.x (MCSM) panel to your AI assistant. Once configured, the agent can send real server console commands, browse and edit files, start/stop instances, and upload mods - all through conversation, and all immediate.

⚠️ These tools perform REAL, immediate actions. Grant the account only the permissions you are comfortable handing to an AI (see Security).

Tools

Tool	What it does	Examples
mcsm_console	Send Minecraft console commands in order and return the latest output (real execution)	/say announcements, list, kubejs reload, stop
mcsm_file	Instance file management: list / read / write (auto-creates missing files) / delete (high-risk)	inspect mods, edit kubejs scripts, read logs, remove files
mcsm_instance	Instance-level control (REST, immediate): status / open / restart / stop / kill	start the server, restart after a config change, stop it
mcsm_upload	Upload a local file to an instance directory (two-step direct upload)	drop a new mod jar into mods

Example: "post /say Maintenance in 10 minutes, then stop 10 seconds later" - the assistant uses mcsm_console to do it.

How it works

• Host side (lib/index.js) registers the four mcsm_* tools and manages the panel session (login -> token + cookie, with a shared token cache so repeated calls do not re-login).
• Console opens the daemon stream channel via POST /api/protected_instance/stream_channel, then drives socket.io / engine.io v4 (EIO=4) with stream/auth + stream/input to send commands and capture output.
• Files use the /api/files REST API: list -> GET /api/files/list, read/write -> PUT /api/files, delete -> DELETE /api/files with body { targets: [...] }. On write, a missing target is created first via POST /api/files/touch.
• Instance uses GET /api/instance (status) and POST /api/protected_instance/{open|restart|stop|kill}.
• Upload first requests a channel from POST /api/files/upload, then directly multipart-POSTs the file (field file) to the daemon at {addr}/upload/{password} (the panel returns the address as ws://, which the plugin converts to http://).

Every REST call is authenticated with the login session Cookie + ?token= query parameter + X-Requested-With header, and re-logs-in automatically on HTTP 401 / 403.

Requirements

• DeepSeek Harness Desktop already installed and run at least once (creates the profiles directory).
• An MCSManager 10.x panel, and an MCSM account with console + file permissions on the target instance.
• The instance daemon port must be reachable from where DSH Desktop runs (for console streams and uploads).
• The shared dependency ws (usually already present; see Installation).

Installation

From the unzipped plugin folder, run the included installer:

# Desktop profile (default)
powershell -ExecutionPolicy Bypass -File install.ps1
# or: web profile / both
powershell -ExecutionPolicy Bypass -File install.ps1 -Profile web
powershell -ExecutionPolicy Bypass -File install.ps1 -Profile all

The installer copies the plugin to ~/.dsh/profiles/node_modules/dsh-mcsm-panel, appends an insert entry to ~/.dsh/profiles/<profile>/cordis.patch.yml (idempotent - it will not duplicate), and warns if the shared ws dependency is missing. Then fully quit and restart DSH Desktop - tools load at startup.

Manual install

Place package.json + lib/ under ~/.dsh/profiles/node_modules/dsh-mcsm-panel/, then append to ~/.dsh/profiles/<profile>/cordis.patch.yml:

- insert:
    - id: mcsm-panel
      name: dsh-mcsm-panel

If ws is missing, install it into the shared ~/.dsh/profiles/node_modules (or copy it from the DSH Desktop install directory), otherwise mcsm_console will fail to connect.

Configuration

Open Settings -> Plugins -> MCSM Panel, fill the card, and save:

Field	Meaning
Panel URL	MCSM panel address, e.g. http://127.0.0.1:23333 (HTTPS supported)
Username / Password	Panel login account (stored in plaintext in settings.yaml)
daemonId	ID of the daemon hosting the instance
Instance ID	The instance UUID

Copy daemonId / instanceId from the panel URL bar: #/instances/terminal/files?daemonId=<daemonId>&instanceId=<instanceId>

Four toggles at the bottom of the card enable each tool (mcsm_console, mcsm_file, mcsm_instance, mcsm_upload - all on by default). Saves apply immediately; new tools appear only after a DSH restart.

Security

• Use an account with console + file permissions only on the target instance - never an instance-admin or global admin account.
• Credentials are stored in plaintext in settings.yaml - do not share that file.
• mcsm_console can run stop, /kill, and more; mcsm_file delete and mcsm_instance kill are destructive. Weigh the risk of giving an AI these tools carefully.
• Prefer a trusted/local network; use the panel own HTTPS/TLS across the public internet. For a require-explicit-approval-per-action flow, combine with the dsh-url-gate URL gate - note the gate inspects command text, not mcsm_* tool calls.

Troubleshooting

• Tools appear but say "not fully configured": fill the card and save - it takes effect immediately (tools themselves need a DSH restart to appear after first install).
• mcsm_console fails to connect: instance online? account granted the instance? daemon port (e.g. 24444) reachable? If the panel/daemon uses HTTPS, ensure the daemon supports wss.
• mcsm_file write -> Illegal access path: parent directory not writable or path invalid. Missing files are auto-created, but the parent must exist and the account needs write permission.
• mcsm_instance no response: account lacks permission, or the instance is busy.
• mcsm_upload fails: local path exists? target dir writable? daemon port reachable? Files are limited by the daemon maxFileSize (default 100 MB).
• Uninstall: remove the insert block from cordis.patch.yml, restart, and delete ~/.dsh/profiles/node_modules/dsh-mcsm-panel.

Changelog

v1.0.1 - mcsm_console keeps the most recent output when truncating (was keeping the start) and handles http->ws and https->wss. Added a shared token cache and automatic re-login on 401/403. mcsm_file gained delete, and write auto-creates missing files. Added mcsm_instance and mcsm_upload. Friendlier errors on non-JSON responses; settings card no longer trims the password field, clears drafts after saving, clears errors while editing, and adds toggles for the new tools.

v1.0.0 - Initial release (mcsm_console + mcsm_file).

Files

dsh-mcsm-panel/
├── install.ps1       # installer for DSH Desktop
├── package.json      # plugin manifest
├── lib/
│   ├── index.js      # host: tools + panel session
│   └── client.js     # settings card (browser)
├── README.md
└── README.zh-CN.md   # Chinese

License

MIT