fix: version from package.json, python validation, TCP retry, registry cache, screenshot image content

Closes #15, #16, #17, #18, #19

- Read server version dynamically from package.json instead of hardcoding
- Validate python3 and app_manager.py before delegating to subprocess
- Add retry logic (3x with backoff) for simulator TCP connections
- Cache app registry with 5-minute TTL
- Return MCP image content type from screenshot tool

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: matixan

src/index.ts

@@ -4,6 +4,11 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 
+import fs from "fs";
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+
 // Tool implementations
 import { crosspadBuild, crosspadRun } from "./tools/build.js";
 import { crosspadBuildCheck } from "./tools/build-check.js";
@@ -31,7 +36,7 @@ import type { OnLine } from "./utils/exec.js";
 import type { LoggingLevel } from "@modelcontextprotocol/sdk/types.js";
 
 const server = new McpServer(
-  { name: "crosspad", version: "5.0.0" },
+  { name: "crosspad", version },
   { capabilities: { logging: {} } }
 );
 
@@ -146,8 +151,27 @@ server.tool(
   },
   async ({ action, region, filename, save_to_file, input_action, x, y, pad, velocity, delta, keycode, category, key, value }) => {
     switch (action) {
-      case "screenshot":
-        return jsonResponse(await crosspadScreenshot(save_to_file ?? true, filename));
+      case "screenshot": {
+        const result = await crosspadScreenshot(save_to_file ?? true, filename);
+        if (result.success) {
+          let imageData: string | undefined = result.data_base64;
+          // Read from file if saved to disk
+          if (!imageData && result.file_path) {
+            try {
+              imageData = fs.readFileSync(result.file_path).toString("base64");
+            } catch { /* fall through to JSON response */ }
+          }
+          if (imageData) {
+            return {
+              content: [
+                { type: "image" as const, data: imageData, mimeType: "image/png" },
+                { type: "text" as const, text: JSON.stringify({ success: true, width: result.width, height: result.height, format: result.format, file_path: result.file_path }, null, 2) },
+              ],
+            };
+          }
+        }
+        return jsonResponse(result);
+      }
 
       case "input": {
         if (!input_action) {

src/tools/app-manager.ts

@@ -11,6 +11,7 @@
 
 import fs from "fs";
 import path from "path";
+import { execSync } from "child_process";
 import { CROSSPAD_IDF_ROOT, CROSSPAD_PC_ROOT, getRepos } from "../config.js";
 import { runCommand, runCommandStream, OnLine } from "../utils/exec.js";
 
@@ -120,13 +121,24 @@ function resolvePlatform(platform: string): PlatformInfo | null {
 // HELPERS
 // ═══════════════════════════════════════════════════════════════════════
 
+const REGISTRY_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+let _registryCache: { data: Record<string, AppEntry>; timestamp: number; source: string } | null = null;
+
 function loadRegistryJsonFrom(repoRoot: string): Record<string, AppEntry> | null {
   const registryPath = path.join(repoRoot, "app-registry.json");
+
+  // Return cached if fresh and from same source
+  if (_registryCache && _registryCache.source === registryPath && Date.now() - _registryCache.timestamp < REGISTRY_CACHE_TTL_MS) {
+    return _registryCache.data;
+  }
+
   if (!fs.existsSync(registryPath)) return null;
 
   try {
     const data = JSON.parse(fs.readFileSync(registryPath, "utf-8"));
-    return data.apps ?? {};
+    const apps = data.apps ?? {};
+    _registryCache = { data: apps, timestamp: Date.now(), source: registryPath };
+    return apps;
   } catch {
     return null;
   }
@@ -282,6 +294,30 @@ function requirePlatform(platform: string): { info: PlatformInfo } | { error: Ap
   return { info };
 }
 
+let _pythonOk: boolean | null = null;
+
+function isPythonAvailable(): boolean {
+  if (_pythonOk !== null) return _pythonOk;
+  try {
+    execSync("python3 --version", { stdio: "ignore", timeout: 5000 });
+    _pythonOk = true;
+  } catch {
+    _pythonOk = false;
+  }
+  return _pythonOk;
+}
+
+function validatePythonSetup(info: PlatformInfo): string | null {
+  if (!isPythonAvailable()) {
+    return "python3 is not installed or not in PATH. Install Python 3 to use app management.";
+  }
+  const scriptPath = path.join(info.root, info.scriptDir, "app_manager.py");
+  if (!fs.existsSync(scriptPath)) {
+    return `app_manager.py not found at ${scriptPath}. Run 'idf.py app-list' first to bootstrap the script.`;
+  }
+  return null;
+}
+
 async function runPythonAction(
   info: PlatformInfo,
   action: string,
@@ -291,6 +327,18 @@ async function runPythonAction(
   onLine: OnLine | undefined,
   timeoutMs: number,
 ): Promise<AppActionResult> {
+  const validationError = validatePythonSetup(info);
+  if (validationError) {
+    return {
+      success: false,
+      action,
+      platform: info.label,
+      app_name: appName,
+      output: "",
+      error: validationError,
+    };
+  }
+
   const cmd = buildPythonCmd(info.root, info.scriptDir, method, args);
 
   if (onLine) {

src/utils/remote-client.ts

@@ -15,11 +15,34 @@ export interface RemoteResponse {
   [key: string]: unknown;
 }
 
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 500;
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 /**
  * Send a JSON command to the running simulator and return the response.
+ * Retries up to MAX_RETRIES times on timeout errors (simulator may be loading).
  * Opens a fresh TCP connection per call (simple, stateless).
  */
-export function sendRemoteCommand(command: Record<string, unknown>): Promise<RemoteResponse> {
+export async function sendRemoteCommand(command: Record<string, unknown>): Promise<RemoteResponse> {
+  let lastError: Error | undefined;
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      return await sendRemoteCommandOnce(command);
+    } catch (err: any) {
+      lastError = err;
+      // Only retry on timeout, not on connection refused (simulator not running)
+      if (err.message?.includes("Connection refused")) throw err;
+      if (attempt < MAX_RETRIES) await delay(RETRY_DELAY_MS * attempt);
+    }
+  }
+  throw lastError!;
+}
+
+function sendRemoteCommandOnce(command: Record<string, unknown>): Promise<RemoteResponse> {
   return new Promise((resolve, reject) => {
     const socket = new Socket();
     let buffer = "";