QuModDocs

Appearance

MCDK MCP 工具 ​

MCDK 可以随游戏进程启动一个标准 MCP Server，让 AI / 自动化客户端在开发期读取日志、执行代码、分析 JSON UI、捕获画面并触发重载命令。

它的定位不是让通用 Agent 完全依赖截图和点击“盲测”游戏，而是提供一个可观测、可复现的开发期测试通道。

启用 MCP ​

在 .mcdev.json 中启用 mcp_server_config：

jsonc
{
  "mcp_server_config": {
    "enabled": true,
    "server_ip": "localhost",
    "server_port": 19133
  }
}

然后用 mcdk 启动游戏。MCP Server 会随游戏进程一起启停。

常用工具 ​

Tool说明
get_latest_logs读取最近游戏运行日志
get_log_range按范围读取日志
get_latest_error_logs读取 Python 错误输出
execute_code在客户端或服务端执行 Python 代码
jsonui_debugger分析 Minecraft JSON UI 运行时结构
capture_game_window捕获游戏窗口画面
click_game_window点击游戏窗口指定坐标
reload_game触发游戏或资源级重载

jsonui_debugger 是 UI 开发反馈的主入口。它使用单 Tool + command 子命令设计，避免把大量细碎工具暴露到 MCP tools/list 中。

常用命令：

text
/help
/screens
/overview [--screen=top|all|<screen>] [--nud]
/tree <screen> <path> [--depth=2] [--max-nodes=80]
/html <screen> <path> [--depth=2] [--html-only]
/render <screen> <path> [--depth=2] [--out=<absolute.svg>]
/find <screen> <path> <query> [--depth=5]
/mod-ui [--include-registered] [--children-depth=1]
/reload-ui [--preserve-mod-ui]

客户端连接 ​

支持 SSE 的 MCP 客户端可以直接连接：

jsonc
{
  "mcpServers": {
    "minecraft_be_mcdk": {
      "url": "http://localhost:19133/sse",
      "name": "Minecraft(BE) MCP Server(MCDK)"
    }
  }
}

VSCode / Copilot 等需要桥接的客户端可通过 mcp-remote 连接：

jsonc
{
  "servers": {
    "minecraft_be_mcdk": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:19133/sse",
        "--transport",
        "sse-only"
      ]
    }
  }
}

Stdio Bridge ​

mcdk_stdio_bridge 是 stdio 形态的 MCP 跳板服务，适合只支持 stdio 或不会主动重连的 Agent / IDE 客户端。

直接连接 MCDK 内置 MCP 时，客户端需要等游戏进程启动后再连接；但不少 IDE / Agent 只在启动时连接一次 MCP，或者只支持 stdio 配置。这种情况下，如果游戏尚未启动，客户端可能会连接失败，并且后续不会主动重试。

mcdk_stdio_bridge 用于解决这个时序问题：它本身始终以 stdio MCP Server 的形式被客户端加载，tools/list 不依赖游戏是否已经启动；只有真正调用 Tool 时，才尝试连接并转发到 MCDK 内置 MCP。若游戏 MCP 已可用，请求会被正常转发；若游戏未启动或未启用 MCP，则返回明确的工具错误。

它的行为边界如下：

行为说明
不启动游戏仍然需要先在 .mcdev.json 中启用 mcp_server_config，并用 mcdk 启动游戏
不提前连接初始化和 tools/list 阶段不连接游戏 MCP，避免客户端启动时失败
调用时转发tools/call 发生时才尝试连接 MCDK 内置 MCP
默认目标默认转发到 http://localhost:19133/mcp，端口与 MCDK 默认 MCP 端口一致
可改 host / port当 .mcdev.json 中端口不同，需要在 bridge 的 args 中同步修改

Roo Code 等使用 mcpServers 配置的客户端：

jsonc
{
  "mcpServers": {
    "minecraft_be_mcdk": {
      "command": "mcdk_stdio_bridge",
      "args": []
    }
  }
}

VSCode / Copilot 的 .vscode/mcp.json 使用 servers 作为顶层字段：

jsonc
{
  "servers": {
    "minecraft_be_mcdk": {
      "command": "mcdk_stdio_bridge",
      "args": []
    }
  }
}

如果没有加入 PATH，可把 command 改成构建产物的绝对路径：

jsonc
{
  "mcpServers": {
    "minecraft_be_mcdk": {
      "command": "D:/path/to/mcdk_stdio_bridge.exe",
      "args": []
    }
  }
}

自定义 host / port：

jsonc
{
  "mcpServers": {
    "minecraft_be_mcdk": {
      "command": "mcdk_stdio_bridge",
      "args": ["--host", "localhost", "--port", "19133"]
    }
  }
}

测试工作流 ​

推荐把 MCDK MCP 当作“开发期可观测测试通道”使用：

  1. 在 Mod / Addon 代码中预留开发期测试函数。
  2. 使用 execute_code 调用客户端或服务端测试入口。
  3. 使用 get_latest_logs / get_latest_error_logs 收集结构化结果。
  4. 多轮执行后统计成功率、耗时和异常分布。
  5. 仅在视觉效果本身是测试目标时使用截图和点击能力。

建议测试函数输出稳定前缀和结构化 JSON：

text
[MCDK_TEST] {"case":"spawn_entity","ok":true,"duration_ms":18,"metrics":{"count":1}}

这样 Agent 可以负责规划、调用、解析和归纳，而不是在无稳定观测点的情况下承担全部真实游戏测试行为。

Released under the BSD3 License