Content
# adb-mcp
Go-based MCP server scaffold for orchestrating Android `adb` commands. The initial
drop focuses on configuration, logging, and lifecycle wiring so new MCP tools and
resources can be layered in next.
## Getting Started
```bash
go build ./cmd/adb-mcp
./adb-mcp -config path/to/config.json
```
The binary runs as a long-lived process (stdio MCP transport placeholder) and
terminates via `Ctrl+C`/`SIGTERM`.
### Using the stdio MCP transport
The server now speaks the Model Context Protocol over newline-delimited JSON on
stdin/stdout:
1. Launch `./adb-mcp` (optionally piping into a supervising IDE/tool).
2. Send an `initialize` request (JSON-RPC 2.0) specifying protocol version
`2025-03-26` (or `2024-11-05` for older clients).
3. After receiving the `initialize` result, send `tools/list` and `tools/call`
requests to enumerate and invoke the built-in adb helpers described below.
The transport enforces the MCP handshake, responds to `ping`, and returns
structured `content` arrays for every tool invocation. All requests must be
JSON-RPC objects separated by newlines; batches are supported when the client
sends an array.
## Configuration
Configs are optional JSON files; unspecified values fall back to sane defaults.
```json
{
"adb_path": "/usr/local/bin/adb",
"command_timeout": "45s",
"logging": {
"directory": "~/adb-mcp/logs",
"file_name": "adb-mcp.log",
"level": "debug",
"also_console": true
},
"mcp": {
"transport": "stdio"
}
}
```
Key defaults:
- `adb_path`: `adb` (resolved via PATH)
- `logging.directory`: `$HOME/.adb-mcp/logs`
- `logging.file_name`: `adb-mcp.log`
- `logging.also_console`: `false` (logs go to file by default)
- `command_timeout`: `30s`
- `mcp.transport`: `stdio`
## Logging
The server uses `zerolog` with structured JSON entries. By default logs are
written to `$HOME/.adb-mcp/logs/adb-mcp.log` so long-running commands can flush
rich output without flooding stdout. Enable console mirroring with
`"also_console": true` if you need interactive feedback.
## Built-in Tools
The MCP registry is pre-populated with high-value device management and UI
automation helpers. These surface as MCP tools (and can already be exercised via
`Server.InvokeTool` while the stdio transport is under construction):
- `device.list` — enumerate `adb devices -l` output with optional state filter.
- `device.connect` / `device.disconnect` — manage TCP/IP or Wi-Fi debugging
endpoints (host:port).
- `device.reboot` — reboot into system, bootloader, recovery, or fastboot.
- `ui.tap` / `ui.swipe` — simulate touch interactions; swipe accepts optional
duration in milliseconds.
- `ui.text` — type arbitrary text via `adb shell input text`, encoding
whitespace for reliability.
- `ui.keyevent` — trigger a keycode (e.g., `3` for `KEYCODE_HOME`).
All long-running commands stream their stdout/stderr into the zerolog file so
Codex/Claude integrations can fetch artifacts without blocking stdin/stdout.
