{"id":29763872,"url":"https://github.com/barryw/vicemcp","last_synced_at":"2026-05-15T20:05:41.115Z","repository":{"id":305042067,"uuid":"1021055500","full_name":"barryw/ViceMCP","owner":"barryw","description":"AI-Powered Commodore Development Bridge","archived":false,"fork":false,"pushed_at":"2025-12-15T04:19:53.000Z","size":498,"stargazers_count":2,"open_issues_count":16,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-30T16:42:56.431Z","etag":null,"topics":["c128","c64","commodore","mcp","mcp-server","pet","plus4","vice"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/barryw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-16T20:07:23.000Z","updated_at":"2026-01-14T01:53:42.000Z","dependencies_parsed_at":"2025-10-20T06:16:31.344Z","dependency_job_id":"a34c1e7e-96e1-4372-991d-772a822e3bd0","html_url":"https://github.com/barryw/ViceMCP","commit_stats":null,"previous_names":["barryw/vicemcp"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/barryw/ViceMCP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barryw%2FViceMCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barryw%2FViceMCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barryw%2FViceMCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barryw%2FViceMCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/barryw","download_url":"https://codeload.github.com/barryw/ViceMCP/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barryw%2FViceMCP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33078039,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c128","c64","commodore","mcp","mcp-server","pet","plus4","vice"],"created_at":"2025-07-26T22:16:28.400Z","updated_at":"2026-05-15T20:05:41.110Z","avatar_url":"https://github.com/barryw.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n![ViceMCP Logo](Images/vicemcp-logo.svg)\n\n[![.NET](https://img.shields.io/badge/.NET-9.0+-512BD4.svg)](https://dotnet.microsoft.com/)\n[![Platform](https://img.shields.io/badge/Platform-Linux%20|%20macOS%20|%20Windows-blue.svg)](https://github.com/barryw/ViceMCP)\n[![License](https://img.shields.io/badge/License-MIT-brightgreen.svg)](LICENSE)\n[![Latest Release](https://img.shields.io/github/v/release/barryw/ViceMCP)](https://github.com/barryw/ViceMCP/releases/latest)\n[![CI/CD](https://github.com/barryw/ViceMCP/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/barryw/ViceMCP/actions/workflows/ci-cd.yml)\n[![Coverage](https://codecov.io/gh/barryw/ViceMCP/branch/main/graph/badge.svg)](https://codecov.io/gh/barryw/ViceMCP)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-orange.svg)](https://modelcontextprotocol.io/)\n\n**AI-Powered Commodore Development Bridge**\n\n[MCP Tools Reference](#-mcp-tools-reference) • [Quick Start](#-quick-start) • [Examples](#-examples)\n\n\u003c/div\u003e\n\n## Overview\n\nViceMCP bridges the gap between modern AI assistants and retro computing by exposing the VICE Commodore emulator's powerful debugging capabilities through the Model Context Protocol (MCP). This enables AI assistants like Claude to directly interact with running Commodore 64, VIC-20, PET, and other 8-bit Commodore computer emulations.\n\n### ✨ Key Features\n\n- 🤖 **AI Integration** - Use Claude or other MCP clients to debug Commodore programs\n- 🔍 **Memory Operations** - Read, write, search, and analyze memory in real-time\n- 🐛 **Advanced Debugging** - Set breakpoints, step through code, examine registers\n- ⚡ **Batch Commands** - Execute multiple operations in one shot for 10x performance\n- 📦 **Zero Dependencies** - Native AOT builds available - no .NET runtime needed!\n- 🚀 **Cross-Platform** - Works on Windows, macOS, and Linux\n- 🎮 **Multi-Machine Support** - C64, C128, VIC-20, PET, Plus/4, and more\n\n### ⚡ Batch Commands - 10x Performance Boost!\n\nExecute multiple VICE operations in a single command for massive performance gains:\n\n```json\nexecute_batch [\n  {\"command\": \"write_memory\", \"parameters\": {\"startHex\": \"0xD020\", \"dataHex\": \"00\"}},\n  {\"command\": \"write_memory\", \"parameters\": {\"startHex\": \"0xD021\", \"dataHex\": \"05\"}},\n  {\"command\": \"fill_memory\", \"parameters\": {\"startHex\": \"0x0400\", \"endHex\": \"0x07E7\", \"pattern\": \"A0\"}},\n  {\"command\": \"write_memory\", \"parameters\": {\"startHex\": \"0x0400\", \"dataHex\": \"08 05 0C 0C 0F\"}}\n]\n```\n\n**Result**: Set border/background colors, clear screen, and write \"HELLO\" in ~1.4 seconds instead of ~14 seconds! \n\nCheck out the [batch_examples/](batch_examples/) directory for ready-to-use JSON files.\n\n## Installation\n\n### 📦 Download Release\n\nDownload the latest release for your platform from the [releases page](https://github.com/barryw/ViceMCP/releases/latest).\n\n**Native AOT Builds Available!** 🚀 No .NET runtime required - just download and run:\n- `vicemcp-linux-x64` - Linux x64 native executable\n- `vicemcp-windows-x64` - Windows x64 native executable\n- `vicemcp-macos-x64` - macOS Intel native executable\n- `vicemcp-macos-arm64` - macOS Apple Silicon native executable\n\n### 🐳 Docker\n\n#### Quick Test\n```bash\ndocker run -it ghcr.io/barryw/vicemcp:latest\n```\n\n#### Using with Claude Code CLI\n```bash\n# Using Docker image directly\nclaude mcp add vicemcp \"docker run -i --rm ghcr.io/barryw/vicemcp:latest\"\n\n# With VICE binary path mounted (if you have VICE installed locally)\nclaude mcp add vicemcp \"docker run -i --rm -v /usr/local/bin:/vice:ro ghcr.io/barryw/vicemcp:latest\" --env VICE_BIN_PATH=/vice\n```\n\n#### Manual Configuration for Docker\n```json\n{\n  \"mcpServers\": {\n    \"vicemcp\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"-i\", \"--rm\", \"ghcr.io/barryw/vicemcp:latest\"],\n      \"env\": {\n        \"VICE_MONITOR_PORT\": \"6502\"\n      }\n    }\n  }\n}\n```\n\n#### Docker Compose Setup\n```yaml\n# docker-compose.yml\nversion: '3.8'\nservices:\n  vicemcp:\n    image: ghcr.io/barryw/vicemcp:latest\n    stdin_open: true\n    tty: true\n    environment:\n      - VICE_MONITOR_PORT=6502\n      - VICE_STARTUP_TIMEOUT=5000\n```\n\nThen configure with:\n```bash\nclaude mcp add vicemcp \"docker-compose run --rm vicemcp\"\n```\n\n### 🔧 Build from Source\n\n```bash\ngit clone https://github.com/barryw/ViceMCP.git\ncd ViceMCP\ndotnet build\n```\n\n## Quick Start\n\n### 1️⃣ Start VICE with Binary Monitor\n\n```bash\nx64sc -binarymonitor -binarymonitoraddress 127.0.0.1:6502\n```\n\n### 2️⃣ Configure your MCP Client\n\n#### Using Claude Code CLI (Recommended)\n\n```bash\n# If you downloaded the release binary\nclaude mcp add vicemcp ~/Downloads/vicemcp-osx-arm64/ViceMCP\n\n# Or if you built from source\nclaude mcp add vicemcp ~/RiderProjects/ViceMCP/ViceMCP/bin/Release/net9.0/ViceMCP\n\n# Or using Docker (no installation needed!)\nclaude mcp add vicemcp \"docker run -i --rm ghcr.io/barryw/vicemcp:latest\"\n```\n\nWith VICE path configured (if not in system PATH):\n\n```bash\nclaude mcp add vicemcp ~/Downloads/vicemcp-osx-arm64/ViceMCP --env VICE_BIN_PATH=/Applications/vice-x86-64-gtk3-3.8\n```\n\n#### Manual Configuration\n\nAdd to your Claude Desktop or other MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"vicemcp\": {\n      \"command\": \"/path/to/vicemcp\",\n      \"env\": {\n        \"VICE_BIN_PATH\": \"/path/to/vice/bin\"\n      }\n    }\n  }\n}\n```\n\n### 3️⃣ Start Debugging with AI\n\nAsk your AI assistant to:\n- \"Read memory from $C000 to $C100\"\n- \"Set a breakpoint at $0810\"\n- \"Show me the current CPU registers\"\n- \"Find all JSR $FFD2 instructions in memory\"\n\n## 📚 MCP Tools Reference\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMemory Operations\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n### `read_memory`\nRead bytes from memory and display in hex format.\n```yaml\nParameters:\n  - startHex: Start address (e.g., \"0x0400\" or \"0400\")\n  - endHex: End address\nReturns: Hex string like \"08-05-0C-0C-0F\"\n```\n\n### `write_memory`\nWrite bytes to memory.\n```yaml\nParameters:\n  - startHex: Start address\n  - dataHex: Space-separated hex bytes (e.g., \"A9 00 8D 20 D0\")\nReturns: Confirmation with bytes written\n```\n\n### `copy_memory`\nCopy memory from one location to another.\n```yaml\nParameters:\n  - sourceHex: Source start address\n  - destHex: Destination start address\n  - length: Number of bytes to copy\nReturns: Confirmation of copy operation\n```\n\n### `fill_memory`\nFill memory region with a byte pattern.\n```yaml\nParameters:\n  - startHex: Start address\n  - endHex: End address\n  - pattern: Hex bytes to repeat (e.g., \"AA 55\")\nReturns: Confirmation with pattern used\n```\n\n### `search_memory`\nSearch for byte patterns in memory.\n```yaml\nParameters:\n  - startHex: Search start address\n  - endHex: Search end address\n  - pattern: Hex bytes to find (e.g., \"A9 00\" for LDA #$00)\n  - maxResults: Maximum matches to return (default: 10)\nReturns: List of addresses where pattern found\n```\n\n### `compare_memory`\nCompare two memory regions.\n```yaml\nParameters:\n  - addr1Hex: First region start\n  - addr2Hex: Second region start\n  - length: Bytes to compare\nReturns: List of differences or \"regions identical\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCPU Control\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n### `get_registers`\nGet all CPU register values.\n```yaml\nReturns: A, X, Y, PC, SP, and status flags\n```\n\n### `set_register`\nSet a CPU register value.\n```yaml\nParameters:\n  - registerName: Register name (A, X, Y, PC, SP)\n  - valueHex: New value in hex\nReturns: Confirmation of register update\n```\n\n### `step`\nStep CPU by one or more instructions.\n```yaml\nParameters:\n  - count: Instructions to step (default: 1)\n  - stepOver: Step over subroutines (default: false)\nReturns: Number of instructions stepped\n```\n\n### `continue_execution`\nResume execution after breakpoint.\n```yaml\nReturns: \"Execution resumed\"\n```\n\n### `reset`\nReset the emulated machine.\n```yaml\nParameters:\n  - mode: \"soft\" or \"hard\" (default: \"soft\")\nReturns: Reset confirmation\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eBreakpoint Management\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n### `set_checkpoint`\nSet a breakpoint/checkpoint.\n```yaml\nParameters:\n  - startHex: Start address\n  - endHex: End address (optional)\n  - stopWhenHit: Stop execution on hit (default: true)\n  - enabled: Initially enabled (default: true)\nReturns: Checkpoint number and address range\n```\n\n### `list_checkpoints`\nList all checkpoints.\n```yaml\nReturns: List with status, address range, hit count\n```\n\n### `delete_checkpoint`\nDelete a checkpoint.\n```yaml\nParameters:\n  - checkpointNumber: Checkpoint # to delete\nReturns: Confirmation of deletion\n```\n\n### `toggle_checkpoint`\nEnable or disable a checkpoint.\n```yaml\nParameters:\n  - checkpointNumber: Checkpoint # to toggle\n  - enabled: true to enable, false to disable\nReturns: New checkpoint state\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eFile Operations\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n### `load_program`\nLoad a PRG file into memory.\n```yaml\nParameters:\n  - filePath: Path to PRG file\n  - addressHex: Override load address (optional)\nReturns: Load address and size information\n```\n\n### `save_memory`\nSave memory region to file.\n```yaml\nParameters:\n  - startHex: Start address\n  - endHex: End address\n  - filePath: Output file path\n  - asPrg: Save as PRG with header (default: true)\nReturns: Confirmation with bytes saved\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSystem Control\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n### `start_vice`\nLaunch a VICE emulator instance.\n```yaml\nParameters:\n  - emulatorType: x64sc, x128, xvic, xpet, xplus4, xcbm2, xcbm5x0\n  - arguments: Additional command line arguments\nReturns: Process ID and monitor port\n```\n\n### `get_info`\nGet VICE version information.\n```yaml\nReturns: VICE version and SVN revision\n```\n\n### `ping`\nCheck if VICE is responding.\n```yaml\nReturns: \"Pong! VICE is responding\"\n```\n\n### `get_banks`\nList available memory banks.\n```yaml\nReturns: List of bank numbers and names\n```\n\n### `get_display`\nCapture current display.\n```yaml\nParameters:\n  - useVic: Use VIC (true) or VICII/VDC (false)\nReturns: Display dimensions and image data size\n```\n\n### `quit_vice`\nQuit the VICE emulator.\n```yaml\nReturns: Confirmation of quit\n```\n\n### `send_keys`\nSend keyboard input to VICE.\n```yaml\nParameters:\n  - keys: Text to type (use \\n for Return)\nReturns: Confirmation of keys sent\n```\n\n### `execute_batch` ⚡\nExecute multiple VICE commands in a single operation for significantly improved performance.\n```yaml\nParameters:\n  - commandsJson: JSON array of command specifications\n  - failFast: Stop on first error (default: true)\nReturns: JSON with results of all commands\n```\n**🚀 Performance Tip**: Always use batch execution for multiple related operations. Setting up a sprite display can be 10x faster using batch vs individual commands. See `batch_examples/` for examples.\n\n\u003c/details\u003e\n\n## 💡 Examples\n\n### Debugging a Crash\n```\nAI: Let me examine what caused the crash...\n\u003e read_memory 0x0100 0x01FF  // Check stack\n\u003e get_registers              // See CPU state\n\u003e read_memory 0xC000 0xC020  // Examine code at PC\n```\n\n### Finding Code Patterns\n```\nAI: I'll search for all JSR instructions to $FFD2...\n\u003e search_memory 0x0800 0xBFFF \"20 D2 FF\"\n```\n\n### Interactive Development\n```\nAI: Let me load your program and set a breakpoint...\n\u003e load_program \"game.prg\"\n\u003e set_checkpoint 0x0810      // Break at start\n\u003e continue_execution\n\u003e step 10 true              // Step over subroutines\n```\n\n### Memory Analysis\n```\nAI: I'll check if the sprite data was copied correctly...\n\u003e compare_memory 0x2000 0x3000 64\n```\n\n### Batch Operations for Speed ⚡\n```\nAI: I'll create a red heart sprite in the center of the screen...\n\u003e execute_batch [\n    {\"command\": \"write_memory\", \"parameters\": {\"startHex\": \"0xD020\", \"dataHex\": \"00\"}, \"description\": \"Black border\"},\n    {\"command\": \"write_memory\", \"parameters\": {\"startHex\": \"0xD021\", \"dataHex\": \"00\"}, \"description\": \"Black background\"},\n    {\"command\": \"fill_memory\", \"parameters\": {\"startHex\": \"0x0400\", \"endHex\": \"0x07E7\", \"pattern\": \"20\"}, \"description\": \"Clear screen\"},\n    {\"command\": \"write_memory\", \"parameters\": {\"startHex\": \"0x0340\", \"dataHex\": \"00 66 00 01 FF 80 03 FF C0 07 FF E0 0F FF F0...\"}, \"description\": \"Heart sprite data\"},\n    {\"command\": \"write_memory\", \"parameters\": {\"startHex\": \"0x07F8\", \"dataHex\": \"0D\"}, \"description\": \"Set sprite pointer\"},\n    {\"command\": \"write_memory\", \"parameters\": {\"startHex\": \"0xD015\", \"dataHex\": \"01\"}, \"description\": \"Enable sprite 0\"},\n    {\"command\": \"write_memory\", \"parameters\": {\"startHex\": \"0xD000\", \"dataHex\": \"A0\"}, \"description\": \"Center X position\"},\n    {\"command\": \"write_memory\", \"parameters\": {\"startHex\": \"0xD001\", \"dataHex\": \"86\"}, \"description\": \"Center Y position\"},\n    {\"command\": \"write_memory\", \"parameters\": {\"startHex\": \"0xD027\", \"dataHex\": \"02\"}, \"description\": \"Red color\"}\n  ]\n// Result: Beautiful red heart sprite in 1.4 seconds! (vs 14+ seconds individually)\n```\n\n## 🏗️ Architecture\n\nViceMCP is built with:\n- **.NET 9.0** - Modern, cross-platform runtime\n- **Model Context Protocol** - Standardized AI tool interface\n- **vice-bridge-net** - Robust VICE binary monitor implementation\n- **Async/await patterns** - Efficient concurrent operations\n\n## 🧪 Development\n\n### Prerequisites\n- .NET 9.0 SDK\n- VICE emulator\n- Git\n\n### Building\n```bash\ndotnet build\ndotnet test\ndotnet run --project ViceMCP/ViceMCP.csproj\n```\n\n### Testing\n```bash\ndotnet test\n```\n\nTests use mocking to run without VICE, ensuring fast CI/CD.\n\n## 📖 Documentation\n\n- [Contributing Guidelines](CONTRIBUTING.md)\n- [Known Issues](KNOWN_ISSUES.md)\n\n## 🎯 Use Cases\n\n- 🎮 **Game Development** - Debug crashes, optimize routines, trace execution\n- 🔍 **Reverse Engineering** - Analyze vintage software behavior\n- 📚 **Education** - Learn 6502 assembly with AI assistance\n- 🛠️ **Tool Development** - Automate debugging workflows\n- 🏆 **Demoscene** - Profile and optimize demo effects\n\n## ⚠️ Known Limitations\n\nSee [KNOWN_ISSUES.md](KNOWN_ISSUES.md) for any current limitations.\n\n## 🤝 Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Workflow\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes with tests\n4. Submit a pull request\n\n## 📜 License\n\nThis project is licensed under the MIT License - see [LICENSE](LICENSE) for details.\n\n## 🙏 Acknowledgments\n\n- [VICE Team](https://vice-emu.sourceforge.io/) - The amazing Commodore emulator\n- [Anthropic](https://www.anthropic.com/) - Model Context Protocol\n- [Miha Markic](https://github.com/MihaMarkic) - vice-bridge-net library\n- The Commodore community for keeping the 8-bit dream alive\n\n---\n\n\u003cdiv align=\"center\"\u003e\nMade with ❤️ for the Commodore community\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarryw%2Fvicemcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbarryw%2Fvicemcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarryw%2Fvicemcp/lists"}