c64-debug-mcp 0.1.8 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Henrik Olsson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://badge.fury.io/js/c64-debug-mcp.svg)](https://www.npmjs.com/package/c64-debug-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that enables AI assistants like Claude to debug and interact with Commodore 64 programs running in the VICE emulator.
+Debug Commodore 64 programs through conversation - AI-powered control of the VICE emulator for 6502 assembly and BASIC.
 
 ## Features
 
@@ -17,47 +17,22 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that en
 
 ## Requirements
 
-- **Node.js**: >= 22.13.0
-- **VICE Emulator**: Any recent version with binary monitor support
-  - Download from: https://vice-emu.sourceforge.io/
-  - Supports: x64sc (C64), x128 (C128), xvic (VIC-20), xpet (PET), and others
+- Node.js >= 22.13.0
+- VICE Emulator (https://vice-emu.sourceforge.io/)
+- MCP-compatible AI assistant (Claude Code, Codex, Windsurf, etc.)
 
 ## Installation
 
-### Option 1: No Installation (Recommended)
-
-Use `npx` to automatically run the latest version without installing:
-
-**No setup required!** Just configure Claude Desktop (see below).
-
-### Option 2: Global Installation
-
 ```bash
-npm install -g c64-debug-mcp
+claude mcp add c64debug -- npx -y c64-debug-mcp
 ```
 
-### Option 3: Local Installation
-
-```bash
-npm install c64-debug-mcp
-```
-
-## Usage
-
-### With Claude Desktop
-
-Add to your Claude Desktop configuration file:
-
-**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-**Linux**: `~/.config/Claude/claude_desktop_config.json`
-
-#### Recommended: Using npx (no installation, always latest)
+Or add manually to your MCP client config:
 
 ```json
 {
   "mcpServers": {
-    "c64-debug": {
+    "c64debug": {
       "command": "npx",
       "args": ["-y", "c64-debug-mcp"]
     }
@@ -65,95 +40,16 @@ Add to your Claude Desktop configuration file:
 }
 ```
 
-#### Alternative: Using global installation
-
-```json
-{
-  "mcpServers": {
-    "c64-debug": {
-      "command": "c64-debug-mcp"
-    }
-  }
-}
-```
-
-### With Other MCP Clients
-
-```bash
-# STDIO mode (for Claude Desktop and similar clients)
-c64-debug-mcp
-
-# HTTP mode (for web-based clients)
-c64-debug-mcp-http
-```
-
-### HTTP Server Configuration
-
-The HTTP server can be configured via environment variables:
-
-```bash
-C64_DEBUG_HTTP_HOST=127.0.0.1      # Default: 127.0.0.1
-C64_DEBUG_HTTP_PORT=39080          # Default: 39080
-C64_DEBUG_HTTP_PATH=/mcp           # Default: /mcp
-C64_DEBUG_HTTP_HEALTH_PATH=/healthz # Default: /healthz
-```
-
 ## Quick Start
 
-1. **Start VICE emulator** with binary monitor enabled:
-   ```bash
-   x64sc -remotemonitor -remotemonitoraddress 127.0.0.1:6502
-   ```
-
-2. **Configure Claude Desktop** (add to config file):
-   ```json
-   {
-     "mcpServers": {
-       "c64-debug": {
-         "command": "npx",
-         "args": ["-y", "c64-debug-mcp"]
-       }
-     }
-   }
-   ```
+1. Add MCP server (see Installation above)
 
-3. **Restart Claude Desktop**
-
-4. **Ask Claude to interact with C64**:
+2. Ask your AI assistant to interact with C64:
    - "What's in memory at $D000?"
    - "Set a breakpoint at $1000"
    - "Load and run my program.prg"
-   - "Show me the screen content"
-
-## Available Tools
-
-### Execution Control
-- `execute` - Pause, resume, step, step_over, step_out, or reset
-- `wait_for_state` - Wait for running/stopped state
-- `program_load` - Load PRG files with optional auto-start
-
-### Memory Operations
-- `memory_read` - Read memory by address and length
-- `memory_write` - Write bytes to memory
-- `get_registers` - Get CPU register values
-- `set_registers` - Set CPU register values
 
-### Breakpoints
-- `breakpoint_set` - Create execution or watchpoint breakpoints
-- `breakpoint_clear` - Remove a breakpoint
-- `list_breakpoints` - List all breakpoints
-
-### Display & Input
-- `capture_display` - Capture screen to PNG
-- `get_display_state` - Get screen RAM, color RAM, and graphics mode
-- `get_display_text` - Get text screen content
-- `write_text` - Type text with PETSCII support
-- `keyboard_input` - Send key presses/releases/taps
-- `joystick_input` - Send joystick commands
-
-### State Monitoring
-- `get_monitor_state` - Get execution state and stop reason
-- `get_session_state` - Get detailed emulator session state
+**Important:** The MCP server launches and controls VICE automatically. Your AI assistant owns the emulator process and can reset or restart it at any time. Don't use VICE manually or create valuable work in the emulator while debugging - any unsaved state may be lost when it resets the machine.
 
 ## Example Workflows
 
@@ -162,7 +58,7 @@ C64_DEBUG_HTTP_HEALTH_PATH=/healthz # Default: /healthz
 ```
 You: Load examples/hello.prg and set a breakpoint at $1000
 
-Claude will:
+AI assistant will:
 1. Load the program using program_load
 2. Set a breakpoint at $1000 using breakpoint_set
 3. Resume execution until breakpoint is hit
@@ -174,7 +70,7 @@ Claude will:
 ```
 You: What's the BASIC program in memory?
 
-Claude will:
+AI assistant will:
 1. Read memory from $0801 (BASIC start)
 2. Parse the BASIC tokens
 3. Show you the program listing
@@ -185,103 +81,16 @@ Claude will:
 ```
 You: Show me what's on the screen
 
-Claude will:
+AI assistant will:
 1. Capture the display using capture_display
 2. Save a PNG image
 3. Describe what's visible
 ```
 
-## Configuration
-
-### Environment Variables
-
-- `C64_DEBUG_CONSOLE_LOGS` - Enable verbose logging (1, true, yes, on)
-- `C64_DEBUG_SERVER_NODE` - Path to Node.js executable for smoke tests
-- `C64_DEBUG_HTTP_*` - HTTP server configuration (see above)
-
-### VICE Connection
-
-The MCP server connects to VICE on `localhost:6502` by default. Ensure VICE is started with:
-
-```bash
-x64sc -remotemonitor -remotemonitoraddress 127.0.0.1:6502
-```
-
-Or add to your `~/.vice/vicerc`:
-
-```
-RemoteMonitor=1
-RemoteMonitorAddress=127.0.0.1:6502
-```
-
-## Troubleshooting
-
-### "Cannot connect to VICE"
-- Ensure VICE is running with `-remotemonitor` flag
-- Check that port 6502 is not blocked by firewall
-- Verify VICE is listening: `netstat -an | grep 6502`
-
-### "Command not found: c64-debug-mcp"
-- Ensure global npm bin directory is in PATH: `npm config get prefix`
-- Or use npx: `npx c64-debug-mcp`
-
-### Node version errors
-- This package requires Node.js >= 22.13.0
-- Check version: `node --version`
-- Install latest: https://nodejs.org/
-
-## Development
-
-```bash
-# Clone repository
-git clone https://github.com/henols/c64-debug-mcp.git
-cd c64-debug-mcp/packages/c64-debug-mcp
-
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Run tests
-npm run smoke:http
-
-# Type check
-npm run check
-```
-
-## Architecture
-
-- **TypeScript** with strict type checking
-- **Zod** for schema validation
-- **Mastra MCP** framework for protocol implementation
-- **VICE Binary Monitor Protocol** for emulator communication
-
-## Contributing
-
-Contributions are welcome! Please:
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes with tests
-4. Submit a pull request
-
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details
-
-## Resources
-
-- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
-- [VICE Emulator](https://vice-emu.sourceforge.io/)
-- [VICE Binary Monitor Protocol](https://vice-emu.sourceforge.io/vice_13.html#SEC338)
-- [Smithery MCP Registry](https://smithery.ai/)
-
-## Acknowledgments
-
-Built with the [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic.
-Powered by [VICE](https://vice-emu.sourceforge.io/) - the Versatile Commodore Emulator.
+MIT - see [LICENSE](LICENSE) file
 
----
+**Made with ❤️ for C64 developers and AI-assisted retro coding**
 
-**Happy C64 debugging! 🎮**
+*"The C64 never gets old, it just gets smarter" 🎮*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c64-debug-mcp",
-  "version": "0.1.8",
+  "version": "1.0.0",
   "description": "Model Context Protocol server for C64 debugging via VICE emulator",
   "type": "module",
   "keywords": [
@@ -16,8 +16,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/henols/c64-debug-mcp.git",
-    "directory": "packages/c64-debug-mcp"
+    "url": "git+https://github.com/henols/c64-debug-mcp.git"
   },
   "bugs": "https://github.com/henols/c64-debug-mcp/issues",
   "homepage": "https://github.com/henols/c64-debug-mcp#readme",
@@ -39,7 +38,8 @@
     "build": "tsup src/stdio.ts src/http.ts --format esm,cjs --dts --no-splitting --clean",
     "check": "tsc --noEmit",
     "prepublishOnly": "npm run build && npm run check",
-    "dev:http": "C64_DEBUG_CONSOLE_LOGS=1 /home/henrik/.nvm/versions/node/v22.13.0/bin/node ../../node_modules/tsx/dist/cli.mjs watch src/http.ts"
+    "dev:http": "C64_DEBUG_CONSOLE_LOGS=1 /home/henrik/.nvm/versions/node/v22.13.0/bin/node node_modules/tsx/dist/cli.mjs watch src/http.ts",
+    "release": "bash scripts/release.sh"
   },
   "dependencies": {
     "@mastra/core": "^1.15.0",