Gearcoleco

Gearcoleco is a cross-platform ColecoVision emulator implemented in C++. It runs on Windows, macOS, Linux, BSD and can be used standalone or integrated into tooling as an executable. When using it as an MCP server, you would typically pull or build the Gearcoleco binary and run it in an environment that provides the necessary runtime libraries (such as SDL2). The emulator supports a rich feature set including accurate Z80 and TMS9918 emulation, ROM loading from command line or via drag-and-drop, save states, various controllers, and debugger tooling. To leverage these capabilities in your workflow, start the Gearcoleco binary and provide a ROM file (or use a packaged ROM image) along with any BIOS if required; you can also enable a portable mode by placing a portable.ini next to the binary. The emulator exposes debugging features like a built-in disassembler, breakpoints, a memory editor, and VRAM viewing when run in debug mode. In an MCP setup, you would interact with Gearcoleco through the same binary, with the MCP orchestrating execution, I/O, and any necessary environment configuration.

Prerequisites:

• A supported host OS (Windows, macOS, Linux, or BSD)
• Optional: Docker if you prefer containerized execution
• SDL2 and related dependencies if building from source or running without prebuilt binaries

Installation steps (recommended using Docker):

1. Ensure Docker is installed and running on your system.
2. Pull the Gearcoleco image (if available) or build from source following the project’s build instructions:
   • If an official image exists: docker pull gearcoleco/gearcoleco:latest
   • If building locally: clone the repo and follow the Build Instructions in the README for your platform.
3. Run the server container with necessary BIOS/ROM mappings as volumes if required: docker run -it --rm -v /path/to/bios:/bios -v /path/to/roms:/roms gearcoleco/gearcoleco:latest
4. If you are not using Docker, download the appropriate prebuilt binary from the Gearcoleco releases page for your platform and run it directly (see Build Instructions in the README for platform-specific steps).

Alternative: build from source (generic steps):

• Install prerequisites: a C++ compiler, SDL2, and other dependencies per your platform.
• Clone the Gearcoleco repository.
• Follow platform-specific build steps in the README (Windows: open the Visual Studio solution; macOS/Linux: run the provided make commands).
• Run the resulting binary with appropriate ROM/BIOS paths as arguments or via portable mode.

Tips and common issues:

• BIOS: Gearcoleco requires a BIOS to run. Use the original MD5 2c66f5911e5b42b8ebe113403548eee7 if possible.
• Portable mode: Create a file named portable.ini in the same directory as the binary to enable portable mode.
• Dependencies: Linux users may need SDL2 libraries installed (libsdl2) for proper rendering and input handling.
• Debugging: When running in debug mode, you can access the built-in debugger features such as a JIT disassembler, breakpoints, and memory inspectors.
• Controller support: Gearcoleco can map modern game controllers via a gamecontrollerdb.txt file located alongside the binary; ensure the file is present if you rely on gamepad input.
• If running in a container, ensure BIOS/ROM paths are mounted correctly as volumes and environment variables are set as needed (e.g., BIOS_MD5) to validate BIOS integrity.