C6
AI & MLMediaAPI Integration

C64 Bridge MCP Server REST API Control

Control C64 hardware via MCP server with REST API—create BASIC/assembly, inspect memory in real time, synthesize SID audio, and access retro computing RAG.

View on GitHub

Overview

The C64 Bridge MCP Server exposes a RESTful control surface to interact with Commodore 64 hardware and emulation targets using the Model Context Protocol (MCP). It lets developers create and run BASIC or 6502 assembly programs, inspect and modify memory in real time, synthesize SID audio, and surface retro-computing artifacts through a retrieval-augmented generation (RAG) interface. The server is designed to integrate with AI tooling and developer workflows, enabling program generation, live debugging, and media synthesis from simple HTTP calls.

Because it speaks MCP and provides a REST API (plus optional WebSocket feeds), the server is useful both for automation and for interactive tooling: feed an LLM a device snapshot, ask for a patch in assembly, push the patch to the hardware, and stream memory updates back to your tooling for verification. The RAG layer exposes indexed retro computing documents and cartridge/program archives to support context-aware assistance.

Features

  • REST API for program creation, execution, and memory inspection
  • Create BASIC or 6502 assembly programs remotely and run them on a target
  • Read and write memory (peek/poke) with sub-second latency
  • SID audio synthesis endpoint to render audio from SID data or assembled code
  • RAG interface to query retro computing knowledge, manuals, and program archives
  • WebSocket/events feed for real-time memory and status updates
  • Docker-ready image and lightweight configuration via environment variables

Installation / Configuration

Quick start using Docker (recommended):

# Pull and run the container, exposing the default API port 8080
docker run -d --name c64bridge \
  -p 8080:8080 \
  -e MCP_TARGET=serial:/dev/ttyUSB0 \
  -e RAG_INDEX_PATH=/data/rag-index \
  chrisgleissner/c64bridge:latest

Build and run from source (generic workflow):

git clone https://github.com/chrisgleissner/c64bridge.git
cd c64bridge
# follow the repository-specific build instructions (e.g. make, go build, or npm install)
make build
./c64bridge --config ./config.yaml

Example environment variables in config.yaml or as env vars:

server:
  port: 8080

mcp:
  target: "serial:/dev/ttyUSB0"   # or "tcp:192.168.0.50:9999" or "emu:vice"

rag:
  index_path: "/data/rag-index"
  max_results: 5

sid:
  engine: "internal" # or "external-service"

Available Resources

Key HTTP endpoints (examples; adjust prefix /api depending on deployment):

MethodPathDescription
GET/healthHealth & status
GET/mcp/statusDevice/emulator status
POST/mcp/programsCreate & upload BASIC/assembly program
POST/mcp/programs/{id}/runRun a previously uploaded program
GET/mcp/memory?addr={}&len={}Read memory (peek)
POST/mcp/memoryWrite memory (poke) with JSON body
POST/mcp/sid/synthesizeSynthesize SID audio (returns audio/wav)
POST/mcp/rag/queryRAG query (returns contextual answer + sources)
WS/ws/eventsReal-time events: memory updates, logs

Web UI and event streaming: When enabled, the server may serve a small web UI for manual control and open a WebSocket endpoint for live updates.

Use Cases

  1. Generate and run a BASIC demo from an LLM:

    • POST source code (language: “basic”) to /mcp/programs.
    • Run it with POST /mcp/programs/{id}/run.
    • Stream output via /ws/events or read memory/IO to capture printed text.

  2. Patch a routine in ROM using assembly:

    • Ask an assistant to produce a 6502 patch given a memory map.
    • Upload the assembled bytes to /mcp/memory (POST with addr and data).
    • Verify by GET /mcp/memory?addr=XXXX&len=YY and by running targeted code.

  3. Synthesize SID audio from a SID file or raw program:

    • POST to /mcp/sid/synthesize with content-type application/octet-stream (SID file) or JSON {programId: “…”}.
    • Receive audio/wav for playback or inclusion in a media pipeline.

  4. Retro-computing RAG for context-aware code generation:

    • Query /mcp/rag/query with a question and optional device snapshot.
    • Receive an answer bolstered by primary sources (manual pages, program listings) to reduce hallucination when generating patches or instructions.

Example cURL: assemble and poke memory

# Upload an assembly blob
curl -X POST http://localhost:8080/mcp/programs \
  -H "Content-Type: application/json" \
  -d '{"language":"6502","code":"LDA #$01\nSTA $D020","name":"set-border","autoRun":false}' \
  | jq .

# Write bytes directly to RAM
curl -X POST http://localhost:8080/mcp/memory \
  -H "Content-Type: application/json" \
  -d '{"addr":"0x0400","data":[0xA9,0x01,0x8D,0x20,0xD0]}' \
  | jq .

For developers new to the tool: start with the health and status endpoints, use the programs endpoint to push simple BASIC code, and experiment with memory peek/poke before enabling automated RAG workflows or integrating audio synthesis into pipelines.

Resources

  • GitHub: https://github.com/chrisgleissner/c64bridge
  • Look at the repository README for repo-specific build commands, supported MCP transports, and full API schema.
Tags:ai-mlapi-integrationmedia