Minemcp

🚀 MineMCP

MineMCP 是一款 Minecraft Paper 插件，它實現了 模型上下文協議 (MCP) 服務器，允許 AI 代理通過 HTTP 控制和監控 Minecraft 1.21 服務器。

🚀 快速開始

安裝要求

• Java 21 或更高版本
• Minecraft 1.21 服務器
• Paper 或 Purpur 服務器軟件（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"  # 請將此值更改為安全的隨機令牌！

重要提示：為了安全起見，請務必更改默認令牌！

生成安全令牌

# Linux/macOS
openssl rand -hex 32

# 或者使用任何密碼生成器創建強令牌

啟動服務器

1. 啟動安裝了 MineMCP 的 Minecraft 服務器。
2. MCP 服務器將自動在端口 3000 上啟動（可配置）。
3. 在控制檯中查看：[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",
      ...
    }
  }
}

🔧 技術細節

安全注意事項

1. 令牌保護：切勿將令牌提交到版本控制系統。
2. 網絡安全：默認情況下，服務器綁定到 0.0.0.0（所有接口）。
3. 防火牆規則：僅允許受信任的 IP 訪問端口 3000。
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. 在 src/main/java/me/axeno/minemcp/tools/impl/ 中創建一個新類，繼承 McpTool。
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 許可證 - 詳情請參閱 LICENSE 文件。

📞 支持

• 問題反饋：GitHub Issues

為 Minecraft 和 AI 社區精心打造 ❤️