# CoCo 3 MCP Bridge

An MCP server that runs a Color Computer 3 in MAME so an AI assistant can type BASIC, mount disks, take screen snapshots, and peek/poke at memory.  


- Screenshots are at the bottom of this README.

## OS Information

- This version is for Windows 10 or newer.
- It can be easily adapted for Linux, MacOS, BSD.

## Requirements

- [Node.js](https://nodejs.org/) 20 or newer
- [MAME](https://www.mamedev.org/) with CoCo 3 ROMs
- [ToolShed](https://github.com/nitros9project/toolshed) `decb` (only if you want to build disk images)

## Public Release / Setup

This repository does not bundle MAME, CoCo 3 ROMs, or ToolShed binaries due to licensing and copyright restrictions. Users must install these dependencies locally:

- **MAME & CoCo 3 ROMs**: Download [MAME](https://www.mamedev.org/) and supply your own legal CoCo 3 ROMs (e.g., `coco3.zip`). You can place `mame.exe` and `roms/` directly in the project's `mame/` directory (see [mame/README.md](mame/README.md)), or point to an existing MAME installation on your system.
- **ToolShed (**`decb`**)**: ToolShed is required if you want to build disk images with `coco_build_disk`. Download or compile [ToolShed](https://github.com/nitros9project/toolshed) and place `decb.exe` in the `toolshed/` directory (see [toolshed/README.md](toolshed/README.md)), or configure `DECB_PATH` in `.env`.

For CoCo ROMs, software, and documentation, visit the [Color Computer Archive](https://colorcomputerarchive.com/).

## Setup

```bash
cd MCP
cp .env.example .env
```

Edit `.env` so `MAME_PATH`, `MAME_ROMPATH`, and `DECB_PATH` point at your local installs.

```bash
npm install
npm run build
```



## Run

Point your MCP client at `MCP/dist/index.js` (working directory: the repo root, or `MCP` if you adjust the path). Then use the `coco_start` tool to launch MAME — don’t start MAME separately.

`coco_start` turns on real lowercase by default (runs `WIDTH 40`; pass `trueLowercase: false` to skip).

## Files

```text
MCP/storage/disks/       disk images (.dsk)
MCP/storage/host/bas/    BASIC sources on the PC
MCP/storage/host/bin/    .BIN files
MCP/storage/host/data/   other host files
```

Mount with a path like `storage/disks/game.dsk`. See `MCP/storage/README.md`.

## Screenshots

![screenshot](media/shot1.png)

![screenshot](media/shot2.png)

![screenshot](media/shot3.png)

![screenshot](media/shot4.png)


## Disclosure

Agentic AI was used in the development of this app.

## License

[MIT](LICENSE)