# mobile-next/mobile-mcp architecture

> Architecture diagram of the GitHub repository mobile-next/mobile-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mobile-next/mobile-mcp
- Repository: https://github.com/mobile-next/mobile-mcp

## Overview

##### Project Type and Purpose
- This is an open‐source, platform‐agnostic CLI/server (Node.js) that implements the Model Context Protocol (MCP) for mobile automation.
- It exposes a standard MCP interface (via STDIO) so clients (IDEs or agent frameworks) can drive iOS/Android apps on simulators, emulators, or real devices using native accessibility snapshots or image‐based fallbacks.

##### File‐Structure Analysis
- Top‐level entries:
– server.json, package.json, tsconfig.json, build/config files
– src/ directory containing all TypeScript modules
– test/ directory with corresponding unit tests
- Key modules in src/:
– index.ts / mobilecli.ts – application entrypoints & CLI parsing
– server.ts – Core MCP server implementation (message routing, request/response lifecycle)
– android.ts, ios.ts, iphone‐simulator.ts – platform‐specific drivers/interfaces
– webdriver‐agent.ts – iOS WebDriverAgent bridge
– robot.ts – coordinate‐based tap simulation
– png.ts, image‐utils.ts – image decoding & screenshot analysis
– logger.ts – centralized logging utility

##### Architecture from README
– Clients (Agents, LLMs, IDEs) ↔ MCP Server ↔ Device drivers (Android, iOS, Simulator)
– Fallback flows: Accessibility Tree vs. Screenshot + Image Analysis
- Dependencies & protocols:
– STDIO (MCP messages)
– ADB (Android Platform Tools)
– xcrun / simctl / WebDriverAgent (iOS)
– Node.js v22+ runtime

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Clients (IDE/Agent Frameworks)"]:::client
    click Client "https://github.com/mobile-next/mobile-mcp/tree/main/n/a"

    %% MCP Core
    subgraph "MCP Server (Node.js)" 
        direction TB
        Entry["Application Entry (index.ts)"]:::core
        click Entry "https://github.com/mobile-next/mobile-mcp/blob/main/src/index.ts"
        CLI["CLI Parser (mobilecli.ts)"]:::core
        click CLI "https://github.com/mobile-next/mobile-mcp/blob/main/src/mobilecli.ts"
        Engine["MCP Engine / Router (server.ts)"]:::core
        click Engine "https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts"
        Logger["Logging Utility (logger.ts)"]:::core
        click Logger "https://github.com/mobile-next/mobile-mcp/blob/main/src/logger.ts"
        Config["Server Config (server.json)"]:::core
        click Config "https://github.com/mobile-next/mobile-mcp/blob/main/server.json"
    end

    %% Platform Connectors
    subgraph "Platform Connectors" 
        direction TB
        AndroidMod["Android Driver (android.ts)"]:::platform
        click AndroidMod "https://github.com/mobile-next/mobile-mcp/blob/main/src/android.ts"
        iOSMod["iOS Driver (ios.ts)"]:::platform
        click iOSMod "https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts"
        SimMod["iPhone Simulator (iphone-simulator.ts)"]:::platform
        click SimMod "https://github.com/mobile-next/mobile-mcp/blob/main/src/iphone-simulator.ts"
        WDA["WebDriverAgent Bridge (webdriver-agent.ts)"]:::platform
        click WDA "https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts"
    end

    %% Helpers
    subgraph "Interaction Helpers"
        direction TB
        PNG["PNG Decoder (png.ts)"]:::helper
        click PNG "https://github.com/mobile-next/mobile-mcp/blob/main/src/png.ts"
        ImgUtil["Image Utils (image-utils.ts)"]:::helper
        click ImgUtil "https://github.com/mobile-next/mobile-mcp/blob/main/src/image-utils.ts"
        Robot["Input Simulator (robot.ts)"]:::helper
        click Robot "https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts"
    end

    %% External Dependencies
    subgraph "External Tools & Devices"
        direction TB
        ADB["ADB (Android SDK)"]:::external
        XCODE["Xcode CLI / simctl"]:::external
        AndroidDev["Android Device/Emulator"]:::external
        iOSDev["iOS Device"]:::external
        SimDev["Simulator"]:::external
    end

    %% Flow Connections
    Client -->|"stdin MCP request"| Entry
    Entry -->|"parse CLI"| CLI
    CLI -->|"route request"| Engine
    Engine -->|"log"| Logger
    Engine -->|"invoke handler"| AndroidMod
    Engine -->|"invoke handler"| iOSMod
    Engine -->|"invoke handler"| SimMod

    AndroidMod -->|"accessibility snapshot"| Engine
    AndroidMod -->|"screenshot fallback"| PNG
    iOSMod -->|"accessibility snapshot"| Engine
    iOSMod -->|"screenshot fallback"| PNG
    SimMod -->|"accessibility snapshot"| Engine
    SimMod -->|"screenshot fallback"| PNG

    PNG -->|decode| ImgUtil
    ImgUtil -->|calculate coords| Robot
    Robot -->|action result| Engine

    AndroidMod -->|via ADB| ADB
    ADB -->|communicates| AndroidDev

    iOSMod -->|via WDA| WDA
    WDA -->|uses Xcode CLI| XCODE
    XCODE -->|controls| iOSDev

    SimMod -->|via simctl| XCODE
    XCODE -->|controls| SimDev

    Engine -->|"serialize response"| Client

    %% Styling
    classDef client fill:#B0C4DE,stroke:#333,stroke-width:1px
    classDef core fill:#98FB98,stroke:#333,stroke-width:1px
    classDef platform fill:#FFA500,stroke:#333,stroke-width:1px
    classDef helper fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
