# C64UltimateMcpServer

> C64 Ultimate MCP Server

- **Type:** MCP server
- **Install:** `agentstack add mcp-ch0mik-c64ultimatemcpserver`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ch0mik](https://agentstack.voostack.com/s/ch0mik)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ch0mik](https://github.com/ch0mik)
- **Source:** https://github.com/ch0mik/C64UltimateMcpServer

## Install

```sh
agentstack add mcp-ch0mik-c64ultimatemcpserver
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# C64 Ultimate MCP Server

**English** | [**Polski**](#-c64-ultimate-mcp-server-polski)

> ⚙️ **This project was built 100% using AI Agent prompts** - Every line of code, configuration, and documentation was generated through conversational prompts to GitHub Copilot Agent.

Comprehensive **Model Context Protocol (MCP)** server for the **Commodore 64 Ultimate** device with **46 MCP tools**, **15 MCP prompts**, and **55 embedded documentation resources**. Built in C# with enterprise-grade architecture, type safety, and comprehensive API coverage.

**License:** MIT License (see [LICENSE](LICENSE) file)

## 🎥 Demo Video

[](https://www.youtube.com/watch?v=1q80quIIkV0?cc_load_policy=1&cc_lang_pref=en)

## ⚡ Key Features

- **Complete Ultimate 64 API Support**: 46 MCP tools covering the Ultimate REST API plus PRG generation workflows
- **MCP Prompts Support**: 15 prompt templates exposed through `prompts/list` and `prompts/get`
- **BASIC to PRG Compilation**: Real-time compilation of BASIC V2 source code to executable PRG files
- **MCP Resources**: 55 embedded documentation resources (BASIC specs, Assembly guides, examples, source catalogs, Kernal API, memory maps, graphics, sound, I/O, drive, printer, keyboard/control codes, disassembly)
- **Separated Client Library**: Reusable `C64UltimateClient` NuGet package with clean async API
- **Clean Architecture**: Client → Service → MCP wrapper pattern with proper DI
- **Streamable HTTP Transport**: Remote multi-client support with session-aware MCP interactions
- **Streaming Support**: Video, audio, and debug streaming capabilities
- **Binary File Support**: Upload PRG files via base64, file path, or URL
- **ASP.NET Core 8.0/10.0**: Modern, high-performance web framework
- **Enterprise Configuration**: appsettings.json with environment overrides
- **Type Safety**: C# static typing with full null-safety and nullable reference types
- **Structured Logging**: Separate loggers for client and service layers
- **Production-Ready**: Zero errors/warnings, comprehensive error handling
- **Agent Integration**: Works with Continue, Copilot, Cody, Cursor, Claude Desktop

## 🧠 Embedded Knowledge Resources

The server exposes a curated MCP resource catalog under `c64://resources/index`. The resources are stored in `C64UltimateMcpServer/Resources/data` as OKF-style markdown or plain-text assets and are wired through `C64ResourceCatalog` and `C64ResourceProvider`.

Recent additions make the resource set more useful for agents writing Commodore 64 games, demos, and hardware-aware programs:

- **Source provenance**: `c64://sources/classic-c64-references` records the classic C64 books/manuals used as source material without requiring host-specific source paths.
- **Example routing**: `c64://examples/index` and `c64://examples/game-demo-patterns` route agents to embedded examples that work with the built-in PRG generators and portable game/demo pattern notes.
- **Ready-to-use assembly examples**: `c64://examples/assembly/raster-bars-demo`, `c64://examples/assembly/sprite-demo`, and `c64://examples/assembly/joystick-game-loop` provide compact, tested starting points for demos and games.
- **Generator-tested adaptations**: `c64://examples/assembly/hires-dot-burst-generator` and `c64://examples/assembly/dreadline-fastscroll-generator` preserve source ideas from upstream C64 sources/C64AIToolChain in forms that compile through `ultimate_generate_assembly_prg`.
- **Embedded reference sources**: `c64://examples/assembly/hires-fire-line-demo` and `c64://examples/assembly/hires-line-draw-library` preserve the upstream HIRES graphics demo/library inside the MCP server.
- **Practical coding references**: `c64://assembly/ml-kernal-quickstart`, `c64://memory/mapping-notes`, expanded KERNAL API notes, and improved sprite/charset guidance help agents choose safe memory locations, KERNAL calls, and VIC-II workflows.

The embedded examples are intentionally small and aligned with the built-in BASIC/assembly PRG generators. Larger C/cc65 examples are indexed as reference material until a C compiler workflow is added.

## 🚀 Quick Start

```bash
# 1. Build
dotnet build

# 2. Configure (optional, defaults to http://192.168.0.120)
export Ultimate__BaseUrl=http://your-c64-ultimate-ip:port

# 3. Run
dotnet run

# 4. Server starts on http://localhost:8080
```

## 📦 Installation

### Requirements
- **.NET 10.0 SDK** - [Download](https://dotnet.microsoft.com/download)
- **C64 Ultimate device** - On your network
- **Curl or HTTP client** - For testing
- **Docker** (optional) - [Download](https://www.docker.com/products/docker-desktop)

### Setup

```bash
git clone https://github.com/ch0mik/C64UltimateMcpServer.git
cd C64UltimateMcpServer
dotnet build
dotnet run
```

## ⚙️ Configuration

### appsettings.json
```json
{
  "Ultimate": {
    "BaseUrl": "http://192.168.0.120"
  }
}
```

### Environment Variable
```bash
Ultimate__BaseUrl=http://192.168.0.120
```

### Docker
```yaml
environment:
  - Ultimate__BaseUrl=http://192.168.0.120
```

## 🤖 Agent Integration

### Continue IDE (Recommended)

1. **Install Continue** - https://continue.dev
2. **Configure** `.continue/config.json`:
```json
{
  "models": [
    {
      "title": "Claude",
      "provider": "openai",
      "model": "claude-3-5-sonnet"
    }
  ],
  "mcp_servers": {
    "c64-ultimate": {
      "url": "http://localhost:8080"
    }
  }
}
```

3. **Use in Chat**:
```
@C64 reboot the device
@C64 load and run /games/loderunner.prg
@C64 what config categories are available?
```

### VS Code Chat (GitHub Copilot)

1. **Install** - GitHub Copilot Chat extension
2. **Configure** `.vscode/settings.json`:
```json
{
  "github.copilot.chat.mcpServers": [
    {
      "name": "C64 Ultimate",
      "type": "streamable-http",
      "url": "http://localhost:8080"
    }
  ]
}
```

3. **Use**:
```
@C64 reboot device
@C64 mount disk /games/disk1.d64
```

### Cody (Sourcegraph)

```bash
cody mcp add c64-ultimate http://localhost:8080
```

Then in Cody:
```
Ask Cody: Use C64 Ultimate MCP to reboot the device
Ask Cody: List all available config categories
```

### Cursor IDE

1. **Configure** `.cursor/mcp.json`:
```json
{
  "servers": [
    {
      "name": "C64 Ultimate",
      "type": "http",
      "url": "http://localhost:8080"
    }
  ]
}
```

2. **Use slash commands**:
```
/c64 reboot device
/c64 load program
```

## 🛠️ Tools (46 Total)

### Machine Control (5)
- **ultimate_reset_machine** - Soft reset C64 (preserves configuration)
- **ultimate_reboot_device** - Full device restart (reinitializes cartridge)
- **ultimate_pause_machine** - Pause machine execution
- **ultimate_resume_machine** - Resume machine execution
- **ultimate_power_off** - Power off C64

### Program Management (7)
- **ultimate_generate_basic_prg** - Generate PRG from BASIC source code with token conversion
- **ultimate_generate_assembly_prg** - Generate PRG from 6510 assembly source code
- **ultimate_load_program** - Load PRG program from filesystem
- **ultimate_run_program** - Load and execute PRG from disk
- **ultimate_run_prg_binary** - Execute program from binary data, URL or file
- **ultimate_run_cartridge** - Load and run cartridge
- **ultimate_menu_button** - Simulate menu button press

### Memory Management (5)
- **ultimate_read_memory** - Read C64 RAM memory contents
- **ultimate_write_memory** - Write to RAM memory
- **ultimate_write_memory_binary** - Write binary data to memory
- **ultimate_get_debug_register** - Read debug register
- **ultimate_set_debug_register** - Write to debug register

### Audio Playback (5)
- **ultimate_play_sid** - Play SID file with optional song number
- **ultimate_play_sid_binary** - Play SID from binary data, URL or file
- **ultimate_play_mod** - Play Amiga MOD file
- **ultimate_start_stream** - Start audio/video/debug stream
- **ultimate_stop_stream** - Stop active stream

### Drive Management (7)
- **ultimate_get_drives** - Get information about all disk drives
- **ultimate_mount_disk** - Mount disk image from filesystem or binary data
- **ultimate_unmount_disk** - Unmount disk image
- **ultimate_reset_drive** - Reset selected disk drive
- **ultimate_set_drive_mode** - Change drive operating mode
- **ultimate_turn_drive_on** - Power on disk drive
- **ultimate_turn_drive_off** - Power off disk drive

### Disk Creation (4)
- **ultimate_create_d64** - Create 1541 disk image (D64)
- **ultimate_create_d71** - Create 1571 disk image (D71)
- **ultimate_create_d81** - Create 1581 disk image (D81)
- **ultimate_create_dnp** - Create Native Partition disk image (DNP)

### ROM Management (1)
- **ultimate_load_drive_rom** - Load custom ROM to disk drive

### File Management (1)
- **ultimate_get_file_info** - Get file information

### Configuration Management (8)
- **ultimate_get_config_categories** - Get list of available configuration categories
- **ultimate_get_config_category** - Get all settings in a category
- **ultimate_get_config_item** - Get single configuration value
- **ultimate_set_config_item** - Set configuration value
- **ultimate_bulk_config_update** - Update multiple settings at once
- **ultimate_save_config** - Save current configuration to flash
- **ultimate_load_config** - Load configuration from flash
- **ultimate_reset_config** - Reset configuration to defaults

### Connection Management (2)
- **ultimate_get_connection** - Get current connection settings
- **ultimate_set_connection** - Change device hostname/port

### System Information (1)
- **ultimate_version** - Get C64 Ultimate API version

## 💬 Prompts (15 Total)

- **basic-program** - BASIC program workflow prompt
- **assembly-program** - Assembly workflow prompt
- **assembly-prg-build** - Assembly-to-PRG build workflow prompt
- **sid-music** - SID composition workflow prompt
- **graphics-demo** - VIC-II graphics demo workflow prompt
- **printer-job** - Printer workflow prompt
- **memory-debug** - Memory inspection / patch workflow prompt
- **drive-manager** - Drive management workflow prompt
- **game-loop-basic** - BASIC game loop workflow prompt
- **petscii-ui-layout** - PETSCII UI layout workflow prompt
- **keyboard-input-c64** - Keyboard input workflow prompt
- **sprite-marker-workflow** - Sprite marker workflow prompt
- **sid-sfx-basic** - SID SFX workflow prompt
- **c64_basic_program_prompt** - Legacy BASIC prompt template exposed as an MCP prompt
- **c64_sid_music_prompt** - Legacy SID prompt template exposed as an MCP prompt

Important: prompts are MCP prompts, not tools.  
Use `prompts/list` and `prompts/get` for prompts, and `tools/call` only for tools.

## Summary (46 Total Tools)

- **Machine Control**: 5 tools
- **Program Management**: 7 tools
- **Memory Management**: 5 tools
- **Audio Playback**: 5 tools
- **Drive Management**: 7 tools
- **Disk Creation**: 4 tools
- **ROM Management**: 1 tool
- **File Management**: 1 tool
- **Configuration Management**: 8 tools
- **Connection Management**: 2 tools
- **System Information**: 1 tool

## 📚 Resources (55 Total)

Embedded documentation accessible via MCP Inspector at `http://localhost:8000`:

### BASIC Resources (9)
- **c64://basic/spec** - BASIC V2 Language Specification
- **c64://basic/pitfalls** - BASIC Pitfalls and Common Gotchas
- **c64://basic/examples/hello-world** - Hello World Example
- **c64://basic/examples/joystick** - Joystick Input Example
- **c64://basic/examples/bounce** - Bounce Animation Example
- **c64://basic/examples/wave** - Wave Animation Example
- **c64://basic/examples/entchen-petscii** - PETSCII example
- **c64://basic/examples/games/snake** - Snake example
- **c64://basic/examples/games/tictactoe** - Tic-tac-toe example

### Assembly Resources (5)
- **c64://assembly/spec** - 6510 Assembly Language Specification
- **c64://assembly/tooling-notes** - 6510 Assembly Tooling Notes for MCP compiler subset
- **c64://assembly/ml-kernal-quickstart** - Machine-language KERNAL quickstart
- **c64://assembly/examples/hello-sys** - Minimal SYS-start assembly example
- **c64://assembly/examples/text-scroll** - VIC-II text scroller (softscroll + hardscroll) example

### Memory Resources (5)
- **c64://memory/map** - C64 Memory Map (0x0000-0xFFFF)
- **c64://memory/kernal** - Kernal Memory Map (ROM $E000-$FFFF)
- **c64://memory/low** - Low Memory Map (0x0000-0x03FF)
- **c64://memory/mapping-notes** - Practical memory placement and banking notes
- **c64://memory/symbols** - Common memory symbols

### Graphics Resources (4)
- **c64://graphics/vic-spec** - VIC-II Chip Specification
- **c64://graphics/charset** - Character Set Reference
- **c64://graphics/petscii** - PETSCII style guide
- **c64://graphics/sprite-charset-best-practices** - Sprite/charset guidance

### Sound Resources (4)
- **c64://sound/sid-spec** - SID Chip specification
- **c64://sound/sid-programming** - SID programming guide
- **c64://sound/sid-file-structure** - SID file format documentation
- **c64://sound/sidwave** - SIDWAVE format reference

### I/O Resources (5)
- **c64://io/cia-spec** - CIA Chip specification
- **c64://io/io-spec** - I/O Port specification
- **c64://io/joystick** - Joystick reference
- **c64://io/keyboard-c64** - Keyboard matrix reference
- **c64://io/control-codes-c64** - Control code reference

### Drive Resources (1)
- **c64://drive/spec** - 1541/1571/1581 Disk Drive Specification

### Printer Resources (6)
- **c64://printer/commodore-spec** - Commodore Printer Specification
- **c64://printer/epson-spec** - Epson Printer Specification
- **c64://printer/spec** - Unified printer guide
- **c64://printer/prompts** - Printer prompt routing guide
- **c64://printer/commodore-bitmap** - Commodore bitmap printing
- **c64://printer/epson-bitmap** - Epson bitmap printing

### API Resources (2)
- **c64://api/basic-api** - BASIC callable API reference
- **c64://api/kernal-api** - Kernal callable API reference

### Example Resources (11)
- **c64://examples/index** - Example source routing index
- **c64://examples/game-demo-patterns** - Game and demo pattern notes
- **c64://examples/assembly/dreadline-fastscroll-generator** - Dreadline-derived fastscroll generator example
- **c64://examples/assembly/raster-bars-demo** - Raster bars assembly demo
- **c64://examples/assembly/sprite-demo** - Single sprite assembly demo
- **c64://examples/assembly/joystick-game-loop** - Joystick game loop assembly skeleton
- **c64://examples/assembly/hires-fire-line-demo** - HIRES fire/line demo reference
- **c64://examples/assembly/hello-world-kernal** - KERNAL hello world assembly example
- **c64://examples/assembly/hires-dot-burst-generator** - HIRES dot burst generator example
- **c64://examples/assembly/hires-line-draw-library** - HIRES line draw library reference
- **c64://examples/basic/token-control-codes** - BASIC token/control-code example

Example provenance:

| Resource | Origin | Notes |
| --- | --- | --- |
| `c64://examples/assembly/raster-bars-demo` | C64 Ultimate MCP Server | Compact generator-tested demo written for `ultimate_generate_assembly_prg`. |
| `c64://examples/assembly/sprite-demo` | C64 Ultimate MCP Server | Compact generator-tested sprite setup/movement demo. |
| `c64://examples/assembly/joystick-game-loop` | C64 Ultimate MCP Server | Compact generator-tested joystick/game-loop skeleton. |
| `c64://examples/assembly/hello-world-kernal` | upstream C64 sources | Embedded adaptation of the upstream C64 assembly hello-world example for the built-in assembly PRG generator. |
| `c64://examples/basic/token-control-codes` | upstream C64 sources | Embedded BASIC token/control-code example for the built-in BASIC PRG generator. |
| `c64://examples/assembly/hires-fire-line-demo` | upstream C64 sources | Embedded reference source for the HIRES fire/line demo; kept as reference because it uses an include-style library split. |
| `c64://examples/assembly/hires-line-draw-library` | upstream C64 sources | Embedded reference source for the HIRES line drawing and dot-stepping library. |
| `c64://examples/assembly/hires-dot-burst-generator` | upstre

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ch0mik](https://github.com/ch0mik)
- **Source:** [ch0mik/C64UltimateMcpServer](https://github.com/ch0mik/C64UltimateMcpServer)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-ch0mik-c64ultimatemcpserver
- Seller: https://agentstack.voostack.com/s/ch0mik
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.