Hytale MCP Plugin

Hytale MCP

Hytale服务器的模型上下文协议插件

将OpenCode、Claude、ChatGPT和Gemini等人工智能助手直接连接到您的Hytale服务器

Preview

 ](https://github.com/Metrakit/hytale-MCP-plugin/releases)  

指南：https://top-games.net/guides/connect-ai-hytale-server-mcp

特性 • 安装 • 配置 • 用法 • API • 贡献

______________________________________________________________________

目录

• 关于
• 特性
• 需求
• 安装
• 配置
• 用法
• API 参考
• 延伸
• 最佳实践
• 故障排除
• 常见问题解答
• 建筑
• 贡献
• 许可证
• 支持

关于

Hytale MCP通过模型上下文协议（MCP）将AI助手的功能带到您的Hytale服务器。此插件使Claude、ChatGPT和Gemini等AI模型能够与您的服务器交互，从而实现自动化、创造性构建和增强的服务器管理。

用例

• 创意建筑 -告诉AI“在我的位置建造一座埃菲尔铁塔”，并观察它建造复杂的结构
• 服务器自动化 -自动化玩家管理等日常任务
• 管理工具 -使用自然语言命令管理服务器
• 开发与测试 -快速原型化和测试游戏机制

无论您是服务器管理员、构建者还是开发人员，Hytale MCP都为AI集成提供了安全且可扩展的基础。

特性

核心能力

• 完全支持MCP协议 -符合标准的模型上下文协议实现
• 安全认证 -基于令牌的身份验证，具有单独的管理员和玩家权限
• 可扩展架构 -易于使用的插件系统，用于添加自定义功能
• 精细权限 -针对不同用户级别的细粒度访问控制
• AI客户端兼容 -适用于OpenCode、Claude、ChatGPT、Gemini和任何兼容MCP的客户端

内置工具

• 世界建筑 -使用批处理块放置，使用自然语言提示构建任何内容
• 地形编辑 -平整矩形区域用于建筑基础
• 项目管理 -通过智能物品搜索为玩家提供物品
• 区块发现 -搜索并分类所有可用块
• 玩家管理 -列出玩家、获取位置、管理库存、发送消息
• 服务器管理 -执行命令、广播消息、踢球员
• 信息检索 -访问服务器统计数据、世界信息、区块类型和玩家数据
• 日志管理 -按级别、日期和行数过滤和检索服务器日志

需求

• Nitrado网络服务器插件

安装

快速开始

1. 下载 最新的 MCP-1.*.*.jar 从 发布页面
2. 安装 这 Nitrado网络服务器插件 （所需依赖性）
3. 地方 服务器中的两个JAR文件 mods/ 目录
4. 开始 您的服务器生成默认配置
5. 配置 您的令牌和权限（请参阅 配置)
6. 重启 您的服务器

该插件将在 http://your-server:port/Top-Games/MCP/mcp

快速示例

安装后，您可以测试连接：

# Test basic connectivity
curl http://localhost:port/Top-Games/MCP/mcp

# List available tools (with authentication)
curl -X POST http://localhost:port/Top-Games/MCP/mcp \
  -H "Authorization: Bearer your-admin-token" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

配置

第一次运行后，将在以下位置创建配置文件 mods/MCP/config.json:

备注：服务器端口是在WebServer插件设置中配置的，而不是在此处。

{
  "auth": {
    "enabled": true,
    "adminTokens": [
      "your-admin-token-here"
    ],
    "playerTokens": [
      "your-player-token-here"
    ]
  },
  "features": {
    "players": {
      "listPlayers": false,
      "executeCommand": false,
      "broadcastMessage": false,
      "setBlock": false,
      "getPlayerPosition": false,
      "getLogs": false,
      "sendChatMessage": false,
      "getBlockTypes": false,
      "listBlocks": false,
      "getWorldInfo": false,
      "getServerInfo": false
    },
    "admins": {
      "listPlayers": true,
      "executeCommand": true,
      "broadcastMessage": true,
      "setBlock": true,
      "getPlayerPosition": true,
      "getLogs": true,
      "sendChatMessage": true,
      "getBlockTypes": true,
      "listBlocks": true,
      "getWorldInfo": true,
      "getServerInfo": true
    },
    "maxBlocksBatch": 1000
  }
}

配置参考

服务器设置

认证设置

功能权限

为每个权限级别配置功能可用性：

其他设置：

• maxBlocksBatch （int，默认值：1000）-每单位最大块数 set_blocks_batch 呼叫

权限结构：

• features.admins -管理员令牌持有者可用的功能
• features.players -玩家代币持有者可用的功能

禁用HTTPS（HTTP连接）

默认情况下，Nitrado WebServer插件使用HTTPS。如果需要通过HTTP连接，可以在WebServer插件配置中禁用TLS。

地点： mods/Nitrado_WebServer/config.json

添加或修改 Tls 章节：

{
  "Tls": {
    "Insecure": true
  }
}

用法

连接AI客户端

要将AI助手连接到您的Hytale服务器：

1. 配置您的AI客户端 连接到MCP端点
2. 提供端点URL: http://your-server:port/Top-Games/MCP/mcp
3. 验证 在请求标头中使用Bearer令牌：

   Authorization: Bearer your-token-here

客户端设置示例

对于OpenCode或其他MCP客户端，添加以下配置：

{
  "mcpServers": {
    "hytale-mcp": {
      "url": "http://your-server:port/Top-Games/MCP/mcp",
      "headers": {
        "Authorization": "Bearer your-admin-token"
      }
    }
  }
}

API 参考

可用工具

set_block

将单个块放置在指定坐标处。

示例提示：

在坐标x:10、y:64、z:10处放置一块砂岩砖

参数：

• x （int）：X坐标
• y （int）：Y坐标
• z （int）：Z坐标
• blockType （string）：块标识符（例如。， Rock_Sandstone_Brick)
• world （string）：世界名称

示例响应：

{
  "success": true,
  "message": "Block placed successfully",
  "x": 10,
  "y": 64,
  "z": 10,
  "world": "world",
  "blockType": "Rock_Sandstone_Brick"
}

list_players

列出服务器上当前连接的所有玩家。

示例提示：

“服务器上当前有谁在线？” “列出所有连接的玩家”

答复：

{
  "count": 5,
  "players": [
    {
      "uuid": "player-uuid",
      "name": "PlayerName"
    }
  ]
}

get_server_info

获取有关服务器的信息，包括名称、版本和正常运行时间。

示例提示：

“服务器状态如何？” “显示服务器信息和正常运行时间”

答复：

{
  "name": "My Hytale Server",
  "version": "1.0.0",
  "uptime": "2 days, 5 hours, 30 minutes",
  "tps": 20.0
}

list_blocks

使用智能分类和缓存列出所有可用块。非常适合发现用于构建或赠送物品的物品ID。

示例提示：

“给我看看所有的石块” “查找包含‘砖’的构建块” “列出20个装饰块”

参数：

• limit （int，可选）：返回的最大块数
• search （字符串，可选）：按名称过滤块的搜索词（不区分大小写）
• category （字符串，可选）：按类别筛选（建筑、装饰、自然、矿石、石头、木材、金属、玻璃、食品、工具、武器、杂项）

示例请求-搜索石头：

{
  "search": "stone",
  "limit": 10
}

示例请求-获取所有构建块：

{
  "category": "building",
  "limit": 50
}

答复：

{
  "total": 1234,
  "returned": 10,
  "blocks": [
    {
      "name": "hytale:stone_brick",
      "id": 42,
      "category": "building"
    },
    {
      "name": "hytale:sandstone",
      "id": 87,
      "category": "stone"
    }
  ],
  "categoryStats": {
    "building": 250,
    "stone": 180,
    "wood": 120,
    "nature": 300,
    "decoration": 95,
    "misc": 289
  },
  "searchTerm": "stone"
}

give_item

使用向玩家提供物品 /give 命令。

示例提示：

“给米歇尔10根棍子” “给PlayerName 64块石头砖”

参数：

• player （string）：要将项目赋予的玩家名称
• itemId （string）：项目ID（使用 list_blocks 查找ID）
• quantity （int，可选）：要给出的数量（默认值：1）

请求示例：

{
  "player": "Michel",
  "itemId": "Ingredient_Stick",
  "quantity": 10
}

答复：

{
  "player": "Michel",
  "itemId": "Ingredient_Stick",
  "quantity": 10,
  "command": "give Michel Ingredient_Stick --quantity=10",
  "status": "executed"
}

flatten_terrain

将矩形地形区域平整到特定高度，非常适合建筑基础。用石块填充下方，用空气清除上方。

示例提示：

“在我的位置平整一块50x50的区域，用于建造城堡” “在64米高的地方建造一个100块宽的石头平台” “为大型建筑准备地形，使其平坦”

参数：

• world （字符串）：世界UUID
• x1, z1 （int）：第一个角坐标
• x2, z2 （int）：第二个角坐标
• y （int）：要压平的高度
• fillBlock （字符串，可选）：填充表面以下的块类型（默认值：“hytale:dirt”）
• maxHeight （int，可选）：清除上方的最大高度（默认值：y+10）

示例请求-创建一个50x50的石头平台：

{
  "world": "world-uuid-here",
  "x1": 100,
  "z1": 100,
  "x2": 150,
  "z2": 150,
  "y": 64,
  "fillBlock": "hytale:stone"
}

答复：

{
  "area": 2601,
  "minX": 100,
  "maxX": 150,
  "minZ": 100,
  "maxZ": 150,
  "flattenY": 64,
  "maxHeight": 74,
  "fillBlock": "hytale:stone",
  "blocksPlaced": 166464,
  "blocksCleared": 26010,
  "totalBlocks": 192474,
  "durationMs": 1250,
  "status": "success"
}

execute_command

执行服务器命令。

示例提示：

“让米歇尔成为一名操作员” “执行‘天气晴朗’命令” “将时间设置为每天”

参数：

{
  "command": "op Michel"
}

答复：

{
  "command": "op Michel",
  "status": "executed"
}

broadcast_message

向所有连接的玩家广播消息。

示例提示：

“向所有人宣布服务器将在5分钟后重新启动” “向所有玩家广播欢迎信息”

参数：

{
  "message": "Welcome to our server!"
}

答复：

{
  "message": "Welcome to our server!",
  "status": "broadcasted"
}

get_logs

使用可选筛选检索服务器日志。

示例提示：

“显示最近50个错误日志” “获取昨天的服务器日志” “日志中最近的警告是什么？”

参数：

• lines （int，可选）：要检索的行数（默认值：100，最大值：1000）
• level （字符串，可选）：按日志级别筛选（例如，“INFO”、“WARNING”、“ERROR”、“SEVERE”）
• date （字符串，可选）：日志文件日期格式为“YYYY-MM-DD”

请求示例：

{
  "lines": 50,
  "level": "ERROR"
}

答复：

{
  "lineCount": 50,
  "level": "ERROR",
  "content": "[2026-02-01 10:30:45] [ERROR] Failed to connect to database\n[2026-02-01 10:30:45 [ERROR] Connection timeout\n...",
  "timestamp": "2026-02-01T10:32:00"
}

具体日期请求示例：

{
  "date": "2024-01-14",
  "lines": 200
}

set_blocks_batch

在单个请求中在指定的世界坐标处设置多个块（可配置限制，默认值：1000个块）。

示例提示：

“在我的位置建造一堵10x10的石墙” 在坐标x:100、y:64、z:200处创建房屋 “在我的位置建造埃菲尔铁塔复制品” “在我附近建一座小城堡”

参数：

• blocks （array）：块对象的数组，每个对象都有x、y、z、blockType

- x （int）：X坐标 - y （int）：Y坐标 - z （int）：Z坐标 - blockType （string）：块标识符（例如。， Rock_Sandstone_Brick)

• world （string）：世界名称（可选，默认为当前世界）

请求示例：

{
  "blocks": [
    {"x": 10, "y": 64, "z": 10, "blockType": "Rock_Sandstone_Brick"},
    {"x": 11, "y": 64, "z": 10, "blockType": "Rock_Sandstone_Brick"},
    {"x": 10, "y": 64, "z": 11, "blockType": "Rock_Sandstone_Brick"}
  ]
}

答复：

{
  "total": 3,
  "success": 3,
  "failed": 0,
  "results": [
    {"x": 10, "y": 64, "z": 10, "blockType": "Rock_Sandstone_Brick", "status": "success"},
    {"x": 11, "y": 64, "z": 10, "blockType": "Rock_Sandstone_Brick", "status": "success"},
    {"x": 10, "y": 64, "z": 11, "blockType": "Rock_Sandstone_Brick", "status": "success"}
  ]
}

get_player_position

获取特定玩家的当前位置（x，y，z）和旋转（偏航，俯仰）。

示例提示：

“米歇尔在哪里？” “获取我当前的职位” “PlayerName的坐标是多少？”

参数：

• player （string）：玩家名称

请求：

{
  "player": "Michel"
}

答复：

{
  "name": "Michel",
  "uuid": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
  "position": {
    "x": 1943.18,
    "y": 124.0,
    "z": 603.64,
    "yaw": -1.91,
    "pitch": 0.0,
    "worldUuid": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}

get_world_info

获取有关世界的信息，包括名称、种子和维度。

示例提示：

“世界种子是什么？” “显示当前世界的信息” “产卵点在哪里？”

答复：

{
  "name": "My World",
  "seed": 123456789,
  "dimension": "overworld",
  "spawn": {
    "x": 0,
    "y": 100,
    "z": 0
  }
}

send_chat_message

向特定玩家发送聊天消息。

示例提示：

“向米歇尔发送欢迎信息” “告诉PlayerName他们的建筑看起来很棒” “向管理员发送有关此问题的消息”

参数：

• player （string）：目标玩家名称
• message （string）：要发送的消息

请求：

{
  "player": "Michel",
  "message": "Welcome to the server!"
}

答复：

{
  "message": "Welcome to the server!",
  "status": "sent"
}

MCP协议端点

该插件实现了标准的MCP JSON-RPC 2.0端点：

发布 /mcp

MCP工具操作的主要终点。

可用方法：

• initialize -初始化MCP连接并协商功能
• tools/list -根据身份验证级别列出可用工具
• tools/call -使用指定参数执行工具
• ping -健康检查端点

请求示例：

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "params": {},
  "id": 1
}

获取 /mcp

返回插件元数据和版本信息。

示例响应：

{
  "name": "MCP",
  "version": "1.0.0",
  "protocol": "mcp",
  "description": "Model Context Protocol for Hytale servers"
}

扩展自定义功能

创建自定义功能很简单（例如使用另一个插件）。实施 McpFeature 接口：

public class MyCustomFeature implements McpFeature {
    private final HytaleLogger logger;

    public MyCustomFeature(HytaleLogger logger) {
        this.logger = logger;
    }

    @Override
    public String getName() {
        return "my_custom_feature";
    }

    @Override
    public McpTool getToolDefinition() {
        return new McpTool(
            "my_custom_feature",
            "Description of what this feature does",
            "function"
        );
    }

    @Override
    public McpToolResponse execute(McpToolCall call, McpAuthManager.AuthLevel authLevel) {
        try {
            // Your custom logic here
            
            JsonObject result = new JsonObject();
            result.addProperty("data", "your result");
            
            return McpToolResponse.success(GSON.toJson(result));
        } catch (Exception e) {
            logger.atSevere().withCause(e).log("Error in custom feature");
            return McpToolResponse.error("Failed: " + e.getMessage());
        }
    }

    @Override
    public boolean hasPermission(McpAuthManager.AuthLevel authLevel, McpConfig config) {
        // Define who can use this feature
        return authLevel == McpAuthManager.AuthLevel.ADMIN;
    }
}

然后在你的插件中注册它 registerFeatures() 方法：

featureRegistry.registerFeature(new MyCustomFeature(logger));

最佳实践

• 强代币 -生成加密安全的随机令牌（32+个字符）

  # Example token generation
  openssl rand -base64 32

• 最低权限 -仅启用用户实际需要的功能

- 限制 executeCommand 仅限管理员令牌 - 如果不需要，禁用玩家功能

故障排除

常见问题

Plugin not loading

症状： MCP插件未出现在服务器日志或插件列表中

解决：

• 验证是否安装并启用了WebServer插件
• 检查JAR文件是否正确 mods/ 目录
• 查看服务器启动日志中的错误消息

Authentication failures

症状： 401未经授权或身份验证错误

解决：

• 确认令牌与配置完全匹配
• 验证令牌是否在正确的数组中(adminTokens 对比 playerTokens)
• 检查一下 auth.enabled 设置为 true
• 确保您使用了正确的标题： Authorization: Bearer
• 尝试暂时禁用身份验证以隔离问题

Features not available

症状： 工具未显示在中 tools/list 回应

解决：

• 检查中的功能权限 config.json 对于您的身份验证级别
• 验证您的令牌类型（管理员/玩家）是否启用了该功能
• 查看服务器日志以查找功能初始化错误
• 确保配置文件是有效的JSON
• 配置更改后重新启动服务器

Connection refused

症状： 无法连接到MCP终结点

解决：

• 验证WebServer插件是否正在运行并正确配置
• 检查使用的端口是否正确
• 确保防火墙允许连接到端口
• 确认端点路径正确： /Top-Games/MCP/mcp
• 测试用 curl 或类似的工具（Postman）来验证基本连接

常见问题解答

一般问题

Q： 什么是模型上下文协议（MCP）？ A： MCP是一个开放标准，使AI助手能够安全地连接到外部工具和数据源。它允许AI模型以标准化的方式与您的Hytale服务器进行交互。

Q： 哪些AI助手是兼容的？ A： 任何支持模型上下文协议的AI助手，包括Claude、ChatGPT（带插件）、Gemini和其他兼容MCP的客户端。

Q： 这需要对Hytale服务器进行任何修改吗？ A： 不是。这是一个与Nitrado WebServer插件配合使用的标准插件。不需要修改服务器。

Q： 我可以在生产服务器上使用它吗？ A： 是的，但请确保您遵循安全最佳实践：使用强令牌，仅启用必要的功能，并适当限制权限。

技术问题

Q： 对性能有何影响？ A： 最小。该插件仅在AI助手拨打电话时处理请求。优化批处理操作以减少服务器负载。

Q： 我可以添加自定义工具/功能吗？ A： 是的！该插件具有可扩展的架构。看 延伸 详情请参阅第节。

Q： 一次可以放置多少个块有限制吗？ A： 是的 set_blocks_batch 每个请求的操作有一个可配置的最大值（默认值：1000个块），以防止服务器过载。这 flatten_terrain 该工具对大规模地形操作有更高的限制。

Q： 玩家可以有不同的权限级别吗？ A： 是的。您可以为管理员令牌和玩家令牌配置单独的权限集，从而实现细粒度的控制。

贡献

我们欢迎社区的贡献！以下是您可以提供帮助的方式：

报告问题

• 使用
• 在创建新问题之前，检查问题是否已经存在
• 包括详细信息：服务器版本、插件版本、错误日志

提交变化

1. 克隆该仓库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 进行更改
4. 彻底测试
5. 以明确的信息提交(git commit -m 'Add amazing feature')
6. 推你的叉子(git push origin feature/amazing-feature)
7. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

版权所有（c）2026顶级游戏

支持

获取帮助

• 问题和Bug:

实用链接

• 模型上下文协议规范
• Nitrado网络服务器插件