hostdeck

hostdeck

hostdeck is a small local bridge to FadeHost's hosted MCP server, which looks after an account's game servers, Discord bots, hosted apps and VPS instances. From one surface you can power machines on and off, read consoles, edit server files, take backups, deploy apps from a repository, and keep an eye on usage and firewalls.

The bridge keeps no hosting data and runs no hosting logic of its own. It serves the upstream server's tool list locally, exactly as captured from the live endpoint, and forwards each tool call upstream, returning the result untouched.

Tools

Game servers:

• list_servers — every game server the account can manage (own plus team-shared), with id, game, status and address. Call this first to discover server ids. No arguments.
• get_server — one server in full: status, software and version, RAM/disk usage, key settings, ports, node type and the most recent crash diagnosis. Required: server.
• get_console_logs — recent raw console output. Required: server. Optional: lines (50-400, default 150).
• get_live_stats — live memory and CPU usage of a running server. Required: server.
• get_player_activity — join/leave/chat counts and recent players over a window. Required: server. Optional: hours (1-168, default 24).
• start_server, stop_server, restart_server — power actions through the same guarded paths as the panel buttons; stop and restart save the world first. Required: server.
• send_console_command — run one console command on a running Minecraft server over RCON, without a leading slash. Required: server, command.

Backups and worlds:

• list_backups — off-site backup snapshots of a server (id, time, size). Required: server.
• create_backup — trigger an off-site backup now. Required: server.
• get_world_activity — chunk counts, disk use and pruning headroom for a Minecraft Java world. Required: server.
• prune_world — remove barely-visited chunks; dry run by default. Required: server. Optional: threshold, dry_run.
• undo_world_prune — restore the world files from before the most recent prune. Required: server.

Creation:

• create_server — create a game server, optionally from a preset or with per-game options. Required: name. Optional: game, software, version, region, ram_mb, preset, options.
• get_creation_options — the presets and per-game options create_server accepts. Optional: game.
• create_app — deploy a Discord bot or web app from a GitHub or GitLab repository. Required: name, repo_url. Optional: kind, region, tier, runtime, branch, start_command, build_command, build_mode, env, web_address, port.

Files:

• list_files — list a directory in a server's file system (jailed to that server). Required: server. Optional: path.
• read_file — read a text file (capped at 96KB; binary files are refused). Required: server, path.
• write_file — create or overwrite a text file (capped at 192KB; overwrites without backup). Required: server, path, content.

Bots and apps:

• list_bots — the hosted Discord bots on the account: id, name, status, runtime and source repo. No arguments.
• get_bot_logs — runtime logs of a hosted bot. Required: bot.
• power_bot — start, stop or restart a hosted bot. Required: bot, action (start, stop or restart).
• redeploy_app — pull the latest commit of a hosted app or bot and start it again. Required: app.
• list_app_deployments — deploy history: commits, newest first, and which commit is live. Required: app.
• rollback_app — pin an app to an earlier commit, or follow the latest again. Required: app. Optional: commit.
• get_app_usage — plan limits, latest and peak readings, and traffic for an app. Required: app.
• get_app_firewall — the outbound policy and rules an app runs under. Required: app.
• set_app_firewall — replace the outbound list of a paid app: open, or allowlist with rules. Required: app, policy. Optional: rules.
• get_app_refusals — what the firewall actually turned away in the last day. Required: app.
• list_app_schedules — scheduled commands of an app, with ids, last runs and next runs. Required: app.
• create_app_schedule — add a cron-scheduled shell command to an app. Required: app, cron, command. Optional: enabled.
• delete_app_schedule — remove a scheduled command. Required: app, schedule_id.
• move_app_region — move a paid app to another region, or read where it runs now. Required: app. Optional: region.
• list_app_variables — the NAMES of an app's environment variables (values are never returned). Required: app.
• set_app_variables — add, change or remove environment variables. Required: app. Optional: set, unset.

VPS instances:

• list_vps — the account's managed VPS instances with id, plan, specs, status, region and SSH host. No arguments.
• power_vps — start, shut down or reboot a VPS. Required: vps, action (start, shutdown or reboot).

Configuration

• FADEHOST_MCP_URL (optional) — override the upstream endpoint. Defaults to https://api.fadehost.com/mcp. (The override hook is this rebuild's own labelled reconstruction.)
• FADEHOST_API_KEY (optional) — when set, every upstream request carries an X-API-Key: <key> header; the header name is the one the upstream's registry record declares. When it is not set, no such header is sent. (The env name and this forwarding are also a labelled reconstruction; the original surface was captured keyless.)

Forwarding mechanics

On the first tool call the client opens a streamable HTTP session with the upstream: a JSON-RPC initialize request (protocolVersion 2025-03-26, clientInfo name hostdeck), then a notifications/initialized notification, then the tools/call request carrying the caller's arguments unchanged. When the upstream answers initialize with an Mcp-Session-Id header, that value rides on every later request of the session, which is reused for the life of the process. Replies may arrive as plain JSON or as server-sent events; both are read.

Successful upstream results pass through verbatim, including any isError flag the upstream sets. Failures — a JSON-RPC error, a non-2xx status, an unreadable response, or a request that cannot be completed — come back as an isError result whose text starts with hostdeck error: (this rendering is this rebuild's own labelled reconstruction).

CLI

Each tool is also a subcommand taking one JSON argument string (omit it for tools that take none):

npx @reneturcios/hostdeck list_servers
npx @reneturcios/hostdeck get_server '{"server":"server_42"}'
npx @reneturcios/hostdeck send_console_command '{"server":"server_42","command":"list"}'
npx @reneturcios/hostdeck --version

Exit codes: 0 on success, 1 on an isError result, 2 on a usage error.

MCP server

npx -y @reneturcios/hostdeck mcp

MCP client config:

{
  "mcpServers": {
    "hostdeck": {
      "command": "npx",
      "args": ["-y", "@reneturcios/hostdeck", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/hostdeck
docker run --rm ghcr.io/cloudcorprecords/hostdeck --version

The container's default command is mcp, so the first form is a stdio MCP server; any other arguments reach the CLI normally.

Development

npm install
npm run build
npm test
npm run dev

The test suite runs entirely against a stubbed JSON-RPC upstream — no live network calls.

License

MIT — see LICENSE.