金大哥 - minemcp MCP 详情

article

README

🚀 MineMCP

MineMCP 是一款 Minecraft Paper 插件，它实现了模型上下文协议 (MCP) 服务器，允许 AI 代理通过 HTTP 控制和监控 Minecraft 1.21 服务器。

🚀 快速开始

安装要求

Java 21 或更高版本
Minecraft 1.21 服务器
Paper 或 Purpur 服务器软件（Spigot 可能可用，但未得到官方支持）

安装步骤

下载预构建的 JAR 文件

从发布页面下载最新版本。
将 MineMCP-1.0.0-all.jar 文件放置在服务器的 plugins/ 文件夹中。
启动/重启你的服务器。
在 plugins/MineMCP/config.yml 中配置令牌。

配置

首次运行后，编辑 plugins/MineMCP/config.yml 文件：

server:
  port: 3000
  token: "your-secret-token-here"  # 请将此值更改为安全的随机令牌！

重要提示：为了安全起见，请务必更改默认令牌！

生成安全令牌

# Linux/macOS
openssl rand -hex 32

# 或者使用任何密码生成器创建强令牌

启动服务器

启动安装了 MineMCP 的 Minecraft 服务器。
MCP 服务器将自动在端口 3000 上启动（可配置）。
在控制台中查看：[MineMCP] MCP server started on port 3000。

使用 MCP 客户端进行连接

使用带有 MCP 扩展的 VS Code

在项目中创建或编辑 .vscode/mcp.json 文件：

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

✨ 主要特性

世界操作

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 - 获取特定玩家的详细信息（健康状况、库存、位置、效果等）

💻 使用示例

执行命令

{
  "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",
      ...
    }
  }
}

🔧 技术细节

安全注意事项

令牌保护：切勿将令牌提交到版本控制系统。
网络安全：默认情况下，服务器绑定到 0.0.0.0（所有接口）。
防火墙规则：仅允许受信任的 IP 访问端口 3000。
文件系统访问：工具可以访问整个服务器目录，请谨慎使用。

贡献代码

欢迎贡献代码！请遵循以下步骤：

分叉此仓库。
创建一个功能分支 (git checkout -b feature/amazing-feature)。
提交你的更改 (git commit -m 'Add amazing feature')。
将更改推送到分支 (git push origin feature/amazing-feature)。
打开一个拉取请求。

添加新工具

在 src/main/java/me/axeno/minemcp/tools/impl/ 中创建一个新类，继承 McpTool。
实现所需的方法 (getSchema() 和 execute())。
在 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 许可证 - 详情请参阅 LICENSE 文件。

📞 支持

问题反馈：GitHub Issues

为 Minecraft 和 AI 社区精心打造 ❤️

minemcp