Majster-AI — Agente de diagnóstico UDS automotriz vía MCP

Car_Diagnostic_AI — también conocido como CDA y Majster-AI — es un agente de diagnóstico que conecta un modelo de lenguaje grande a los módulos de control de un automóvil a través de UDS/CAN, a un índice local de manuales de taller y a la búsqueda web en vivo. Las tres capacidades se exponen como servidores independientes del Model Context Protocol y son orquestadas por un agente LangGraph con una barrera estricta de humano en el circuito para cualquier cosa que escriba en el vehículo.

Desarrollado y probado contra un Land Rover Freelander 2 (2010, 2.2 TD4).

Incluye una interfaz web Cyber-HUD: un chasis 3D interactivo cuyos pines de módulo se encuentran en coordenadas reales del vehículo, medidores de telemetría en vivo y una puerta de arrastrar para autorizar cualquier escritura en el automóvil.

⚠️ Por defecto usa un simulador y es READ_ONLY

Un clon recién hecho no puede transmitir en un bus real ni escribir en un vehículo. Ambas cosas requieren un cambio de configuración deliberado. Lee docs/SAFETY.md antes de conectar un automóvil que te importe.

Lo que realmente hace

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.

Observa lo que no hizo: adivinar y ofrecer borrar los códigos.

Related MCP server: Codex MCP Server

Arquitectura

        +--------------------------------------------------+
        |   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. Lee DTCs, datos en vivo y DIDs sin procesar de cualquier módulo; borra códigos solo a través del protocolo de aprobación. Cinco backends intercambiables más un simulador de ECU integrado.

• RAG_Workshop_MCP — ChromaDB sobre tus propios PDFs de manuales de taller. Se ejecuta completamente en el dispositivo; cada respuesta lleva una cita de archivo y página.

• Web_Search_MCP — Tavily con un respaldo DuckDuckGo sin clave, ponderado hacia foros de Land Rover.

• El orquestador — READ_ONLY por defecto; cada escritura pausa el grafo y espera a un humano.

Detalle completo en docs/ARCHITECTURE.md.

Instalación

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

En Termux u otro dispositivo ARM donde los extras pesados no se compilen, omítelos: el proyecto está diseñado para funcionar sin ellos:

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

Comprueba que funciona

majster-ai doctor

También disponible como cda y car-diagnostic-ai, o python main.py <command>.

Configuración

Todo vive en .env. Los valores predeterminados son seguros, por lo que un archivo vacío es un archivo válido. Los ajustes más importantes:

# --- 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

Consulta .env.example para ver todas las opciones, anotadas.

Uso

Interactivo

majster-ai chat

De una sola vez

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

Herramientas directas, sin 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

Manuales de taller

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

Los manuales se indexan y buscan localmente. No se sube nada.

Interfaz web

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

Para el desarrollo del frontend, ejecuta el servidor de desarrollo de Vite junto a él:

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

La interfaz transmite telemetría en vivo, muestra la salud de los módulos en un chasis 3D y se detiene para un gesto de arrastrar para autorizar antes de cualquier escritura. Al hacer clic en un código de falla, la cámara vuela al componente al que se refiere: un código de chasis como C0034 va al sensor de la rueda delantera derecha, no al módulo ABS en el compartimiento del motor.

majster-ai web se vincula a 127.0.0.1 por defecto. Cualquier cosa que pueda alcanzar el puerto puede pedirle al agente que proponga una escritura; la puerta de aprobación sigue vigente, pero la solicitud sería respondida por quien esté allí. Usa --host 0.0.0.0 solo en una red que controles.

Como servidores MCP para otro cliente

majster-ai serve car_interface           # stdio transport

La configuración para Claude Desktop y otros está en docs/ARCHITECTURE.md.

Modelo de seguridad

Cuatro capas independientes se interponen entre el modelo y el vehículo. Una escritura tiene que pasar por todas ellas.

El navegador es simplemente otro aprobador. El control deslizante envía un booleano; el token de confirmación se crea y se canjea dentro del proceso del servidor y nunca aparece en ningún marco de WebSocket. Un cliente puede responder a la pregunta que el servidor eligió hacer; nunca puede plantear una, y nunca puede acuñar la credencial que realiza la escritura.

La capa 2 vive en el servicio detrás del servidor MCP, por lo que protege el automóvil incluso cuando algo que no sea este agente está conduciendo.

========================================================================
  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:

Detalle completo en docs/SAFETY.md.

Hardware

El Freelander 2 usa CAN ISO 15765-4 a 500 kbit/s con identificadores de 11 bits, en los pines OBD-II 6 (CAN-H) y 14 (CAN-L).

Configuración para cada uno, además de Termux, Raspberry Pi y qué adaptadores ELM327 funcionan realmente: docs/HARDWARE.md.

Sobre los datos en este repositorio

Solo dos direcciones de diagnóstico en cualquier automóvil están legisladas y, por lo tanto, son seguras: las direcciones del tren motriz 0x7E0/0x7E8 y 0x7E1/0x7E9. Todo lo demás en el mapa de módulos integrado proviene de la comunidad y se distribuye marcado como verified: false.

Lo mismo se aplica al escalado de datos en vivo: los PIDs SAE J1979 son estándar y están marcados como verificados; los DIDs del fabricante son propietarios y ninguno se incluye, porque un número incorrecto con confianza es el peor resultado posible de una herramienta de diagnóstico.

Para descubrir qué es cierto para tu automóvil:

majster-ai scan

Luego registra lo que respondió en data/modules.json. Consulta docs/FREELANDER2.md.

Desarrollo

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

Toda la suite se ejecuta contra el simulador de ECU en proceso: sin hardware, sin clave de API, sin red:

736 passed, 1 skipped

El simulador es una implementación UDS real en lugar de un simulacro, por lo que la lógica de reintento, el códec DTC, las herramientas MCP y la puerta HITL se ejecutan contra el mismo flujo de bytes que verán en un bus real. La inyección de fallas hace que los caminos de bus inestable sean deterministas:

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 ejecuta lint, la suite en Python 3.10/3.11/3.12, los invariantes de seguridad como su propio trabajo, y un trabajo de integración que inicia los servidores MCP como subprocesos reales.

Estructura del proyecto

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

Descargo de responsabilidad

Este proyecto es para fines educativos y de investigación. No es una herramienta de diagnóstico certificada ni un sustituto del equipo del fabricante o de un técnico calificado.

Los autores no aceptan ninguna responsabilidad por daños al vehículo, daños a los módulos de control, reparaciones fallidas, garantías anuladas o lesiones derivadas del uso de este software. Eres responsable de entender qué hace cualquier comando antes de que llegue al bus de tu automóvil. Si no estás seguro, no lo envíes.

Descargo de responsabilidad

El proyecto sirve únicamente para fines educativos y de investigación. El autor no se hace responsable de ningún daño al vehículo, daño a los controladores (ECU) o lesiones corporales resultantes del uso de este software.

Asegúrate siempre de saber qué comandos — especialmente los comandos de ESCRITURA — se envían al bus CAN de tu automóvil.

Licencia

MIT — consulta LICENSE.

Los manuales de taller tienen derechos de autor y no se distribuyen con este proyecto. data/manuals/ está en gitignore; consigue los tuyos legalmente.