Content
# logicanalyzer-mcp
A logic analyzer tool and MCP server for firmware debugging, reverse engineering, and CI/CD hardware verification. Built in Go with a DSLogic-first hardware abstraction layer.
## What it does
- **Capture** digital signals from a logic analyzer (DSLogic, or mock/replay for testing)
- **Decode** protocols: UART, SPI, I2C, CAN, 1-Wire (native Go), with user-defined JS decoders via embedded goja engine
- **Analyze** timing, detect anomalies, compare captures, search decoded frames
- **Trigger** on edges, patterns, timeouts, and compound conditions
- **Assert** signal correctness in CI/CD pipelines (`logicanalyzer assert`)
- **Debug interactively** via MCP — let an LLM drive the logic analyzer to trace firmware issues
- **Visualize** waveforms, protocol decodes, and anomalies in a browser-based viewer
## Install
### From source (pure Go, no hardware needed)
```bash
git clone --recurse-submodules https://github.com/DatanoiseTV/logicanalyzer-mcp.git
cd logicanalyzer-mcp
make build
```
This produces a binary with:
- Mock and replay devices (no hardware needed)
- 5 native Go decoders (UART, SPI, I2C, CAN, 1-Wire)
- JavaScript decoder runtime (goja) for custom protocols
- Full CLI, MCP server, web viewer, session management
### With DSLogic hardware support
`make build-full` auto-compiles libsigrok4DSL from the included git submodule:
```bash
# Install system dependencies (one time)
make install-deps # macOS: brew install cmake pkg-config glib libusb libzip
# Full build (auto-compiles C deps from submodules)
make build-full
```
On Linux:
```bash
sudo apt-get install -y cmake pkg-config libglib2.0-dev libusb-1.0-0-dev libzip-dev
make build-full
```
### Using Claude Code (MCP server)
#### Via CLI
```bash
claude mcp add logicanalyzer -- /path/to/logicanalyzer mcp
```
Or if installed to your PATH:
```bash
claude mcp add logicanalyzer -- logicanalyzer mcp
```
#### Via config file
Add to `~/.claude/settings.json` or project-level `.claude/settings.json`:
```json
{
"mcpServers": {
"logicanalyzer": {
"command": "/path/to/logicanalyzer",
"args": ["mcp"]
}
}
}
```
## MCP Tools
The MCP server exposes 18 tools with detailed LLM-friendly descriptions. An LLM can drive a full debug session:
| Category | Tools |
|----------|-------|
| Discovery | `device_list`, `device_configure`, `channel_survey` |
| Capture | `capture_start`, `capture_status`, `capture_stop`, `capture_get` |
| Analysis | `decode`, `analyze_timing`, `analyze_anomalies`, `compare_captures`, `search_frames` |
| Session | `session_list`, `session_get`, `session_annotate`, `capture_replay` |
| Decoder | `decoder_list`, `decoder_info`, `decoder_install` |
| Debug | `investigate` (auto survey + detect + capture + decode + report) |
Example LLM workflow:
1. `investigate` -- "what's on the wire?"
2. `decode` with auto-detect -- confirms SPI, decodes frames
3. `analyze_anomalies` -- "CS glitch at frame 5"
4. `compare_captures` against known-good -- "this transaction is missing"
## CLI Usage
```bash
# Discovery
logicanalyzer devices # List connected devices
logicanalyzer survey --duration 100ms # Quick channel activity survey
# Capture
logicanalyzer capture \
--channels 0,1,2 --labels CLK,MOSI,CS \
--rate 10MHz --duration 500ms \
--decode spi --channel-map clk=0,mosi=1,cs=2 \
--output capture.json
# Decode
logicanalyzer decode capture.json
logicanalyzer decode capture.json --protocol spi --format json
# CI/CD assertions (exit 0 = pass, 1 = fail, 2 = error)
logicanalyzer assert capture.json \
--no-anomalies \
--frame-count "spi >= 10" \
--field "spi[0].mosi == 0x9F"
# Compare two captures
logicanalyzer diff before.json after.json
# Search decoded frames
logicanalyzer search capture.json "mosi == 0x9F"
# Session management
logicanalyzer session list
logicanalyzer session show <session-id>
logicanalyzer session tag <session-id> debug,spi
# Decoders
logicanalyzer decoder list
logicanalyzer decoder info spi
logicanalyzer decoder load custom-protocol.js
# Web viewer
logicanalyzer serve --port 8080
# MCP server (stdio)
logicanalyzer mcp
```
## Web Viewer
Start with `logicanalyzer serve` and open `http://localhost:8080`. Features:
- Zoomable/pannable waveform display (mouse wheel + drag)
- Protocol decode overlay with frame annotations
- Anomaly markers (color-coded by severity)
- Auto-scaling time axis
- Session browser sidebar
- Decoded frames table
- Statistics panel
## Go Library
```go
import (
"github.com/DatanoiseTV/logicanalyzer-mcp/pkg/analyzer"
"github.com/DatanoiseTV/logicanalyzer-mcp/pkg/hal/mock"
)
// Open a mock device (for testing)
a, _ := analyzer.OpenMock(analyzer.MockConfig{
NumChannels: 3,
Signals: []mock.SignalConfig{
{Channel: 0, Generator: mock.SPISignal(1_000_000, []byte{0x9F}, 0, 0)},
},
})
defer a.Close()
// Or replay from a recorded capture
a, _ := analyzer.OpenReplay("golden-capture.json")
// Capture and decode
result, _ := a.Capture(analyzer.CaptureConfig{
Channels: []analyzer.ChannelConfig{{Index: 0, Label: "CLK"}, {Index: 1, Label: "MOSI"}, {Index: 2, Label: "CS"}},
SampleRate: 10_000_000,
Duration: 100 * time.Millisecond,
})
decoded, _ := result.Decode("spi", analyzer.DecodeOpts{
Channels: map[string]int{"clk": 0, "mosi": 1, "cs": 2},
})
fmt.Println(decoded.Frames[0].Data["mosi"]) // "0x9F"
```
## Custom JS Decoders
Write decoders in JavaScript for proprietary or uncommon protocols:
```javascript
({
id: "my_sensor",
name: "My Sensor Protocol",
description: "Custom protocol decoder",
requiredChannels: [
{name: "clk", description: "Clock"},
{name: "data", description: "Data"}
],
decode: function(stream) {
var edges = stream.risingEdges("clk");
var frames = [];
var byte_val = 0, bit_count = 0, start = 0;
for (var i = 0; i < edges.length; i++) {
if (bit_count === 0) start = edges[i].timestamp;
byte_val = (byte_val << 1) | stream.sample("data", edges[i].sampleIndex);
bit_count++;
if (bit_count === 8) {
frames.push({
start: start, end: edges[i].timestamp,
data: {value: "0x" + byte_val.toString(16).toUpperCase()},
annotation: "0x" + byte_val.toString(16).toUpperCase()
});
byte_val = 0; bit_count = 0;
}
}
return frames;
},
detectApplicability: function(stream) { return 0; }
})
```
Load via CLI (`logicanalyzer decoder load protocol.js`) or MCP (`decoder_install` tool).
## Architecture
```
cmd/logicanalyzer/ CLI + MCP server entrypoint
pkg/
analyzer/ Public Go library API
capture/ Capture manager, trigger engine
decoder/ Edge detection, decoder pipeline, auto-detect
native/ Native Go decoders
uart/ UART 8N1
spi/ SPI (CPOL/CPHA)
i2c/ I2C with ACK/NACK tracking
can/ CAN 2.0A with CRC, bit destuffing
onewire/ Dallas 1-Wire (reset, presence, commands)
js/ JavaScript decoder runtime (goja)
analysis/ Timing measurement, anomaly detection, diff, search
session/ File-backed session & capture storage
schema/ JSON schema types (CaptureResult, Frame, Anomaly, ...)
hal/ Hardware abstraction layer
mock/ Mock device with signal generators
replay/ Replay from captured files
dslogic/ DSLogic CGo bridge (libsigrok4DSL)
output/ Output formatters (JSON, table, CSV)
mcp/ MCP server (18 tools)
web/ Embedded web viewer (SPA)
third_party/
DSView/ DreamSourceLab DSView (libsigrok4DSL source)
libsigrokdecode/ sigrok protocol decoders (100+)
build-libsigrok/ CMake wrapper for standalone lib build
```
## Make Targets
```
make build Pure Go build (mock/replay, no hardware)
make build-full Full build (auto-compiles libsigrok4DSL from submodule)
make build-mcp MCP-only binary
make install-deps Install system dependencies (brew/apt)
make test Run all tests
make serve Start web viewer on :8080
make mcp Start MCP server on stdio
make check-deps Verify system dependencies
make clean Remove build artifacts
```
## License
MIT
