vHal MCP Server

MCP server for Android Vehicle Hardware Abstraction Layer (vHAL) documentation and source code analysis. This server provides intelligent tools for exploring vHAL properties, understanding their relationships, and implementing automotive climate control systems.

Overview

The vHAL MCP Server helps Android Automotive developers by providing:

• Property Analysis: Discover vHAL properties and their relationships

• Source Code Lookup: Find Android source code implementations

• Implementation Guidance: Get step-by-step implementation recommendations

• Documentation Summarization: Access curated vHAL documentation insights

Demo

See the vHAL MCP Server in action:

https://github.com/user-attachments/assets/6fcdc5fb-6cbb-4c69-9528-fa3bdee4acb1

Example: Analyzing HVAC properties and implementation guidance using Claude Desktop with the vHAL MCP Server

Features

Core Tools

summarize_vhal(question)

• Summarizes vHAL implementation based on specific questions

• Analyzes Android automotive documentation

• Provides contextual answers for vHAL development

lookup_android_source_code(keyword, category)

• Searches Android source code for vHAL properties

• Returns property definitions with IDs and categories

• Provides direct links to source code locations

discover_related_properties(property_or_category)

• Analyzes property relationships and dependencies

• Suggests implementation order for complex features

• Groups properties by functional categories

analyze_vhal_implementation(property_name)

• Shows detailed source code analysis for specific properties

• Provides implementation examples and usage patterns

• Includes dependency analysis and best practices

generate_vhal_implementation_code(...)

• Generates complete VHAL property implementation code for AAOS

• Creates all necessary files, configurations, tests, and documentation

• Supports all VHAL data types, property groups, and access modes

• Includes HAL definitions, Java APIs, tests, and build configurations

generate_vhal_pr_message(...)

• Generates comprehensive pull request messages for VHAL implementations

• Creates structured PR descriptions with technical details and testing requirements

• Includes professional titles, change summaries, and review checklists

• Ready-to-copy-paste format for GitHub/GitLab integration

validate_vhal_sources_and_enhance_summary(question, include_source_validation, max_sources_to_check)

• Enhanced vHAL summary with complete source transparency and validation

• Validates URL accessibility to detect broken or moved documentation links

• Provides confidence scoring based on source reliability and accessibility

• Shows clear citations with response times and last-modified dates

• Suggests alternative sources for failed URLs

• Distinguishes between cached vs. live data for transparency

validate_vhal_property_request(property_name, property_description, ...)

• Validates vHAL property requests following Android best practices

• Checks if property already exists in latest Android release (Android 16)

• Recommends using existing Android properties when available

• Generates VENDOR_ properties with proper naming convention when needed

• Provides comprehensive analysis with similarity scoring and recommendations

• Supports all VHAL data types, property groups, and configurations

• Integrates with existing code generation tools for complete implementation

Installation

Prerequisites

• Python 3.12 or higher

• Internet connection for documentation scraping

• MCP-compatible client (Claude Desktop, Zed, or other MCP clients)

Local Setup

1. Clone the repository

   Using HTTPS:

   git clone https://github.com/feevlic/vhal-mcp-server.git

   Using SSH:

   git clone git@github.com:feevlic/vhal-mcp-server.git

2. Navigate to the project directory

   cd vhal-mcp-server

3. Install dependencies

   pip install -e .

MCP Client Configuration

Claude Desktop Configuration

1. Find your

   which uv

2. Locate your Claude Desktop configuration file

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%/Claude/claude_desktop_config.json

3. Add the server configuration

   Edit the configuration file and add the following (replace the paths with your actual paths):

   { "mcpServers": { "vhal-mcp-server": { "command": "/Users/[]/.local/bin/uv", "args": ["run", "--directory", "/Users/[]/vhal-mcp-server", "python", "main.py"], "env": { "PYTHONPATH": "/Users/[]/vhal-mcp-server" } } } }

You can find an example in the config folder.

Important:

• Replace /path/to/your/uv with the output from step 1 (e.g., /Users/yourusername/.local/bin/uv)

• Replace /path/to/vhal-mcp-server with the actual path where you cloned the repository

• On macOS, GUI applications like Claude Desktop may not have access to your shell's PATH, so using full paths is required

4. Restart Claude Desktop

   After saving the configuration file, completely quit and restart Claude Desktop for the MCP server to be loaded.

5. Allow MCP server access

   When you first ask a question that requires the vHAL tools, Claude will prompt you to allow the MCP server to use its tools. Click "Allow" to enable the vHAL analysis capabilities.

Usage

Basic Usage

The server exposes MCP tools that can be used through compatible clients. Each tool accepts specific parameters and returns structured information about vHAL properties and implementations.

Beginner Prompt Examples

Start with these simple prompts to explore vHAL capabilities:

Basic Property Discovery

Simple Implementation Questions

Property Lookup

Basic Temperature Control

Understanding Property Types

Advanced Prompt Examples

Once familiar with basic concepts, try these comprehensive prompts:

Complete System Implementation

Multi-Zone Climate Control

Seat Memory System

Safety-Critical Features

Performance Optimization

Custom Property Development

VHAL Code Generation Examples

Use the generate_vhal_implementation_code tool to create complete VHAL implementations:

Smart Dashboard Lighting System

Electric Vehicle Charging Management

Advanced HVAC Zone Control

Biometric Seat Adjustment

VHAL Pull Request Generation Examples

Use the generate_vhal_pr_message tool to create professional pull request messages:

Smart Dashboard Lighting PR

EV Charging System PR

Advanced HVAC Zone Control PR

VHAL Property Validation Examples

Use the validate_vhal_property_request tool to follow Android best practices and validate property requests:

Check for Existing Properties

Validate Climate Control Properties

Custom Vehicle Feature Validation

Advanced Property Validation

Property Type Validation

Expert Prompt: Complete VHAL System Development

This expert-level prompt demonstrates using all 6 MCP tools in a comprehensive workflow for developing a complete automotive system:

VHAL Code Generator Features

The generate_vhal_implementation_code tool creates complete, production-ready VHAL implementations:

Generated Files

For each VHAL property, the generator creates:

Core HAL Files:

• types.hal - Property definition and enums

• DefaultConfig.h - Property configuration

• EmulatedVehicleHal.cpp - Implementation logic

• VehicleProperty.aidl - AIDL interface

Framework Integration:

• VehiclePropertyIds.java - Java constants

• CarPropertyManager.java - API methods

• Configuration JSON files

Testing:

• VehicleHalTest.cpp - C++ unit tests

• VehiclePropertyTest.java - Java integration tests

System Configuration:

• SEPolicy rules

• Build configurations

• Documentation

Tool Parameters

Required:

• name: Property name (e.g., "HVAC_STEERING_WHEEL_HEAT")

• property_id: Unique property ID (hex format, e.g., "0x15400A03")

• property_type: Data type (BOOLEAN, INT32, INT64, FLOAT, STRING, BYTES, *_VEC, MIXED)

• group: Property group (HVAC, SEAT, LIGHTS, POWER, CLIMATE, etc.)

• access: Access mode (READ, WRITE, READ_WRITE)

• change_mode: Change mode (STATIC, ON_CHANGE, CONTINUOUS)

• description: Property description for documentation

Optional:

• units: Units (e.g., "celsius", "rpm")

• min_value: Minimum value for numeric types

• max_value: Maximum value for numeric types

• areas: List of vehicle areas/zones

• enum_values: Dict of enum names and values for INT32 enum properties

• dependencies: List of dependent property names

• sample_rate_hz: Sample rate for continuous properties

Property Types Supported

Basic Types:

• BOOLEAN: True/false values

• INT32: 32-bit integers

• INT64: 64-bit integers

• FLOAT: Floating point numbers

• STRING: Text values

• BYTES: Binary data

Vector Types:

• INT32_VEC: Arrays of integers

• FLOAT_VEC: Arrays of floats

• STRING_VEC: Arrays of strings

• BYTES_VEC: Arrays of binary data

Special Types:

• MIXED: Complex structured data

Property Groups

• BODY: Body control systems

• CABIN: Interior cabin controls

• CLIMATE: Climate control systems

• DISPLAY: Display and infotainment

• ENGINE: Engine management

• HVAC: Heating, ventilation, air conditioning

• INFO: Vehicle information

• INSTRUMENT_CLUSTER: Dashboard instruments

• LIGHTS: Lighting systems

• MIRROR: Mirror controls

• POWER: Power management

• SEAT: Seat controls

• VEHICLE_MAP_SERVICE: Navigation services

• WINDOW: Window controls

• VENDOR: Vendor-specific properties

Generated Output

When you use the code generator, it produces:

1. Complete Summary - Property configuration and overview

2. Generated Files - All 10+ necessary implementation files with syntax highlighting

3. Implementation Guide - Step-by-step integration instructions

4. Usage Examples - Sample code for using the property

5. Build Commands - AAOS build and test commands

Use Cases

Climate Control System Development

Implement comprehensive HVAC systems with proper property relationships:

• Temperature Control: Multi-zone heating and cooling

• Fan Management: Speed and direction control with feedback

• Air Conditioning: AC compressor and recirculation control

• Auxiliary Heating: Seat warmers, steering wheel, and mirror heating

• Safety Features: Defrost and defogging capabilities

Seat Control Systems

Develop advanced seat control features:

• Memory Systems: Position storage and recall

• Comfort Features: Heating, cooling, and massage functions

• Movement Control: Multi-axis positioning and adjustment

• Safety Integration: Occupancy detection and airbag coordination

Property Discovery and Analysis

Understand vHAL property ecosystems:

• Dependency Mapping: Identify property relationships

• Implementation Planning: Get step-by-step development guidance

• Source Code Analysis: Access real Android implementations

• Best Practices: Learn from existing property patterns

Configuration

MCP Client Integration

To use with MCP-compatible clients, configure the server endpoint and ensure proper tool registration. The server automatically discovers and exposes all available vHAL analysis tools.

Performance Optimization

The server uses parallel scraping and caching mechanisms for optimal performance:

• Parallel Documentation Scraping: Concurrent fetching of Android documentation

• Property Database Caching: In-memory storage of frequently accessed properties

• Source Code Analysis Caching: Optimized repeated analysis operations

Development

Project Structure

Testing

Run the test suite:

Contributing

1. Fork the repository

2. Create a feature branch

3. Implement your changes with tests

4. Submit a pull request

Requirements

• mcp[cli] >= 1.10.1 - Model Context Protocol implementation

• requests >= 2.31.0 - HTTP client for documentation scraping

• beautifulsoup4 >= 4.12.0 - HTML parsing for documentation

• lxml >= 4.9.0 - XML/HTML processing

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

For questions, issues, or contributions:

• Repository: https://github.com/feevlic/vhal-mcp-server

• Issues: https://github.com/feevlic/vhal-mcp-server/issues

• Documentation: Refer to Android vHAL documentation at https://source.android.com/docs/automotive/vhal

Related Resources

• Android Automotive Documentation

• Model Context Protocol (MCP)