This was created as part of our submission for the Anthropic Gradio MCP's 1st Birthday hackathon: https://huggingface.co/spaces/MCP-1st-Birthday/Vehicle-Diagnostic-Assistant

This repository is covering the AI Agent. The MCP Server, which we also developed as part of this hackathon is accessible here: https://github.com/castlebbs/Embedded-MCP-ELM327

For this second hackathon, we decided to have fun and created an AI agent that connects directly to your car and helps you diagnose issues.

For this project, we have done:

• AI agent and chatbot to perform car diagnostics
• Diagnostic MCP server, which we installed directly on an OBD-II device.

There is an OBD-II port in most cars that lets a diagnostic device communicate with the car's computer. Mechanics attach their scanner to this port to read car health information and find out why warning lights are on.

Above is the OBD-II dongle, which we used, we had to open it to replace the firmware with our special hackathon firmware ☺️

This demo on HuggingFace space is connecting to an OBD-II simulator (we don't want everyone to mess with our car :-). Fun fact, the simulator is also a Gradio space: OBD-II Simulator Gradio space

If you want more details on how we implemented the MCP Server on the diagnostic device, navigate to the "MCP Server on embedded device" tab.

Check our participation to the previous event: In-game AI Generation of 3D environments.

The Vehicle Diagnostic Assistant consists of three main components:

1. Gradio Web Interface - User-facing chat interface with streaming responses
2. LangChain/LangGraph Agent - Orchestrates tool calls and AI reasoning
3. MCP Server - Provides vehicle diagnostic capabilities via Model Context Protocol

User → Gradio UI → LangGraph Agent → MCP Tools → OBD-II Device → Vehicle ECU
                        ↓
                   AI Model (Nebius/Anthropic)
                        ↓
                   Additional Tools (YouTube, VIN decoder, calculators)

The agent uses LangGraph for stateful conversation management with streaming support:

• Model: Configurable LLM backends:
  • Nebius AI (Qwen3-Coder-480B, Llama-3.3-70B, DeepSeek-R1)
• Checkpointing: InMemorySaver for conversation state persistence
• Message Streaming: Token-by-token streaming with tool call tracking
• Session Management: Thread-based conversation isolation using UUID

Agent Configuration:

agent = create_agent(
    model=model,
    system_prompt=system_prompt,
    tools=all_tools,
    checkpointer=checkpointer,
)

Transport: HTTP-based streaming protocol (streamable_http) Protocol: JSON-RPC 2.0 over HTTP Endpoints:

• Physical device: http://192.168.10.69/mcp
• Simulator: https://castlebbs-elm327-simulator.hf.space/gradio_api/mcp/

Available MCP Tools:

• get_system_status - MCP Server status information
• send_elm327_command - Raw ELM327 AT commands and OBD-II PID queries
• get_history - Historical PID data retrieval

The agent has access to specialized processing tools:

OBD-II Data Processing:

• hex_to_decimal(hex_value) - Convert hex responses to decimal
• combine_bytes(byte_a, byte_b, byte_c, byte_d) - Multi-byte value combination (big-endian)
• calculate_obd_value(formula, bytes) - Apply OBD-II formulas (e.g., (A*256+B)/4 for RPM)

Vehicle Information:

• decode_vin(vin) - VIN lookup via NHTSA vPIC API
• search_youtube_video(query) - Tutorial search for repairs

Safety Features:

• safe_eval() - Sandboxed formula evaluation (no arbitrary code execution)
• Limited operators: +, -, *, /, //, %, **, unary +/-
• Exponent limits and division-by-zero protection

Hardware Platform:

• MCU: WinnerMicro W600-B800
• RTOS: FreeRTOS
• Network Stack: lwIP
• Communication: UART to ELM327 chip (38400 baud, 8N1)

Firmware Features:

• OTA (Over-The-Air) firmware updates
• UDP syslog for remote debugging
• ELM327 protocol driver with simulation mode
• HTTP server for MCP endpoint
• JSON-RPC 2.0 request handler

Protocol Stack:

MCP Client (Agent) → HTTP Request → JSON-RPC 2.0 → MCP Method Router → Tool Handlers → ELM327 Driver → UART → ELM327 Chip → CAN Bus → Vehicle ECU

OBD-II (On-Board Diagnostics II) is a standardized vehicle diagnostic protocol:

• PIDs (Parameter IDs): Standardized codes for sensor data (e.g., 01 0C for engine RPM)
• DTCs (Diagnostic Trouble Codes): Error codes in format P0XXX, C0XXX, B0XXX, U0XXX
• Modes:
  • Mode 01: Current data
  • Mode 02: Freeze frame data
  • Mode 03: Stored DTCs
  • Mode 04: Clear DTCs
  • Mode 09: Vehicle information (VIN)

ELM327: Industry-standard OBD-II interpreter chip that translates UART commands to CAN/ISO protocols.

• Python 3.8+
• pip package manager
• Access to an OBD-II device or simulator

1. Clone the repository:

   git clone <repository-url>
   cd Vehicle-Diagnostic-Assistant

2. Install dependencies:

   pip install -r requirements.txt

3. Configure API keys:

   • For Nebius AI: Set NEBIUS_API_KEY environment variable

4. Configure MCP server endpoint in app.py:

   "url": "http://192.168.10.69/mcp",  # Physical device
   # or
   "url": "https://castlebbs-elm327-simulator.hf.space/gradio_api/mcp/",  # Simulator

5. Launch the application:

   python app.py

docker-compose up --build

Example 1: Check Engine Status

User: "Get system information"
Agent: [Calls get_system_status tool] → Shows information about the ELM327 MCP server.

Example 2: Read Engine RPM

User: "What's my current RPM?"
Agent: [Calls send_obd2_command with PID 01 0C] → "41 0C 1A F8"
Agent: [Calls combine_bytes + calculate_obd_value] → "1710 RPM"

Example 3: Decode VIN

User: "Decode VIN 5TDKRKEC7PS142916"
Agent: [Calls decode_vin tool] → Returns make, model, year, engine specs

Example 4: Diagnose Error Code

User: "I have a P0420 code, what does it mean?"
Agent: [Analyzes DTC] → "Catalyst System Efficiency Below Threshold"
Agent: [Calls search_youtube_video] → Returns repair tutorial link

Custom PID Calculation:

# The agent can calculate any OBD-II PID using formulas
# Example: Fuel pressure (PID 01 0A)
calculate_obd_value("A * 3", byte_a="4F")  # Returns 237 kPa

Historical Data Analysis:

# Retrieve historical PID data collected by the MCP server
get_history(pid="01 0C", limit=10)  # Last 10 RPM readings

langchain                    # LLM framework
langchain[anthropic]         # Anthropic Claude support (optional)
langchain_nebius             # Nebius AI integration
langchain-mcp-adapters       # MCP protocol adapters
gradio                       # Web UI framework
youtube-search               # YouTube API wrapper

• WinnerMicro W600 SDK - FreeRTOS, lwIP, peripheral drivers
• EasyLogger - Modified for UDP syslog support
• Custom Libraries:
  • elm327.c - ELM327 protocol driver
  • mcp_http.c - HTTP server for MCP
  • mcp_jsonrpc.c - JSON-RPC 2.0 implementation
  • mcp_methods.c - MCP tool handlers

The agent uses a system prompt defined in prompts.py.

The dtc_display.py module provides a custom Gradio component for rendering Diagnostic Trouble Codes with:

• Color-coded severity (red for critical, yellow for warnings)
• Description and probable causes
• Suggested repairs

The agent implements token-by-token streaming with:

• Real-time tool call visualization
• Argument accumulation for partial tool calls
• Concurrent message tracking for multiple tools
• Smooth UX with loading indicators

The Gradio OBD-II Simulator provides:

• Simulated ECU responses without a real vehicle
• Configurable engine parameters
• DTC injection for testing diagnostic workflows
• Safe environment for development

The agent can query any standard PID, including:

• 01 00: PIDs supported [01-20]
• 01 0C: Engine RPM
• 01 0D: Vehicle speed
• 01 05: Engine coolant temperature
• 01 0F: Intake air temperature
• 01 11: Throttle position
• 01 10: MAF air flow rate
• 01 0E: Timing advance
• 01 2F: Fuel tank level
• 09 02: Vehicle Identification Number (VIN)

• MCP Connection Failures: Graceful degradation with error messages
• Tool Timeouts: 20-second timeout with retry logic
• Invalid Responses: Hex validation and format checking
• Division by Zero: Protected in all calculation tools
• Malformed JSON-RPC: Error code responses per spec

• @stargarnet: AI agent development
• @castlebbs: MCP server and embedded firmware

• Nebius Token Factory

Frontend & Agent:

• Gradio 6 - Interactive web interface
• LangChain/LangGraph - Agent orchestration
• Nebius AI / Anthropic Claude - Language models

Backend Tools:

• MCP Server (embedded in OBD-II dongle or simulator)
  • System status monitoring
  • ELM327 command execution
  • OBD-II PID queries
  • Historical data retrieval
• OBD-II response decoding tools
• Hexadecimal conversion utilities
• NHTSA vPIC VIN decoder
• YouTube search integration

Embedded System:

• WinnerMicro W600-B800 MCU
• FreeRTOS + lwIP
• Custom ELM327 driver
• HTTP/JSON-RPC server

Vehicle-Diagnostic-Assistant/
├── app.py                      # Main Gradio application
├── tools.py                    # Custom LangChain tools
├── prompts.py                  # System prompts for the agent
├── dtc_display.py              # DTC rendering component
├── requirements.txt            # Python dependencies
├── docker-compose.yml          # Docker deployment config
├── Dockerfile                  # Container build instructions
├── styles.css                  # Custom UI styling
│
├── assets/                     # Images and media
│   ├── obd.png                 # Hardware photos
│   ├── agent.png               # UI screenshots
│   └── probes.png              # Firmware upload setup
│
├── MCP_servers/
│   └── gradio-OBD2-simulator/  # Simulator MCP server
│       ├── app.py              # Gradio simulator interface
│       └── README.md           # Simulator documentation
│
├── hackathon_detail.md         # Hackathon submission details
├── mcp_server_detail.md        # Embedded firmware documentation
└── LICENSE                     # Project license

• app.py: Main application entry point. Initializes LangGraph agent, connects to MCP server, handles streaming chat interface
• tools.py: Defines custom tools for hex conversion, byte combination, OBD-II calculation, VIN decoding, and YouTube search
• prompts.py: Contains the system prompt that gives the agent knowledge of vehicle diagnostics
• dtc_display.py: Custom Gradio component for rendering diagnostic trouble codes with color coding
• mcp_server_detail.md: Complete technical documentation of the embedded firmware implementation

MCP Server Connection Failed

• Verify the device is powered and connected to Wi-Fi
• Check the IP address matches the configuration
• Ensure firewall allows HTTP traffic on port 80
• Test with simulator first: https://castlebbs-elm327-simulator.hf.space/gradio_api/mcp/

No Response from Vehicle

• Ensure vehicle ignition is ON (engine doesn't need to run)
• Check OBD-II dongle is fully inserted into vehicle port
• Verify ELM327 chip is responding to AT commands
• Try resetting the ELM327: send ATZ command

Tool Timeout Errors

• Increase timeout in app.py: "timeout": 30.0
• Check network latency to MCP server
• Verify vehicle ECU is responsive (try different PIDs)

Invalid Hex Values

• Ensure responses are properly formatted (space-separated hex bytes)
• Check for "NO DATA" or error responses from ELM327
• Verify PID is supported by the vehicle (01 00 query)

This project is licensed under the terms specified in the LICENSE file.