┌─────────────────────── Host Machine ──────────────────────────┐
│                                                               │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  Docker Network: byd-internal (172.28.0.0/16)           │  │
│  │                                                         │  │
│  │  ┌──────────────────────┐    MCP (SSE)   ┌──────────┐  │  │
│  │  │  AI Agent            │◄──────────────►│  BYD     │  │  │
│  │  │  (OpenClaw / Claude) │                │  Bridge  │  │  │
│  │  │                      │                │          │  │  │
│  │  │  Tools:              │                │  Tools:  │  │  │
│  │  │  · get_battery()     │                │  · poll  │  │  │
│  │  │  · get_vehicle()     │                │  · cache │  │  │
│  │  │  · get_all_data()    │                │  · serve │  │  │
│  │  │  · get_health()      │                │          │  │  │
│  │  └──────────────────────┘                └─────┬────┘  │  │
│  │                                                 │      │  │
│  │                                        BYD Cloud API    │  │
│  │                                                 │      │  │
│  │                                            ┌────▼────┐ │  │
│  │                                            │  BYD    │ │  │
│  │                                            │  Cloud  │ │  │
│  │                                            └─────────┘ │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                               │
│  Credentials stored in .env — never leave this machine        │
└───────────────────────────────────────────────────────────────┘

// get_battery() response
{
  "soc_percent": 73,
  "charging_status": "disconnected",
  "estimated_range_km": 280,
  "mileage_km": 12450,
  "outside_temp_c": 31.5,
  "cabin_temp_c": 28.0,
  "speed_kmh": 0,
  "engine_power_kw": 0.0,
  "fuel_percent": null,
  "last_updated": "2026-07-31T08:30:00+00:00"
}

docker pull ghcr.io/pavelpervi/byd-vehicle-bridge:latest

mkdir -p /opt/byd-bridge && cd /opt/byd-bridge

cat > .env << 'EOF'
BYD_USERNAME=your@email.com
BYD_PASSWORD=your-password
BYD_COUNTRY=IL
BYD_MODE=minimal   # or "full"
EOF

# docker-compose.yml
cat > docker-compose.yml << 'EOF'
services:
  byd-bridge:
    image: ghcr.io/pavelpervi/byd-vehicle-bridge:latest
    container_name: byd-bridge
    restart: unless-stopped
    env_file: .env
    networks:
      - byd-internal
    healthcheck:
      test: ["CMD", "python3", "-c", "import socket; s=socket.create_connection(('localhost', 8000), timeout=5); s.close()"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

networks:
  byd-internal:
    driver: bridge
    ipam:
      config:
        - subnet: 172.28.0.0/16
EOF

docker compose up -d

# Connect the OpenClaw container to the bridge network
docker network connect byd-internal <openclaw-container-name>

# Register the MCP server
openclaw mcp add byd-bridge --url http://byd-bridge:8000 --transport sse --timeout 30

{
  "mcpServers": {
    "byd-bridge": {
      "command": "docker",
      "args": ["exec", "-i", "byd-bridge", "python3", "-m", "byd_bridge"]
    }
  }
}

# Check the container is running
docker ps | grep byd-bridge

# View logs
docker logs byd-bridge

# Test the MCP tools
openclaw mcp call byd-bridge get_health
openclaw mcp call byd-bridge get_battery

{
  "status": "ok",
  "mode": "minimal",
  "vehicle_connected": true,
  "last_successful_poll": "2026-07-31T08:30:00+00:00",
  "poll_interval_s": 60,
  "error": null
}

byd-vehicle-bridge/
├── src/
│   └── byd_bridge/              ← Python package
│       ├── __init__.py
│       ├── __main__.py          ← Entry: python -m byd_bridge
│       ├── config.py            ← Settings from env vars (lazy singleton)
│       ├── state.py             ← BridgeState + background poller
│       └── server.py            ← MCP server with 4 tools
├── tests/
│   ├── __init__.py
│   ├── conftest.py              ← Shared fixtures
│   ├── test_config.py           ← 12 tests: validation, defaults, errors
│   ├── test_state.py            ← 5 tests: init, data shapes, copy safety
│   └── test_server.py           ← 11 tests: before/after poll, registration
├── .github/
│   └── workflows/
│       ├── tests.yml            ← CI: runs tests on every PR
│       └── docker-build.yml     ← CD: builds & pushes image to ghcr.io
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml               ← Modern Python project config
├── requirements.txt
├── .env.example
├── .gitignore
├── README.md
└── LICENSE

# Install dependencies
pip install -r requirements.txt
pip install -e .

# Run all 28 tests
python -m pytest tests/ -v

git clone https://github.com/pavelpervi/byd-vehicle-bridge.git
cd byd-vehicle-bridge
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -e .

# Set BYD credentials
export BYD_USERNAME=your@email.com
export BYD_PASSWORD=your-password
export BYD_COUNTRY=IL
export BYD_MODE=minimal

# Start the MCP server
python -m byd_bridge

# Set test env vars (required by config module)
export BYD_USERNAME=test@example.com
export BYD_PASSWORD=test-password

# Run all tests
python -m pytest tests/ -v

docker build -t byd-bridge .
docker run --rm -p 8000:8000 --env-file .env byd-bridge