Minecraft Ops MCP

Сервис MCP stdio для управления и эксплуатации серверов Minecraft. Текущая версия реализована на базе официального MCP Python SDK и поддерживает следующие бэкенды:

• MCSManager API: жизненный цикл экземпляров, логи, управление файлами, консольные команды.

• RCON: резервный вариант для традиционных консольных команд.

• Minecraft Server Management Protocol (MSMP): протокол управления JSON-RPC over WebSocket для Minecraft Java 1.21.9+.

Документация

• Руководство пользователя: 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

Запуск

Рекомендуется установить зависимости проекта в текущем окружении Python перед запуском:

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

При разработке и отладке можно также явно указать PYTHONPATH:

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

Разработка и тестирование

Модульное тестирование:

cd /home/damoc/codes/minecraft-ops-mcp
PYTHONPATH=src python3 -B -m unittest discover -s tests

Проверка синтаксиса:

python3 -m compileall -q src scripts

Протокольные интеграционные зонды см. в docs/TEST_REPORT_2026-04-14.md и docs/RELEASE_CHECKLIST.md.

Пример конфигурации 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",
        "RCON_HOST": "127.0.0.1",
        "RCON_PORT": "25575",
        "RCON_PASSWORD": "replace-me",
        "MSMP_URL": "ws://127.0.0.1:25585",
        "MSMP_SECRET": "replace-me",
        "MINECRAFT_OPS_RAW_COMMAND_ALLOWLIST": "list,time,help",
        "MINECRAFT_OPS_RAW_COMMAND_DENYLIST": "stop,op,deop,ban,ban-ip"
      }
    }
  }
}

Также можно обратиться к .env.example и добавить переменные в конфигурацию вашего MCP-клиента. Сам сервис не считывает файл .env автоматически, чтобы избежать неявных источников конфигурации во время выполнения.

Основные инструменты

MCSManager:

• server.list_daemons

• server.get_daemon_system

• server.list_instances

• server.get_instance

• server.start

• server.stop

• server.restart

• server.kill

• server.send_command

• server.get_logs

• instance.create

• instance.update_config

• instance.update_config_patch

• instance.clone_from_template

• instance.delete

• instance.reinstall

• instance.run_update_task

• file.list

• file.read

• file.download_prepare

• file.download_local

• file.upload_prepare

• file.upload_local

• file.upload_url

• file.write

• file.write_new

• file.delete

• file.move

• file.copy

• file.mkdir

• file.touch

• file.compress

• file.uncompress

Универсальные инструменты для разных бэкендов:

• server.save_world: приоритет MSMP, затем RCON, затем MCSManager.

• server.broadcast: приоритет MSMP, затем RCON, затем MCSManager.

RCON:

• rcon.command

• rcon.list_players

• rcon.time_query

• rcon.save_all

MSMP:

• msmp.discover

• msmp.call

• msmp.players.list

• msmp.players.kick

• msmp.server.status

• msmp.server.save

• msmp.server.stop

• msmp.bans.get

• msmp.bans.add

• msmp.bans.remove

• msmp.bans.set

• msmp.bans.clear

• msmp.ip_bans.get

• msmp.ip_bans.add

• msmp.ip_bans.remove

• msmp.ip_bans.set

• msmp.ip_bans.clear

• msmp.allowlist.get

• msmp.allowlist.add

• msmp.allowlist.remove

• msmp.allowlist.set

• msmp.allowlist.clear

• msmp.operators.get

• msmp.operators.add

• msmp.operators.remove

• msmp.operators.set

• msmp.operators.clear

• msmp.gamerules.get

• msmp.gamerules.update

• msmp.server_settings.get

• msmp.server_settings.list

• msmp.server_settings.set

Политика безопасности

Операции с высоким уровнем риска требуют явных параметров:

{ "confirm": true }

Если вы хотите, чтобы агент сначала объяснил, что он собирается сделать, передайте:

{ "dry_run": true }

К инструментам с высоким уровнем риска относятся: запуск/остановка/перезагрузка/завершение экземпляра, выполнение произвольных команд, запись/удаление/перемещение/сжатие/распаковка/загрузка файлов, скачивание на хост MCP, исключение игроков, блокировка, изменение белого списка/OP/игровых правил/настроек сервера и т.д. Все вызовы инструментов записываются в журнал аудита, расположение по умолчанию:

/tmp/minecraft-ops-mcp-audit.jsonl

Его можно отключить, установив MINECRAFT_OPS_AUDIT_LOG= в пустое значение.

Для произвольных команд можно дополнительно ограничить использование с помощью префиксного списка разрешенных/запрещенных команд:

MINECRAFT_OPS_RAW_COMMAND_ALLOWLIST=list,time,help
MINECRAFT_OPS_RAW_COMMAND_DENYLIST=stop,op,deop,ban,ban-ip

Рекомендации по бэкендам

• Жизненный цикл экземпляров, логи и управление файлами: используйте преимущественно MCSManager API.

• Игроки, белый список, OP, игровые правила, настройки сервера: используйте преимущественно MSMP.

• Для старых версий сервера или возможностей, не покрываемых MSMP: используйте RCON или необработанные команды MCSManager.

Не выставляйте RCON, MSMP и API-ключи MCSManager в публичную сеть. MSMP/RCON лучше всего слушать только на localhost, через VPN или туннели; для MCSManager рекомендуется использовать API-ключ с низкими привилегиями.

Описание параметров MSMP

msmp.call передает JSON-RPC params «как есть», что подходит для новых методов с существенными различиями в версиях сервера:

{
  "method": "minecraft:server/status",
  "read_only": true
}

Для операций записи используйте confirm=true или сначала dry_run=true. read_only=true пропускает подтверждение только для методов MSMP, находящихся в белом списке «только для чтения», таких как rpc.discover, minecraft:players, minecraft:server/status, запросы списков и чтение настроек сервера.