velajs-mcp

MCP server for VelaJS quick app runtime debugging. Provides AI agents with tools to interact with Vela emulators — screenshots, UI interaction, page inspection, and debug session management.

Installation

npm install -g velajs-mcp

MCP Configuration

{
  "mcpServers": {
    "velajs": {
      "command": "npx",
      "args": ["velajs-mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "velajs": {
      "command": "velajs-mcp"
    }
  }
}

Usage

The server runs in CLI mode by default (no IDE required). It connects directly to Vela emulators via gRPC and MQTT.

Typical workflow

1. List available emulators: list_emulators → returns all VVDs with running status
2. Start debug session: start_debug({ projectPath, emulatorName }) → builds project, starts emulator, pushes app
3. Interact with the app: take_screenshot, tap, swipe, get_snapshot, etc.

Prerequisites

• aiot-toolkit installed (for start_debug)
• At least one Vela Virtual Device (VVD) created via npx aiot createEmulator

Tools

Debug & Device Management

| Tool | Description | |------|-------------| | list_emulators | List all VVDs with running status | | start_debug | Start debug session (build + emulator + push app) | | get_debug_status | Get current debug session status and active devices |

UI Interaction (requires deviceId)

| Tool | Description | |------|-------------| | take_screenshot | Capture emulator screen as PNG | | tap | Tap at coordinates | | double_tap | Double tap at coordinates | | long_press | Long press at coordinates | | swipe | Swipe from point A to B | | scroll | Scroll at position | | send_key | Send key event (Home, Back, etc.) | | input_text | Input text into focused field |

Page Inspection (requires deviceId)

| Tool | Description | |------|-------------| | get_snapshot | Get page DOM tree | | get_element | Get element details by ID | | navigate | Navigate to a route | | execute_script | Execute JavaScript in page context | | get_console_logs | Get console log output | | clear_console_logs | Clear collected console logs | | get_network_requests | Get captured network requests | | clear_network_requests | Clear captured network requests | | get_storage | Read local storage data | | get_performance_metrics | Get performance metrics |

Modes

• CLI mode (default): Direct gRPC/MQTT connection to emulators. No IDE needed.
• IDE mode (--runMode IDE): Used by VSCode/Kiro extensions. Communicates via MQTT + GrpcChannel through the IDE plugin.

Development

# Build
npm run build

# Run tests
npm test

# Start in dev mode (watch)
npm run dev

License

MIT