GitHub - cliffhall/mcp-c64: An MCP server for developing BASIC and Assembly Language programs for the Commodore 64 (original) (raw)

An MCP server for developing BASIC and Assembly Language programs for the Commodore 64

Optimal C64 development stack
- Emulator: VICE
- Assembler: 64tass
- Tokenizer: petcat
REPL - A minimal command line client for interacting directly with the MCP server.
MCP Server working with the ability to:
- Assemble 6502 assembly language programs to .prg format
- Tokenize BASIC programs to .prg format
- Launch and run .prg format programs in the emulator

REQUIREMENTS

Install

Node + npm - Javascript runtime environment
- Install the latest stable Node release (comes with npm).
VICE - The Versatile Commodore Emulator
- Read the Manual
- Download binary for your platform
- Includes emulator and tokenizer/detokenizer (petcat)
64Tass - The 6502 assembler for C64
- Read the Manual
- Install
  * MacOSX - brew install tass64
  * Windows - Download the latest binary

Configure

Create .env file

Create file .env in the root of your project.
- If you have downloaded the project source, you can copy .env-example
Add / modify vars
- ASSEMBLER - pointing to the 64tass assembler executable (full path if not in PATH)
- TOKENIZER - pointing to the petcat tokenizer executable (full path if not in PATH)
- EMULATOR - pointing to the x64sc emulator executable (full path if not in PATH)
- ASM_PATH - pointing to your assembly source folder
- BASIC_PATH- pointing to your basic source folder

Example `.env` file

ASSEMBLER=64tass TOKENIZER=/Users/zaphod/vice/bin/petcat EMULATOR=/Users/zaphod/vice/x64sc.app/Contents/MacOS/x64sc

ASM_PATH=./asm/hello BASIC_PATH=./basic/token

Example `mcp.json` file for Cursor

{ "mcpServers": { "mcp-c64": { "command": "npx", "args": ["-y", "mcp-c64"], "env": { "ASSEMBLER": "64tass", "TOKENIZER": "/Users/zaphod/vice/bin/petcat", "EMULATOR": "/Users/zaphod/vice/x64sc.app/Contents/MacOS/x64sc", "ASM_PATH": "/Users/zaphod/Projects/retro-game/asm/", "BASIC_PATH": "/Users/zaphod/Projects/retro-game/basic/" } } } }

Example `mcp.json` file for VSCode

{ "mcp": { "servers": { "mcp-c64": { "type": "stdio", "command": "npx", "args": [ "-y", "mcp-c64" ], "env": { "ASSEMBLER": "64tass", "TOKENIZER": "/Users/zaphod/vice/bin/petcat", "EMULATOR": "/Users/zaphod/vice/x64sc.app/Contents/MacOS/x64sc", "ASM_PATH": "/Users/zaphod/Projects/retro-game/asm/", "BASIC_PATH": "/Users/zaphod/Projects/retro-game/basic/" } } } } }

Example configuration for Github Copilot

{ "servers": { "mcp-c64": { "type": "stdio", "command": "npx", "args": ["-y", "mcp-c64"], "env": { "ASSEMBLER": "64tass", "TOKENIZER": "/Users/zaphod/vice/bin/petcat", "EMULATOR": "/Users/zaphod/vice/x64sc.app/Contents/MacOS/x64sc", "ASM_PATH": "/Users/zaphod/Projects/retro-game/asm/", "BASIC_PATH": "/Users/zaphod/Projects/retro-game/basic/" } } } }

The REPL

A minimal MCP Client which allows you to interact with the mcp-c64 server. It doesn't invoke LLMs but rather allows you to invoke the tools as an LLM would.

Running the REPL

Invoke with npm run repl
You will see a menu of available commands.

MCP Interactive Client
=====================
Connected to mcp-c64 server via STDIO transport

Available commands:
  help                       - Show this help
  list-tools                 - List available tools
  call-tool <name> [args]    - Call a tool with optional JSON arguments
  quit                       - Exit the program

>

The list-tools command

Lists the available tools in the MCP server.
These are the tools that the LLM could call, and the descriptions it would see

> list-tools

Available tools:
  - assemble_program: Assemble an assembly language program.
        Only the .asm source filename is required in file parameter, output .prg and .map files will be generated.
        Any additional args such as -a, -cbm-prg, etc. should be supplied in an array in the args parameter.
  - tokenize_program: Tokenize a BASIC program.
        Only the .bas source filename is required in file parameter, output .prg file will be generated.
        Any additional args such as -w2, etc. should be supplied in an array in the args parameter.
  - run_program: Run an assembled or tokenized program.
        The .prg filename is required in file parameter, and the program's path is required in path parameter.
        Any additional args such as -console, etc. should be supplied in an array in the args parameter.
        
>

The call-tool command

Allows you to call a tool on the MCP server just as the LLM would
You pass the tool name and its arguments as a JSON string

`assemble_program` tool

Uses 64tass to assemble a 6502 assembly language program
To target the Commodore 64 using Unicode or standard ASCII input, include the -a and -cbm-prg arguments
Refer to the 64tass command line options reference for more info on configuring the assembler behaviors

> call-tool assemble_program {"file":"hello_world.asm", "args": ["-a", "--cbm-prg"]}
Calling tool 'assemble_program' with args: { file: 'hello_world.asm', args: [ '-a', '--cbm-prg' ] }
Tool result:
{
  output: '64tass Turbo Assembler Macro V1.60.3243\n' +
    '64TASS comes with ABSOLUTELY NO WARRANTY; This is free software, and you\n' +
    'are welcome to redistribute it under certain conditions; See LICENSE!\n' +
    '\n' +
    'Assembling file:   asm/hello/hello_world.asm\n' +
    'Output file:       asm/hello/hello_world.prg\n' +
    'Passes:            2\n',
  error: '',
  status: 0
}

>

`tokenize_program` tool

Uses the petcat command included with the VICE emulator
To tokenize a Unicode or standard ASCII file for the Commodore 64, include the -w2 argument
See the petcat command line options reference for more info on configuring the tokenizer input and output behavior
See the C64-Wiki for PETSCII control characters that can be used in BASIC strings for such things as cursor movement and character color

> call-tool tokenize_program {"file":"token_test.bas", "args": ["-w2","-v"]}}
Calling tool 'tokenize_program' with args: { file: 'token_test.bas', args: [ '-w2', '-v' ] }
Tool result:
{
  output: '/Users/zaphod/Projects/retro-game\n',
  error: '\nLoad address 0801\nControl code set: enabled\n\n',
  status: 0
}

>

`run_program` tool

Uses the x64sc executable included with the VICE emulator package
To take a screenshot on exit, include the -exitscreenshot argument followed by a file name argument
See the x64sc command line options reference for more info on configuring the emulator behavior

> call-tool run_program {"file":"token_test.prg", "path":"/Users/zaphod/Projects/retro-game/basic/token", "args": ["-exitscreenshot","token_test.png"]}
Calling tool 'run_program' with args: {
  file: 'token_test.prg',
  path: '/Users/zaphod/Projects/retro-game/basic/token',
  args: [ '-exitscreenshot', 'token_test.png' ]
}
Tool result:
{ output: '', error: '', status: 0 }

>