@retrotech71/appleii-agent 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mike Daley
+
+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

@@ -0,0 +1,164 @@
+# @appleii/mcp-agent
+
+MCP server for the [Apple //e browser emulator](https://github.com/mikedaley/web-a2e) — control the emulator with AI agents via the AG-UI protocol.
+
+## What It Does
+
+This MCP (Model Context Protocol) server bridges AI agents like Claude with the Apple //e browser emulator. Through natural language, agents can:
+
+- **Manage windows** — show, hide, and focus emulator windows (BASIC editor, CPU debugger, disk drives, etc.)
+- **Load disk images** — insert floppy disks and SmartPort hard drive images from the filesystem
+- **Write BASIC programs** — read, edit, and load Applesoft BASIC programs into the emulator
+- **Assemble code** — write 65C02 assembly, assemble, and load into memory
+- **Control the emulator** — power on/off, reset, type text, manage expansion slots
+- **Inspect state** — read memory, CPU registers, and emulator status
+
+## Prerequisites
+
+- Node.js 18+
+- The [Apple //e emulator](https://github.com/mikedaley/web-a2e) running in your browser
+
+## Installation
+
+### From npm
+
+```bash
+npm install -g @appleii/mcp-agent
+```
+
+### From source
+
+```bash
+git clone https://github.com/mikedaley/appleii-agent.git
+cd appleii-agent
+npm install
+```
+
+## Configuration
+
+Add to your MCP client configuration. For Claude Code, edit `~/.claude/mcp.json`:
+
+### If installed globally
+
+```json
+{
+  "mcpServers": {
+    "appleii-agent": {
+      "command": "appleii-agent"
+    }
+  }
+}
+```
+
+### If installed from source
+
+```json
+{
+  "mcpServers": {
+    "appleii-agent": {
+      "command": "node",
+      "args": ["/path/to/appleii-agent/src/index.js"]
+    }
+  }
+}
+```
+
+## Usage
+
+1. Start the Apple //e emulator in your browser (`npm run dev` in the emulator repo)
+2. Open your MCP client (e.g., Claude Code)
+3. The MCP server starts automatically when the client connects
+4. Click the sparkle icon in the emulator toolbar to verify the connection (yellow = connected)
+
+### Example Prompts
+
+```
+Show the CPU debugger window
+Load ~/Documents/ProDOS_2_4_2.dsk into drive 1
+Write a BASIC program that draws a sine wave
+Install the SmartPort card in slot 7
+Load ~/Images/Total_Replay.hdv into SmartPort device 1
+Turn on the emulator and boot from disk
+Save 256 bytes from memory address $0800 to ~/output.bin
+```
+
+## Available Tools
+
+### Emulator Control
+| Tool | Description |
+|------|-------------|
+| `emma_command` | Generic command wrapper — routes to all frontend tools |
+| `showWindow` | Show and bring a window to front |
+| `hideWindow` | Hide a window |
+| `focusWindow` | Bring a window to front |
+
+### File Operations
+| Tool | Description |
+|------|-------------|
+| `load_disk_image` | Load a floppy disk image (.dsk, .do, .po, .nib, .woz) |
+| `load_smartport_image` | Load a SmartPort hard drive image (.hdv, .po, .2mg) |
+| `load_file` | Load any file (binary or text) |
+| `save_basic_file` | Save a BASIC program to a .bas file |
+| `save_asm_file` | Save assembly source to a .s or .asm file |
+| `save_disk_file` | Save binary disk data to a file |
+
+### Server Management
+| Tool | Description |
+|------|-------------|
+| `server_control` | Start, stop, restart, or check server status |
+| `set_https` | Toggle HTTPS mode |
+| `set_debug` | Toggle debug logging |
+| `get_state` | Get current server state |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3033` | HTTP server port |
+| `HTTPS` | `false` | Set to `true` for HTTPS mode |
+
+## How It Works
+
+```
+Claude Code ──MCP (stdio)──> MCP Server ──HTTP/SSE──> Browser Emulator
+                                  │
+                          AG-UI Protocol
+                     (event-based, bidirectional)
+```
+
+The MCP server communicates with Claude Code over stdio (standard MCP transport) and with the browser emulator over HTTP using Server-Sent Events (AG-UI protocol). Tool calls from the AI agent are forwarded to the emulator frontend, which executes them and returns results.
+
+## HTTPS Mode
+
+For HTTPS support:
+
+```bash
+# Generate self-signed certificate
+npm run generate-cert
+
+# Start with HTTPS
+HTTPS=true npm start
+```
+
+Or toggle at runtime via the `set_https` tool.
+
+## Troubleshooting
+
+**MCP server won't connect**
+- Ensure Node.js 18+ is installed
+- Check that the path in your MCP config is correct
+- Restart your MCP client
+
+**Emulator shows disconnected (gray sparkle)**
+- Make sure the emulator is running in your browser
+- Click the sparkle icon to view connection details
+- Check that port 3033 is not in use by another process
+
+**Tools return errors**
+- The emulator must be powered on for most tools to work
+- SmartPort tools require the SmartPort card to be installed in an expansion slot
+- Disk tools validate file formats before loading
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@retrotech71/appleii-agent",
+  "version": "1.0.0",
+  "description": "MCP server for the Apple //e browser emulator — control the emulator and integrate with AI agents",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "appleii-agent": "src/index.js"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "start:https": "HTTPS=true node src/index.js",
+    "generate-cert": "openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' -keyout key.pem -out cert.pem -days 365"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ag-ui",
+    "apple-ii",
+    "apple-iie",
+    "emulator",
+    "retro",
+    "6502",
+    "claude",
+    "ai-agent"
+  ],
+  "author": "Shawn Bullock <shawn@agenticexpert.ai>, Mike Daley <michael_daley@icloud.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mikedaley/appleii-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mikedaley/appleii-agent/issues"
+  },
+  "homepage": "https://github.com/mikedaley/appleii-agent#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  }
+}

package/src/http-server.js

@@ -0,0 +1,432 @@
+/*
+ * http-server.js - HTTP/HTTPS server for AG-UI event communication
+ *
+ * Written by
+ *  Shawn Bullock <shawn@agenticexpert.ai>
+ */
+
+import http from "http";
+import https from "https";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { execSync } from "child_process";
+import { logger } from "./logger.js";
+import { tools } from "./tools/index.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * HTTP/HTTPS Server for AG-UI protocol events
+ */
+export class HttpServer {
+  constructor(port, useHttps = false, debug = true) {
+    this.port = port;
+    this.useHttps = useHttps;
+    this.debug = debug;
+    this.server = null;
+    this.clients = new Set();
+    this.pendingToolResults = new Map();
+    this.eventQueue = [];
+  }
+
+  /**
+   * Generate self-signed certificate for HTTPS
+   */
+  _generateCertificate(certPath, keyPath) {
+    // Try mkcert first (locally-trusted certs), fall back to openssl (self-signed)
+    try {
+      execSync("mkcert -version", { stdio: "pipe" });
+      logger.log("Generating locally-trusted certificate with mkcert...");
+      execSync(`mkcert -key-file "${keyPath}" -cert-file "${certPath}" localhost 127.0.0.1 ::1`, { stdio: "pipe" });
+      logger.log("Certificate generated successfully (trusted by browser)");
+      return;
+    } catch (e) {
+      // mkcert not available, fall back to openssl
+    }
+
+    logger.log("Generating self-signed HTTPS certificate with openssl...");
+    logger.log("Tip: Install mkcert for browser-trusted certs: brew install mkcert && mkcert -install");
+
+    try {
+      const cmd = `openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' -keyout "${keyPath}" -out "${certPath}" -days 365`;
+      execSync(cmd, { stdio: "pipe" });
+      logger.log("Certificate generated (self-signed — browser may not trust it)");
+    } catch (error) {
+      throw new Error(
+        "Failed to generate certificate. Install mkcert (recommended) or OpenSSL:\n" +
+        "  mkcert: brew install mkcert && mkcert -install\n" +
+        "  macOS: brew install openssl\n" +
+        "  Linux: sudo apt-get install openssl\n" +
+        "  Windows: https://slproweb.com/products/Win32OpenSSL.html"
+      );
+    }
+  }
+
+  /**
+   * Start the HTTP/HTTPS server
+   */
+  async start() {
+    return new Promise((resolve, reject) => {
+      const requestHandler = (req, res) => {
+        this._handleRequest(req, res);
+      };
+
+      if (this.useHttps) {
+        const certPath = path.join(__dirname, "cert.pem");
+        const keyPath = path.join(__dirname, "key.pem");
+
+        // Auto-generate certificates if they don't exist
+        if (!fs.existsSync(certPath) || !fs.existsSync(keyPath)) {
+          try {
+            this._generateCertificate(certPath, keyPath);
+          } catch (error) {
+            reject(error);
+            return;
+          }
+        }
+
+        this.server = https.createServer({
+          key: fs.readFileSync(keyPath),
+          cert: fs.readFileSync(certPath),
+        }, requestHandler);
+      } else {
+        this.server = http.createServer(requestHandler);
+      }
+
+      this.server.listen(this.port, () => {
+        resolve();
+      });
+
+      this.server.on("error", (error) => {
+        reject(error);
+      });
+    });
+  }
+
+  /**
+   * Handle incoming HTTP requests
+   */
+  async _handleRequest(req, res) {
+    // Log requests in debug mode, but skip heartbeat to reduce noise
+    if (this.debug && req.url !== "/heartbeat") {
+      logger.log(`[HTTP] ${req.method} ${req.url}`);
+    }
+
+    // Enable CORS with Private Network Access (required for public HTTPS → localhost)
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+    res.setHeader("Access-Control-Allow-Private-Network", "true");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    if (req.method === "GET" && req.url === "/events") {
+      // SSE endpoint for streaming events to frontend
+      this._handleEventStream(req, res);
+      return;
+    }
+
+    if (req.method === "POST" && req.url === "/tool-result") {
+      // Receive TOOL_CALL_RESULT from frontend
+      await this._handleToolResult(req, res);
+      return;
+    }
+
+    if (req.method === "GET" && req.url === "/health") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "ok" }));
+      return;
+    }
+
+    if (req.method === "GET" && req.url === "/heartbeat") {
+      // Lightweight heartbeat endpoint for checking if server is running
+      res.writeHead(200, {
+        "Content-Type": "application/json",
+        "Access-Control-Allow-Origin": "*",
+      });
+      res.end(JSON.stringify({ alive: true }));
+      return;
+    }
+
+    if (req.method === "POST" && req.url === "/call-tool") {
+      // Call an MCP tool from the frontend
+      await this._handleCallTool(req, res);
+      return;
+    }
+
+    res.writeHead(404);
+    res.end("Not Found");
+  }
+
+  /**
+   * Handle Server-Sent Events stream
+   */
+  _handleEventStream(req, res) {
+    if (this.debug) {
+      logger.log("[HTTP] SSE client connected");
+    }
+
+    // Set SSE headers
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      "Connection": "keep-alive",
+    });
+
+    // Send initial comment to establish connection
+    // This ensures the browser fires the 'onopen' event
+    res.write(": connected\n\n");
+
+    // Add client to set
+    const client = { req, res };
+    this.clients.add(client);
+
+    // Send queued events to new client
+    this.eventQueue.forEach((event) => {
+      this._writeSSE(res, event);
+    });
+
+    // Handle client disconnect
+    req.on("close", () => {
+      if (this.debug) {
+        logger.log("[HTTP] SSE client disconnected");
+      }
+      this.clients.delete(client);
+
+      // Clear event queue when all clients disconnect
+      // This prevents replaying old commands to new sessions
+      if (this.clients.size === 0) {
+        this.eventQueue = [];
+        if (this.debug) {
+          logger.log("[HTTP] All clients disconnected, cleared event queue");
+        }
+      }
+    });
+  }
+
+  /**
+   * Handle tool result from frontend
+   */
+  async _handleToolResult(req, res) {
+    const body = await this._readBody(req);
+
+    if (this.debug) {
+      logger.log("[HTTP] Received:", body);
+    }
+
+    try {
+      const event = JSON.parse(body);
+
+      if (event.type === "TOOL_CALL_RESULT") {
+        const { tool_call_id, content } = event;
+
+        if (this.debug) {
+          logger.log(`[HTTP] Tool result for ${tool_call_id}:`, content);
+        }
+
+        // Resolve pending promise
+        const pending = this.pendingToolResults.get(tool_call_id);
+        if (pending) {
+          pending.resolve(content);
+          this.pendingToolResults.delete(tool_call_id);
+        }
+      }
+
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "ok" }));
+
+    } catch (error) {
+      if (this.debug) {
+        logger.log("[HTTP] Error:", error.message);
+      }
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: error.message }));
+    }
+  }
+
+  /**
+   * Handle call tool request from frontend
+   */
+  async _handleCallTool(req, res) {
+    const body = await this._readBody(req);
+
+    if (this.debug) {
+      logger.log("[HTTP] Call tool request:", body);
+    }
+
+    try {
+      const request = JSON.parse(body);
+      const { tool: toolName, args = {} } = request;
+
+      if (!toolName) {
+        throw new Error("tool parameter is required");
+      }
+
+      // Find the tool
+      const toolModule = tools.find(t => t.tool.name === toolName);
+      if (!toolModule) {
+        throw new Error(`Unknown tool: ${toolName}`);
+      }
+
+      // Call the tool handler
+      const result = await toolModule.handler(args, this);
+
+      if (this.debug) {
+        logger.log(`[HTTP] Tool ${toolName} result:`, JSON.stringify(result));
+      }
+
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(result));
+
+    } catch (error) {
+      if (this.debug) {
+        logger.log("[HTTP] Error:", error.message);
+      }
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({
+        success: false,
+        error: error.message
+      }));
+    }
+  }
+
+  /**
+   * Read request body
+   */
+  _readBody(req) {
+    return new Promise((resolve, reject) => {
+      let body = "";
+      req.on("data", (chunk) => {
+        body += chunk.toString();
+      });
+      req.on("end", () => {
+        resolve(body);
+      });
+      req.on("error", (error) => {
+        reject(error);
+      });
+    });
+  }
+
+  /**
+   * Send AG-UI event to all connected clients
+   */
+  async sendEvent(event) {
+    if (this.debug) {
+      logger.log("[HTTP] Sending event:", JSON.stringify(event));
+    }
+
+    // Add to queue (keep last 100 events for reconnecting clients)
+    this.eventQueue.push(event);
+    if (this.eventQueue.length > 100) {
+      this.eventQueue.shift();
+    }
+
+    // Send to all connected clients
+    this.clients.forEach((client) => {
+      this._writeSSE(client.res, event);
+    });
+  }
+
+  /**
+   * Write Server-Sent Event
+   */
+  _writeSSE(res, event) {
+    res.write(`data: ${JSON.stringify(event)}\n\n`);
+  }
+
+  /**
+   * Wait for tool result from frontend
+   */
+  waitForToolResult(toolCallId, timeoutMs = 5000) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingToolResults.delete(toolCallId);
+        reject(new Error("Tool result timeout"));
+      }, timeoutMs);
+
+      this.pendingToolResults.set(toolCallId, {
+        resolve: (result) => {
+          clearTimeout(timeout);
+          resolve(result);
+        },
+        reject,
+      });
+    });
+  }
+
+  /**
+   * Stop the HTTP/HTTPS server
+   */
+  async stop() {
+    if (this.server) {
+      // Close all SSE connections
+      this.clients.forEach((client) => {
+        client.res.end();
+      });
+      this.clients.clear();
+
+      return new Promise((resolve) => {
+        this.server.close(() => {
+          this.server = null;
+          resolve();
+        });
+      });
+    }
+  }
+
+  /**
+   * Restart the HTTP/HTTPS server
+   */
+  async restart() {
+    await this.stop();
+    await this.start();
+  }
+
+  /**
+   * Change HTTPS mode and restart
+   */
+  async setHttps(enabled) {
+    const wasRunning = this.server !== null;
+    if (wasRunning) {
+      await this.stop();
+    }
+    this.useHttps = enabled;
+    if (wasRunning) {
+      await this.start();
+    }
+  }
+
+  /**
+   * Set debug mode
+   */
+  setDebug(enabled) {
+    this.debug = enabled;
+    if (this.debug) {
+      logger.log("[HTTP] Debug mode enabled");
+    } else {
+      logger.log("[HTTP] Debug mode disabled");
+    }
+  }
+
+  /**
+   * Get server status
+   */
+  getStatus() {
+    return {
+      running: this.server !== null,
+      https: this.useHttps,
+      debug: this.debug,
+      port: this.port,
+      clients: this.clients.size,
+      protocol: this.useHttps ? "https" : "http",
+      url: `${this.useHttps ? "https" : "http"}://localhost:${this.port}`,
+    };
+  }
+}