Minecraft Ops

minecraft-ops-mcp 是面向 Minecraft 服务器管理和运维的 MCP 服务，支持 stdio、旧版 HTTP+SSE 和当前 Streamable HTTP。它以 MCSManager 作为主控制面，并提供：

• 通过 MCSManager 管理实例生命周期、日志、文件、上传和下载；
• 通过按实例解析的 RCON 执行老版本或命令型运维操作；
• 通过按实例解析的 MSMP 管理 Minecraft Java 1.21.9+；
• 为整合包开发提供 jar 元数据、modlist 快照、应用/回滚和测试记录。

当前后端模型

MCP 客户端只配置 MCSManager。RCON 和 MSMP 是实例级配置：

• RCON 从目标实例的 MCSManager 配置读取：enableRcon、rconIp、rconPort、rconPassword。
• MSMP 从目标实例的 server.properties 读取：management-server-*。

工具调用通过 daemonId 和 uuid 选择目标实例。同一个 MCP 进程可以管理多个服务器，因为 RCON/MSMP 连接在每次调用时动态解析，而不是从客户端环境变量读取固定 endpoint。

安装运行

cd /home/damoc/codes/minecraft-ops-mcp
python3 -m pip install -e .
minecraft-ops-mcp

默认使用 stdio transport。开发调试：

cd /home/damoc/codes/minecraft-ops-mcp
PYTHONPATH=src python3 -m minecraft_ops_mcp

HTTP 远程访问：

# 旧版 HTTP+SSE transport，兼容 MCP 2024-11-05 客户端
MINECRAFT_OPS_MCP_BEARER_TOKEN=replace-with-long-random-token \
PYTHONPATH=src python3 -m minecraft_ops_mcp \
  --transport sse \
  --host 0.0.0.0 \
  --port 8000 \
  --allowed-host mcsm-host.example:8000

# 当前 MCP 标准推荐的 Streamable HTTP transport，适合支持 --url 的客户端
MINECRAFT_OPS_MCP_BEARER_TOKEN=replace-with-long-random-token \
PYTHONPATH=src python3 -m minecraft_ops_mcp \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 8000 \
  --allowed-host mcsm-host.example:8000

端点默认值：

• SSE：GET /sse，客户端随后向 /messages/?session_id=... POST。
• Streamable HTTP：/mcp。
• 健康检查：/health。

本地 Codex 注册远程 Streamable HTTP MCP：

codex mcp add minecraft-ops --url http://mcsm-host.example:8000/mcp

如果 HTTP MCP 设置了 bearer token，本地 Codex 也需要能读取同名环境变量：

export MINECRAFT_OPS_MCP_BEARER_TOKEN=replace-with-long-random-token
codex mcp add minecraft-ops --url http://mcsm-host.example:8000/mcp --bearer-token-env-var MINECRAFT_OPS_MCP_BEARER_TOKEN

codex mcp add --url 只注册客户端配置，不会启动远程服务。HTTP 模式需要在 MCP 所在主机用 systemd、tmux、容器或进程管理器保持服务运行。

HTTP transport 默认启用 Host/Origin 校验。绑定非本机地址时还默认要求 MINECRAFT_OPS_MCP_BEARER_TOKEN，除非显式设置 MINECRAFT_OPS_MCP_ALLOW_UNAUTHENTICATED_HTTP=true。反向代理或公网域名部署时必须设置 --allowed-host 或 MINECRAFT_OPS_MCP_ALLOWED_HOSTS，浏览器客户端还需要设置 --allowed-origin 或 MINECRAFT_OPS_MCP_ALLOWED_ORIGINS。

快速配置 Codex

仓库提供了快速配置脚本，会安装 minecraft-ops-runbook skill，并通过 codex mcp add 注册 MCP server：

cd /home/damoc/codes/minecraft-ops-mcp
MCSM_BASE_URL=http://your-mcsm-host:23333 \
MCSM_API_KEY=replace-me \
MCSM_DEFAULT_DAEMON_ID=replace-me \
MCSM_DEFAULT_INSTANCE_UUID=replace-me \
scripts/quick_setup.py --write --replace

脚本默认把敏感配置写入 $CODEX_HOME/minecraft-ops-mcp.env，权限为 0600，并生成 $CODEX_HOME/bin/minecraft-ops-mcp-launch 作为 MCP 启动器。Codex config 中只保存启动器路径，不直接保存 API key。

只预览不写入：

scripts/quick_setup.py

生成通用 MCP JSON 片段：

scripts/quick_setup.py --print-json

生成 Streamable HTTP 客户端片段：

scripts/quick_setup.py --mcp-transport streamable-http --print-json

MCP 客户端配置

最小示例：

{
  "mcpServers": {
    "minecraft-ops": {
      "command": "python3",
      "args": ["-m", "minecraft_ops_mcp"],
      "cwd": "/home/damoc/codes/minecraft-ops-mcp",
      "env": {
        "PYTHONPATH": "src",
        "MCSM_BASE_URL": "http://127.0.0.1:23333",
        "MCSM_API_KEY": "replace-me",
        "MCSM_DEFAULT_DAEMON_ID": "replace-me",
        "MCSM_DEFAULT_INSTANCE_UUID": "replace-me",
        "MINECRAFT_OPS_AUDIT_LOG": "/tmp/minecraft-ops-mcp-audit.jsonl"
      }
    }
  }
}

生产建议配置安全边界：

MINECRAFT_OPS_RAW_COMMAND_ALLOWLIST=list,time,help
MINECRAFT_OPS_RAW_COMMAND_DENYLIST=stop,op,deop,ban,ban-ip
MINECRAFT_OPS_MAX_BYTES=268435456
MINECRAFT_OPS_UPLOAD_ALLOWED_DIRS=/tmp/minecraft-ops-mcp-downloads,/srv/minecraft-staging
MINECRAFT_OPS_FILE_OPERATION_WHITELIST=server.properties,config,mods,logs,crash-reports
MINECRAFT_OPS_UPLOAD_URL_ALLOWED_DOMAINS=example.com,cdn.example.com
MINECRAFT_OPS_MODPACK_WORKSPACE=/srv/minecraft-ops/modpack-workspace

可选协议默认值：

MINECRAFT_OPS_RCON_TIMEOUT_SECONDS=5
MINECRAFT_OPS_RCON_ENCODING=utf-8
MINECRAFT_OPS_MSMP_TIMEOUT_SECONDS=8
MINECRAFT_OPS_MSMP_TLS_VERIFY=true

可选 MCP transport 变量：

MINECRAFT_OPS_MCP_TRANSPORT=stdio
MINECRAFT_OPS_MCP_HOST=127.0.0.1
MINECRAFT_OPS_MCP_PORT=8000
MINECRAFT_OPS_MCP_ALLOWED_HOSTS=mcsm-host.example:8000
MINECRAFT_OPS_MCP_ALLOWED_ORIGINS=https://agent.example
MINECRAFT_OPS_MCP_BEARER_TOKEN=replace-with-long-random-token

完整变量见 .env.example。

工具分组

• server.*：实例状态、生命周期、日志、保存、广播、控制台命令。
• instance.*：创建、更新、patch、克隆、删除、重装、更新任务。
• file.*：列目录、读写、创建、上传、下载、复制、移动、压缩。
• rcon.*：RCON 配置读写、安全封装和原始 RCON 命令。
• msmp.*：MSMP 配置读写、状态、玩家、封禁、白名单、OP、gamerule、server settings、原始 JSON-RPC。
• modpack.*：jar 检查、modlist 快照、diff、应用/回滚、启动分类、测试记录。

高风险工具需要 dry_run=true 或 confirm=true。原始命令还会受到 allowlist/denylist 策略约束。

常见流程

健康检查：

1. server.get_instance
2. server.get_logs
3. msmp.config.get，启用后调用 msmp.server.status / msmp.players.list
4. rcon.config.get，需要时调用 rcon.list_players / rcon.time_query

启用或修改 RCON：

1. rcon.config.get
2. rcon.config.set {"dry_run": true, ...}
3. rcon.config.set {"confirm": true, ...}
4. 如需加载新配置，重启实例
5. 用 rcon.list_players 验证

启用或修改 MSMP：

1. msmp.config.get
2. msmp.config.set {"dry_run": true, ...}
3. msmp.config.set {"confirm": true, ...}
4. 如需加载新配置，重启实例
5. 用 msmp.discover 或 msmp.server.status 验证

整合包兼容测试：

1. modpack.snapshot_modlist
2. agent 外部检索候选版本资料
3. modpack.apply_modlist {"dry_run": true}
4. modpack.apply_modlist {"confirm": true}
5. 启动测试服并读日志
6. modpack.classify_startup_result
7. modpack.record_test_run
8. 必要时 modpack.rollback_snapshot

测试

本地检查：

PYTHONPATH=src python3 -B -m unittest discover -s tests
python3 -m compileall -q src scripts

真实后端探针需要可丢弃的 MCSManager/Minecraft 测试环境：

python3 -B scripts/mcp_integration_probe.py > /tmp/minecraft-ops-mcp-probe-report.json
python3 -B scripts/msmp_temp_instance_probe.py > /tmp/minecraft-ops-mcp-msmp-probe-report.json
python3 -B scripts/multi_server_backend_probe.py > /tmp/minecraft-ops-mcp-multi-probe-report.json

多服务器探针会创建两个临时实例，验证同一个 MCP 进程可以按 daemonId 和 uuid 动态连接不同的 RCON/MSMP endpoint。

文档

• 用户手册：docs/USER_MANUAL.md
• 开发者手册：docs/DEVELOPER_GUIDE.md
• 当前不足与路线：docs/LIMITATIONS.md
• 测试报告：docs/TEST_REPORT_2026-04-14.md
• 发布清单：docs/RELEASE_CHECKLIST.md
• 安全说明：SECURITY.md
• 变更日志：CHANGELOG.md

建议与 minecraft-ops-runbook skill 配合使用。