crosspad-mcp-server

[PC] Launch the built simulator binary in the background. Returns pid + exe_path. Refuses to spawn a duplicate if one is already responding on the TCP control port (use force=true to override). Fails if binary not built — call crosspad_build first. Currently PC-only (IDF firmware doesn't run on the …

[PC sim] Stop the running PC simulator. Identifies the process by /proc/<pid>/exe match against the built binary (Linux) or pgrep -x basename (macOS/Windows), sends SIGTERM, waits up to 3s, then SIGKILL stragglers. Returns killed PIDs and whether anything still answers on the TCP control port. Curre…

[PC] Health check for a build — detects stale exe, new sources missing from build system, dirty submodules. Use before crosspad_build to decide if rebuild needed. Currently PC-only.

[ESP HW] List all connected USB serial devices. Identifies CrossPad devices separately and tags each with `kind`: 'esp-native' (rev <2.0, ESP32-S3 native USB, VID 0x303a/PID 0x3456) or 'stm-bridge' (rev 2.0, STM32 composite CDC+MIDI bridge, VID 0x0483/PID 0x5740 — STM programs the ESP over LPUART2).

[PC] Build and run the Catch2 test suite for crosspad-pc. PREFER THIS over invoking the test binary directly — configures cmake with BUILD_TESTING=ON, parses Catch2 output into passed/failed counts and errors, supports filter and list_only. Pass `labels` to run the GUI harness instead: those cases l…

[PC sim] Read runtime statistics from the running PC simulator: pad state, capabilities, heap, registered apps, active pad logic.

[PC sim] Read settings from the running simulator.

[PC sim] Write a single setting on the running simulator.

Git status across ALL detected CrossPad repos in one call: branch, HEAD, dirty files, submodule sync state. PREFER THIS over running `git status` per repo — handles the 5-repo monorepo layout in one shot.

Show submodule drift in a parent repo (crosspad-pc or platform-idf): commits ahead/behind pinned, changed files, uncommitted work. Use to inspect dev-mode work before pinning.

Update a submodule in a parent repo to the latest commit on a tracking branch (git fetch + checkout origin/<branch> + stage). Destructive: discards local commits in the submodule that aren't on the remote branch.

Commit staged changes in a specific CrossPad repo. PREFER THIS over raw `git commit` — handles repo aliases (idf/pc/arduino/core/gui), refuses on merge conflicts, uses 0600 tempfiles for messages (no shell-quoting issues with quotes/newlines/backticks), and never pushes. Stages files[] first if supp…

Search for symbol DEFINITIONS (classes, functions, macros, enums, typedefs) across CrossPad repos via git grep. PREFER THIS over raw `grep -r` or `git grep` — it filters to definitions only (skips call sites/declarations), classifies kind, and aggregates across all repos automatically. Substring mat…

List all crosspad-core interfaces (I*-prefixed classes in crosspad-core/include/crosspad/).

Find all classes implementing a given interface across CrossPad repos. Returns className, file path, platform. Use crosspad_list_interfaces first if you don't know exact names.

List platform capability flags (Capability enum) and which capabilities each platform sets.

List apps registered via REGISTER_APP() macro by scanning source files. Different from crosspad_apps_list (which reads the package registry).

List apps from the crosspad-apps registry, aggregating installation status across all detected platform repos. Reads JSON; no Python required. Different from crosspad_list_apps_source (which scans REGISTER_APP() in source code).

Install an app from the crosspad-apps registry as a git submodule. Requires gh CLI authenticated. Delegates to <repo>/{tools|scripts}/app_manager.py.

Remove an installed app submodule from a platform repo. Delegates to app_manager.py.

Sync a platform's apps.json manifest with existing submodules (rebuild manifest from disk state).

The crosspad-core abstraction layer, three ways. action=interfaces lists the I*-prefixed interfaces in crosspad-core/include/crosspad/. action=implementations finds every class implementing one, across all repos, with the platform it belongs to (run action=interfaces first if you do not know the exa…

[ESP HW] Record what the CrossPad is playing, through its own UAC2 endpoint — one cable, no external interface. start returns a cap_N handle and records in the background so you can drive the pads meanwhile; stop returns the WAV as a link with peak/rms dBFS, overruns and whether the take was silent.…

Offline analysis of a WAV — touches no hardware. onset: did the hits land, and when (pass the times you played as `expected`)? click: are there glitches in the render? silence: is this path dead? multitone: does the loopback reproduce the tones? velocity: does loudness track velocity monotonically? …

[ESP HW] Typed CDC control verbs (main/hil_control.cpp) through the crosspad-hil daemon. verb=app {list|start name|stop|destroy|self_close|versions}, kit {list|status|load kit_id}, pad {press idx vel|release idx|pressure idx val|stats [reset]|notes|info idx}, enc {rotate delta|press [ms]|group|focus…

[ESP HW] STM32-bridge console (boot log, panics, PerfMon) through the crosspad-hil daemon. open → con_N handle (DTR/RTS deasserted so opening never reboots the board; reset=true pulses reset explicitly); read {since_seq, wait_ms, match, limit} → {lines: [[seq, line]], next_seq, lines_lost}; expect {…

Search the ecosystem's prose (crosspad-docs, the BSP guides, the bundled skill pages) and return the matching sections rather than whole pages. Use it for 'how does X work' and 'why does the board do Y' questions — the hardware traps, the app lifecycle, the audio routing and the HIL workflow are wri…

Environment doctor. Host checks: hil_python interpreter, crosspad-hil version vs the one this server needs, platform-idf root, ESP-IDF env, crosspad-pc root, per-rev build dirs and firmware age, simulator binary staleness. Daemon checks merged in: udev/dialout, port locks (holder PID + purpose), rtm…

[ESP HW | PC sim] One-call state snapshot (~300 tokens): apps {running, available}, ui {focus {ref,label}, group [{ref,label}], drawer, theme, app}, kit, leds, pads, mem, ble, console counters. Refs `e<i>` are ENC_GROUP indices for crosspad_ui focus — any UI action invalidates them and the next snap…

[ESP HW] Drive the pads: a rate across a pad set, or a pattern with real timings ({t_ms, pad, vel, gate_ms}) — use the pattern to play something. Runs in the background behind a stim_N handle so you can record or read state meanwhile. status reports what was sent, the PAD_STATS delta the device actu…

[ESP HW] Use this machine's Bluetooth radio to talk to the CrossPad's BLE MIDI: scan, connect, send notes into it, listen to what it sends out, and measure the round-trip. It matches the board by the address the board itself reports and refuses to guess between look-alikes. Needs the `ble` extra ins…

[ESP HW] One call, the whole evidence set for a panic: reset reason, the panic registers, the backtrace decoded to source lines against the ELF of the build that is actually flashed, the heap after the restart, and the surrounding console lines as a link. Point it at a log file, at an open console h…

Compiler-backed symbol intelligence via clangd over the project's compile_commands.json. Answers what a grep cannot: `references` (who actually calls this), `implementations` (what overrides this virtual), `hover` (resolved type plus the doc comment), `call_hierarchy` (incoming callers), `definition…

Poll, wait on, cancel or list long-running crosspad tasks (build, flash, hil_run, capture, stimulus, submodule_update). Task handles are task_<n>; results are kept 1 h after completion. Use this when your client does not support the MCP tasks capability.

[ESP HW] Drive the device UI by snapshot refs. focus ref=e<i> moves the encoder focus to that group entry (ENC_GROUP + ENC_FOCUS → ENC_ROTATE by the delta); press = encoder click; rotate delta; back = the app's own Back (APP_SELF_CLOSE); start_app name; stop_app (APP_STOP, rebuilds the launcher). Ev…