@retrotech71/appleii-agent 1.0.1 → 1.0.5

package/README.md

@@ -38,19 +38,23 @@ npm install
 
 Add to your MCP client configuration. For Claude Code, edit `~/.claude/mcp.json`:
 
-### If installed globally
+### Option 1: Using bunx (Recommended)
+
+Runs the published package directly with Bun:
 
 ```json
 {
   "mcpServers": {
     "appleii-agent": {
-      "command": "appleii-agent"
+      "type": "stdio",
+      "command": "bunx",
+      "args": ["-y", "@retrotech71/appleii-agent"]
     }
   }
 }
 ```
 
-### If installed from source
+### Option 2: Local development from source
 
 ```json
 {
@@ -109,6 +113,9 @@ Save 256 bytes from memory address $0800 to ~/output.bin
 | `set_https` | Toggle HTTPS mode |
 | `set_debug` | Toggle debug logging |
 | `get_state` | Get current server state |
+| `get_version` | Get MCP server version information |
+| `shutdown_remote_server` | Shutdown another MCP server instance on the same port |
+| `disconnect_clients` | Gracefully disconnect all connected emulator clients |
 
 ## Environment Variables
 
@@ -154,6 +161,13 @@ Or toggle at runtime via the `set_https` tool.
 - Click the sparkle icon to view connection details
 - Check that port 3033 is not in use by another process
 
+**Reclaiming the Apple II Agent port (multiple MCP instances)**
+- The MCP server handles port conflicts gracefully and won't fail
+- Use `server_control` with action `status` to check if port is in use
+- Use `shutdown_remote_server` to reclaim the port by stopping the other instance
+- After shutdown, use `server_control` with action `start` to start this instance on the reclaimed port
+- Note: A server stopped via `shutdown_remote_server` can only be restarted by its owning MCP instance
+
 **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retrotech71/appleii-agent",
-  "version": "1.0.1",
+  "version": "1.0.5",
   "description": "MCP server for the Apple //e browser emulator — control the emulator and integrate with AI agents",
   "type": "module",
   "main": "src/index.js",

package/src/http-server.js

@@ -30,6 +30,8 @@ export class HttpServer {
     this.pendingToolResults = new Map();
     this.eventQueue = [];
     this.emulatorDomain = null; // Domain where the emulator is running
+    this.portInUse = false; // Track if port is in use by another instance
+    this.externallyShutdown = false; // Track if shutdown came from external command
   }
 
   /**
@@ -69,6 +71,11 @@ export class HttpServer {
    * Start the HTTP/HTTPS server
    */
   async start() {
+    // Log if restarting after external shutdown (informational only)
+    if (this.externallyShutdown && this.debug) {
+      logger.log("[HTTP] Restarting after external shutdown");
+    }
+
     return new Promise((resolve, reject) => {
       const requestHandler = (req, res) => {
         this._handleRequest(req, res);
@@ -97,11 +104,29 @@ export class HttpServer {
       }
 
       this.server.listen(this.port, () => {
+        // Successfully started - clear flags
+        this.portInUse = false;
+        this.externallyShutdown = false;
+        if (this.debug) {
+          logger.log(`[HTTP] Server listening on port ${this.port}`);
+        }
         resolve();
       });
 
       this.server.on("error", (error) => {
-        reject(error);
+        // Handle port already in use gracefully
+        if (error.code === "EADDRINUSE") {
+          this.portInUse = true;
+          this.server = null;
+          if (this.debug) {
+            logger.log(`[HTTP] Port ${this.port} already in use - server not started`);
+          }
+          // Resolve instead of reject to keep MCP alive
+          resolve();
+        } else {
+          // Other errors still reject
+          reject(error);
+        }
       });
     });
   }
@@ -117,7 +142,7 @@ export class HttpServer {
 
     // 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-Methods", "GET, POST, OPTIONS, HEAD");
     res.setHeader("Access-Control-Allow-Headers", "Content-Type");
     res.setHeader("Access-Control-Allow-Private-Network", "true");
 
@@ -127,6 +152,18 @@ export class HttpServer {
       return;
     }
 
+    if (req.method === "HEAD" && req.url.startsWith("/events")) {
+      // Check if connection is allowed (for single-client mode)
+      if (this.clients.size > 0) {
+        res.writeHead(409, { "Content-Type": "text/plain" });
+        res.end("Another Apple //e Emulator Already Connected");
+      } else {
+        res.writeHead(200, { "Content-Type": "text/event-stream" });
+        res.end();
+      }
+      return;
+    }
+
     if (req.method === "GET" && req.url.startsWith("/events")) {
       // SSE endpoint for streaming events to frontend
       this._handleEventStream(req, res);
@@ -161,6 +198,33 @@ export class HttpServer {
       return;
     }
 
+    if (req.method === "POST" && req.url === "/shutdown") {
+      // External shutdown command - stops server and prevents restart
+      if (this.debug) {
+        logger.log("[HTTP] Received external shutdown command");
+      }
+
+      // Mark as externally shutdown
+      this.externallyShutdown = true;
+
+      // Send response before shutting down
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({
+        status: "shutting_down",
+        message: "Server shutting down. Can only be restarted by owning MCP instance."
+      }));
+
+      // Stop the server after response is sent (internal=false to preserve externallyShutdown flag)
+      setTimeout(async () => {
+        await this.stop(false);
+        if (this.debug) {
+          logger.log("[HTTP] Server stopped by external shutdown");
+        }
+      }, 100);
+
+      return;
+    }
+
     res.writeHead(404);
     res.end("Not Found");
   }
@@ -169,6 +233,16 @@ export class HttpServer {
    * Handle Server-Sent Events stream
    */
   _handleEventStream(req, res) {
+    // Check if a client is already connected (single client mode)
+    if (this.clients.size > 0) {
+      if (this.debug) {
+        logger.log("[HTTP] Rejecting connection - another client already connected");
+      }
+      res.writeHead(409, { "Content-Type": "text/plain" });
+      res.end("Another Apple //e Emulator Already Connected");
+      return;
+    }
+
     // Parse domain from query parameter
     const url = new URL(req.url, `http://localhost:${this.port}`);
     const domain = url.searchParams.get("domain");
@@ -196,7 +270,7 @@ export class HttpServer {
     res.write(": connected\n\n");
 
     // Add client to set
-    const client = { req, res };
+    const client = { req, res, domain };
     this.clients.add(client);
 
     // Send queued events to new client
@@ -376,7 +450,7 @@ export class HttpServer {
   /**
    * Stop the HTTP/HTTPS server
    */
-  async stop() {
+  async stop(internal = true) {
     if (this.server) {
       // Close all SSE connections
       this.clients.forEach((client) => {
@@ -387,6 +461,14 @@ export class HttpServer {
       return new Promise((resolve) => {
         this.server.close(() => {
           this.server = null;
+          // Only clear externallyShutdown flag if this is an internal stop
+          // (from the owning MCP instance)
+          if (internal && this.externallyShutdown) {
+            this.externallyShutdown = false;
+            if (this.debug) {
+              logger.log("[HTTP] External shutdown flag cleared by owning instance");
+            }
+          }
           resolve();
         });
       });
@@ -441,6 +523,8 @@ export class HttpServer {
       url: `${this.useHttps ? "https" : "http"}://localhost:${this.port}`,
       emulatorDomain: this.emulatorDomain,
       llmsTxtUrl: this.emulatorDomain ? `${this.emulatorDomain}/llms.txt` : null,
+      portInUse: this.portInUse,
+      externallyShutdown: this.externallyShutdown,
     };
   }
 
@@ -450,4 +534,46 @@ export class HttpServer {
   getLlmsTxtUrl() {
     return this.emulatorDomain ? `${this.emulatorDomain}/llms.txt` : null;
   }
+
+  /**
+   * Gracefully disconnect all clients
+   */
+  disconnectAllClients() {
+    if (this.clients.size === 0) {
+      if (this.debug) {
+        logger.log("[HTTP] No clients to disconnect");
+      }
+      return { disconnected: 0 };
+    }
+
+    const count = this.clients.size;
+
+    // Send disconnect event to all clients before closing
+    this.clients.forEach((client) => {
+      try {
+        // Send a custom disconnect event
+        this._writeSSE(client.res, {
+          type: "DISCONNECT",
+          reason: "Server requested disconnect",
+          graceful: true,
+        });
+        // Close the connection
+        client.res.end();
+      } catch (error) {
+        if (this.debug) {
+          logger.log(`[HTTP] Error disconnecting client: ${error.message}`);
+        }
+      }
+    });
+
+    this.clients.clear();
+    this.eventQueue = [];
+    this.emulatorDomain = null;
+
+    if (this.debug) {
+      logger.log(`[HTTP] Gracefully disconnected ${count} client(s)`);
+    }
+
+    return { disconnected: count };
+  }
 }

package/src/index.js

@@ -29,7 +29,18 @@ async function main() {
 
     const protocol = USE_HTTPS ? "https" : "http";
     logger.log("Apple II MCP Agent initialized");
-    logger.log(`${protocol.toUpperCase()} server listening on ${protocol}://localhost:${HTTP_PORT}`);
+
+    // Check if HTTP server actually started
+    const status = httpServer.getStatus();
+    if (status.running) {
+      logger.log(`${protocol.toUpperCase()} server listening on ${protocol}://localhost:${HTTP_PORT}`);
+    } else if (status.portInUse) {
+      logger.log(`Port ${HTTP_PORT} already in use - HTTP server not started`);
+      logger.log("Use server_control tool to attempt start again or shutdown_remote_server to stop the other instance");
+    } else if (status.externallyShutdown) {
+      logger.log("HTTP server cannot start - was externally shutdown");
+      logger.log("Restart the MCP instance to enable HTTP server");
+    }
 
   } catch (error) {
     logger.log("Failed to start Apple II MCP Agent:", error);

package/src/tools/disconnect-clients.js

@@ -0,0 +1,27 @@
+/*
+ * disconnect-clients.js - Disconnect all connected clients
+ *
+ * Written by
+ *  Shawn Bullock <shawn@agenticexpert.ai>
+ */
+
+export const tool = {
+  name: "disconnect_clients",
+  description: "Gracefully disconnect all connected Apple //e emulator clients",
+  inputSchema: {
+    type: "object",
+    properties: {},
+  },
+};
+
+export function handler(args, httpServer) {
+  const result = httpServer.disconnectAllClients();
+
+  return {
+    success: true,
+    disconnected: result.disconnected,
+    message: result.disconnected > 0
+      ? `Disconnected ${result.disconnected} client(s)`
+      : "No clients were connected",
+  };
+}

package/src/tools/get-version.js

@@ -0,0 +1,27 @@
+/*
+ * get-version.js - Get MCP server version information
+ *
+ * Written by
+ *  Shawn Bullock <shawn@agenticexpert.ai>
+ */
+
+import { VERSION, NAME, DESCRIPTION } from "../version.js";
+
+export const tool = {
+  name: "get_version",
+  description: "Get the Apple II MCP Agent version information",
+  inputSchema: {
+    type: "object",
+    properties: {},
+    required: [],
+  },
+};
+
+export function handler() {
+  return {
+    success: true,
+    name: NAME,
+    version: VERSION,
+    description: DESCRIPTION,
+  };
+}

package/src/tools/index.js

@@ -10,6 +10,9 @@ import * as serverControl from "./server-control.js";
 import * as setHttps from "./set-https.js";
 import * as setDebug from "./set-debug.js";
 import * as getState from "./get-state.js";
+import * as getVersion from "./get-version.js";
+import * as disconnectClients from "./disconnect-clients.js";
+import * as shutdownRemoteServer from "./shutdown-remote-server.js";
 import * as showWindow from "./show-window.js";
 import * as hideWindow from "./hide-window.js";
 import * as focusWindow from "./focus-window.js";
@@ -25,6 +28,9 @@ export const tools = [
   setHttps,
   setDebug,
   getState,
+  getVersion,
+  disconnectClients,
+  shutdownRemoteServer,
   showWindow,
   hideWindow,
   focusWindow,

package/src/tools/server-control.js

@@ -7,7 +7,7 @@
 
 export const tool = {
   name: "server_control",
-  description: "Control the AG-UI HTTP/HTTPS server (start, stop, restart)",
+  description: "Control the AG-UI HTTP/HTTPS server (start, stop, restart, status). To reclaim or take over a port when another instance is using it: (1) First call shutdown_remote_server to stop the other instance, then (2) Call this tool with action 'start' to start this instance.",
   inputSchema: {
     type: "object",
     properties: {
@@ -25,26 +25,65 @@ export async function handler(args, httpServer) {
   const { action } = args;
 
   switch (action) {
-    case "start":
-      if (httpServer.getStatus().running) {
-        return { status: "already_running", ...httpServer.getStatus() };
+    case "start": {
+      const currentStatus = httpServer.getStatus();
+
+      if (currentStatus.running) {
+        return { status: "already_running", ...currentStatus };
       }
+
       await httpServer.start();
-      return { status: "started", ...httpServer.getStatus() };
+      const newStatus = httpServer.getStatus();
+
+      if (newStatus.portInUse) {
+        return {
+          status: "failed_to_start",
+          reason: "port_in_use",
+          message: `Port ${newStatus.port} is already in use by another instance. Use shutdown_remote_server tool to stop it.`,
+          ...newStatus
+        };
+      }
+
+      return { status: "started", ...newStatus };
+    }
 
-    case "stop":
-      if (!httpServer.getStatus().running) {
-        return { status: "already_stopped", ...httpServer.getStatus() };
+    case "stop": {
+      const currentStatus = httpServer.getStatus();
+      if (!currentStatus.running) {
+        return { status: "already_stopped", ...currentStatus };
       }
       await httpServer.stop();
       return { status: "stopped", ...httpServer.getStatus() };
+    }
 
-    case "restart":
+    case "restart": {
       await httpServer.restart();
-      return { status: "restarted", ...httpServer.getStatus() };
+      const newStatus = httpServer.getStatus();
+
+      if (newStatus.portInUse) {
+        return {
+          status: "failed_to_restart",
+          reason: "port_in_use",
+          message: `Port ${newStatus.port} is already in use by another instance. Use shutdown_remote_server tool to stop it.`,
+          ...newStatus
+        };
+      }
+
+      return { status: "restarted", ...newStatus };
+    }
+
+    case "status": {
+      const status = httpServer.getStatus();
+
+      // Add helpful messages based on state
+      if (status.portInUse && !status.running) {
+        status.message = `Port ${status.port} is in use. Use shutdown_remote_server to stop the other instance.`;
+      } else if (status.externallyShutdown && !status.running) {
+        status.message = "Server was externally shutdown. Use server_control to restart.";
+      }
 
-    case "status":
-      return httpServer.getStatus();
+      return status;
+    }
 
     default:
       throw new Error(`Unknown action: ${action}`);

package/src/tools/shutdown-remote-server.js

@@ -0,0 +1,113 @@
+/*
+ * shutdown-remote-server.js - Shutdown remote MCP server instance
+ *
+ * Written by
+ *  Shawn Bullock <shawn@agenticexpert.ai>
+ */
+
+import http from "http";
+import https from "https";
+
+export const tool = {
+  name: "shutdown_remote_server",
+  description: "Shutdown a remote Apple II MCP server instance running on the same port. Use this when port is already in use by another instance. To reclaim or take over a port: (1) Call this tool to shutdown the other instance, then (2) Call server_control with action 'start' to start this instance.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      port: {
+        type: "number",
+        description: "Port number of the remote server (default: 3033)",
+        default: 3033,
+      },
+      useHttps: {
+        type: "boolean",
+        description: "Whether the remote server is using HTTPS (default: false)",
+        default: false,
+      },
+    },
+  },
+};
+
+export async function handler(args, httpServer) {
+  const port = args.port || 3033;
+  const useHttps = args.useHttps || false;
+  const protocol = useHttps ? "https" : "http";
+  const url = `${protocol}://localhost:${port}/shutdown`;
+
+  return new Promise((resolve, reject) => {
+    const requestModule = useHttps ? https : http;
+
+    const options = {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      // For self-signed certificates, ignore certificate errors
+      rejectUnauthorized: false,
+    };
+
+    const req = requestModule.request(url, options, (res) => {
+      let data = "";
+
+      res.on("data", (chunk) => {
+        data += chunk;
+      });
+
+      res.on("end", () => {
+        try {
+          const response = JSON.parse(data);
+          resolve({
+            success: true,
+            port,
+            protocol,
+            message: `Remote server on ${protocol}://localhost:${port} successfully shutdown`,
+            response,
+          });
+        } catch (error) {
+          resolve({
+            success: true,
+            port,
+            protocol,
+            message: `Remote server on ${protocol}://localhost:${port} shutdown (raw response)`,
+            rawResponse: data,
+          });
+        }
+      });
+    });
+
+    req.on("error", (error) => {
+      // Connection refused or other errors
+      if (error.code === "ECONNREFUSED") {
+        resolve({
+          success: false,
+          port,
+          protocol,
+          error: "connection_refused",
+          message: `No server found at ${protocol}://localhost:${port}`,
+        });
+      } else {
+        resolve({
+          success: false,
+          port,
+          protocol,
+          error: error.code || "unknown",
+          message: `Failed to connect to ${protocol}://localhost:${port}: ${error.message}`,
+        });
+      }
+    });
+
+    req.on("timeout", () => {
+      req.destroy();
+      resolve({
+        success: false,
+        port,
+        protocol,
+        error: "timeout",
+        message: `Request to ${protocol}://localhost:${port} timed out`,
+      });
+    });
+
+    req.setTimeout(5000); // 5 second timeout
+    req.end();
+  });
+}

package/src/version.js

@@ -0,0 +1,20 @@
+/*
+ * version.js - Version information from package.json
+ *
+ * Written by
+ *  Shawn Bullock <shawn@agenticexpert.ai>
+ */
+
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const packageJsonPath = join(__dirname, "..", "package.json");
+const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+
+export const VERSION = packageJson.version;
+export const NAME = packageJson.name;
+export const DESCRIPTION = packageJson.description;