# 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):

```bash
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

```bash
npx -y @reneturcios/hostdeck mcp
```

MCP client config:

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

## Docker

```bash
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

```bash
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`.