Ryan Malloy e0c05dc72a Add connectivity and settings mixins (50 → 65 tools)

New mixins:
- connectivity.py: adb_connect, adb_disconnect, adb_tcpip, adb_pair,
  device_properties (batch getprop)
- settings.py: settings_get/put, wifi/bluetooth/airplane toggles,
  screen_brightness, screen_timeout, notification_list, clipboard_get,
  media_control

Also fixes clipboard_set false-positive on devices where
cmd clipboard returns exit 0 but has no implementation.

2026-02-11 03:05:27 -07:00

2.6 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

mcadb - A FastMCP server exposing Android Debug Bridge (ADB) functionality through the Model Context Protocol. Enables AI assistants to automate Android devices via screenshots, input simulation, app control, UI inspection, file transfer, and shell commands.

Commands

# Install dependencies
uv sync

# Run the server locally
uv run mcadb

# Run directly with uvx (no install needed)
uvx mcadb

# Development dependencies
uv sync --group dev

# Linting and formatting
uv run ruff check src/
uv run ruff format src/

# Type checking
uv run mypy src/

# Docker (requires privileged mode for USB access)
docker compose up --build

Architecture

Modular MCPMixin architecture with 65 tools across 8 domain mixins:

src/server.py: FastMCP app and ADBServer class (thin orchestrator inheriting all mixins)
src/config.py: Persistent singleton config (~/.config/adb-mcp/config.json)
src/models.py: Pydantic models (DeviceInfo, CommandResult, ScreenshotResult)
src/mixins/base.py: Core ADB execution with run_adb(), run_shell(), and injection-safe run_shell_args() using shlex.quote()
src/mixins/devices.py: Device discovery, info, logcat, reboot
src/mixins/connectivity.py: TCP/IP connect/disconnect, wireless pairing, device properties
src/mixins/input.py: Tap, swipe, scroll, keys, text, clipboard, shell command
src/mixins/apps.py: Launch, close, install, intents, broadcasts
src/mixins/screenshot.py: Screen capture, recording, display settings
src/mixins/ui.py: Accessibility tree dump, element search, text polling
src/mixins/files.py: Push, pull, list, delete, exists
src/mixins/settings.py: System settings, radio toggles, brightness, notifications, clipboard read, media control

Key Patterns

All tools use run_shell_args() (injection-safe) except shell_command which intentionally uses run_shell() for raw commands
Developer mode tools are gated by is_developer_mode() checks and tagged with tags={"developer"}
Destructive operations use ctx.elicit() for user confirmation
@mcp_tool() and @mcp_resource() decorators from fastmcp.contrib.mcp_mixin

MCP Client Configuration

{
  "mcpServers": {
    "mcadb": {
      "command": "uvx",
      "args": ["mcadb"]
    }
  }
}

Device Requirements

ADB installed and accessible in PATH
USB debugging enabled on Android device
For Docker: --privileged flag and /dev/bus/usb volume mount required

2.6 KiB Raw Blame History