Ryan Malloy
a55ad3f551
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.
75 lines
2.4 KiB
Markdown
75 lines
2.4 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 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
|