crosspad-mcp-server 4.0.0

package/src/tools/screenshot.ts

@@ -0,0 +1,100 @@
+/**
+ * MCP tool: capture a screenshot from the running CrossPad simulator.
+ * The simulator encodes PNG natively via stb_image_write.
+ *
+ * When saving to file, the simulator writes the PNG directly to disk
+ * (no base64 round-trip over TCP). Otherwise returns inline base64.
+ */
+
+import { sendRemoteCommand, isSimulatorRunning } from "../utils/remote-client.js";
+import fs from "fs";
+import path from "path";
+import { CROSSPAD_PC_ROOT } from "../config.js";
+
+export interface ScreenshotResult {
+  success: boolean;
+  width?: number;
+  height?: number;
+  format?: string;
+  file_path?: string;
+  data_base64?: string;
+  size?: number;
+  error?: string;
+}
+
+/**
+ * Take a screenshot of the simulator window.
+ * @param save_to_file If true, simulator writes PNG directly to disk (fast path).
+ * @param filename     Custom filename (default: screenshot_<timestamp>.png)
+ * @param region       "full" for entire window (490x680), "lcd" for LCD only (320x240)
+ */
+export async function crosspadScreenshot(
+  saveToFile: boolean = true,
+  filename?: string,
+  region: "full" | "lcd" = "full"
+): Promise<ScreenshotResult> {
+  const running = await isSimulatorRunning();
+  if (!running) {
+    return {
+      success: false,
+      error: "Simulator is not running. Use crosspad_run to start it.",
+    };
+  }
+
+  try {
+    if (saveToFile) {
+      // Fast path: simulator writes PNG directly to disk
+      const fname = filename || `screenshot_${Date.now()}.png`;
+      const screenshotsDir = path.join(CROSSPAD_PC_ROOT, "screenshots");
+      if (!fs.existsSync(screenshotsDir)) {
+        fs.mkdirSync(screenshotsDir, { recursive: true });
+      }
+      const filePath = path.join(screenshotsDir, fname).replace(/\\/g, "/");
+
+      const cmd: Record<string, unknown> = { cmd: "screenshot", file: filePath };
+      if (region === "lcd") cmd.region = "lcd";
+      const resp = await sendRemoteCommand(cmd);
+
+      if (!resp.ok) {
+        return {
+          success: false,
+          error: (resp.error as string) || "Screenshot failed",
+        };
+      }
+
+      return {
+        success: true,
+        width: resp.width as number,
+        height: resp.height as number,
+        format: "png",
+        file_path: filePath,
+        size: resp.size as number,
+      };
+    }
+
+    // Inline path: returns base64-encoded PNG
+    const inlineCmd: Record<string, unknown> = { cmd: "screenshot" };
+    if (region === "lcd") inlineCmd.region = "lcd";
+    const resp = await sendRemoteCommand(inlineCmd);
+
+    if (!resp.ok) {
+      return {
+        success: false,
+        error: (resp.error as string) || "Screenshot failed",
+      };
+    }
+
+    return {
+      success: true,
+      width: resp.width as number,
+      height: resp.height as number,
+      format: "png",
+      data_base64: resp.data as string,
+    };
+  } catch (err: any) {
+    return {
+      success: false,
+      error: err.message,
+    };
+  }
+}

package/src/tools/settings.ts

@@ -0,0 +1,68 @@
+/**
+ * MCP tool: read/write CrossPad settings via the running simulator.
+ */
+
+import { sendRemoteCommand, isSimulatorRunning } from "../utils/remote-client.js";
+
+export interface SettingsGetResult {
+  success: boolean;
+  settings?: Record<string, unknown>;
+  error?: string;
+}
+
+export interface SettingsSetResult {
+  success: boolean;
+  key?: string;
+  value?: number;
+  error?: string;
+}
+
+/**
+ * Read settings from the running simulator.
+ * @param category  "all", "display", "keypad", "vibration", "wireless", "audio", "system"
+ */
+export async function crosspadSettingsGet(
+  category: string = "all"
+): Promise<SettingsGetResult> {
+  const running = await isSimulatorRunning();
+  if (!running) {
+    return { success: false, error: "Simulator is not running. Use crosspad_run to start it." };
+  }
+
+  try {
+    const resp = await sendRemoteCommand({ cmd: "settings_get", category });
+    if (!resp.ok) {
+      return { success: false, error: (resp.error as string) || "settings_get failed" };
+    }
+    // Remove 'ok' field, pass the rest as settings
+    const { ok, ...settings } = resp;
+    return { success: true, settings };
+  } catch (err: any) {
+    return { success: false, error: err.message };
+  }
+}
+
+/**
+ * Write a single setting on the running simulator.
+ * @param key    Dotted key name (e.g. "lcd_brightness", "keypad.eco_mode", "vibration.enable")
+ * @param value  Numeric value (booleans: 0=false, 1=true)
+ */
+export async function crosspadSettingsSet(
+  key: string,
+  value: number
+): Promise<SettingsSetResult> {
+  const running = await isSimulatorRunning();
+  if (!running) {
+    return { success: false, error: "Simulator is not running. Use crosspad_run to start it." };
+  }
+
+  try {
+    const resp = await sendRemoteCommand({ cmd: "settings_set", key, value });
+    if (!resp.ok) {
+      return { success: false, error: (resp.error as string) || "settings_set failed" };
+    }
+    return { success: true, key: resp.key as string, value: resp.value as number };
+  } catch (err: any) {
+    return { success: false, error: err.message };
+  }
+}

package/src/tools/stats.ts

@@ -0,0 +1,38 @@
+/**
+ * MCP tool: read runtime statistics from the running CrossPad simulator.
+ */
+
+import { sendRemoteCommand, isSimulatorRunning } from "../utils/remote-client.js";
+
+export interface StatsResult {
+  success: boolean;
+  stats?: Record<string, unknown>;
+  error?: string;
+}
+
+/**
+ * Query runtime statistics from the simulator:
+ * - Platform capabilities (active flags)
+ * - Pad state (16 pads: pressed, playing, note, channel, RGB color)
+ * - Active pad logic handler + registered handlers
+ * - Registered apps
+ * - Heap stats (SRAM/PSRAM)
+ * - Settings summary (brightness, theme, kit, audio engine)
+ */
+export async function crosspadStats(): Promise<StatsResult> {
+  const running = await isSimulatorRunning();
+  if (!running) {
+    return { success: false, error: "Simulator is not running. Use crosspad_run to start it." };
+  }
+
+  try {
+    const resp = await sendRemoteCommand({ cmd: "stats" });
+    if (!resp.ok) {
+      return { success: false, error: (resp.error as string) || "stats failed" };
+    }
+    const { ok, ...stats } = resp;
+    return { success: true, stats };
+  } catch (err: any) {
+    return { success: false, error: err.message };
+  }
+}

package/src/tools/symbols.ts

@@ -0,0 +1,185 @@
+import fs from "fs";
+import { REPOS } from "../config.js";
+import { runCommand } from "../utils/exec.js";
+
+export interface SymbolResult {
+  symbol: string;
+  kind: "class" | "function" | "macro" | "enum" | "typedef";
+  file: string;
+  line: number;
+  context: string;
+  repo: string;
+}
+
+export interface SymbolSearchResult {
+  query: string;
+  kind_filter: string;
+  results: SymbolResult[];
+  total_matches: number;
+  truncated: boolean;
+}
+
+/**
+ * Build a regex pattern that matches definition lines containing the query.
+ * Each kind has a specific pattern that only matches declarations/definitions.
+ */
+function buildPattern(query: string, kind: string): string {
+  const q = query; // Already escaped by caller
+  const patterns: string[] = [];
+
+  if (kind === "class" || kind === "all") {
+    // class/struct definition: class Foo { or class Foo : public Bar {
+    patterns.push(`(class|struct)\\s+\\w*${q}\\w*\\s*[:{]`);
+    patterns.push(`(class|struct)\\s+\\w*${q}\\w*\\s*$`); // multi-line def
+  }
+  if (kind === "macro" || kind === "all") {
+    patterns.push(`#define\\s+\\w*${q}\\w*`);
+  }
+  if (kind === "enum" || kind === "all") {
+    patterns.push(`enum\\s+(class\\s+)?\\w*${q}\\w*`);
+  }
+  if (kind === "typedef" || kind === "all") {
+    patterns.push(`using\\s+\\w*${q}\\w*\\s*=`);
+    patterns.push(`typedef\\s+.*\\b\\w*${q}\\w*\\s*;`);
+  }
+  if (kind === "function" || kind === "all") {
+    // Function definition: type name( or void name(  — exclude calls by requiring return type or line start
+    patterns.push(`^\\w[\\w:\\s*&<>]+\\b\\w*${q}\\w*\\s*\\(`);
+  }
+
+  return patterns.join("|");
+}
+
+/**
+ * Search for symbol definitions (classes, functions, macros, enums) across CrossPad repos.
+ * Only matches definition lines, not usages.
+ */
+export function crosspadSearchSymbols(
+  query: string,
+  kind: string = "all",
+  repos: string[] = ["all"],
+  maxResults: number = 50
+): SymbolSearchResult {
+  const results: SymbolResult[] = [];
+
+  const targetRepos = repos.includes("all")
+    ? Object.entries(REPOS)
+    : Object.entries(REPOS).filter(([name]) => repos.includes(name));
+
+  const pattern = buildPattern(escapeForRegex(query), kind);
+  if (!pattern) {
+    return { query, kind_filter: kind, results: [], total_matches: 0, truncated: false };
+  }
+
+  for (const [repoName, repoPath] of targetRepos) {
+    if (!fs.existsSync(repoPath)) continue;
+
+    const grepCmd = `git grep -n -E "${escapeForShell(pattern)}" -- "*.hpp" "*.h" "*.cpp" "*.c"`;
+    const result = runCommand(grepCmd, repoPath, 30_000);
+
+    if (!result.success && result.stdout.length === 0) continue;
+
+    for (const line of result.stdout.split("\n")) {
+      if (!line.trim()) continue;
+
+      const match = line.match(/^([^:]+):(\d+):(.*)$/);
+      if (!match) continue;
+
+      const [, file, lineStr, content] = match;
+      const lineNum = parseInt(lineStr, 10);
+      const trimmedContent = content.trim();
+
+      // Skip forward declarations (class Foo;)
+      if (/^\s*(class|struct)\s+\w+\s*;/.test(trimmedContent)) continue;
+      // Skip includes
+      if (/^\s*#include/.test(trimmedContent)) continue;
+      // Skip comments
+      if (/^\s*(\/\/|\/\*|\*)/.test(trimmedContent)) continue;
+
+      const detectedKind = classifyDefinition(trimmedContent);
+      if (!detectedKind) continue;
+      if (kind !== "all" && detectedKind !== kind) continue;
+
+      const symbolName = extractSymbolName(trimmedContent, detectedKind);
+      if (!symbolName) continue;
+
+      // Symbol name must contain query
+      if (!symbolName.toLowerCase().includes(query.toLowerCase())) continue;
+
+      // Deduplicate by symbol+file
+      const key = `${symbolName}:${file}`;
+      if (results.some((r) => `${r.symbol}:${r.file.split("/").pop()}` === key)) continue;
+
+      results.push({
+        symbol: symbolName,
+        kind: detectedKind,
+        file: `${repoPath}/${file}`.replace(/\\/g, "/"),
+        line: lineNum,
+        context: trimmedContent.slice(0, 150),
+        repo: repoName,
+      });
+
+      if (results.length >= maxResults) break;
+    }
+
+    if (results.length >= maxResults) break;
+  }
+
+  return {
+    query,
+    kind_filter: kind,
+    results: results.slice(0, maxResults),
+    total_matches: results.length,
+    truncated: results.length >= maxResults,
+  };
+}
+
+function escapeForShell(s: string): string {
+  // Only escape shell metacharacters, NOT backslashes (needed for regex \s \w etc.)
+  return s.replace(/["`$]/g, "\\$&");
+}
+
+function escapeForRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function classifyDefinition(line: string): SymbolResult["kind"] | null {
+  if (/^\s*#define\s+/.test(line)) return "macro";
+  if (/^\s*enum\s+/.test(line)) return "enum";
+  if (/^\s*(typedef|using)\s+/.test(line)) return "typedef";
+  if (/^\s*(class|struct)\s+\w+/.test(line)) return "class";
+  // Function: starts with type qualifier, has word( pattern
+  if (/^[\w:][\w:\s*&<>,]*\b\w+\s*\(/.test(line) &&
+      !/^\s*(if|while|for|switch|return|delete|new|throw|sizeof)\b/.test(line)) {
+    return "function";
+  }
+  return null;
+}
+
+function extractSymbolName(line: string, kind: SymbolResult["kind"]): string | null {
+  switch (kind) {
+    case "class": {
+      const m = line.match(/(?:class|struct)\s+(\w+)/);
+      return m ? m[1] : null;
+    }
+    case "macro": {
+      const m = line.match(/#define\s+(\w+)/);
+      return m ? m[1] : null;
+    }
+    case "enum": {
+      const m = line.match(/enum\s+(?:class\s+)?(\w+)/);
+      return m ? m[1] : null;
+    }
+    case "typedef": {
+      const m = line.match(/using\s+(\w+)\s*=/) || line.match(/typedef\s+.*\b(\w+)\s*;/);
+      return m ? m[1] : null;
+    }
+    case "function": {
+      // Last word before opening paren: returnType funcName(
+      const m = line.match(/\b(\w+)\s*\(/);
+      return m ? m[1] : null;
+    }
+    default:
+      return null;
+  }
+}

package/src/tools/test.ts

@@ -0,0 +1,264 @@
+import fs from "fs";
+import path from "path";
+import { CROSSPAD_PC_ROOT, VCPKG_TOOLCHAIN } from "../config.js";
+import { runBuild, runBuildStream, OnLine } from "../utils/exec.js";
+import { IS_WINDOWS } from "../config.js";
+
+export interface TestResult {
+  success: boolean;
+  tests_found: boolean;
+  build_output: string;
+  test_output: string;
+  passed: number;
+  failed: number;
+  errors: string[];
+  duration_seconds: number;
+}
+
+const TESTS_DIR = path.join(CROSSPAD_PC_ROOT, "tests");
+const BIN_DIR = path.join(CROSSPAD_PC_ROOT, "bin");
+const EXE_EXT = IS_WINDOWS ? ".exe" : "";
+const TEST_EXE = path.join(BIN_DIR, `crosspad_tests${EXE_EXT}`);
+
+/**
+ * Build and run the crosspad test suite (Catch2).
+ * If tests/ dir doesn't exist, offers to scaffold it.
+ */
+export async function crosspadTest(
+  filter: string = "",
+  listOnly: boolean = false,
+  onLine?: OnLine
+): Promise<TestResult> {
+  const startTime = Date.now();
+
+  // Check if test infrastructure exists
+  if (!fs.existsSync(TESTS_DIR)) {
+    return {
+      success: false,
+      tests_found: false,
+      build_output: "",
+      test_output: `No tests/ directory found. Use crosspad_test_scaffold to create test infrastructure.`,
+      passed: 0,
+      failed: 0,
+      errors: ["tests/ directory not found"],
+      duration_seconds: 0,
+    };
+  }
+
+  // Ensure cmake is configured with BUILD_TESTING=ON
+  onLine?.("stdout", "[crosspad] Configuring cmake with BUILD_TESTING=ON...");
+
+  const generator = process.env.CMAKE_GENERATOR || (IS_WINDOWS ? "Ninja" : "");
+  const genFlag = generator ? ` -G ${generator}` : "";
+  const configCmd = `cmake -B build${genFlag} -DCMAKE_TOOLCHAIN_FILE=${VCPKG_TOOLCHAIN} -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON`;
+
+  let configResult;
+  if (onLine) {
+    configResult = await runBuildStream(configCmd, CROSSPAD_PC_ROOT, onLine, 120_000);
+  } else {
+    configResult = runBuild(configCmd, CROSSPAD_PC_ROOT, 120_000);
+  }
+
+  if (!configResult.success) {
+    return {
+      success: false,
+      tests_found: true,
+      build_output: (configResult.stdout + "\n" + configResult.stderr).slice(-3000),
+      test_output: "",
+      passed: 0,
+      failed: 0,
+      errors: parseErrors(configResult.stdout + "\n" + configResult.stderr),
+      duration_seconds: (Date.now() - startTime) / 1000,
+    };
+  }
+
+  // Build tests target
+  onLine?.("stdout", "[crosspad] Building test target...");
+
+  const buildCmd = "cmake --build build --target crosspad_tests";
+  let buildResult;
+  if (onLine) {
+    buildResult = await runBuildStream(buildCmd, CROSSPAD_PC_ROOT, onLine, 300_000);
+  } else {
+    buildResult = runBuild(buildCmd, CROSSPAD_PC_ROOT, 300_000);
+  }
+
+  if (!buildResult.success) {
+    return {
+      success: false,
+      tests_found: true,
+      build_output: (buildResult.stdout + "\n" + buildResult.stderr).slice(-3000),
+      test_output: "",
+      passed: 0,
+      failed: 0,
+      errors: parseErrors(buildResult.stdout + "\n" + buildResult.stderr),
+      duration_seconds: (Date.now() - startTime) / 1000,
+    };
+  }
+
+  if (!fs.existsSync(TEST_EXE)) {
+    return {
+      success: false,
+      tests_found: true,
+      build_output: buildResult.stdout.slice(-1000),
+      test_output: "Test executable not found after build",
+      passed: 0,
+      failed: 0,
+      errors: [`${TEST_EXE} not found`],
+      duration_seconds: (Date.now() - startTime) / 1000,
+    };
+  }
+
+  // Run tests
+  let testCmd = `"${TEST_EXE}"`;
+  if (listOnly) {
+    testCmd += " --list-tests";
+  } else {
+    testCmd += " --reporter compact";
+    if (filter) {
+      testCmd += ` "${filter}"`;
+    }
+  }
+
+  onLine?.("stdout", "[crosspad] Running tests...");
+
+  let testResult;
+  if (onLine) {
+    testResult = await runBuildStream(testCmd, CROSSPAD_PC_ROOT, onLine, 120_000);
+  } else {
+    testResult = runBuild(testCmd, CROSSPAD_PC_ROOT, 120_000);
+  }
+
+  const testOutput = testResult.stdout + "\n" + testResult.stderr;
+
+  // Parse Catch2 compact output
+  const { passed, failed } = parseCatch2Output(testOutput);
+
+  const result: TestResult = {
+    success: testResult.success,
+    tests_found: true,
+    build_output: buildResult.stdout.slice(-500),
+    test_output: testOutput.slice(-5000),
+    passed,
+    failed,
+    errors: testResult.success ? [] : parseErrors(testOutput),
+    duration_seconds: (Date.now() - startTime) / 1000,
+  };
+
+  onLine?.("stdout", `[crosspad] Tests ${result.success ? "PASSED" : "FAILED"}: ${passed} passed, ${failed} failed (${result.duration_seconds.toFixed(1)}s)`);
+
+  return result;
+}
+
+/**
+ * Scaffold the test infrastructure: CMakeLists.txt additions + sample test file.
+ * Returns file contents — does NOT write to disk.
+ */
+export function crosspadTestScaffold(): { files: Record<string, string>; cmake_patch: string } {
+  const files: Record<string, string> = {};
+
+  // tests/CMakeLists.txt
+  files["tests/CMakeLists.txt"] = `# CrossPad test suite — Catch2 v3
+Include(FetchContent)
+
+FetchContent_Declare(
+  Catch2
+  GIT_REPOSITORY https://github.com/catchorg/Catch2.git
+  GIT_TAG        v3.5.2
+)
+FetchContent_MakeAvailable(Catch2)
+
+# Collect test sources
+file(GLOB_RECURSE TEST_SOURCES "\${CMAKE_CURRENT_SOURCE_DIR}/*.cpp")
+
+add_executable(crosspad_tests \${TEST_SOURCES})
+
+target_link_libraries(crosspad_tests PRIVATE
+  Catch2::Catch2WithMain
+)
+
+# Include crosspad-core headers (for testing core logic)
+target_include_directories(crosspad_tests PRIVATE
+  \${CMAKE_SOURCE_DIR}/crosspad-core/include
+  \${CMAKE_SOURCE_DIR}/crosspad-gui/include
+  \${CMAKE_SOURCE_DIR}/src
+)
+
+# Same defines as main target
+target_compile_definitions(crosspad_tests PRIVATE
+  PLATFORM_PC=1
+  CP_LCD_HOR_RES=320
+  CP_LCD_VER_RES=240
+)
+
+# Add crosspad-core sources we want to test (non-platform-specific)
+# Add individual source files as needed:
+# target_sources(crosspad_tests PRIVATE
+#   \${CMAKE_SOURCE_DIR}/crosspad-core/src/SomeFile.cpp
+# )
+
+include(CTest)
+include(Catch)
+catch_discover_tests(crosspad_tests)
+`;
+
+  // tests/test_pad_manager.cpp — sample test
+  files["tests/test_pad_manager.cpp"] = `#include <catch2/catch_test_macros.hpp>
+
+// Example: test crosspad-core types without full platform init
+// #include <crosspad/pad/PadManager.hpp>
+// #include <crosspad/platform/PlatformCapabilities.hpp>
+
+TEST_CASE("Sanity check", "[core]") {
+    REQUIRE(1 + 1 == 2);
+}
+
+// TEST_CASE("PlatformCapabilities bitflags", "[core][capabilities]") {
+//     using crosspad::Capability;
+//     using crosspad::setPlatformCapabilities;
+//     using crosspad::hasCapability;
+//     using crosspad::hasAnyCapability;
+//
+//     setPlatformCapabilities(Capability::Midi | Capability::Pads);
+//
+//     REQUIRE(hasCapability(Capability::Midi));
+//     REQUIRE(hasCapability(Capability::Pads));
+//     REQUIRE_FALSE(hasCapability(Capability::AudioOut));
+//     REQUIRE(hasAnyCapability(Capability::Midi | Capability::AudioOut));
+// }
+`;
+
+  // Patch for root CMakeLists.txt
+  const cmakePatch = `
+# Add this near the end of your CMakeLists.txt, before any final install/packaging:
+# --- Test suite ---
+if(EXISTS "\${CMAKE_SOURCE_DIR}/tests/CMakeLists.txt")
+  add_subdirectory(tests)
+endif()
+`;
+
+  return { files, cmake_patch: cmakePatch };
+}
+
+function parseCatch2Output(output: string): { passed: number; failed: number } {
+  // Catch2 compact reporter: "Passed X test(s)" / "Failed X test(s)"
+  const passedMatch = output.match(/(\d+)\s+assertion[s]?\s+.*passed/i) ||
+                      output.match(/All tests passed\s*\((\d+)/i);
+  const failedMatch = output.match(/(\d+)\s+assertion[s]?\s+.*failed/i) ||
+                      output.match(/test cases?:\s*\d+\s*\|\s*(\d+)\s+failed/i);
+
+  return {
+    passed: passedMatch ? parseInt(passedMatch[1], 10) : 0,
+    failed: failedMatch ? parseInt(failedMatch[1], 10) : 0,
+  };
+}
+
+function parseErrors(output: string): string[] {
+  const errors: string[] = [];
+  for (const line of output.split("\n")) {
+    if (/\berror\b/i.test(line) && !line.includes("error(s)")) {
+      errors.push(line.trim());
+    }
+  }
+  return errors.slice(0, 20);
+}