Majster-AI — автомобильный UDS-диагностический агент на базе MCP

Car_Diagnostic_AI — также известный как CDA и Majster-AI — это диагностический агент, который подключает большую языковую модель к блокам управления автомобиля через UDS/CAN, к локальному индексу руководств по ремонту и к живому веб-поиску. Три возможности представлены в виде независимых серверов Model Context Protocol и оркеструются агентом LangGraph с жёстким шлюзом human-in-the-loop для всего, что записывает данные в автомобиль.

Разработан и протестирован на Land Rover Freelander 2 (2010, 2.2 TD4).

Поставляется с веб-интерфейсом Cyber-HUD: интерактивное 3D-шасси, контакты модулей которого расположены в реальных координатах автомобиля, датчики телеметрии в реальном времени и шлюз перетаскивания для авторизации любых записей в автомобиль.

⚠️ По умолчанию работает с симулятором и в режиме READ_ONLY

Свежий клон не может передавать данные на реальную шину и не может записывать в автомобиль. Оба действия требуют осознанного изменения конфигурации. Прочтите docs/SAFETY.md перед подключением к автомобилю, который вам дорог.

Что он на самом деле делает

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.

Обратите внимание, чего он не делал: не гадал и не предлагал стереть коды.

Related MCP server: Canopy

Архитектура

        +--------------------------------------------------+
        |   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. Читает DTC, живые данные и сырые DID с любого модуля; стирает коды только через процедуру подтверждения. Пять взаимозаменяемых бэкендов плюс встроенный симулятор ECU.

• RAG_Workshop_MCP — ChromaDB поверх ваших собственных PDF-руководств по ремонту. Работает полностью на устройстве; каждый ответ содержит цитату с указанием файла и страницы.

• Web_Search_MCP — Tavily с запасным вариантом DuckDuckGo без ключа, с приоритетом форумов Land Rover.

• Оркестратор — READ_ONLY по умолчанию; каждая запись приостанавливает граф и ждёт человека.

Полные подробности в docs/ARCHITECTURE.md.

Установка

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

На Termux или другом ARM-устройстве, где тяжёлые дополнения не собираются, пропустите их — проект спроектирован так, чтобы работать без них:

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

Проверка работоспособности

majster-ai doctor

Также доступен как cda и car-diagnostic-ai, или python main.py <command>.

Настройка

Всё находится в .env. Значения по умолчанию безопасны, поэтому пустой файл — это допустимый файл. Наиболее важные настройки:

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

См. .env.example — все параметры с пояснениями.

Использование

Интерактивный режим

majster-ai chat

Разовый запуск

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

Прямые инструменты, без 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

Руководства по ремонту

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

Руководства индексируются и ищутся локально. Ничего не загружается.

Веб-интерфейс

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

Для разработки фронтенда запустите dev-сервер Vite параллельно:

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

Интерфейс транслирует телеметрию в реальном времени, показывает состояние модулей на 3D-шасси и приостанавливается для жеста перетаскивания перед любой записью. Клик по коду неисправности перемещает камеру к компоненту, на который он указывает — код шасси, например C0034, ведёт к датчику переднего правого колеса, а не к модулю ABS в моторном отсеке.

majster-ai web по умолчанию привязывается к 127.0.0.1. Всё, что может достичь порта, может попросить агента предложить запись; шлюз одобрения по-прежнему действует, но на запрос ответит тот, кто там находится. Используйте --host 0.0.0.0 только в сети, которой вы управляете.

Как MCP-серверы для другого клиента

majster-ai serve car_interface           # stdio transport

Конфигурация для Claude Desktop и других клиентов — в docs/ARCHITECTURE.md.

Модель безопасности

Четыре независимых уровня находятся между моделью и автомобилем. Запись должна пройти через все.

Браузер — просто ещё один утверждающий. Слайдер отправляет одно логическое значение; токен подтверждения создаётся и используется внутри серверного процесса и никогда не появляется ни в одном кадре WebSocket. Клиент может ответить на вопрос, который сервер решил задать, — но не может задать свой и не может создать учётные данные, выполняющие запись.

Уровень 2 находится в сервисе за MCP-сервером, поэтому он защищает автомобиль, даже когда управляет не этот агент.

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

Полные подробности в docs/SAFETY.md.

Оборудование

Freelander 2 использует ISO 15765-4 CAN на 500 кбит/с с 11-битными идентификаторами, на контактах OBD-II 6 (CAN-H) и 14 (CAN-L).

Настройка для каждого, плюс Termux, Raspberry Pi и какие адаптеры ELM327 действительно работают: docs/HARDWARE.md.

О данных в этом репозитории

Только два диагностических адреса на любом автомобиле законодательно закреплены и поэтому достоверны: адреса силового агрегата 0x7E0/0x7E8 и 0x7E1/0x7E9. Всё остальное во встроенной карте модулей получено от сообщества и поставляется с пометкой verified: false.

То же самое относится к масштабированию живых данных: PID из SAE J1979 являются стандартными и помечены как проверенные; DID производителей являются проприетарными, и ни один не поставляется вообще, потому что уверенно-неверное число — это худший возможный результат диагностического инструмента.

Чтобы выяснить, что верно для вашего автомобиля:

majster-ai scan

Затем запишите, что ответило, в data/modules.json. См. docs/FREELANDER2.md.

Разработка

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

Весь набор тестов работает против внутрипроцессного симулятора ECU — без оборудования, без API-ключа, без сети:

736 passed, 1 skipped

Симулятор — это реальная реализация UDS, а не заглушка, поэтому логика повторов, кодек DTC, инструменты MCP и шлюз HITL работают с тем же потоком байтов, который они увидят на реальной шине. Инъекция сбоев делает пути нестабильной шины детерминированными:

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 запускает lint, набор тестов на Python 3.10/3.11/3.12, инварианты безопасности как отдельную задачу и интеграционную задачу, которая запускает MCP-серверы как реальные подпроцессы.

Структура проекта

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

Отказ от ответственности

Этот проект предназначен для образовательных и исследовательских целей. Он не является сертифицированным диагностическим инструментом и не заменяет оборудование производителя или квалифицированного техника.

Авторы не несут ответственности за повреждение автомобиля, повреждение блоков управления, неудачный ремонт, аннулирование гарантии или травмы, возникшие в результате использования этого программного обеспечения. Вы несёте ответственность за понимание того, что делает любая команда, прежде чем она попадёт на шину вашего автомобиля. Если вы не уверены — не отправляйте её.

Отказ от ответственности

Проект служит исключительно образовательным и исследовательским целям. Автор не несёт ответственности за любые повреждения автомобиля, повреждения блоков управления (ECU) или телесные повреждения, возникшие в результате использования этого программного обеспечения.

Всегда убеждайтесь, что вы знаете, какие команды — особенно команды ЗАПИСИ — отправляются на шину CAN вашего автомобиля.

Лицензия

MIT — см. LICENSE.

Руководства по ремонту защищены авторским правом и не распространяются вместе с этим проектом. data/manuals/ находится в gitignore; приобретайте свои законным путём.