MCDebugLauncher

A command-line Minecraft launcher designed for rapid testing, mod development, and AI agent automation. Supports all major mod loaders (Forge, NeoForge, Fabric, Quilt, OptiFine), comprehensive error diagnostics, and structured output for programmatic control.

中文文档

Features

• One-Command Launch: Install and launch any Minecraft version with any mod loader in a single command
• Multi-Loader Support: Vanilla, Forge, NeoForge, Fabric, Quilt, LegacyFabric, OptiFine
• Intelligent Diagnostics: Automatic crash report collection, log analysis, and error detection
• Agent-Friendly: JSON-structured output for AI agents and automation tools
• Developer Tools: Debug logging, performance profiling, headless mode support
• Instance Isolation: Independent instances with separate mods, configs, and Java versions
• Automatic Java Detection: Detects Java version requirements and provides upgrade instructions
• Instance Management: Mod management, configuration import/export, world backup/restore
• Enterprise-Grade: Production-ready code quality with comprehensive error handling

Quick Start

# Create and launch a Fabric instance
mdl create my-instance --mc-version 1.21.1 --loader fabric
mdl launch my-instance

# Manage mods
mdl mod list my-instance
mdl mod install my-instance fabric-api-0.92.0.jar

# Backup and restore worlds
mdl backup create my-instance world1
mdl backup list my-instance
mdl backup restore my-instance world1_20260727_120000

# View logs and diagnostics
mdl logs my-instance --follow
mdl diagnose my-instance --analyze

Agent API

MCDebugLauncher includes a built-in HTTP/WebSocket server for programmatic control by AI agents and automation tools.

# Start the agent server
mdl agent --port 8080

REST API:

# Get server status
curl http://localhost:8080/api/v1/status

# Execute commands
curl -X POST http://localhost:8080/api/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"command":"list","args":[],"options":{}}'

WebSocket Events:

import asyncio
import websockets

async def listen():
    async with websockets.connect("ws://localhost:8080/api/v1/events") as ws:
        async for message in ws:
            event = json.loads(message)
            print(f"[{event['type']}] {event.get('message', '')}")

See docs/specification.md for complete API documentation.

Documentation

• Specification - Complete CLI and API reference
• Research Document - Technical analysis and architecture decisions

Contributing

Contributions are welcome! Please read our contribution guidelines before submitting pull requests. LINUX.DO Community

Acknowledgments

This project was developed with assistance from AI (Claude). Technical research and implementation guidance were provided through human-AI collaboration.

The following open-source projects served as inspiration and technical references:

• PrismLauncher - Modern Minecraft launcher
• PortableMC - CLI launcher design patterns
• HeadlessMC - Headless testing infrastructure
• MC-CLI - Agent control interfaces

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.