Minecraft Diagnostic MCP

Minecraft诊断MCP

minecraft-diagnostic-mcp 是用于Minecraft环境的模型上下文协议诊断服务器。它不是Minecraft插件，它不会进入服务器 plugins/ 文件夹，并且它不在游戏服务器内运行；它与MCP客户端一起运行，并通过文件、日志、本地运行时访问或Docker运行时访问来检查服务器。

它可以从三个实际角度检查服务器：

• 从磁盘上的服务器文件进行备份分析
• 针对本地运行的Minecraft服务器的本地运行时分析
• 针对容器化Minecraft服务器的Docker运行时分析

它还可以通过以下方式暴露给MCP客户端：

• stdio 用于基于本地流程的集成
• streamable-http 用于桌面或浏览器风格的MCP连接流

它还可以在MCP服务器运行时，针对新检测到的严重运行时问题发送Discord webhook警报。

该项目设计为一个小型分层MCP核心，具有：

• 插件清单和插件检查
• 服务器配置linting
• 最近使用启动感知诊断进行日志分析
• 带有解释和建议操作的分组诊断
• AI客户端的统一快照入口点

其他项目文档：

• AGENTS.md 适用于维护人员和编码代理
• ALERTING.md 用于Discord警报行为和调整
• CONTRACT.md 用于支撑表面和稳定的响应场
• DEVELOPMENT.md 用于本地设置和工作流
• DEPLOYMENT.md VM/systemd和HTTP暴露指南
• SUPPORT.md 对于预期 1.0 支持边界
• RELEASE_CHECKLIST.md 用于预发布验证
• TODO.md 对于实际积压的工作

用例

典型用例包括：

• 启动失败后调试损坏的插件
• 检查隐藏在运行时日志噪声中的启动警告
• 在不运行服务器的情况下分析备份
• 对本地或Docker化服务器进行轻量级运行时检查
• 为MCP客户端提供结构化的诊断视图，而不仅仅是原始日志
• 通过webhook将新检测到的严重运行时问题转发给Discord

不是插件

这个项目不是Bukkit、Spigot、Paper或Purpur插件。

它不会进入服务器 plugins/ 它不会从JVM内部扩展游戏服务器。

相反，它是一个外部MCP服务器，从外部检查Minecraft服务器状态。

它支持什么

支持的执行模式：

• backup：磁盘上服务器目录的只读分析
• runtime + local 后端：直接对本地运行的服务器进行RCON和文件系统访问
• runtime + docker 后端：容器中的Docker CLI plus rcon-cli
• auto：首选运行时（如果可用），否则在可能的情况下回退到备份分析

当前MCP工具：

• 管理工具：

- rcon - list_players - help - server_stats - server_logs - check_server_status

• 诊断工具：

- list_plugins - inspect_plugin - lint_server_config - analyze_recent_logs - get_server_snapshot

安装

Python要求：

• python 3.10+

以可编辑模式安装项目：

pip install -e .

这为您提供了两个实用的切入点：

python -m minecraft_diagnostic_mcp

或

minecraft-diagnostic-mcp

对于Claude Desktop或其他MCP客户端，您还可以将它们指向已安装的控制台脚本或直接运行模块。

配置

配置是基于环境变量的。示例配置文件提供在 .env.example.

对于本地开发，将示例值复制到您的shell环境或首选的本地env加载工作流中，然后仅调整与您的模式相关的变量。

核心设置：

• MCP_TRANSPORT

- stdio - streamable-http

• MCP_HTTP_HOST
• MCP_HTTP_PORT
• MCP_HTTP_PATH
• MCP_ANALYSIS_MODE

- backup - runtime - auto

• MCP_RUNTIME_BACKEND

- docker - local

• MCP_SERVER_ROOT
• MCP_PLUGINS_DIR
• MCP_LOGS_DIR
• MCP_CONTAINER_NAME
• MCP_LOCAL_RCON_HOST
• MCP_LOCAL_RCON_PORT
• MCP_LOCAL_RCON_PASSWORD
• MCP_LOCAL_SERVER_JAR
• MCP_DISCORD_ALERTS_ENABLED
• MCP_DISCORD_WEBHOOK_URL
• MCP_DISCORD_ALERT_USERNAME
• MCP_DISCORD_ALERT_POLL_SECONDS
• MCP_DISCORD_ALERT_SCAN_LINES
• MCP_DISCORD_ALERT_MIN_PRIORITY
• MCP_DISCORD_ALERT_STATE_FILE

模式示例

备份模式：

set MCP_TRANSPORT=stdio
set MCP_ANALYSIS_MODE=backup
set MCP_SERVER_ROOT=C:\path\to\mcserver
set MCP_PLUGINS_DIR=plugins
set MCP_LOGS_DIR=logs
python -m minecraft_diagnostic_mcp

本地运行时模式：

set MCP_TRANSPORT=stdio
set MCP_ANALYSIS_MODE=runtime
set MCP_RUNTIME_BACKEND=local
set MCP_SERVER_ROOT=C:\path\to\mcserver-runtime
set MCP_PLUGINS_DIR=plugins
set MCP_LOGS_DIR=logs
set MCP_LOCAL_RCON_HOST=127.0.0.1
set MCP_LOCAL_RCON_PORT=25575
set MCP_LOCAL_RCON_PASSWORD=your-local-rcon-password
python -m minecraft_diagnostic_mcp

Docker运行时模式：

set MCP_TRANSPORT=stdio
set MCP_ANALYSIS_MODE=runtime
set MCP_RUNTIME_BACKEND=docker
set MCP_CONTAINER_NAME=mc
set MCP_SERVER_ROOT=/optional/fallback/path
python -m minecraft_diagnostic_mcp

桌面式MCP连接UI的流式HTTP模式：

set MCP_TRANSPORT=streamable-http
set MCP_HTTP_HOST=127.0.0.1
set MCP_HTTP_PORT=8000
set MCP_HTTP_PATH=/mcp
set MCP_ANALYSIS_MODE=backup
set MCP_SERVER_ROOT=C:\path\to\mcserver
python -m minecraft_diagnostic_mcp

然后使用：

• 姓名： minecraft-diagnostic-mcp
• 运输： Streamable HTTP
• 网址： http://127.0.0.1:8000/mcp

Discord webhook警报：

set MCP_DISCORD_ALERTS_ENABLED=true
set MCP_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
set MCP_DISCORD_ALERT_POLL_SECONDS=30
set MCP_DISCORD_ALERT_SCAN_LINES=400
set MCP_DISCORD_ALERT_MIN_PRIORITY=50
python -m minecraft_diagnostic_mcp

启用警报后，服务器会运行一个轻量级的后台轮询器，检查最近的诊断结果，并仅对新检测到的活动高严重性问题发送Discord警报。已解析的历史项和常规运行时噪声将被忽略。

运行流程

每种模式的推荐运行流程：

1. 设置特定于模式的环境变量。
2. 使用以下命令启动MCP服务器 python -m minecraft_diagnostic_mcp.
3. 在MCP客户端中，首先 get_server_snapshot().
4. 向下钻取：

- analyze_recent_logs() - lint_server_config() - list_plugins() - inspect_plugin("PluginName")

测试

使用以下命令运行测试套件：

python -m unittest discover -s tests -v

这些测试有意轻量级，并侧重于：

• 解析器行为
• 服务层行为
• 快照聚合
• 启动感知日志分析

它们不需要实时的Minecraft服务器或Docker守护进程。

开发者笔记

对于当地发展：

• 直接编辑环境变量或从 .env.example
• 运行测试 python -m unittest discover -s tests -v
• 使用以下命令在本地运行MCP服务器 python -m minecraft_diagnostic_mcp
• 使用 MCP_TRANSPORT=streamable-http 如果您的MCP客户端需要URL而不是本地命令

如果您正在迭代运行时行为，请首选：

• backup 夹具样式只读调试模式
• runtime + local 对于本地运行的沙盒服务器
• runtime + docker 对于真正的容器化部署目标

局限性

当前范围：

• 当前插件清单覆盖范围之外没有插件/插件生态系统
• 没有完整的事件管理工作流程
• 没有深入的字节码分析
• 无依赖图引擎
• 无自动修复或自动生成报告

运行时注意事项：

• Docker运行时模式需要Docker CLI访问和可访问的容器
• 本地运行时模式要求运行启用RCON的Minecraft服务器
• 备份模式是只读的，不提供实时播放器/运行时信息

支持矩阵

当前预期支持边界：

• backup 模式

- 状态：支持 - 期望：只读文件系统分析

• runtime + docker

- 状态：支持 - 预期：Docker CLI可用，目标容器存在，在容器中 rcon-cli 作品

• runtime + local

- 状态：当前本地进程工作流在Windows上受支持 - 预期：本地服务器进程正在运行，并且启用了RCON

• stdio

- 状态：支持

• streamable-http

- 状态：支持

降级模式行为：

• 如果缺少Docker CLI，运行时就绪输出现在会明确地显示出来
• 如果目标Docker容器丢失，就绪输出会明确指出
• 如果选择了本地后端，但找不到匹配的Java进程，就绪输出会明确表示
• 如果缺少备份输入，备份准备明确表示
• 运行时和备份准备有效载荷还携带新鲜时间戳

关于正式的支持边界和发布承诺，请参见：

• SUPPORT.md
• CONTRACT.md
• RELEASE_CHECKLIST.md

项目结构

高层布局：

src/minecraft_diagnostic_mcp/
  collectors/
  analyzers/
  parsers/
  services/
  tools/
  models/

该架构有意保持适度：

• 工具公开MCP功能
• 服务编排用例
• 从Docker、文件系统或本地运行时读取的收集器
• 解析器对原始输入进行归一化处理
• 分析器产生结构化诊断

发布范围

当前稳定版本： 1.0.0

1.0.0 包括：

• 稳定MCP工具名称
• 备份/运行时/传输模式的明确支持边界
• MCP客户端的可预测诊断有效载荷
• 实际部署和警报文档
• 来自单元测试和工作流式烟雾检查的信心

故意超出范围 1.0.0:

• 深度字节码分析
• 自动修复
• 仪表板或报告产品
• 通用Minecraft控制平面功能

预发布检查表

• 通过测试
• 记录支持边界
• 已执行发布检查表
• .env.example 当前
• README已更新
• 不 __pycache__ 在存储库中跟踪