mcp-c64

The mcp-c64 server provides an MCP-based development pipeline for Commodore 64 projects. It exposes tools to assemble 6502 assembly into .prg, tokenize BASIC into .prg, and run the resulting programs inside the VICE emulator. A minimal REPL client lets you list available tools, call tools with structured arguments, and view tool outputs. You can interact with the server by invoking the REPL client (npm run repl) or by integrating with editors/IDEs via the provided mcp.json configurations that point to the npx-based server. Available tools include: assemble_program (assemble 64tass into .prg and optional auxiliary files), tokenize_program (tokenize BASIC with petcat), and run_program (launch the .prg in x64sc with optional emulator arguments).

Prerequisites:

• Node.js and npm installed on your system
• VICE emulator installed (including petcat tokenizer and x64sc)
• 64tass assembler installed and accessible in PATH

Install steps:

1. Install Node.js and npm from https://nodejs.org/
2. Install the MCP server package (example: npm install -g mcp-c64 or clone the repository and run npm install in the project root)
3. Ensure VICE components are installed and accessible:
   • petcat tokenizer (provided with VICE)
   • x64sc emulator (provided by VICE)
4. Create a .env file in the project root and set paths to assembler, tokenizer, emulator, and source folders, e.g.: ASSEMBLER=64tass TOKENIZER=/path/to/petcat EMULATOR=/path/to/x64sc ASM_PATH=./asm/ BASIC_PATH=./basic/
5. Start the MCP server (example using npm/npx): npx -y mcp-c64 or if using a local install: npm run start
6. Open the REPL (npm run repl) to interact with the server and call tools like assemble_program, tokenize_program, and run_program.

Tips and notes:

• The mcp.json example demonstrates running via npx with environment variables for the required tools. Adjust ASSEMBLER, TOKENIZER, EMULATOR, ASM_PATH, and BASIC_PATH to match your environment.
• The REPL allows you to call tools with structured JSON arguments, for example: {"file":"hello.asm","args":["-a","--cbm-prg"]} for assembling, or {"file":"token.bas","path":"/path/to/basic","args":["-w2"]} for tokenizing.
• Ensure the paths in env variables are correct for your OS (macOS/Linux use forward slashes; Windows paths may differ).
• If you encounter permission issues with npx, consider installing the package locally and running via npm scripts.
• When running programs, you can pass additional emulator arguments (e.g., -exitscreenshot) to capture state or control behavior.
• The environment variables are user-specific; keep them out of version control in production setups.