Ryan Malloy a55ad3f551 Rename project to mcadb

Package name, script entry point, FastMCP server name, Docker
service, and all documentation updated from android-mcp-server
to mcadb. Project URLs now point to git.supported.systems.
Also removed deprecated docker-compose version attribute.

2026-02-10 19:37:16 -07:00

2.4 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 50 tools across 6 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/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

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.4 KiB Raw Blame History