dsview-mcp

Local MCP server for building an agent-facing integration around DreamSourceLab DSView.

Current scope:

• detect the local DSView installation and decoder/resource directories
• detect currently attached DreamSourceLab USB devices
• enumerate installed DreamSourceLab-compatible protocol decoders
• inspect DSView session files (.dsc) and capture bundles (.dsl)
• list shipped default session presets
• build a native probe helper against the DSView source tree
• probe devices through DSView's native ds_* API
• run buffered native single-shot logic captures with sample-rate, sample-count, channel-enable, and simple-trigger control
• return raw-capture metadata plus a quick first-pass signal activity summary
• run native single-decoder protocol decode against saved raw captures
• run native linear decoder stacks against saved raw captures
• provide protocol-specific stack entry points for I2C, SPI, and UART
• analyze decoded captures for line health, transaction structure, and common protocol-level anomalies
• export structured decoder annotations as JSON plus a small preview in the MCP response
• create managed session artifact bundles with manifests, raw captures, decoder output, analysis JSON, and run reports
• persist trigger/timing artifacts plus structured findings alongside capture/decode/analyze runs
• persist event-window artifacts as raw capture snippets around findings, I2C transactions, and SPI transfers
• run UART baudrate/inversion sweeps and SPI mode/bit-order sweeps with confidence scoring
• expose a Codex-friendly standard workflow path with a preflight smoke test and protocol-specific capture entry points
• export managed session artifact bundles as ZIP files
• run end-to-end capture_and_analyze_* workflows for I2C, SPI, and UART that persist their artifacts automatically, including optional sweep reports

Why this exists:

• DSView exposes rich logic-analyzer features in the GUI: trigger configuration, protocol decoder stacks, result search/export, and session save/load
• the installed DSView binary on this machine only exposes a minimal CLI (--help, --version, --loglevel, --storelog, optional file argument)
• the DSView source tree includes the real low-level APIs in libsigrok4DSL and libsigrokdecode4DSL

Important findings from the current machine:

• DSView is installed at /usr/local/bin/DSView
• decoder scripts are installed under /usr/local/share/libsigrokdecode4DSL/decoders
• default session presets are installed under /usr/local/share/DSView/res
• the DSView executable exports ds_*, sr_*, and srd_* symbols, but it cannot be loaded directly via ctypes because it is a PIE executable
• a native helper can be built locally against the DSView source tree and can already enumerate devices through ds_get_device_list()
• the currently attached hardware is detected natively as DSLogic PLus
• native buffered logic capture now works against the attached DSLogic PLus from the MCP server without GUI automation
• native single-decoder protocol decode now works through libsigrokdecode4DSL
• native linear decoder stacks now work through libsigrokdecode4DSL session stacking
• protocol-aware analysis now works on top of decoded output for I2C, SPI, and UART
• session artifact handling now works for managed capture/decode/analyze runs, including ZIP export
• timing artifacts now include trigger metadata, capture health, and per-channel edge/pulse summaries
• timing artifacts now include I2C bus-free / ACK metrics and SPI transfer / clock metrics
• findings artifacts now include AI-friendly diagnostic findings with severity, evidence, sample ranges, and next actions
• event windows now include raw binary slices plus an index JSON for quick drill-down from findings to signal excerpts
• parameter sweeps now compare UART baudrate/inversion candidates and SPI mode/bit-order candidates, then rank them with confidence scores
• sweep findings now emit actionable mismatch hints such as suspected UART baudrate or SPI mode mismatches
• a dsview_smoke_test tool now verifies DSView installation, decoder inventory, native helper build, device visibility, and optional live capture
• synthetic verification succeeded with 0:uart on generated test data and produced one decoded byte annotation (0x55)
• synthetic verification succeeded with 1:uart -> midi and produced a decoded MIDI note-on annotation
• synthetic verification succeeded with 1:spi -> spiflash and produced a decoded RDID command annotation
• synthetic verification succeeded with 1:i2c and produced decoded bus/address/data annotations
• live verification succeeded on the attached DSLogic PLus: capture plus decoder execution completed headless without crashes and returned zero annotations on an idle capture
• live verification of the analysis layer succeeded on an idle UART-style capture and correctly flagged channel 0 as stuck-low with No UART bytes decoded
• managed session artifact verification succeeded on a headless UART capture-and-analyze run and produced a session manifest plus exported ZIP bundle
• live verification now also persists timing and findings artifacts for managed session runs

What is still missing for fuller phase 2 coverage:

• list_devices
• select_device
• list_device_modes
• list_device_config
• capture_repeat
• export_decoder_results
• richer trigger models beyond the current simple-trigger path
• .dsc/.dsl session round-trip for captures and decoder setups
• importing arbitrary existing captures/decodes into a managed artifact session

Recommended architecture for phase 2:

1. Extend the native helper from probe/capture into config-list and decoder commands.
2. Wrap those commands from this MCP server.
3. Keep .dsc and .dsl file compatibility so the agent can round-trip with the DSView GUI.

Why not automate the GUI directly:

• it is fragile
• it does not return structured machine-readable decode data
• it is difficult to make reliable for unattended debugging sessions

This repository now provides discovery/introspection, real native single-shot logic capture, single-decoder decode, linear decoder stacks, protocol-aware analysis, and managed session artifact handling with direct entry points for I2C, SPI, and UART. The next step is richer config listing, more trigger coverage, import of existing artifacts, and fuller DSView session import/export.

Recommended Codex standard path:

1. Run dsview_smoke_test(live_capture=true) before a live debug session.
2. Use one of capture_and_analyze_i2c_native, capture_and_analyze_spi_native, or capture_and_analyze_uart_native as the primary artifact-producing workflow.
3. Enable run_parameter_sweep=true for SPI/UART when decode quality is uncertain.
4. Use recommended_debug_workflows(protocol=...) to retrieve the MCP's preferred workflow sequence and default arguments.