can-engineering-mcp
# can-engineering-mcp
A [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI agents deterministically inspect, author, convert, validate, and diagnose Controller Area Network (Classical CAN & CAN FD) databases and trace logs.
LLMs are good at systems reasoning and root-cause synthesis, but bad at raw hex parsing, Motorola bit-numbering math, and scanning million-line trace files. This server does the deterministic heavy lifting — bit-packing validation, streaming log aggregation, transport-protocol reassembly, statistical anomaly detection — and hands the agent compact, token-efficient summaries instead of raw bytes.
## What it does
19 tools across six stages:
- **DBC discovery** — inspect a database, fuzzy-search messages/signals/IDs/units, render an exact Intel/Motorola bit-layout grid, validate for bit overlaps and structural errors.
- **DBC authoring** — atomic, backed-up (`.bak`) mutation of nodes, messages, and signals, with an auto-packer that finds free bit ranges and rejects overlapping writes with a structured conflict map.
- **Templates & conversion** — generate clean-room J1939, CANopen (CiA 301), and UDS/ISO-TP skeleton databases from scratch; convert between `.dbc`/`.dbf`/`.arxml`/`.kcd`/`.sym`/`.xlsx`; diff two databases into an engineering changelog (bit shifts, scale changes, cycle-time changes).
- **Trace ingestion** — stream `.asc`/`.blf`/`.trc`/`.log`/`.csv`/`.parquet` traces (tested against real files up to 500MB+), summarize per-arbitration-ID statistics, query decoded signal trends, and filter/export with a safe (non-`eval`) signal-condition expression language.
- **Transport protocol & UDS** — a real ISO 15765-2 (ISO-TP) state machine for SF/FF/FC/CF reassembly, UDS (ISO 14229) service and negative-response-code decoding, J1939-21 BAM/CMDT multi-packet reassembly.
- **Bus health & reverse engineering** — bus-load/microburst analysis, error-storm and Bus-Off detection, cycle-time jitter and alive-counter fault detection, and a heuristic classifier that reverse-engineers undocumented frames (constant masks, counters, checksums, continuous signals, discrete flags) into a draft candidate DBC.
## Install
```bash
pip install can-engineering-mcp
```
Or from source, editable:
```bash
git clone https://github.com/kankan-sarkar/canbus-mcp.git
cd canbus-mcp
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
```
## Register with an MCP client
Add to your client's MCP server config (e.g. Claude Code's `.mcp.json` for a single project, or its user-scope config to enable it everywhere):
```json
{
"mcpServers": {
"can-engineering-mcp": {
"command": "/path/to/python",
"args": ["-m", "can_mcp.server"]
}
}
}
```
File access is sandboxed to the current working directory the server is launched in (override with the `CAN_MCP_WORKSPACE_ROOT` environment variable).
## Development
```bash
pytest # full suite runs offline in well under 15s, against synthetic generated fixtures only
```
Every fixture is generated deterministically in-memory (`tests/fixtures/generator.py`) — nothing proprietary, nothing downloaded.
## Dependency & license guardrails
Only permissively-licensed (MIT/BSD-2-Clause/BSD-3-Clause/LGPLv3-dynamic-link) dependencies are used: `mcp`, `cantools`, `canmatrix`, `python-can`, `polars`, `duckdb`, `pydantic`, `lxml`, `openpyxl`, `canopen`. No proprietary database content (e.g. the SAE J1939 Digital Annex) is bundled; protocol templates (J1939, CANopen, UDS/ISO-TP) are clean-room structural generators built from public framing specifications.
## License
MIT — see [`LICENSE`](LICENSE).
TDQS
Scored across 19 tools
The tools target clearly distinct resources and actions: database inspection/search, message/signal/ECU editing, format conversion, trace summarization/query/export, diagnostics, and reverse engineering. Overlaps such as summarize_trace_log vs analyze_bus_health_and_faults and query_decoded_signals vs filter_and_export_trace are separated by clear output and purpose differences.
All names use consistent snake_case and are generally verb_noun oriented, which makes them predictable. Minor inconsistency exists in operation vocabulary and granularity, e.g. upsert_dbc_message vs add_or_update_signal, and manage_ecu_node bundles add/rename/delete while message and signal lifecycle operations are split.
Nineteen tools is slightly heavy for the stated scope, but the domain spans database engineering, trace analysis, diagnostics, and reverse engineering, so each tool has a plausible role. It is not inflated with redundant or vague operations.
The surface covers database creation, inspection, editing, validation, conversion, diffing, trace analysis/export, UDS/J1939 decoding, health diagnostics, and reverse engineering. Minor gaps remain around direct detailed read/get operations, explicit load/save database lifecycle, and full editing of value tables or arbitrary attributes.