Majster-AI — Automotive-UDS-Diagnoseagent über MCP

Car_Diagnostic_AI — auch bekannt als CDA und Majster-AI — ist ein Diagnoseagent, der ein großes Sprachmodell über UDS/CAN mit den Steuergeräten eines Fahrzeugs verbindet, mit einem lokalen Index von Werkstatthandbüchern und mit Live-Websuche. Die drei Fähigkeiten werden als unabhängige Model Context Protocol-Server bereitgestellt und von einem LangGraph-Agenten orchestriert, mit einer strikten Human-in-the-Loop-Sperre für alles, was in das Fahrzeug schreibt.

Entwickelt und getestet gegen einen Land Rover Freelander 2 (2010, 2.2 TD4).

Es wird mit einer Cyber-HUD-Weboberfläche geliefert: einem interaktiven 3D-Fahrgestell, dessen Modul-Pins an realen Fahrzeugkoordinaten sitzen, Live-Telemetrie-Anzeigen und einem Drag-to-Authorize-Gate für alles, was in das Fahrzeug schreibt.

⚠️ Es ist standardmäßig auf Simulator und READ_ONLY eingestellt

Ein frischer Klon kann nicht auf einem echten Bus senden und nicht in ein Fahrzeug schreiben. Beides erfordert eine bewusste Konfigurationsänderung. Lesen Sie docs/SAFETY.md, bevor Sie sich mit einem Auto verbinden, das Ihnen wichtig ist.

Was es tatsächlich tut

you> The car goes into limp mode on the motorway. What's wrong with it?

  [agent.plan] Calling: read_dtc
  [car.read_dtc] Reading DTCs from ECM
  [agent.plan] Calling: read_live_data
  [agent.plan] Calling: search_manual

majster> Three codes stored in the ECM, and I think two of them are one fault:

  P0299 (confirmed) — turbocharger underboost
  P2015 (confirmed) — intake manifold runner position sensor
  P0401 (pending)   — EGR flow insufficient

  Live data backs up the underboost: manifold pressure reads 101 kPa at idle
  against 100 kPa barometric, so the turbo isn't building any boost at all.

  P0299 and P2015 together on a DW12 is a familiar pattern — both are air-path
  faults and the swirl-flap linkage sits right next to the actuator. The
  manual (fl2_engine.pdf, page 412) says actuator vacuum should reach 0.6 bar
  at idle; that's the measurement that would separate a seized actuator rod
  from a boost leak, and it's a five-minute check before anyone buys a turbo.

  The pending EGR code I'd leave alone for now — it hasn't confirmed, and a
  fouled EGR is a plausible consequence of running underboost rather than a
  separate fault.

Beachten Sie, was es nicht getan hat: raten und anbieten, die Fehlercodes zu löschen.

Related MCP server: Codex MCP Server

Architektur

        +--------------------------------------------------+
        |   Cyber-HUD  (React · Three.js · Framer Motion)   |
        +---------------------------+----------------------+
                                    | WS /ws/diagnostics
        +---------------------------+----------------------+
        |         FastAPI  (telemetry · agent · HITL)       |
        +---------------------------+----------------------+
                                    |
                     +--------------+------------+
                     |     LangGraph agent       |
                     |  Claude Opus 5 / Ollama   |
                     +-------------+-------------+
                                   |
                 +-----------------+-----------------+
                 |                 |                 |
       +---------v------+ +--------v-------+ +-------v--------+
       | Car_Interface  | | RAG_Workshop   | |  Web_Search    |
       |      MCP       | |      MCP       | |      MCP       |
       +---------+------+ +--------+-------+ +-------+--------+
                 |                 |                 |
        UDS over CAN       local manuals      Tavily / DuckDuckGo

• Car_Interface_MCP — python-can + udsoncan. Liest DTCs, Live-Daten und rohe DIDs von jedem Modul; löscht Codes nur über den Freigabe-Handshake. Fünf austauschbare Backends plus einen integrierten ECU-Simulator.

• RAG_Workshop_MCP — ChromaDB über Ihre eigenen Werkstatthandbuch-PDFs. Läuft vollständig auf dem Gerät; jede Antwort enthält eine Datei- und Seitenangabe.

• Web_Search_MCP — Tavily mit einem schlüssellosen DuckDuckGo-Fallback, gewichtet auf Land-Rover-Foren.

• Der Orchestrator — standardmäßig READ_ONLY; jeder Schreibvorgang pausiert den Graphen und wartet auf einen Menschen.

Ausführliche Details in docs/ARCHITECTURE.md.

Installation

git clone https://github.com/Mati83mon/Car_Diagnostic_Ai.git
cd Car_Diagnostic_Ai

python3 -m venv .venv
source .venv/bin/activate           # Windows: .venv\Scripts\activate

pip install -e ".[all,dev]"         # or: pip install -r requirements.txt

cp .env.example .env                # then edit it

Auf Termux oder einem anderen ARM-Gerät, auf dem die schweren Zusätze nicht gebaut werden können, überspringen Sie sie — das Projekt ist so konzipiert, dass es auch ohne sie funktioniert:

pip install -e ".[car,mcp,agent,web]"

Prüfen, ob es funktioniert

majster-ai doctor

Auch verfügbar als cda und car-diagnostic-ai, oder python main.py <command>.

Konfiguration

Alles befindet sich in .env. Die Standardwerte sind sicher, daher ist eine leere Datei eine gültige Datei. Die wichtigsten Einstellungen:

# --- safety -----------------------------------------------------------
MAJSTER_WRITE_ENABLED=false      # master switch. Leave false.
MAJSTER_REQUIRE_APPROVAL=true    # human-in-the-loop. Leave true.

# --- vehicle interface -------------------------------------------------
MAJSTER_CAN_BACKEND=virtual      # virtual|socketcan|slcan|serial|j2534|rfcomm
MAJSTER_CAN_CHANNEL=can0
MAJSTER_CAN_BITRATE=500000

# --- LLM ----------------------------------------------------------------
ANTHROPIC_API_KEY=sk-ant-...     # Claude Opus 5; falls back to Ollama if unset
MAJSTER_OLLAMA_MODEL=qwen2.5:7b-instruct

# --- web search ---------------------------------------------------------
TAVILY_API_KEY=tvly-...          # optional; DuckDuckGo is used without it

Siehe .env.example für jede Option, mit Anmerkungen.

Verwendung

Interaktiv

majster-ai chat

Einmalig

majster-ai ask "why is the DPF light on?"

Direkte Werkzeuge, ohne LLM

majster-ai dtc --module ECM              # read fault codes
majster-ai dtc --all                     # scan every module
majster-ai live RPM COOLANT_TEMP MAF     # read live data
majster-ai scan                          # discover which ECUs answer
majster-ai clear --module ECM            # write: prompts for approval

Werkstatthandbücher

cp ~/manuals/*.pdf data/manuals/
majster-ai ingest
majster-ai search "swirl flap removal procedure"

Handbücher werden lokal indiziert und durchsucht. Es wird nichts hochgeladen.

Weboberfläche

cd frontend && npm install && npm run build   # once
majster-ai web                                # http://127.0.0.1:8000

Für die Frontend-Entwicklung führen Sie den Vite-Dev-Server parallel dazu aus:

majster-ai web            # terminal 1 — API on :8000
cd frontend && npm run dev  # terminal 2 — UI on :5173, proxying to :8000

Die UI streamt Live-Telemetrie, zeigt den Modulzustand auf einem 3D-Fahrgestell und pausiert für eine Drag-to-Authorize-Geste vor jedem Schreibvorgang. Ein Klick auf einen Fehlercode bewegt die Kamera zu der Komponente, auf die er sich bezieht — ein Fahrgestellcode wie C0034 führt zum Sensor des rechten Vorderrads, nicht zum ABS-Modul im Motorraum.

majster-ai web bindet standardmäßig an 127.0.0.1. Alles, was den Port erreichen kann, kann den Agenten bitten, einen Schreibvorgang vorzuschlagen; die Freigabesperre bleibt bestehen, aber die Eingabeaufforderung würde von demjenigen beantwortet, der dort ist. Verwenden Sie --host 0.0.0.0 nur in einem Netzwerk, das Sie kontrollieren.

Als MCP-Server für einen anderen Client

majster-ai serve car_interface           # stdio transport

Die Konfiguration für Claude Desktop und andere befindet sich in docs/ARCHITECTURE.md.

Sicherheitsmodell

Vier unabhängige Ebenen stehen zwischen dem Modell und dem Fahrzeug. Ein Schreibvorgang muss alle durchlaufen.

Der Browser ist einfach ein weiterer Genehmiger. Der Schieberegler sendet einen booleschen Wert; das Bestätigungstoken wird im Serverprozess erstellt und eingelöst und erscheint nie in einem WebSocket-Frame. Ein Client kann die Frage beantworten, die der Server zu stellen gewählt hat — er kann nie eine stellen und nie die Berechtigung erzeugen, die den Schreibvorgang ausführt.

Ebene 2 befindet sich im Dienst hinter dem MCP-Server, sodass sie das Auto auch dann schützt, wenn etwas anderes als dieser Agent den Dienst steuert.

========================================================================
  WRITE OPERATION - HUMAN APPROVAL REQUIRED
========================================================================
  Operation : clear_dtc
  Module    : ECM (Engine Control Module - 2.2 TD4)
  Scope     : ALL stored DTCs in this module
  Risk      : MEDIUM        Reversible: NO
  Will erase 3 code(s):
      - P0299-00     Turbocharger/Supercharger A Underboost Condition
      - P2015-00     Intake Manifold Runner Position Sensor/Switch Circuit
      - P0401-00     Exhaust Gas Recirculation Flow Insufficient Detected

  Consequences:
      ! Freeze-frame data captured when the fault occurred will be lost.
      ! Readiness monitors reset; the vehicle may fail an emissions test.
      ! Clearing does not repair anything. If the fault is still present
        the code will return.
========================================================================

  Type 'yes' to authorise, anything else to decline:

Ausführliche Details in docs/SAFETY.md.

Hardware

Der Freelander 2 verwendet ISO 15765-4 CAN mit 500 kbit/s und 11-Bit-Identifikatoren, an den OBD-II-Pins 6 (CAN-H) und 14 (CAN-L).

Einrichtung für jede, plus Termux, Raspberry Pi und welche ELM327-Adapter tatsächlich funktionieren: docs/HARDWARE.md.

Über die Daten in diesem Repository

Nur zwei Diagnoseadressen an jedem Auto sind gesetzlich festgelegt und daher sicher: die Antriebsstrangadressen 0x7E0/0x7E8 und 0x7E1/0x7E9. Alles andere in der integrierten Modulkarte stammt aus der Community und wird mit verified: false markiert ausgeliefert.

Das Gleiche gilt für die Skalierung von Live-Daten: Die SAE-J1979-PIDs sind Standard und als verifiziert markiert; Hersteller-DIDs sind proprietär und keine werden überhaupt ausgeliefert, weil eine selbstbewusst falsche Zahl das schlechtestmögliche Ergebnis eines Diagnosewerkzeugs ist.

Um herauszufinden, was für Ihr Auto zutrifft:

majster-ai scan

Dann notieren Sie, was geantwortet hat, in data/modules.json. Siehe docs/FREELANDER2.md.

Entwicklung

make install-dev
make check                # black --check, flake8, pytest
make test-cov             # coverage report

Die gesamte Testsuite läuft gegen den prozessinternen ECU-Simulator — keine Hardware, kein API-Schlüssel, kein Netzwerk:

736 passed, 1 skipped

Der Simulator ist eine echte UDS-Implementierung und kein Mock, sodass die Wiederholungslogik, der DTC-Codec, die MCP-Tools und das HITL-Gate alle gegen denselben Bytestrom laufen, den sie auf einem echten Bus sehen werden. Fehlerinjektion macht die Pfade für unzuverlässige Busse deterministisch:

ecm.inject_faults(drop_next=2)      # two silent timeouts, then fine
ecm.inject_faults(pending_next=3)   # three NRC 0x78, then the answer
ecm.inject_faults(busy_next=1)      # one NRC 0x21 busyRepeatRequest

CI führt Lint, die Testsuite auf Python 3.10/3.11/3.12, die Sicherheitsinvarianten als eigenen Job und einen Integrationsjob aus, der die MCP-Server als echte Unterprozesse startet.

Projektstruktur

majster_ai/
├── agent/              LangGraph orchestrator, HITL, LLM providers
├── mcp_servers/
│   ├── car_interface/  UDS/CAN — the safety gate lives in service.py
│   ├── rag_workshop/   local manual retrieval
│   └── web_search/     Tavily / DuckDuckGo
├── web/                FastAPI + /ws/diagnostics, WebSocketApprover
├── config.py           settings and the two safety gates
└── cli.py
frontend/               React + Three.js Cyber-HUD (see frontend/README.md)
tests/                  736 tests, all hardware-free
docs/                   ARCHITECTURE, SAFETY, HARDWARE, FREELANDER2

Haftungsausschluss

Dieses Projekt dient Bildungs- und Forschungszwecken. Es ist kein zertifiziertes Diagnosewerkzeug und kein Ersatz für die Ausrüstung des Herstellers oder einen qualifizierten Techniker.

Die Autoren übernehmen keine Haftung für Schäden am Fahrzeug, Schäden an Steuergeräten, fehlgeschlagene Reparaturen, erloschene Garantien oder Verletzungen, die durch die Verwendung dieser Software entstehen. Sie sind dafür verantwortlich, zu verstehen, was ein Befehl bewirkt, bevor er den Bus Ihres Autos erreicht. Wenn Sie sich nicht sicher sind, senden Sie ihn nicht.

Haftungsausschluss

Das Projekt dient ausschließlich Bildungs- und Forschungszwecken. Der Autor übernimmt keine Verantwortung für Schäden am Fahrzeug, Schäden an Steuergeräten (ECU) oder Körperverletzungen, die aus der Nutzung dieser Software resultieren.

Stellen Sie immer sicher, dass Sie wissen, welche Befehle — insbesondere Schreibbefehle — an den CAN-Bus Ihres Autos gesendet werden.

Lizenz

MIT — siehe LICENSE.

Werkstatthandbücher sind urheberrechtlich geschützt und werden nicht mit diesem Projekt verteilt. data/manuals/ ist gitignored; besorgen Sie sich Ihre eigenen legal.