Minecraft控制协议插件

一个Minecraft Paper插件,通过HTTP协议实现AI代理对Minecraft 1.21服务器的控制和监控。

  • by AxenoDev
  • Java
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 AxenoDev/MineMCP

使用说明

MineMCP

一个Minecraft Paper插件,实现了 模型上下文协议(MCP) 服务器,使AI代理能够通过HTTP控制和监视Minecraft 1.21服务器。

🛠️ 可用工具

世界操纵

  • pose_block -在特定坐标处放置一个块
  • break_block -在特定坐标处打断一个块
  • fill_block -用块填充区域

命令执行

  • execute_command -使用输出捕获执行任何Minecraft命令

文件系统

  • read_file -从服务器读取文本文件
  • write_file -将文本文件写入服务器
  • read_file_base64 -以Base64格式读取二进制文件
  • write_file_base64 -从Base64写入二进制文件
  • list_directory -列出目录内容

服务器信息

  • list_plugins -获取所有已安装的插件
  • get_logs -检索最近的服务器日志
  • get_online_players -列出所有在线玩家
  • get_player -获取特定玩家的详细信息(健康、库存、位置、效果等)

📋 需求

  • Java 21 或更高
  • 我的世界1.21 服务器
  • 纸张 或 紫癜 服务器软件(Spigot可能可以工作,但不受官方支持)

🚀 安装

下载预构建JAR

  1. 从下载最新版本 发布 页
  2. 地方 MineMCP-1.0.0-all.jar 在您的服务器中 plugins/ 文件夹
  3. 启动/重新启动服务器
  4. 在中配置令牌 plugins/MineMCP/config.yml

⚙️ 配置

第一次运行后,编辑 plugins/MineMCP/config.yml:

server:
  port: 3000
  token: "your-secret-token-here"  # Change this to a secure random token!

重要:始终更改默认令牌以确保安全!

生成安全令牌

# Linux/macOS
openssl rand -hex 32

# Or use any password generator to create a strong token

🔌 用法

启动服务器

  1. 安装MineMCP启动Minecraft服务器
  2. MCP服务器将在端口3000(可配置)上自动启动
  3. 检查控制台是否: [MineMCP] MCP server started on port 3000

与MCP客户端连接

在MCP扩展中使用VS代码

创建或编辑 .vscode/mcp.json 在您的项目中:

{
  "mcpServers": {
    "minecraft": {
      "url": "http://localhost:3000/sse?token=your-secret-token-here"
    }
  }
}

📚 API示例

执行命令

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_command",
    "arguments": {
      "command": "time set day"
    }
  }
}

放置一个块

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "pose_block",
    "arguments": {
      "world": "world",
      "x": 100,
      "y": 64,
      "z": 200,
      "material": "DIAMOND_BLOCK"
    }
  }
}

获取玩家信息

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_player",
    "arguments": {
      "player": "PlayerName",
      ...
    }
  }
}

🔒 安全考虑

  1. 令牌保护:永远不要将令牌提交给版本控制
  2. 网络安全:默认情况下,服务器绑定到 0.0.0.0 (所有接口)
  3. 防火墙规则:仅限制端口3000访问受信任的IP
  4. 文件系统访问:工具可以访问整个服务器目录-请谨慎使用

🤝 贡献

欢迎投稿!请按照以下步骤操作:

  1. 克隆该仓库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 提交您的更改(git commit -m 'Add amazing feature')
  4. 推到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

添加新工具

  1. 创建一个扩展的新类 McpTool 在 src/main/java/me/axeno/minemcp/tools/impl/
  2. 实施所需的方法(getSchema() 和 execute())
  3. 在中注册该工具 ToolHandler.java 构造函数

例子:

public class MyTool extends McpTool {
    public MyTool() {
        super("my_tool", "Description of my tool");
    }

    @Override
    public ObjectNode getSchema() {
        ObjectNode schema = mapper.createObjectNode();
        schema.put("type", "object");
        // Define your schema...
        return schema;
    }

    @Override
    public ObjectNode execute(JsonNode args) throws Exception {
        CompletableFuture<String> future = new CompletableFuture<>();
        
        Bukkit.getScheduler().runTask(MineMCP.getInstance(), () -> {
            try {
                // Your Bukkit operations here
                future.complete("Success!");
            } catch (Exception e) {
                future.completeExceptionally(e);
            }
        });
        
        String result = future.get(10, TimeUnit.SECONDS);
        return createTextResult(result);
    }
}

📄 许可证

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

📞 支持


由...制作❤️ 适用于Minecraft和AI社区