# 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

```bash
# 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

```json
{
  "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
