smolmux-gdb-mcp

smolmux

ポータブルな C11 デバイスマルチプレクサーです。デバイス接続（シリアル UART、GDB スタブ）を開いたまま保持し、改行区切り JSON を使用して Unix ソケット経由で複数のクライアントからのアクセスを多重化します。

単一の静的バイナリで、低レイテンシーかつ小さなフットプリントを実現しています。Linux での日常的なシリアル通信や GDB の初期化向けに設計されています。

初めての方へ：docs/START-HERE.md は、1 画面で確認できる案内ページです。目的（実行する、AI エージェントと新しいボードを立ち上げる、アーキテクチャを理解する、コードをいじる）を選ぶと、適切なドキュメントを案内します。

1 つのポートで 3 つのクライアント

1 つのブローカーが ESP32-S3 の UART を保持します。モニター（上部）はリアルタイムで監視します。下部のペインでは、スクリプトが temp を送信し、同じ回線で応答を受け取り、ボードをリセットしてプロンプトを待ちます。その後、esptool が with-port 経由でフラッシュ ID を読み取ります。ブローカーは一時停止し、esptool が実行され、ブローカーが再開しますが、モニターはポートを使い続けられます。

例：未知のボードを調査する

1 つのブローカーが SWD を保持し、smolmux-gdb-mcp が probe_unknown_board を実行します。SAM C21 Xplained Pro では、この処理によって CPUID から Cortex-M0+ をデコードし、SAM DSU DID で部品名を特定し、誤った STM32 の判定を退け、スターター用の *.gdb-profile.json を書き込みました。ツール、レジスター値、プロファイルの形式については、docs/demo-samc21-probe-transcript.md をご覧ください。

日常的なシリアル通信（複数クライアント、U-Boot の割り込み、フラッシャーへの引き渡し）については、docs/daily-driver.md をご覧ください。

特長

• vtable ポリモーフィズムによる シリアル UART、GDB MI、シリアル over TCP（telnet + RFC2217）デバイスリンク
• Unix ソケット経由での 複数の同時クライアント と、ロールベースのアクセス制御（オブザーバー／コントローラー／テイクオーバー）
• Expect エンジン - デバイスのバイトストリームを並行して正規表現で照合し、タイムアウトに対応
• 異常検知 - クールダウンとインシデント追跡を備えたパターンベースのクラッシュ／エラー検知
• 出力履歴 - 後から参加したクライアントが再生できる、タイムスタンプ付きリングバッファー
• 構造化ログ - JSONL I/O ログと、人間が読みやすいローテーション対応テキストログ （I/O ログには、ログインプロンプトで入力した内容も含め、デバイスとの送受信内容がすべて記録されます。ログはプライベートな 状態ディレクトリ内に 0600 で作成され、smolmux はシンボリックリンク経由での書き込みや、 別のユーザーが所有するファイルへの書き込みを拒否します）
• ネットワークシンク - リモートアクセス用の TCP と WebSocket（デフォルトではループバック）。 ワイヤープロトコルは平文であり、ハンドシェイクを完了したクライアントは、コンソールへの書き込み、ピン、BREAK、SysRq、GDB を含むデバイスの完全な制御権を取得します。 ループバックで --auth-token を指定しない場合、ブローカーは $XDG_RUNTIME_DIR（または /tmp）内に 0600 のファイルとしてトークンを生成するため、ほかのローカルユーザーやプロセスは接続できません。自分の smolmux-monitor / smolmux-mcp はトークンを自動的に読み取り、smolmux-cli token で表示できます。リモートから使用する場合は、ポートを公開するのではなく、バインド先をループバックに保ち、SSH トンネルまたは WireGuard 経由で接続してください。smolmux は、--auth-token が指定されていない状態でのループバック以外への TCP バインドを拒否します。--insecure-no-auth を指定すると、両方の保護機能が無効になります。
• MCP サーバー - 単独で動作する smolmux-mcp / smolmux-gdb-mcp は実行中のブローカーに接続します。単一プロセスの stdio 用に、インプロセスの --mcp シンクも任意で利用できます
• 起動追跡と自動応答 - 順序付きの起動ステージ、停止イベント、常時有効な expect->send ルール
• 自動起動の割り込み - bootdelay=0 の U-Boot 向けに、ブローカー側でキーを連続送信します（オプションで DTR/RTS リセットも実行）
• デバイスプロファイル／ボードマニフェスト - プロンプト、異常、複数配線ボード向けの JSON 設定
• 自動再接続 - USB シリアル切断時に指数バックオフで復旧
• ビルド時の機能選択 - Kconfig ベース。UART のみのビルドには GDB/TCP/WebSocket のコードは含まれません

クイックスタート

前提条件：Linux、C11 コンパイラー、CMake 3.21 以降、Python 3 と kconfiglib（構成手順でこれを使って機能ヘッダーを生成します）。libpcre2-8 は任意です。利用できない場合、正規表現の照合には POSIX が使われます。

# Debian/Ubuntu
sudo apt install build-essential cmake python3 python3-pip libpcre2-dev
pip install kconfiglib   # or in a venv; Debian's system Python may need
                         # --break-system-packages

cmake -B build && cmake --build build -j$(nproc)
./build/smolmux /dev/ttyUSB0

クライアントを接続します：

# Needs a running broker (above). Auto-discovers the socket from the port name.
./build/smolmux-monitor /dev/ttyUSB0

日常的なワークフロー（プロファイル、ログ、U-Boot の割り込み、複数配線ボード）については、 docs/daily-driver.md を参照してください。目的別のルーター：docs/START-HERE.md。

ビルド

cmake -B build && cmake --build build -j$(nproc)   # Default (all features)
ctest --test-dir build                               # Run tests

機能プロファイル

cp configs/defconfig.minimal .config && cmake -B build    # UART only, no sinks/watcher
cp configs/defconfig.uart .config && cmake -B build       # UART + MCP sink + watcher
cp configs/defconfig.embedded .config && cmake -B build   # Embedded target profile
cp configs/defconfig.full .config && cmake -B build       # Everything (GDB, TCP, WS, MCP, watcher)

または、機能を直接切り替えます：

cmake -B build -DSM_ENABLE_GDB=OFF -DSM_ENABLE_SINK_WS=OFF

開発者向けベンチマーク（出力コアレッサーのハーネスなど）は、デフォルトでは無効です：

cmake -B build -DSM_BUILD_BENCH=ON && cmake --build build --target bench_coalesce

対話型の設定：

cmake --build build --target menuconfig

静的ビルド

cmake -B build -DSM_MUSL_STATIC=ON    # Fully static musl binary (zero runtime deps)
cmake -B build -DSM_STATIC=ON         # Static linking (except glibc)

使用方法

smolmux <port> [options]

Options:
  -b, --baud <rate>           Baud rate (default: 115200)
  -s, --socket <path>         Unix socket path
  -l, --log-dir <dir>         I/O log directory
                              (default: $XDG_STATE_HOME/smolmux or
                               ~/.local/state/smolmux)
  -t, --text-log-dir <dir>    Text log directory
  -p, --profile <path>        Device profile JSON file
  --board <name>              Group this wire under a board (for discovery)
  --role <label>              This wire's role on the board (console, swd, ...)
  --gdb                       Use GDB MI link instead of UART
  --gdb-path <path>           Path to gdb binary (default: gdb)
  --gdb-target <spec>         GDB target (e.g., localhost:3333)
  --serial-tcp <host:port>    Connect to a serial-over-TCP device server
                              (ser2net, socat, terminal server; telnet +
                              RFC2217 baud/DTR/RTS/break control)
  --mcp                       Enable in-process MCP stdio sink (prefer standalone
                              smolmux-mcp against a daemon broker for daily use)
  --tcp-port <port>           Enable TCP sink (default: 5555)
  --tcp-bind <addr>           TCP bind address (default: 127.0.0.1)
  --auth-token <token>        Require token in hello from TCP clients
                              (prefer env SMOLMUX_AUTH_TOKEN - hidden from ps)
  --auth-token-file <path>    Read the token from a file
  --insecure-no-auth          Serve TCP/WS with no token. Without it, a
                              loopback listener gets a generated token
                              (0600 file; smolmux-cli token prints it) and
                              a non-loopback --tcp-bind is refused.
  --ws-port <port>            Enable WebSocket sink (default: 5556)
  --no-text-log               Disable text log
  --no-io-log                 Disable JSONL I/O log
  --no-reconnect              Don't auto-reconnect on disconnect
  --wait-device <seconds>     Wait for the device path before open
  --gdb-allow-shell           Permit GDB shell/python/eval (off by default)
  --list-ports                List available serial ports and exit
  --list-profiles             List available device profiles and exit
  --help-protocol             Show wire protocol documentation
  -v, --verbose               Enable debug logging
  -V, --version               Show version
  -h, --help                  Show this help

ワイヤープロトコル

Unix ソケット（TCP/WS シンクでも同様）上の、改行区切り JSON です。バイナリデータは base64 でエンコードされます。メッセージセットは、セッション制御、expect、履歴、異常、起動ステージ、自動起動時のキー連続送信、自動応答をカバーします。

完全なリファレンス：./build/smolmux --help-protocol（常にこのバイナリに対応しています）。

クライアント -> ブローカー： hello、send、send_expect、takeover、release、status、pin_control、set_baud、suspend、resume、history_request、incidents_request、configure_anomaly、interrupt_autoboot、configure_autoresponder、autoresponders_request

ブローカー -> クライアント： welcome、output、input_echo、expect_result、status_response、error、history_response、incidents_response、anomaly、autoboot_result、boot_stage、boot_stall、autoresponders_response、autoresponder_fired、suspended、resumed、link_down、link_up

セッション例：

-> {"type":"hello","name":"my-tool","role":"controller","protocol_version":1}
<- {"type":"welcome","broker_version":"x.y.z","protocol_version":1,"port":"/dev/ttyUSB0","baud":115200,"your_role":"controller"}
-> {"type":"send","id":"1","data":"dW5hbWUgLWEK"}
<- {"type":"output","data":"TGludXggNC4xOS4w...","timestamp":1709654321.123}

アーキテクチャ

┌───────────┐  ┌───────────┐
│ uart link │  │  gdb link │   <- device-facing, compiled in/out via Kconfig
└─────┬─────┘  └─────┬─────┘
      │              │
      ▼              ▼
┌──────────────────────────────┐
│         smolmux core         │  <- epoll event loop, message bus,
│  history · logging · anomaly │    role enforcement, expect engine
└──┬───────┬───────┬───────┬───┘
   │       │       │       │
   ▼       ▼       ▼       ▼
┌──────┐┌─────┐┌─────┐┌──────┐
│ unix ││ tcp ││ ws  ││ mcp  │  <- sinks, also compiled in/out
│socket││sink ││sink ││ sink │
└──────┘└─────┘└─────┘└──────┘

アーキテクチャの詳細については、DESIGN.md を参照してください。

依存関係

必須： cJSON（同梱、単一ファイル）

自動検出： PCRE2（libpcre2-8）。存在する場合は正規表現エンジンとして使用します。バックトラッキングを内部で制限できるためです。存在しない場合、ビルドは自動的に POSIX ERE にフォールバックするため、必須ではありません。-DSM_ENABLE_PCRE2=ON（見つからない場合はエラー）または -DSM_ENABLE_PCRE2=OFF でいずれかを強制できます。

コアには、POSIX と cJSON 以外に必須の外部依存関係はありません。

関連ツール

• smolmux-cli - コマンドラインクライアント（コマンドの送信、出力の読み取り。with-port <cmd> はポートを一時停止し、フラッシャーなどの外部ツールを実行してから、必ず再開します）
• smolmux-monitor - エスケープシーケンスに対応した対話型ターミナルクライアント（プレフィックスキーを押してからコマンドを入力します。プレフィックスはデフォルトで Ctrl-] です。-e で変更でき、例：-e esc または -e ^A）
• smolmux-mcp - スタンドアロン MCP サーバー：実行中のブローカーに接続し、シリアルツール（serial_send_command、serial_read、serial_boot_status、serial_add_autoresponder、…）を公開します。代替手段として、ブローカーの --mcp シンクを使うと、MCP をプロセス内に組み込めます。
• smolmux-gdb-mcp - GDB デバッグ用スタンドアロン MCP サーバー：--gdb リンクを保持するブローカー経由で、21 個のツールを提供します。ブレークポイント、ステップ実行、バックトレース、名前付きレジスター、メモリー、式の評価、障害レジスターのデコード（コアが対応している場合）、周辺機器の読み取り、gdb_interrupt、および現時点での ARM Cortex-M における未知のボードの調査（gdb_identify_target / gdb_generate_profile。その他のアーキテクチャは今後対応予定）が含まれます。リソースとプロンプトには smolmux-gdb://board-probing と probe_unknown_board が含まれます。SM_ENABLE_GDB が有効な場合にビルドされます。SAM C21 Xplained Pro でチップ ID の検証済みです。
• smolmux-watcher - 異常を監視し、インシデントレポートをディスクに保存するデーモン

関連ドキュメント

• まずはこちら - 目的別の案内（毎日の使用、新しいボード、アーキテクチャ、開発）。
• MCP のセットアップ - smolmux-mcp / smolmux-gdb-mcp を Claude Code、Claude Desktop、または Cursor に登録する方法。
• 日常的な使用 - 推奨ビルド、実行時フラグ、U-Boot のブレークイン、起動段階、ボード、フラッシャーとの共存。
• ボード探索ワークフロー - 新しいボードの手順書（手動または AI エージェントを使用）：配線、SWD による識別、コンソール、周辺機器。
• ボード Bring-up テンプレート - ボードごとに複製して使用する情報記録テンプレート。
• 永続的なシリアルデバイス名 - UART ドングルの安定したデバイス名（/dev/serial/rpi-console など）。
• ハードウェア検証マトリックス - 実機で検証済みの項目と、まだ実証されていない項目。
• DESIGN.md / CLAUDE.md - アーキテクチャとコントリビューター向けガイド。

無料版と Pro

このリポジトリのすべては MIT ライセンスです。完全なソースコード、ワイヤープロトコル、汎用デバイスプロファイル、ビルドシステムが含まれます。自分でビルドすれば、製品の全機能を利用できます。

smolmux Pro は機能制限ではなく利便性を提供します。ビルド済みの静的バイナリー（x86_64 + aarch64、musl、実行時依存関係ゼロ）、プロファイルごとのメモが付いた厳選プロファイルパック、および6 か月間のメールサポートが含まれます。買い切り（$79）です。ZIP パスを使った MCP のセットアップ方法は docs/MCP-SETUP-FULL.md にあります（この公開リポジトリにも含まれています）。

smolmux Pro を購入 - 買い切り $79 - ダウンロードには、最新の静的バイナリーとプロファイルパックが含まれます。

ライセンス

MIT。cJSON は独自の MIT ライセンス（deps/cJSON/LICENSE）に基づいて同梱されています。