Skip to content
Android Pilot Android Pilot

Architecture

MCP Protocol

Section titled “MCP Protocol”

Android Pilot MCP implements the Model Context Protocol — a standard for connecting AI editors to external tools.

How It Works

Section titled “How It Works”
  1. Your AI editor (Claude Code, Cursor, etc.) starts the MCP server as a subprocess
  2. Communication happens over stdio (stdin/stdout)
  3. The editor sends JSON-RPC requests describing which tool to call
  4. The server executes the tool (runs adb, Gradle, etc.) and returns results
  5. The editor uses the results to answer your question or complete the task

Transport

Section titled “Transport”

Android Pilot uses stdio transport — the simplest and most compatible option. The server reads from stdin and writes to stdout.

Beyond Tools

Section titled “Beyond Tools”

In addition to its 39 tools, the server registers the logging capability and exposes MCP Resources for read-only device state and MCP Prompts for common multi-step workflows. Long-running tools also report MCP progress notifications and honor client-initiated cancellation via AbortSignal.

Project Structure

Section titled “Project Structure”
android-pilot-mcp/
├── src/
│   ├── index.ts           # Entry point: MCP server setup, capability registration
│   ├── environment.ts     # Android SDK detection (ANDROID_HOME, platform fallbacks)
│   ├── executor.ts        # Command execution (spawn, stdin piping, cancellation)
│   ├── types.ts           # Shared TypeScript types (Environment, etc.)
│   ├── tools/              # Tool implementations, one directory per category
│   │   ├── build/          # Gradle build, task runner, clean, dependencies, lint
│   │   ├── device/         # Emulators, AVDs, APK install, app lifecycle, WiFi ADB, file transfer
│   │   ├── debug/          # Logcat, screenshots, screen recording, UI dump, shell
│   │   ├── scaffold/       # Project/activity/fragment/Compose screen generation
│   │   ├── analyze/        # APK inspection and permissions
│   │   ├── intent/         # Intents, broadcasts, deep links
│   │   └── sdk/            # SDK package listing and installation
│   │       └── index.ts    # registerXTools(server, env) entry point per category
│   ├── resources/          # MCP Resources (android://devices, android://avds, ...)
│   │   └── index.ts
│   ├── prompts/             # MCP Prompts (debug-crash, setup-emulator, ...)
│   │   └── index.ts
│   ├── utils/               # Shared utilities
│   │   ├── logger.ts        # Structured logging + MCP logging capability
│   │   ├── response.ts      # Response helpers, output truncation, error wrapping
│   │   └── validation.ts    # Input validation (paths, package names, device IDs, shell args)
│   └── templates/           # Scaffolding templates (.tmpl files for Kotlin/XML/Gradle)
├── tests/                   # Vitest test suite, mirrors the src/ layout
├── docs/                    # This documentation site (Astro Starlight)
└── build/                   # Compiled output (tsc + copied templates)

Each category directory under src/tools/ exports a registerXTools(server, env) function from its index.ts that calls server.registerTool() for every tool in that category, with a title, inputSchema, optional outputSchema, and MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). These are all called from src/index.ts, alongside registerResources() and registerPrompts().

Security Model

Section titled “Security Model”
  • All tool inputs are validated using Zod schemas
  • File paths are validated to prevent path traversal
  • Shell commands are executed with proper escaping
  • The server runs with the same permissions as your user account
  • No network access is required — all communication is local via stdio