Files

T

Jeancarlo 8b0eb42fec add MCP developer tool with multi-unit support

First developer tool for the XDJ-100SX project. Connects Claude Code
directly to the Pi over SSH — push skin files, take screenshots, restart
Mixxx, flash Pico firmware, and more without leaving the editor.

Available MCP tools:
- run_command, read_file, write_file, list_files
- push_skin, pull_skin, push_skin_file, pull_skin_file
- push_midi, pull_midi
- take_screenshot, navigate_panel
- restart_mixxx
- check (preflight: SSH, Mixxx, Pico, audio)
- pico_bootloader, pico_flash
- discover_units — scan network for all reachable XDJ Pi units
- select_unit — switch active connection mid-session (multi-unit support)

Also adds --about flag and TUI About modal with authors and credits,
and fixes scrolling/close behavior on Help and About modals.

By: Jeancarlo Cardoso de Faria Filho (jaianlab) <jaianlabworks@gmail.com>

2026-05-08 01:24:15 -03:00

4.0 KiB

Raw Permalink Blame History

XDJ-100SX Developer Tool

Claude Code MCP server + CLI + TUI for the XDJ-100SX Pi system. Push skin files, take screenshots, flash firmware, and manage the Pi — all from your editor.

Requirements

pip install paramiko watchdog textual

Quick start

python3 tools/xdj-pi-dev.py --check      # verify connection + environment
python3 tools/xdj-pi-dev.py --status     # live Pi + Mixxx status
python3 tools/xdj-pi-dev.py --ui         # interactive TUI
python3 tools/xdj-pi-dev.py --about      # authors & credits
python3 tools/xdj-pi-dev.py --help       # full command reference

Connection

The tool tries these in order:

--host flag
XDJ_HOST environment variable
XDJ100SX.local — mDNS, works on any network (WiFi or LAN)
192.168.10.2 — static IP fallback for direct cable

Direct cable (no router)

One-time setup on your machine:

# macOS
sudo ifconfig en0 alias 192.168.10.1 255.255.255.0

# Linux
sudo ip addr add 192.168.10.1/24 dev eth0

# Windows (run as Administrator)
netsh interface ip set address "Ethernet" static 192.168.10.1 255.255.255.0

Then on the Pi (once):

python3 tools/xdj-pi-dev.py --setup-pi-dhcp

After that the Pi hands out IPs automatically — no manual config needed on any machine.

Multi-unit

Each Pi should have a unique hostname:

python3 tools/xdj-pi-dev.py --set-hostname xdj-unit2

Then from Claude Code:

discover_units — lists all reachable XDJ units on the network
select_unit — switches the active connection to a specific unit

Claude Code MCP setup

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "xdj-pi-dev": {
      "command": "python3",
      "args": ["tools/xdj-pi-dev.py"]
    }
  }
}

Add to .claude/settings.local.json:

{
  "enabledMcpjsonServers": ["xdj-pi-dev"]
}

Restart Claude Code. Once connected, you can say things like:

"push the skin and take a screenshot"
"change the play button color in style.qss, push and screenshot"
"restart Mixxx and navigate to the beat loop panel"
"flash the firmware"
"find all XDJ units on the network"

CLI reference

Setup

--check                  # preflight: deps, SSH, Mixxx, audio, Pico
--discover               # scan network for all Pi units
--setup-pi-dhcp          # configure Pi as DHCP server on eth0
--setup-ssh-keys         # passwordless SSH (recommended)
--set-hostname NAME      # rename Pi (e.g. xdj-unit2)
--backup-image           # backup SD card to .tar archive
--restore-ssh            # recovery guide if SSH is locked out

Skin development

--push                   # push all skin files to Pi
--push "*.qss"           # push only matching files
--pull                   # pull skin files from Pi to repo
--screenshot             # capture Pi display
--screenshot --panel ks  # navigate to panel first (hc/bl/bj/ks/st)
--restart                # restart Mixxx
--watch                  # watch, auto-push + screenshot on save
--watch --panel hc       # watch with panel navigation

MIDI

--push-midi              # push MIDI mapping to Pi
--pull-midi              # pull MIDI mapping from Pi
--midi-mon               # stream live MIDI messages (Ctrl-C to stop)

Pico firmware

--setup-pico-cli         # install arduino-cli on Pi (one-time)
--pico-compile           # compile firmware on Pi
--pico-bootloader        # reset Pico to UF2 bootloader
--pico-flash FILE.uf2    # flash a local .uf2 to Pi
--analyze                # live GPIO signal analyzer

Other

--cmd 'CMD'              # run arbitrary SSH command on Pi
--host 192.168.1.42      # target a specific IP or hostname
--ui                     # open interactive TUI (requires textual)
--about                  # show authors and credits

Skin development guide

See SKIN_DEV.md for Mixxx widget types, layout rules, ConfigKeys, QSS constraints, and color palette — everything Claude needs to build and modify skin files correctly.

4.0 KiB Raw Permalink Blame History