Ryan Malloy
e0c05dc72a
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.
77 lines
2.6 KiB
Markdown
77 lines
2.6 KiB
Markdown
# 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 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
|
|
|
|
```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
|