crosspad-mcp-server

MCP (Model Context Protocol) server that gives Claude Code full control over the CrossPad development workflow — build, test, manage app packages, interact with the simulator, search code across repos. All from natural language.

Install

claude mcp add crosspad -- npx -y crosspad-mcp-server

Or with custom repo paths:

claude mcp add crosspad \
  --env CROSSPAD_IDF_ROOT=/path/to/platform-idf \
  --env CROSSPAD_PC_ROOT=/path/to/crosspad-pc \
  -- npx -y crosspad-mcp-server

That's it. Restart Claude Code and the tools are available.

Alternative: .mcp.json in your project

Add to your repo root — Claude Code picks it up automatically:

{
  "mcpServers": {
    "crosspad": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "crosspad-mcp-server"],
      "env": {
        "CROSSPAD_IDF_ROOT": "/path/to/platform-idf",
        "CROSSPAD_PC_ROOT": "/path/to/crosspad-pc"
      }
    }
  }
}

Alternative: Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "crosspad": {
      "command": "npx",
      "args": ["-y", "crosspad-mcp-server"],
      "env": {
        "CROSSPAD_IDF_ROOT": "/path/to/platform-idf"
      }
    }
  }
}

Skills (start here)

This package ships two Claude Code skills (bundled in the crosspad plugin):

• crosspad — the entry point. An ecosystem map, install/config guide, per-role guides (user / firmware dev / server contributor), a tool cheat-sheet, and an FAQ. A fresh agent should read this first. Lives at skills/crosspad/SKILL.md; run bash skills/crosspad/scripts/doctor.sh to check your environment.
• swd-tracer — real-time SWD variable tracing for CrossPad r20 (STM32G0B1) over ST-Link (see the SWD tracing section below).

Install both as a plugin:

/plugin marketplace add CrossPad/crosspad-mcp     # or a local path to this repo
/plugin install crosspad@crosspad

Tools (28) + resources

v8 unifies platform-axis tools: build/run/kill/check/flash now take platform (or transport) as an arg instead of being split per-platform. Migration table at the bottom of this file.

Each tool is focused on a single action. Strict schema validation (ranges on MIDI/pad values, enums on platforms/repos) catches bad inputs before execution.

Build & flash

SWD tracing (crosspad_trace)

Non-halting real-time trace of STM32G0B1 firmware variables via ST-Link — the same technique as ST-Studio/CubeMonitor but driven directly from the LLM session.

Recommended: the swd-tracer skill. This repo ships a Claude Code skill (skills/swd-tracer/) + plugin manifest so a fresh agent automatically understands the tracer and can walk you through configuring every environment (pyOCD venv, config paths, udev rules, the Debug ELF) and the doctor→symbols→start→read→ui→stop workflow. Install it as a plugin:

/plugin marketplace add CrossPad/crosspad-mcp     # or a local path to this repo
/plugin install crosspad@crosspad

The plugin bundles BOTH this MCP server and the skill, so a new machine gets the tracer end-to-end in one install. (Already running the server? The skill alone also lives at skills/swd-tracer/SKILL.md.)

Prerequisites (the skill's scripts/setup-venv.sh automates this)

Install pyocd and pyelftools into a Python venv (system Python is usually PEP-668 locked, so a venv is required):

bash skills/swd-tracer/scripts/setup-venv.sh
# or manually:
python3 -m venv ~/.local/share/crosspad-mcp/venv
~/.local/share/crosspad-mcp/venv/bin/pip install "pyocd>=0.44" pyelftools

Point the server at that venv via config_set (or set it directly in ~/.config/crosspad-mcp/config.json):

action=config_set  key=pyocd_python  value=~/.local/share/crosspad-mcp/venv/bin/python
action=config_set  key=stm_elf_path  value=/path/to/CrossPad_STM32_r20.elf

Linux udev note: without a udev rule the ST-Link probe requires root. Run bash skills/swd-tracer/scripts/install-udev-rules.sh (writes /etc/udev/rules.d/49-stlink.rules, then replug the probe), or add the official rules from pyocd / ST so your user can open the device without sudo.

Actions

Signal names accept array indexing, struct members, and whole-array/slice expansion: s_inputs[0], s_adc_raw[3], hpcd.Init.speed, s_adc_raw[*], s_inputs[0:8] (out-of-bounds indices are rejected against the DWARF length).

Example — trace ADC rail and pad inputs

action=doctor
# resolve any blocking issues...
action=symbols  query=s_vbat
action=start    signals=["s_vbat_mv","s_inputs[0]"]  rate_hz=100
action=status
action=read     max_points=500
action=save
action=stop

Tests

Simulator interaction

Git / repos

Code search & scaffolding

App package manager (crosspad-apps registry)

Resources

Migration: v7 → v8

Platform/transport now flows as an arg, not as part of the tool name. Net: 30 → 28 tools.

Run/kill/check are PC-only today (the platform arg is reserved for future symmetry — IDF firmware doesn't run on the host). Build modes are validated per-platform: reconfigure is PC-only; fullclean is IDF-only.

Migration: v6 → v7

Tools removed (logic moved to docs): crosspad_scaffold_app, crosspad_test_scaffold. Tools consolidated:

Net: 42 tools → 30 tools + 1 resource (v7). Subsequent unification in v8 → 28 tools (see above).

All tools return a uniform envelope: { "success": boolean, ...data, "error"?: string }. On failure the result also has the MCP-protocol isError: true flag set so clients can route errors distinctly from successful calls.

Each tool carries MCP annotations (readOnlyHint, destructiveHint, openWorldHint) — clients use these for confirmation prompts. Read-only tools (status, search, list) skip the prompt; destructive tools (commit, flash, build_idf clean, apps_install) trigger one.

Configuration

Each repo path is individually configurable via env vars. If not set, falls back to $CROSSPAD_GIT_DIR/<repo-name> (flat layout).

Repos are discovered dynamically — only repos that exist on disk appear in tool results. No flat directory structure is assumed when env vars are set.

Transport

stdio (default) — npx crosspad-mcp-server. Standard MCP transport for Claude Code / Claude Desktop / IDE plugins.

HTTP (--http <port>) — npx crosspad-mcp-server --http 3000. Exposes a Streamable HTTP endpoint at http://localhost:<port>/mcp for remote dev boxes or browser-based MCP clients. Stateful sessions (Mcp-Session-Id header echoed after initialize). One transport, multi-session multiplexed internally.

# Minimal HTTP smoke test:
npx crosspad-mcp-server --http 3000
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"x","version":"0"}}}'

How it works

Static tools (build, repos, code, apps) work without the simulator — they operate on the filesystem, git, and Python package manager.

Interactive tools (sim) communicate with the running PC simulator via TCP on localhost:19840 using newline-delimited JSON.

Streaming — long-running tools (build, test, log) emit output line-by-line via MCP logging, so Claude sees progress in real-time.

App manager — reads registry JSON directly for listing (aggregated across all repos). Mutations delegate to app_manager.py (at tools/ for IDF, scripts/ for PC/Arduino) from crosspad-apps.

Development

git clone https://github.com/CrossPad/crosspad-mcp.git
cd crosspad-mcp
npm install
npm run dev      # watch mode
npm run build    # one-shot build
npm test         # run unit tests
npm run test:watch  # tests in watch mode

src/
  index.ts              — 41 focused tool registrations (one tool per action)
  config.ts             — per-repo env vars, dynamic discovery, IDF/MSVC paths
  config.test.ts        — config unit tests (fs mocking)
  utils/
    exec.ts             — platform-aware command execution (MSVC/IDF/shell)
    git.ts              — repo status, submodule pins
    remote-client.ts    — TCP client for simulator (localhost:19840)
  tools/
    app-manager.ts      — crosspad_apps: multi-platform registry + Python subprocess
    architecture.ts     — interfaces, REGISTER_APP scan
    build.ts            — PC build + run
    build-check.ts      — build health check
    diff-core.ts        — submodule drift analysis
    idf-build.ts        — ESP-IDF build
    input.ts            — simulator input events
    log.ts              — exe log capture
    repos.ts            — multi-repo git status
    scaffold.ts         — app boilerplate generation
    screenshot.ts       — simulator screenshots
    settings.ts         — simulator settings R/W
    stats.ts            — simulator runtime stats
    symbols.ts          — cross-repo symbol search
    test.ts             — Catch2 test runner
    *.test.ts           — unit tests for each module

License

MIT — Part of the CrossPad project.