crosspad-mcp-server 4.0.0

package/dist/utils/remote-client.js

@@ -0,0 +1,94 @@
+/**
+ * TCP client for communicating with the CrossPad simulator's remote control server.
+ * Protocol: newline-delimited JSON over TCP on localhost:19840.
+ */
+import { Socket } from "net";
+const REMOTE_PORT = 19840;
+const REMOTE_HOST = "127.0.0.1";
+const CONNECT_TIMEOUT = 3000;
+const RESPONSE_TIMEOUT = 15000;
+/**
+ * Send a JSON command to the running simulator and return the response.
+ * Opens a fresh TCP connection per call (simple, stateless).
+ */
+export function sendRemoteCommand(command) {
+    return new Promise((resolve, reject) => {
+        const socket = new Socket();
+        let buffer = "";
+        let resolved = false;
+        const cleanup = () => {
+            if (!resolved) {
+                resolved = true;
+                socket.destroy();
+            }
+        };
+        // Connect timeout
+        socket.setTimeout(CONNECT_TIMEOUT);
+        socket.on("connect", () => {
+            // Extend timeout for response
+            socket.setTimeout(RESPONSE_TIMEOUT);
+            // Send command as newline-delimited JSON
+            const msg = JSON.stringify(command) + "\n";
+            socket.write(msg);
+        });
+        socket.on("data", (data) => {
+            buffer += data.toString();
+            // Look for newline-delimited response
+            const nlIdx = buffer.indexOf("\n");
+            if (nlIdx >= 0) {
+                const line = buffer.slice(0, nlIdx);
+                resolved = true;
+                socket.destroy();
+                try {
+                    resolve(JSON.parse(line));
+                }
+                catch {
+                    resolve({ ok: false, error: "invalid JSON response", raw: line });
+                }
+            }
+        });
+        socket.on("timeout", () => {
+            cleanup();
+            reject(new Error("Connection/response timeout — is the simulator running?"));
+        });
+        socket.on("error", (err) => {
+            cleanup();
+            if (err.code === "ECONNREFUSED") {
+                reject(new Error("Connection refused — simulator is not running or remote control is disabled. Start with crosspad_run first."));
+            }
+            else {
+                reject(new Error(`TCP error: ${err.message}`));
+            }
+        });
+        socket.on("close", () => {
+            if (!resolved) {
+                resolved = true;
+                if (buffer.length > 0) {
+                    try {
+                        resolve(JSON.parse(buffer));
+                    }
+                    catch {
+                        resolve({ ok: false, error: "incomplete response", raw: buffer });
+                    }
+                }
+                else {
+                    reject(new Error("Connection closed without response"));
+                }
+            }
+        });
+        socket.connect(REMOTE_PORT, REMOTE_HOST);
+    });
+}
+/**
+ * Check if the simulator's remote control server is reachable.
+ */
+export async function isSimulatorRunning() {
+    try {
+        const resp = await sendRemoteCommand({ cmd: "ping" });
+        return resp.ok === true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=remote-client.js.map

package/dist/utils/remote-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-client.js","sourceRoot":"","sources":["../../src/utils/remote-client.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "crosspad-mcp-server",
+  "version": "4.0.0",
+  "description": "MCP development server for CrossPad",
+  "mcpName": "io.github.crosspad/crosspad-mcp",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/server.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "name": "io.github.crosspad/crosspad-mcp",
+  "description": "Development workflow server for CrossPad — build, test, run, screenshot, and navigate code",
+  "version": "4.0.0",
+  "repository": {
+    "url": "https://github.com/CrossPad/crosspad-mcp",
+    "source": "github",
+    "id": "CrossPad/crosspad-mcp"
+  },
+  "packages": [
+    {
+      "registry_type": "npm",
+      "registry_base_url": "https://registry.npmjs.org",
+      "identifier": "crosspad-mcp-server",
+      "version": "4.0.0",
+      "runtime_hint": "npx",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

package/src/config.ts

@@ -0,0 +1,45 @@
+import path from "path";
+import os from "os";
+
+export const IS_WINDOWS = process.platform === "win32";
+export const IS_MAC = process.platform === "darwin";
+
+// Base directory for all CrossPad repos (override with CROSSPAD_GIT_DIR)
+const defaultGitDir = IS_WINDOWS
+  ? "C:/Users/Mateusz/GIT"
+  : path.join(os.homedir(), "GIT");
+const GIT_DIR = process.env.CROSSPAD_GIT_DIR || defaultGitDir;
+
+export const CROSSPAD_PC_ROOT =
+  process.env.CROSSPAD_PC_ROOT || path.join(GIT_DIR, "crosspad-pc");
+
+export const REPOS: Record<string, string> = {
+  "crosspad-core": path.join(GIT_DIR, "crosspad-core"),
+  "crosspad-gui": path.join(GIT_DIR, "crosspad-gui"),
+  "crosspad-pc": CROSSPAD_PC_ROOT,
+  "ESP32-S3": path.join(GIT_DIR, "ESP32-S3"),
+  "2playerCrosspad": path.join(GIT_DIR, "P4_TEST", "2playerCrosspad"),
+  "crosspad-idf": path.join(GIT_DIR, "crosspad-idf"),
+};
+
+// MSVC — only used on Windows
+export const VCVARSALL =
+  process.env.VCVARSALL ||
+  "C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\VC\\Auxiliary\\Build\\vcvarsall.bat";
+
+// vcpkg — platform-aware defaults
+const defaultVcpkgRoot = IS_WINDOWS ? "C:/vcpkg" : path.join(os.homedir(), "vcpkg");
+const vcpkgRoot = process.env.VCPKG_ROOT || defaultVcpkgRoot;
+export const VCPKG_TOOLCHAIN = path.join(vcpkgRoot, "scripts", "buildsystems", "vcpkg.cmake");
+
+export const BUILD_DIR = path.join(CROSSPAD_PC_ROOT, "build");
+
+const EXE_EXT = IS_WINDOWS ? ".exe" : "";
+export const BIN_EXE = path.join(CROSSPAD_PC_ROOT, "bin", `CrossPad${EXE_EXT}`);
+
+// ESP-IDF
+export const CROSSPAD_IDF_ROOT =
+  process.env.CROSSPAD_IDF_ROOT || path.join(GIT_DIR, "crosspad-idf");
+
+const defaultIdfPath = path.join(os.homedir(), "esp", "v5.5", "esp-idf");
+export const IDF_PATH = process.env.IDF_PATH || defaultIdfPath;

package/src/index.ts

@@ -0,0 +1,484 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { crosspadBuild, crosspadRun } from "./tools/build.js";
+import { crosspadReposStatus } from "./tools/repos.js";
+import { crosspadScaffoldApp } from "./tools/scaffold.js";
+import { crosspadInterfaces, crosspadApps } from "./tools/architecture.js";
+import { crosspadBuildCheck } from "./tools/build-check.js";
+import { crosspadSearchSymbols } from "./tools/symbols.js";
+import { crosspadDiffCore } from "./tools/diff-core.js";
+import { crosspadLog } from "./tools/log.js";
+import { crosspadTest, crosspadTestScaffold } from "./tools/test.js";
+import { crosspadScreenshot } from "./tools/screenshot.js";
+import { crosspadInput, InputAction } from "./tools/input.js";
+import { crosspadSettingsGet, crosspadSettingsSet } from "./tools/settings.js";
+import { crosspadStats } from "./tools/stats.js";
+import { crosspadIdfBuild } from "./tools/idf-build.js";
+import type { OnLine } from "./utils/exec.js";
+import type { LoggingLevel } from "@modelcontextprotocol/sdk/types.js";
+
+const server = new McpServer(
+  {
+    name: "crosspad",
+    version: "4.0.0",
+  },
+  {
+    capabilities: {
+      logging: {},
+    },
+  }
+);
+
+/**
+ * Create an OnLine callback that streams each line to the MCP client
+ * via logging notifications. Build output is "info", errors are "error".
+ */
+function makeStreamLogger(logger: string): OnLine {
+  return (stream, line) => {
+    if (!line.trim()) return; // skip empty lines
+    const level: LoggingLevel = stream === "stderr" ? "warning" : "info";
+    server.server.sendLoggingMessage({ level, logger, data: line }).catch(() => {});
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// BUILD & RUN
+// ═══════════════════════════════════════════════════════════════════════
+
+server.tool(
+  "crosspad_build",
+  "Build crosspad-pc simulator (incremental, clean, or reconfigure)",
+  {
+    mode: z
+      .enum(["incremental", "clean", "reconfigure"])
+      .default("incremental")
+      .describe(
+        "incremental: just cmake --build. clean: delete build dir + full rebuild. reconfigure: cmake configure + build (use after adding new source files)"
+      ),
+  },
+  async ({ mode }) => {
+    const onLine = makeStreamLogger("build");
+    const result = await crosspadBuild(mode, onLine);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+server.tool(
+  "crosspad_run",
+  "Launch the crosspad-pc simulator (bin/CrossPad.exe). Returns immediately with PID.",
+  {},
+  async () => {
+    const result = crosspadRun();
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+server.tool(
+  "crosspad_build_check",
+  "Quick health check: is the build up to date? Detects stale exe, new source files needing reconfigure, submodule drift, dirty working trees. Use before build to know what mode to use.",
+  {},
+  async () => {
+    const result = crosspadBuildCheck();
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+server.tool(
+  "crosspad_log",
+  "Launch CrossPad.exe, capture stdout/stderr for a few seconds, then kill it. Great for checking init sequence, crash messages, or runtime errors without leaving the process running.",
+  {
+    timeout_seconds: z
+      .number()
+      .default(5)
+      .describe("How long to let the process run before killing it (default: 5)"),
+    max_lines: z
+      .number()
+      .default(200)
+      .describe("Max lines of output to return (default: 200)"),
+  },
+  async ({ timeout_seconds, max_lines }) => {
+    const onLine = makeStreamLogger("log");
+    const result = await crosspadLog(timeout_seconds, max_lines, onLine);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+// ═══════════════════════════════════════════════════════════════════════
+// ESP-IDF BUILD
+// ═══════════════════════════════════════════════════════════════════════
+
+server.tool(
+  "crosspad_idf_build",
+  "Build the crosspad-idf ESP32-S3 firmware using idf.py. Use fullclean after adding new app directories or CMakeLists.txt changes.",
+  {
+    mode: z
+      .enum(["build", "fullclean", "clean"])
+      .default("build")
+      .describe(
+        "build: incremental idf.py build. fullclean: idf.py fullclean + build (required after new app dirs). clean: delete build/ + build."
+      ),
+  },
+  async ({ mode }) => {
+    const onLine = makeStreamLogger("idf-build");
+    const result = await crosspadIdfBuild(mode, onLine);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+// ═══════════════════════════════════════════════════════════════════════
+// TEST
+// ═══════════════════════════════════════════════════════════════════════
+
+server.tool(
+  "crosspad_test",
+  "Build and run the Catch2 test suite. If no tests/ dir exists, tells you to scaffold. Supports filtering by test name.",
+  {
+    filter: z
+      .string()
+      .default("")
+      .describe("Catch2 test name filter (e.g. '[core]' or 'PadManager')"),
+    list_only: z
+      .boolean()
+      .default(false)
+      .describe("Just list available tests without running them"),
+  },
+  async ({ filter, list_only }) => {
+    const onLine = makeStreamLogger("test");
+    const result = await crosspadTest(filter, list_only, onLine);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+server.tool(
+  "crosspad_test_scaffold",
+  "Generate test infrastructure: tests/CMakeLists.txt (Catch2 v3), sample test file, and CMake patch instructions. Returns file contents — does NOT write to disk.",
+  {},
+  async () => {
+    const result = crosspadTestScaffold();
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+// ═══════════════════════════════════════════════════════════════════════
+// REPOS & SUBMODULES
+// ═══════════════════════════════════════════════════════════════════════
+
+server.tool(
+  "crosspad_repos_status",
+  "Show git status across all CrossPad repos (crosspad-core, crosspad-gui, crosspad-pc, ESP32-S3, 2playerCrosspad). Detects dev-mode vs submodule-mode and checks submodule pin sync.",
+  {},
+  async () => {
+    const result = crosspadReposStatus();
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+server.tool(
+  "crosspad_diff_core",
+  "Show what changed in crosspad-core and/or crosspad-gui relative to the pinned submodule commit. Shows commits ahead/behind, changed files, uncommitted changes. Essential for dev-mode workflows.",
+  {
+    submodule: z
+      .enum(["crosspad-core", "crosspad-gui", "both"])
+      .default("both")
+      .describe("Which submodule(s) to diff"),
+  },
+  async ({ submodule }) => {
+    const result = crosspadDiffCore(submodule);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+// ═══════════════════════════════════════════════════════════════════════
+// CODE & ARCHITECTURE
+// ═══════════════════════════════════════════════════════════════════════
+
+server.tool(
+  "crosspad_search_symbols",
+  "Search for classes, functions, macros, enums across all CrossPad repos. Faster than manual grep — uses git grep under the hood.",
+  {
+    query: z.string().describe("Symbol name or substring to search for"),
+    kind: z
+      .enum(["class", "function", "macro", "enum", "typedef", "all"])
+      .default("all")
+      .describe("Filter by symbol kind"),
+    repos: z
+      .array(z.string())
+      .default(["all"])
+      .describe('Repo names to search: "crosspad-core", "crosspad-pc", "ESP32-S3", etc. or ["all"]'),
+    max_results: z
+      .number()
+      .default(50)
+      .describe("Max results to return"),
+  },
+  async ({ query, kind, repos, max_results }) => {
+    const result = crosspadSearchSymbols(query, kind, repos, max_results);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+server.tool(
+  "crosspad_scaffold_app",
+  "Generate boilerplate for a new CrossPad app (cpp, hpp, CMakeLists.txt, optional pad logic). Returns file contents for Claude to write — does NOT create files on disk.",
+  {
+    name: z
+      .string()
+      .describe("PascalCase app name, e.g. 'Metronome'"),
+    display_name: z
+      .string()
+      .optional()
+      .describe("Human-readable name (defaults to name)"),
+    has_pad_logic: z
+      .boolean()
+      .default(false)
+      .describe("Generate IPadLogicHandler stub"),
+    icon: z
+      .string()
+      .default("CrossPad_Logo_110w.png")
+      .describe("Icon filename"),
+  },
+  async ({ name, display_name, has_pad_logic, icon }) => {
+    const result = crosspadScaffoldApp({
+      name,
+      display_name,
+      has_pad_logic,
+      icon,
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+server.tool(
+  "crosspad_interfaces",
+  'Query crosspad-core interfaces and their implementations across all platforms. Use query="list" to list all interfaces, "implementations <InterfaceName>" to find implementations, or "capabilities" to show platform capability flags.',
+  {
+    query: z
+      .string()
+      .describe(
+        '"list", "implementations <InterfaceName>", or "capabilities"'
+      ),
+  },
+  async ({ query }) => {
+    const result = crosspadInterfaces(query);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+server.tool(
+  "crosspad_apps",
+  "List all registered CrossPad apps (found via REGISTER_APP macro or _register_*_app functions).",
+  {
+    platform: z
+      .enum(["pc", "esp32", "2player", "all"])
+      .default("pc")
+      .describe("Which platform to scan"),
+  },
+  async ({ platform }) => {
+    const result = crosspadApps(platform);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+// ═══════════════════════════════════════════════════════════════════════
+// SIMULATOR INTERACTION (requires running simulator with remote control)
+// ═══════════════════════════════════════════════════════════════════════
+
+server.tool(
+  "crosspad_screenshot",
+  "Capture a screenshot from the running CrossPad simulator. Saves PNG to screenshots/ dir by default. Requires the simulator to be running (use crosspad_run first).",
+  {
+    save_to_file: z
+      .boolean()
+      .default(true)
+      .describe("Save to disk (default: true). If false, returns base64 data inline."),
+    filename: z
+      .string()
+      .optional()
+      .describe("Custom filename (default: screenshot_<timestamp>.png)"),
+    region: z
+      .enum(["full", "lcd"])
+      .default("full")
+      .describe("full: entire simulator window (490x680). lcd: LCD screen only (320x240)."),
+  },
+  async ({ save_to_file, filename, region }) => {
+    const result = await crosspadScreenshot(save_to_file, filename, region);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+server.tool(
+  "crosspad_input",
+  `Send input events to the running CrossPad simulator. Requires simulator to be running.
+
+Actions:
+  click {x, y}           — mouse click at window coordinates (490x680 window)
+  pad_press {pad, vel}    — press pad 0-15 with velocity 0-127
+  pad_release {pad}       — release pad 0-15
+  encoder_rotate {delta}  — rotate encoder (positive=CW, negative=CCW)
+  encoder_press           — press encoder button
+  encoder_release         — release encoder button
+  key {keycode}           — SDL keycode (e.g. 13=Enter, 27=Escape)
+
+LCD area is centered at roughly x=85..405, y=20..260 within the 490x680 window.`,
+  {
+    action: z
+      .enum(["click", "pad_press", "pad_release", "encoder_rotate", "encoder_press", "encoder_release", "key"])
+      .describe("Input action type"),
+    x: z.number().optional().describe("X coordinate for click"),
+    y: z.number().optional().describe("Y coordinate for click"),
+    pad: z.number().optional().describe("Pad index 0-15 for pad_press/pad_release"),
+    velocity: z.number().optional().describe("Velocity 0-127 for pad_press (default: 127)"),
+    delta: z.number().optional().describe("Rotation delta for encoder_rotate"),
+    keycode: z.number().optional().describe("SDL keycode for key action"),
+  },
+  async ({ action, x, y, pad, velocity, delta, keycode }) => {
+    let input: InputAction;
+
+    switch (action) {
+      case "click":
+        input = { action: "click", x: x ?? 0, y: y ?? 0 };
+        break;
+      case "pad_press":
+        input = { action: "pad_press", pad: pad ?? 0, velocity: velocity ?? 127 };
+        break;
+      case "pad_release":
+        input = { action: "pad_release", pad: pad ?? 0 };
+        break;
+      case "encoder_rotate":
+        input = { action: "encoder_rotate", delta: delta ?? 1 };
+        break;
+      case "encoder_press":
+        input = { action: "encoder_press" };
+        break;
+      case "encoder_release":
+        input = { action: "encoder_release" };
+        break;
+      case "key":
+        input = { action: "key", keycode: keycode ?? 0 };
+        break;
+      default:
+        return {
+          content: [{ type: "text", text: JSON.stringify({ success: false, error: "Unknown action" }) }],
+        };
+    }
+
+    const result = await crosspadInput(input);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+server.tool(
+  "crosspad_stats",
+  `Query runtime statistics from the running simulator. Returns:
+- Platform capabilities (active flags)
+- Pad state (16 pads: pressed, playing, note, channel, RGB color)
+- Active/registered pad logic handlers
+- Registered apps list
+- Heap stats (SRAM/PSRAM free/total)
+- Settings summary (brightness, theme, kit, audio engine)`,
+  {},
+  async () => {
+    const result = await crosspadStats();
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+server.tool(
+  "crosspad_settings",
+  `Read or write CrossPad settings on the running simulator.
+
+Read: action="get", category="all"|"display"|"keypad"|"vibration"|"wireless"|"audio"|"system"
+Write: action="set", key="<setting_key>", value=<number> (booleans: 0/1)
+
+Writable keys:
+  lcd_brightness (0-255), rgb_brightness (0-255), theme_color (0-255), perf_stats_flags (bitmask)
+  kit (0-255), audio_engine (0/1)
+  keypad.enable, keypad.inactive_lights, keypad.eco_mode, keypad.send_stm/ble/usb/cc (0/1)
+  vibration.enable, vibration.on_touch, vibration.in_min/max, vibration.out_min/max (0-255)
+  master_fx.mute (0/1), master_fx.in_volume, master_fx.out_volume (0-100)
+
+Changes are auto-saved to ~/.crosspad/preferences.json.`,
+  {
+    action: z
+      .enum(["get", "set"])
+      .describe("Read or write settings"),
+    category: z
+      .string()
+      .default("all")
+      .describe("For get: all, display, keypad, vibration, wireless, audio, system"),
+    key: z
+      .string()
+      .optional()
+      .describe("For set: dotted key name (e.g. 'lcd_brightness', 'keypad.eco_mode')"),
+    value: z
+      .number()
+      .optional()
+      .describe("For set: numeric value (booleans: 0=false, 1=true)"),
+  },
+  async ({ action, category, key, value }) => {
+    if (action === "get") {
+      const result = await crosspadSettingsGet(category);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    } else {
+      if (!key || value === undefined) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ success: false, error: "key and value required for set" }) }],
+        };
+      }
+      const result = await crosspadSettingsSet(key, value);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    }
+  }
+);
+
+// ═══════════════════════════════════════════════════════════════════════
+// START
+// ═══════════════════════════════════════════════════════════════════════
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("MCP server failed:", err);
+  process.exit(1);
+});