hostdeck

hostdeck

hostdeck 是一个小型本地桥接程序，用于连接 FadeHost 托管的 MCP 服务，该服务负责管理账户的游戏服务器、Discord 机器人、托管应用和 VPS 实例。通过一个界面，你可以启动和关闭机器、读取控制台、编辑服务器文件、创建备份、从代码仓库部署应用，以及监控用量和防火墙。

该桥接程序不保存托管数据，也不运行自己的托管逻辑。它会在本地提供上游服务的工具列表，内容与从实时端点捕获的内容完全一致，并将每次工具调用转发到上游，原样返回结果。

工具

游戏服务器：

• list_servers — 列出账户可管理的所有游戏服务器（包括自有服务器和团队共享服务器），包含 ID、游戏、状态和地址。请先调用此工具以查找服务器 ID。 无参数。
• get_server — 获取单个服务器的完整信息：状态、软件和版本、RAM／磁盘用量、关键设置、端口、节点类型以及最近一次崩溃诊断。必填：server。
• get_console_logs — 获取近期的原始控制台输出。 必填：server。可选：lines（50-400，默认值为 150）。
• get_live_stats — 获取运行中服务器的实时内存和 CPU 用量。必填：server。
• get_player_activity — 获取指定时间段内的加入／离开／聊天次数及近期玩家信息。必填：server。 可选：hours（1-168，默认值为 24）。
• start_server、stop_server、restart_server — 通过与控制面板按钮相同的防护路径执行电源操作；停止和重启前会先保存世界。 必填：server。
• send_console_command — 通过 RCON 在运行中的 Minecraft 服务器上执行一条控制台命令，命令前不能带斜杠。必填：server、command。

备份和世界：

• list_backups — 列出服务器的异地备份快照（ID、时间、大小）。必填：server。
• create_backup — 立即触发异地备份。 必填：server。
• get_world_activity — 获取 Minecraft Java 世界的区块数量、磁盘用量和可清理空间。必填：server。
• prune_world — 移除几乎无人访问过的区块；默认仅运行预览。 必填：server。可选：threshold、dry_run。
• undo_world_prune — 从最近一次清理前的世界文件恢复。必填：server。

创建：

• create_server — 创建游戏服务器，可选择使用预设或配置各游戏专属选项。 必填：name。可选：game、software、version、region、ram_mb、preset、options。
• get_creation_options — 获取 create_server 接受的预设和各游戏专属选项。可选：game。
• create_app — 从 GitHub 或 GitLab 代码仓库部署 Discord 机器人或 Web 应用。必填：name、repo_url。可选：kind、region、tier、runtime、branch、start_command、build_command、build_mode、env、web_address、port。

文件：

• list_files — 列出服务器文件系统中的目录（仅限该服务器）。必填：server。 可选：path。
• read_file — 读取文本文件（上限为 96KB；不允许读取二进制文件）。必填：server、path。
• write_file — 创建或覆盖文本文件（上限为 192KB；覆盖时不创建备份）。 必填：server、path、content。

机器人和应用：

• list_bots — 账户托管的 Discord 机器人： id、名称、状态、运行时和源代码仓库。不需要 参数。
• get_bot_logs — 获取托管机器人的运行时日志。 必需参数：bot。
• power_bot — 启动、停止或重启托管机器人。 必需参数：bot、action（start、stop 或 restart）。
• redeploy_app — 拉取托管应用或机器人的最新提交并重新 启动。必需参数：app。
• list_app_deployments — 部署历史：提交记录， 按时间从新到旧排列，并显示当前运行的提交。必需参数： app。
• rollback_app — 将应用固定到较早的提交，或 恢复跟随最新提交。必需参数：app。可选参数： commit。
• get_app_usage — 查看应用的套餐限制、最新和峰值 读数，以及流量。必需参数：app。
• get_app_firewall — 查看应用所遵循的出站策略和 规则。必需参数：app。
• set_app_firewall — 替换付费应用的出站列表：设为 open，或设为带规则的 allowlist。 必需参数：app、policy。可选参数： rules。
• get_app_refusals — 查看过去一天中防火墙实际 拒绝的请求。必需参数：app。
• list_app_schedules — 列出应用的计划命令， 包含 ID、上次运行时间和下次运行时间。必需参数：app。
• create_app_schedule — 为应用添加按 cron 计划执行的 shell 命令。必需参数：app、cron、 command。可选参数：enabled。
• delete_app_schedule — 删除计划命令。 必需参数：app、schedule_id。
• move_app_region — 将付费应用迁移到其他区域，或 查看其当前运行区域。必需参数：app。 可选参数：region。
• list_app_variables — 列出应用环境变量的 名称（绝不返回变量值）。 必需参数：app。
• set_app_variables — 添加、更改或删除 环境变量。必需参数：app。可选参数： set、unset。

VPS 实例：

• list_vps — 列出账户托管的 VPS 实例， 包含 ID、套餐、规格、状态、区域和 SSH 主机。 不需要参数。
• power_vps — 启动、关闭或重启 VPS。 必需参数：vps、action（start、shutdown 或 reboot）。

配置

• FADEHOST_MCP_URL（可选）— 覆盖上游端点。默认值为 https://api.fadehost.com/mcp。 （此覆盖钩子是本次重建中自行标注的复原内容。）
• FADEHOST_API_KEY（可选）— 设置后，每个上游请求都会携带 X-API-Key: <key> 标头；标头名称来自上游注册表记录中的声明。未设置时， 不会发送此类标头。（环境变量名称及此转发行为也属于 自行标注的复原内容；原有接口是在未提供密钥的情况下捕获的。）

转发机制

首次调用工具时，客户端会与上游建立可流式传输的 HTTP 会话：先发送 JSON-RPC initialize 请求（protocolVersion 2025-03-26，clientInfo name hostdeck），然后发送 notifications/initialized 通知，最后发送携带调用方原样参数的 tools/call 请求。上游在 initialize 响应中返回 Mcp-Session-Id 标头时，该值会随会话的每个后续请求一同发送； 此会话将在进程运行期间复用。响应 可能是普通 JSON，也可能是服务器发送事件； 两种格式均会读取。

上游成功结果会原样传递，包括上游设置的任何 isError 标志。 发生失败时——包括 JSON-RPC 错误、非 2xx 状态、 无法读取响应或无法完成请求——会返回一个 isError 结果， 其文本以 hostdeck error: 开头（此呈现方式 是本次重建中自行标注的复原内容）。

CLI

每个工具也可作为子命令使用，接受一个 JSON 参数 字符串（不需要参数的工具可省略）：

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

退出代码：成功时为 0，结果为 isError 时为 1， 用法错误时为 2。

MCP 服务

npx -y @reneturcios/hostdeck mcp

MCP 客户端配置：

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

容器的默认命令是 mcp，因此第一种形式会启动 stdio MCP 服务；其他参数则照常传递给 CLI。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全针对桩化的 JSON-RPC 上游运行，不会发起实时网络调用。

许可证

MIT — 详见 LICENSE。