🎮 qwen-idea-mcp

MCP-сервер для AI-разработки Minecraft-модов через IntelliJ IDEA

Позволяет ИИ-ассистенту (Qwen, Claude, GPT, Cherry Studio, Cline и др.) полноценно работать с проектом мода: читать и редактировать код, запускать сборку и Minecraft-клиент, анализировать логи и краш-репорты, делать скриншоты игры и управлять окнами — всё это через единый MCP-протокол.

Разработан в процессе вайбкодинга мода Sculk Echo с помощью Qwen AI.

✨ Возможности

📁 Файловая система (6 инструментов)

• Чтение, создание, удаление файлов с автоматическими бэкапами

• Точечное патчинг кода (search & replace с проверками: не нашёл / неоднозначно)

• Поиск по коду (grep с regex)

• Защита от случайной правки служебных директорий (.gradle, .idea, build, run, gradlew*)

🔨 Сборка и запуск (4 инструмента)

• Запуск Gradle-задач (build, compileJava, runClient и др.)

• Фоновый запуск Minecraft-клиента с логированием вывода в файл

• Мониторинг статуса запущенного клиента

• Корректная остановка процесса (вместе с деревом дочерних)

📊 Логи и отладка (1 инструмент, 4 источника)

• Чтение latest.log, debug.log, свежих краш-репортов, логов фонового запуска

• Фильтрация по regex (ERROR|Exception|Missing)

• Режимы tail/head (краш-репорты с головы)

🖥️ GUI-автоматизация (9 инструментов)

• Скриншоты окон Minecraft, IDEA и всего экрана

• Управление окнами (фокус, разворачивание, список)

• Нажатие клавиш и комбинаций (f3, ctrl+s, enter)

• Клики по координатам, ввод ASCII-текста, паузы

👀 Наблюдение и интеграция (3 инструмента)

• show_in_idea — открыть файл в запущенной IDEA (человек видит правки вживую)

• recent_activity — журнал вызовов сервера (кто, что и когда вызвал)

• project_brief — динамическое досье проекта (загрузчик, modId, пакеты)

🧪 Анализ модов (2 инструмента)

• probe_mod — определение формата мода (NeoForge/Forge/Fabric/Quilt, modId, версии)

• ping — проверка связи + состояние конфигурации

⚙️ Настройка (1 инструмент)

• configure(project_root=...) — первый запуск через чат, без ручного редактирования конфигов

Related MCP server: Minecraft Dev MCP

🚀 Быстрый старт

1. Установка

git clone https://github.com/VladMineModDev/qwen-idea-mcp.git
cd qwen-idea-mcp
python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux / macOS
source .venv/bin/activate

pip install -r requirements.txt

2. Запуск демона

python server.py sse

Сервер запустится на http://127.0.0.1:8765. Не закрывайте это окно — это серверная комната.

3. Подключение к MCP-клиенту

Вариант A: SSE (рекомендуется)

В настройках клиента добавьте SSE-сервер:

• URL: http://127.0.0.1:8765/sse

Пример JSON-конфига (Cherry Studio, Qwen Desktop):

{
  "mcpServers": {
    "qwen-idea": {
      "type": "sse",
      "url": "http://127.0.0.1:8765/sse"
    }
  }
}

Вариант B: stdio через uvx (если клиент не умеет SSE)

{
  "mcpServers": {
    "qwen-idea": {
      "command": "uvx",
      "args": [
        "--from", "mcp[cli]<2",
        "mcp", "run",
        "C:\\path\\to\\qwen-idea-mcp\\server.py"
      ]
    }
  }
}

🎯 Quickstart для мододела (3 минуты)

1. Запустите демон (python server.py sse) и подключите MCP-клиент (URL: http://127.0.0.1:8765/sse)

2. В первом сообщении скажите ИИ:

   Настрой MCP, путь к проекту мода: C:\path\to\your\mod

3. ИИ вызовет configure(), затем project_brief() и начнёт работать:

   • Читать код и ресурсы мода

   • Делать точечные правки через patch_file

   • Запускать сборку и Minecraft

   • Анализировать логи и краши

   • Делать скриншоты окна игры

Примеры запросов:

• «Прочитай главный класс мода и расскажи, что он делает»

• «Запусти runClient и проверь логи на ошибки»

• «Сделай скриншот окна Minecraft»

• «Найди все файлы, где упоминается MyItem»

• «Почини ошибку компиляции, которую показывает run_gradle compileJava»

ИИ работает автономно, вы наблюдаете через IDEA (файлы синхронизируются с диском автоматически) или через show_in_idea (ИИ открывает правленные файлы прямо в редакторе).

⚙️ Конфигурация

mod_config.json

Скопируйте mod_config.example.json в mod_config.json и отредактируйте:

{
  "loader": "neoforge",
  "project_root": "C:\\path\\to\\your\\mod",
  "java_home": "",
  "idea_path": "",
  "host": "127.0.0.1",
  "port": 8765,
  "logs": {
    "client_latest": "run/client/logs/latest.log",
    "client_debug": "run/client/logs/debug.log",
    "crash_dirs": ["run/client/crash-reports", "run/crash-reports"]
  }
}

Поля:

Автодетект: если java_home или idea_path пустые, сервер сам найдёт их в стандартных местах (~/.gradle/jdks, C:\Program Files\JetBrains, JetBrains Toolbox).

🛠️ Каталог инструментов (26)

🔄 Типичные циклы

Цикл правки кода

grep / read_file → patch_file (фрагмент ТОЧНО из read_file) →
run_gradle("compileJava") до exit=0 → show_in_idea(правленный файл) →
stop_client() → run_gradle("runClient", background=True) →
wait(45) → get_logs(source="run", filter_regex="ERROR|Exception")

Разбор краша

get_logs(source="crash", mode="head", lines=120) → стектрейс →
grep / read_file → цикл правки кода

Визуальная проверка

client_status → focus_window("Minecraft") →
screenshot(save_path=...) → press_key / type_text / click_at →
stop_client()

⚠️ Жёсткие правила

• runClient только с background=True (иначе блокировка до таймаута)

• Перед новым runClient всегда вызывайте stop_client()

• Перед patch_file всегда делайте read_file — фрагмент должен совпадать с исходником посимвольно (включая отступы)

• Краш-репорты читайте с mode="head" (стектрейс в начале файла)

• Изменения Java-кода требуют compileJava до runClient

• Изменения ресурсов (текстуры / JSON / lang) требуют только перезапуска клиента

• mod_config.json нельзя править через write_file — только через configure()

• Перед крупным рефакторингом просите человека сделать git commit (бэкапы есть в backups/, но git надёжнее)

🐛 Troubleshooting

📂 Структура проекта

qwen-idea-mcp/
├── server.py                       # Основной сервер (26 инструментов)
├── requirements.txt                # Зависимости
├── README.md                       # Эта документация
├── INSTRUCTIONS_FOR_AI.md          # Инструкции для ИИ (v2)
├── mod_config.example.json         # Шаблон конфигурации (публичный)
├── mod_config.json                 # Локальная конфигурация (git-ignored)
├── test_all_tools.py               # Автотест всех 26 инструментов
├── backups/                        # Бэкапы файлов до правок (git-ignored)
├── logs/                           # Выводы gradle/runClient (git-ignored)
├── state.json                      # PID фонового клиента (git-ignored)
└── server_debug.log                # Чёрный ящик вызовов (git-ignored)

🧪 Автотест

# В одном окне — демон
python server.py sse

# В другом — автотест
python test_all_tools.py

Тест обходит Qwen-клиент и подключается к SSE-демону напрямую через библиотеку mcp. Проверяет все 26 инструментов, пишет результат в консоль и server_debug.log.

Ожидаемый результат v1.5: все 26 ✅, ни одного EXC в логе.

🗺️ Дорожная карта

Актуальные задачи — в Issues:

• Fabric loader support — отдельный mod_config.fabric.example.json, правки run_gradle и get_logs по полю loader

• Forge (legacy) support — поддержка Forge 1.20.1 и ниже

• Linux / macOS — заменить tasklist/taskkill на psutil, кроссплатформенный автодетект

• ModRun кирпич 2: resolve_environment — автоматическое скачивание нужной версии клиента и загрузчика через Mojang piston-meta и Fabric meta API

• ModRun кирпич 3: provision_instance — чистый тестовый инстанс для любого jar-мода

• ModRun кирпич 4: launch_mod — единый запуск мода независимо от его загрузчика

• IntelliJ plugin bridge — плагин IntelliJ Platform с REST/API-мостом (подсветка правок, инспекции, run-конфигурации из MCP)

• Research: true universal loader — обёртка над Sinytra Connector / Patchwork для запуска Fabric-модов внутри NeoForge и наоборот

🤝 Contributing

Pull requests приветствуются! Перед крупным PR:

1. Убедитесь, что python test_all_tools.py проходит полностью (26 ✅)

2. В server_debug.log нет EXC

3. Новые инструменты добавляйте с декоратором @traced и @mcp.tool()

4. Обновите этот README и INSTRUCTIONS_FOR_AI.md

Архитектурные принципы

• Никаких личных путей в коде — всё через mod_config.json и автодетект

• Бэкапы автоматические — каждая правка сохраняется в backups/

• Чёрный ящик — каждый вызов логируется в server_debug.log (START / END / EXC)

• Динамическое досье — специфика проекта получается через project_brief(), не хардкодится в инструкциях

📄 License

MIT License — используйте как хотите. Подробности в файле LICENSE.

🙏 Acknowledgments

• Model Context Protocol — протокол, на котором всё работает

• FastMCP — удобный Python-SDK

• pyautogui / mss / pygetwindow — GUI-автоматизация

• NeoForge / Fabric — загрузчики модов

• Qwen AI — за совместную разработку в процессе вайбкодинга мода Sculk Echo

Made with ❤️ for Minecraft modders

Если вам понравился проект — поставьте ⭐ на GitHub. Это помогает другим мододелам найти инструмент.