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

IDE

Install the aiot-core extension in your IDE (VS Code, Kiro, Cursor, Trae, etc.). The MCP server will be automatically registered — no manual configuration needed.

VS Code — .vscode/mcp.json:

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

Kiro — .kiro/settings/mcp.json:

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

Cursor — .cursor/mcp.json:

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

Trae — .trae/mcp.json:

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

Windsurf — ~/.codeium/windsurf/mcp_config.json:

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

Other IDEs — .mcp.json in workspace root:

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

Tip: Use the command palette command aiot: Copy MCP Config to Clipboard to get the correct JSON.

CLI

Claude Code:

claude mcp add --scope user velajs -- npx -y velajs-mcp

Kiro CLI:

kiro mcp add --scope user velajs -- npx -y velajs-mcp

Cline:

cline mcp add --scope user velajs -- npx -y velajs-mcp

Gemini CLI:

gemini mcp add --scope user velajs -- npx -y velajs-mcp

Others — Create or edit mcp.json in your project root (or wherever your CLI tool reads MCP config):

{
  "mcpServers": {
    "velajs": {
      "command": "npx",
      "args": ["-y", "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