预制体 MCP

预制体 MCP

在Hytale内部托管一个MCP服务器,使代理能够根据提示迭代创作预制件。

实用

Prefab MCP

在 Hytale 服务器内部托管一个 MCP 服务器,使 Claude Code、Github Copilot 或 Codex 等智能体能够基于该服务器自身的实时方块调色板来创作预制件。

提供五个工具:搜索调色板、查看方块信息、运行构建脚本、渲染结果,以及在完成时发布。

MCP 工具 描述
search_blocks 从运行中的服务器获取真实名称(包含模组),并给出每个方块占用的格子尺寸
get_block_information 方块的全部信息:其表面纹理(模型绘制的方块则为物品栏图标)、各旋转角度下的尺寸与占地、支持的 yaw/pitch,以及模型范围
build_prefab 运行你的 JavaScript,将 <name>.prefab.json 写入私有的暂存区
render_prefab 从任意相机角度生成 PNG,让智能体看到自己构建的结果
publish_prefab 将暂存的预制件复制到 prefabs/prefab-mcp/,玩家可以在那里找到它

安装

启动服务器并留意以下日志:

[PrefabMcp|P] Palette snapshot: <your-total> blocks and fluids
[PrefabMcp|P] MCP server listening on http://127.0.0.1:[mcp-port]/mcp

在游戏中运行 /prefab-mcp,会打开一个页面,其中的配置信息(以及需要时的个人令牌)位于可选中并复制的字段中。在仅限本地(即默认)的服务器上,输出如下:

MCP server listening on port <mcp-port>
Add this to your MCP client configuration on this machine. This server is local only, so it
accepts connections from this machine alone; to use it from other devices, set "localOnly": false
in mcp.json and restart.
{
  "mcpServers": {
    "hytale-prefab": {
      "type": "http",
      "url": "http://127.0.0.1:[mcp-port]/mcp"
    }
  }
}

或者让同一台机器上的智能体直接连接:

claude mcp add --transport http hytale-prefab http://127.0.0.1:[mcp-port]/mcp

仅限本地

默认情况下,监听器绑定到回环地址(127.0.0.1),即机器用于与自身通信的地址。发往该地址的流量永远不会离开本机,因此只有与 Hytale 服务器运行在同一台机器上的智能体才能连接,且 /prefab-mcp 始终将 127.0.0.1 作为主机地址显示。

要从其他设备使用,请在 mcp.json 中将 localOnly 设为 false 并重启。此时监听器绑定到 0.0.0.0,即机器拥有的所有网络地址,并接受任何能访问该端口的设备的连接。此时 /prefab-mcp 会改为打印 <server-host> 占位符,因为智能体相对于服务器运行在哪里,以及前面是否有反向代理或 DNS 名称,是服务器无法看到的,所以它会询问而不是猜测:

Add this to your MCP client configuration. Replace <server-host> with this server's address, or
127.0.0.1 if the agent runs on this machine.
{
  "mcpServers": {
    "hytale-prefab": {
      "type": "http",
      "url": "http://[server-host]:[mcp-port]/mcp",
      "headers": {
        "Authorization": "Bearer 657827e9-8e16-4614-b533-4cd444373a46.HvjnLeoLyTwzJ-8kMPhP69Vze-7MXHZz"
      }
    }
  }
}

在关闭本地限制之前,建议启用 requirePersonalToken,因为任何能访问该端口的人都可以生成预制件,无论其在服务器上拥有何种权限。

身份验证

默认关闭。新服务器会将 requirePersonalToken 设为 false,因此服务器一启动即可使用:新服务器同时也是仅限本地的,所以访问它本就需要处在同一台机器上。

{ "requirePersonalToken": true }

当前激活的模式会在启动时说明:

[PrefabMcp|P] Personal tokens NOT required: anyone who can reach the endpoint may use every tool.
              Set "requirePersonalToken": true in mcp.json to require one.

/prefab-mcp 会打印该服务器实际接受的配置:需要令牌时包含 headers 块,不需要时不包含。在令牌功能关闭期间,tokenSecret 在 mcp.json 中处于未使用状态,但仍会生成并保留,以便之后切换时不会改变任何人的令牌。

当 requirePersonalToken 为 true 时,每个 MCP 请求都必须携带拥有以下权限的玩家的个人令牌:

Authorization: Bearer <player-uuid>.<signature>

两部分分别校验。令牌说明是哪个玩家;权限系统说明是否允许。因此撤销某人的权限会立即切断其 MCP 访问,无需轮换密钥或重新签发其他人的令牌。令牌仅通过 /prefab-mcp 显示,仅对运行该命令的玩家显示,且从不记录到日志。

要一次性撤销所有人,请更改 mcp.json 中的 tokenSecret 并重启;所有已签发的令牌都会验证失败。要撤销单个玩家,请撤销其权限。

预制件的创建位置

build_prefab 写入插件数据目录中的暂存区:mods/willchil_PrefabMcp/staging/。该位置在 prefabs/ 之外,因此智能体未完成的迭代永远不会出现在游戏中。render_prefab 优先从暂存区读取。只有 publish_prefab 会写入 prefabs/prefab-mcp/,因此智能体制作的预制件永远不会与管理员或游戏内编辑器制作的预制件混在一起。

服务器关闭时暂存区会被删除。 智能体未发布的任何内容都会丢失。

两个位置都按调用者以相同方式划分:

调用者 暂存位置 发布位置
匿名调用,且服务器不要求令牌 staging/ prefabs/prefab-mcp/
当时在线的玩家 staging/<username>/ prefabs/prefab-mcp/<username>/
当时离线的玩家 staging/offline-players/ prefabs/prefab-mcp/offline-players/

build_prefab 和 publish_prefab 都接受 overwrite,分别用于替换暂存区或发布文件夹中同名的现有预制件。

权限

/prefab-mcp 和每个 MCP 请求都需要 willchil.prefabmcp.command 权限。该节点会在启动时记录到日志:

[PrefabMcp|P] Registered /prefab-mcp (permission: willchil.prefabmcp.command)

配置

首次加载时,插件会写入 mods/willchil_PrefabMcp/mcp.json:

{
  "port": 7520,
  "tokenSecret": "rK-FDBd0xT66CRThXuR30VQDwpj6D3-iSFveyJLinJw",
  "requirePersonalToken": false
}

tokenSecret 在首次加载时随机生成,是每个个人令牌派生所用的盐。

其启动端口为游戏自身绑定端口加 2000,因此同一台机器上的多个服务器不会冲突。

-Dhytale.mcp.port=<n> 可在单次运行中覆盖该文件,而不会写回文件。

如果所选端口已被占用,插件会记录警告并保持关闭,而不会悄悄绑定到其他位置。