@codedroid/mcp 0.1.0 → 0.1.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codedroid",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Your Android phone, through CodeDroid: read the screen, tap and type, hand CodeDroid a whole task, run adb, and verify app changes on the device.",
   "author": {
     "name": "CodeDroid"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codedroid",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Drive your Android phone through CodeDroid, with MCP tools and device testing skills.",
   "author": {
     "name": "CodeDroid"

package/{LICENSE.aura-mcp-connect → LICENSE}

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Dinesh Kumar C
+Copyright (c) 2026 CodeDroid
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,185 +1,80 @@
 # CodeDroid MCP
 
-Gives Claude Code, Codex, Gemini CLI or any MCP client your Android phone, through the CodeDroid app on it:
-read the screen as numbered elements, tap and type, wait for things to appear, hand CodeDroid's
-own agent a whole task, and run adb. The app reads the screen through Android's accessibility
-service, so what the agent gets back is what is really on screen, not a guess from a screenshot
-or a `uiautomator` dump.
+Let Claude Code, Codex, Gemini CLI, or any MCP client use your Android phone.
+Read the screen, interact with apps, take screenshots, and test what you build
+through [CodeDroid](https://get.codedroid.com). Your phone and computer can be on different networks.
 
-It ships as a Claude Code plugin, Codex plugin, and Gemini CLI extension: this MCP server plus two skills, `codedroid-phone` (how to drive
-the phone) and `test-on-device` (build, install, drive, check logcat, report).
+## Get started
 
-## What you need
+You'll need **Node.js 20+** and **CodeDroid on your Android phone**, signed in with
+its accessibility service enabled. Both devices need internet access.
 
-- Node.js 20 or newer on this computer.
-- CodeDroid installed from https://get.codedroid.com, signed in, with its accessibility service on.
-  The phone only needs to be online: no cable, no USB debugging, no shared network.
-- For the `adb` tool only: adb (Android platform-tools) on this computer, and the phone on it
-  (USB debugging, or Wireless debugging: `adb pair <ip:port>`, then `adb connect <ip:port>`).
+### 1. Install for your coding client
 
-## Install
+**Claude Code** — run inside Claude Code:
 
-Claude Code, as a plugin:
-
-```
+```text
 /plugin marketplace add codedroid-team/codedroid-mcp
 /plugin install codedroid@codedroid
 ```
 
-Or the MCP server alone:
-
-```bash
-claude mcp add codedroid -- npx -y @codedroid/mcp
-npx @codedroid/mcp skill install            # the two skills, into ~/.claude/skills
-```
-
-Codex, as a plugin (current CLI):
+**Codex** — run in your terminal:
 
 ```bash
 codex plugin marketplace add codedroid-team/codedroid-mcp
 codex plugin add codedroid@codedroid
 ```
 
-Or the MCP server and skills separately:
-
-```bash
-codex mcp add codedroid -- npx -y @codedroid/mcp
-npx @codedroid/mcp skill install --codex    # into ~/.codex/skills
-```
-
-Codex stops a tool call after 60 s by default; `run_task` waits, test runs and installs can take
-longer. In `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.codedroid]
-command = "npx"
-args = ["-y", "@codedroid/mcp"]
-tool_timeout_sec = 300
-```
-
-Gemini CLI, as an extension (includes the MCP server and both skills):
+**Gemini CLI** — run in your terminal:
 
 ```bash
 gemini extensions install https://github.com/codedroid-team/codedroid-mcp
 ```
 
-Or the MCP server alone:
+Each installation includes the MCP server and skills for phone control and Android app testing.
+Restart your coding client after installing.
 
-```bash
-gemini mcp add --scope user --timeout 300000 codedroid npx -y @codedroid/mcp
-```
+Using another client? See [manual MCP setup](docs/reference.md#mcp-configuration).
 
-Use the extension or the standalone MCP configuration, so the tools are registered once.
-Restart your client after installation, then pair this computer as described below.
+### 2. Pair your phone
 
-Any other client: `{"mcpServers": {"codedroid": {"command": "npx", "args": ["-y", "@codedroid/mcp"]}}}`,
-or, with the daemon running, the streamable HTTP URL `http://127.0.0.1:4826/mcp`.
+1. Open **CodeDroid → Settings → Computers → Pair a computer** on your phone.
+2. Run the command shown there in your computer's terminal. For example:
 
-## Pair this computer
+   ```bash
+   npx -y @codedroid/mcp pair ABCD-EFGH
+   ```
 
-On the phone, open CodeDroid > Settings > Computers > **Pair a computer**. It shows a code and the
-command to run here, valid for 10 minutes:
+3. Tap **Allow** on your phone when prompted.
 
-```bash
-npx -y @codedroid/mcp pair ABCD-EFGH     # then tap Allow on the phone
-```
+Use the command exactly as shown. Pairing codes expire after 10 minutes and work once.
 
-Development builds add `--server=<url>`; run the command as the phone shows it. It saves this
-computer's key in `~/.codedroid/host.json` (readable by you only) and connects once, so the phone
-asks whether to allow the computer while you are still there. `npx @codedroid/mcp connect`
-connects again by hand.
-
-Settings > Computers lists the paired computers; Remove revokes one's key, so it has to pair
-again. While an agent acts on the phone, CodeDroid shows "<computer> is using this phone" with a
-Stop button, which cuts the computer off for a minute. "Allow computers to connect" turns it all off.
-
-## Tools
-
-| Tool | What it does |
-|---|---|
-| `get_screen` | The screen as numbered elements, with the app in front; optionally a screenshot |
-| `take_screenshot` | A JPEG of the screen |
-| `tap`, `long_press` | An element by node, text, resource id or content description (found again on the live screen), or a point |
-| `type_text` | Into the focused field, optionally clearing it first and pressing Enter after |
-| `swipe` | Between two points; also how to scroll |
-| `press_key` | back, home, enter, recents |
-| `open_app`, `list_apps` | Launch an app by package; find its package |
-| `wait_for` | Until text shows, text goes, or an app is in front |
-| `clipboard` | Read or set it |
-| `device_info` | Model, Android version and user, screen, locked, whether CodeDroid is ready |
-| `run_task`, `get_task`, `cancel_task` | CodeDroid's own agent does a goal on the phone and replies (needs CodeDroid signed in) |
-| `adb` | This computer's adb, for the phone when it is on USB or Wireless debugging (`CODEDROID_MCP_ADB=0` leaves it out) |
-| `codedroid_status` | Whether the phone is connected, and if not, exactly why |
-
-Every action answers with `after`: whether the screen changed, the app in front, the keyboard,
-and the first things to tap now. Every failure is JSON with `error`, `message` and `hint`.
-
-## Command line
+### 3. Ask your agent
 
-```bash
-npx @codedroid/mcp pair ABCD-EFGH                # pair with the phone showing the code
-npx @codedroid/mcp connect                       # connect now; tap Allow the first time
-npx @codedroid/mcp status                        # what the daemon sees
-npx @codedroid/mcp call get_screen               # one tool call, for scripts and CI
-npx @codedroid/mcp call tap '{"text": "Display"}'
-npx @codedroid/mcp stop                          # stop the daemon
-```
+> Read the screen on my phone and describe what is open.
 
-| Environment | |
-|---|---|
-| `CODEDROID_SERIAL` | The device the `adb` tool uses when several are on adb (`ANDROID_SERIAL` works too) |
-| `CODEDROID_MCP_PORT` | The daemon's port (default 4826) |
-| `CODEDROID_MCP_ADB=0` | Leave out the `adb` tool |
-| `CODEDROID_MCP_CLIENT` | How the phone names your agent ("Claude Code on borna-mbp") |
-| `ADB` | The adb binary, if not on PATH |
-| `CODEDROID_DEBUG=1` | Stack traces on failure |
+Then try:
 
-## How it works
+- “Open Android Settings and check the Android version.”
+- “Open my app, navigate to sign-in, and take a screenshot.”
+- “Install this APK, launch it, and check for crashes.”*
 
-```
- MCP client ── stdio ── codedroid-mcp ── HTTP ── daemon (one per computer, 127.0.0.1:4826)
-                                                   ├── adb tool: this computer's adb
-                                                   └── wss://<CodeDroid server>/v1/mcp/connect
-                                                         └── relay ── CodeDroid on the phone (its own WebSocket)
-```
-
-- Each client's `codedroid-mcp` starts the shared daemon if it is not running and proxies to it,
-  so every client on the computer shares one connection to the phone, and tool calls run one at
-  a time. The daemon logs to `~/.codedroid/daemon.log`.
-- The phone keeps a WebSocket open to the CodeDroid server and opens it again by itself after a
-  reboot or a network change. The daemon opens one too, with this computer's key from pairing,
-  and the server relays between them. Nothing listens on the phone or on this computer's network.
-- The server tells the phone which computer is connecting; the phone answers (Allow, the first
-  time), then each WebSocket message is one JSON-RPC message.
-- A call whose link drops mid-way is not retried: a tap whose answer was lost still happened.
-  The agent is told so, and reads the screen before trying again.
-
-## When it does not connect
+*Installing APKs and using `adb` also requires Android platform-tools and a USB or wireless
+debugging connection. See [adb setup](docs/reference.md#adb-setup).
 
-Call `codedroid_status` (or `npx @codedroid/mcp status`): it says which of these it is.
+## Need help?
 
-- "Not paired", or "pairing was removed": pair again from Settings > Computers > Pair a computer.
-- "The phone is not connected to CodeDroid": open CodeDroid on the phone, and check it is online,
-  signed in, and "Allow computers to connect" is on in Settings > Computers.
-- "Not allowed on the phone" or "Stopped on the phone": the phone said no; wait a minute.
-- `am force-stop com.codedroid.app`, or `am instrument` against it, switches its accessibility
-  off; turn it on again in Settings > Accessibility. (`pm clear` also signs it out.)
-- `uiautomator dump`, and tests that use UiAutomator, suspend CodeDroid's accessibility while they
-  run; its tools work again once they finish.
-
-## Developing
+Check your connection:
 
 ```bash
-npm install
-npm test                                         # no phone, server or adb needed
-claude mcp add codedroid -- node "$PWD/src/index.js"
+npx -y @codedroid/mcp status
 ```
 
-The app's JVM tests (`./gradlew :app:testDebugUnitTest --tests 'com.codedroid.app.mcp.*'` in
-`CodeDroid-app/`) write `test/fixtures/phone-tools.json`, the phone's tool list the skill test
-checks the skills against, and run `test/phone-contract.mjs`: the bridge against the app's real
-MCP server code, through a stand-in relay. Run `npm install` here first or that test is skipped.
+Manage or revoke computer access in **CodeDroid → Settings → Computers**.
+
+See the [reference guide](docs/reference.md) for tools, manual setup, configuration,
+[troubleshooting](docs/reference.md#troubleshooting), and development.
+
+## License
 
-`src/daemon.js`, `stdio-shim.js`, `proxy-core.js`, `adb-tool.js` and `skill.js` are derived from
-[aura-mcp-connect](https://github.com/Dinesh210805/aura-android-use/tree/main/aura-mcp-connect)
-(MIT, Copyright (c) 2026 Dinesh Kumar C; `LICENSE.aura-mcp-connect`).
+[MIT](LICENSE) © 2026 CodeDroid

package/docs/reference.md

@@ -0,0 +1,188 @@
+# CodeDroid MCP reference
+
+[Back to setup](../README.md)
+
+## Tools
+
+The agent can interact with the phone one step at a time or use `run_task` to delegate a goal
+to CodeDroid's agent. `run_task` returns a task ID. Use `get_task` to wait for completion and
+read progress, or `cancel_task` to stop the task.
+
+| Tool | Description |
+| --- | --- |
+| `get_screen` | Read the current app and screen as numbered accessibility elements; optionally include a screenshot. |
+| `take_screenshot` | Capture a JPEG screenshot. |
+| `tap`, `long_press` | Interact with an element by node, text, resource ID, content description, or screen coordinates. |
+| `type_text` | Enter text in the focused field; optionally clear it first or press Enter afterward. |
+| `swipe` | Swipe or scroll between screen coordinates. |
+| `press_key` | Press Back, Home, Enter, or Recents. |
+| `open_app`, `list_apps` | Launch an app by package name or list installed apps. |
+| `wait_for` | Wait for text to appear or disappear, or for an app to open. |
+| `clipboard` | Read or update the clipboard. |
+| `device_info` | Inspect the device model, Android version, user, screen, lock state, and CodeDroid readiness. |
+| `run_task`, `get_task`, `cancel_task` | Start, monitor, or cancel a task run by CodeDroid's agent. |
+| `adb` | Run local adb commands against the connected phone. |
+| `codedroid_status` | Check the phone connection and get instructions for resolving connection problems. |
+
+Screen interaction tools return an `after` observation with the current app, keyboard state,
+screen changes, and visible elements. Phone tool errors include an error code, message, and
+hint for recovery.
+
+## Manage access
+
+Paired computers appear in **Settings → Computers** on the phone.
+
+- **Remove** revokes a computer's access. Pair again to reconnect it.
+- **Stop** disconnects the active computer and blocks it for one minute.
+- **Allow computers to connect** turns computer access on or off.
+
+CodeDroid displays the computer's name and a Stop button while it acts on the phone.
+
+## adb setup
+
+The optional `adb` tool requires [Android platform-tools](https://developer.android.com/tools/releases/platform-tools)
+on your computer and a USB or wireless debugging connection to your phone.
+
+For USB, enable **USB debugging** in the phone's Developer options, connect the cable, and
+accept the debugging prompt on the phone. Run `adb devices` to check the connection.
+For wireless debugging, see [troubleshooting](#troubleshooting).
+
+## MCP configuration
+
+Use these options when you want the MCP server without a plugin or extension. Configure one
+installation method per client to avoid registering the tools twice.
+
+### Standalone Claude Code server
+
+```bash
+claude mcp add codedroid -- npx -y @codedroid/mcp
+npx -y @codedroid/mcp skill install
+```
+
+The optional second command installs the two skills in `~/.claude/skills`.
+
+### Standalone Codex server
+
+```bash
+codex mcp add codedroid -- npx -y @codedroid/mcp
+npx -y @codedroid/mcp skill install --codex
+```
+
+The optional second command installs the skills in `~/.codex/skills`. For calls longer than Codex's
+60-second default timeout, such as APK installation, set `tool_timeout_sec` in
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.codedroid]
+command = "npx"
+args = ["-y", "@codedroid/mcp"]
+tool_timeout_sec = 300
+```
+
+### Standalone Gemini CLI server
+
+```bash
+gemini mcp add --scope user --timeout 300000 codedroid npx -y @codedroid/mcp
+```
+
+### Other MCP clients
+
+Add this server configuration to your client's MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "codedroid": {
+      "command": "npx",
+      "args": ["-y", "@codedroid/mcp"]
+    }
+  }
+}
+```
+
+Clients that support Streamable HTTP can also connect to `http://127.0.0.1:4826/mcp`.
+After pairing, run `npx -y @codedroid/mcp connect` to start the shared daemon before connecting
+an HTTP client.
+
+### Environment variables
+
+| Variable | Description |
+| --- | --- |
+| `CODEDROID_SERIAL` | Select an adb device when several are connected. `ANDROID_SERIAL` is also supported. |
+| `CODEDROID_MCP_PORT` | Set the local daemon port. Default: `4826`. |
+| `CODEDROID_MCP_ADB=0` | Disable the `adb` tool. |
+| `CODEDROID_MCP_CLIENT` | Set the client name shown on the phone. |
+| `ADB` | Set the path to the adb executable. |
+| `CODEDROID_DEBUG=1` | Include stack traces in diagnostic output. |
+
+## CLI reference
+
+```bash
+npx -y @codedroid/mcp pair ABCD-EFGH
+npx -y @codedroid/mcp connect
+npx -y @codedroid/mcp status
+npx -y @codedroid/mcp call get_screen
+npx -y @codedroid/mcp call tap '{"text": "Display"}'
+npx -y @codedroid/mcp stop
+```
+
+`connect` reconnects a paired computer. `stop` shuts down the local daemon.
+
+## Troubleshooting
+
+Run `npx -y @codedroid/mcp status` or call `codedroid_status` from your agent to diagnose a
+connection problem.
+
+| Problem | Action |
+| --- | --- |
+| Computer is not paired, or pairing was removed | Create a new code in **Settings → Computers → Pair a computer** and run the displayed command. |
+| Phone is not connected | Open CodeDroid, check its internet connection and sign-in, and enable **Allow computers to connect**. |
+| Connection is awaiting approval | Tap **Allow** on the phone. |
+| Connection was denied | Wait one minute, run `npx -y @codedroid/mcp connect`, then tap **Allow**. |
+| Connection was stopped on the phone | Wait one minute before reconnecting. |
+| adb cannot find the phone | Connect it over USB, or run `adb pair <ip:port>` followed by `adb connect <ip:port>` for wireless debugging. |
+
+Force-stopping or running instrumentation against `com.codedroid.app` disables its accessibility
+service. Re-enable it in Android Accessibility settings afterward. Clearing the app's data also
+signs it out. UiAutomator tests and `uiautomator dump` temporarily suspend CodeDroid's
+accessibility access while they run.
+
+## Architecture
+
+```text
+MCP client → stdio bridge → local daemon → CodeDroid relay → Android app
+                              └── local adb
+```
+
+All clients on a computer share a local daemon and its connection to the paired phone. The
+phone and daemon each open an outbound WebSocket to the CodeDroid server. The phone reconnects
+after a restart or network change. MCP screen interactions are serialized on the phone.
+
+Calls interrupted by a connection loss are not automatically replayed: an action may have
+completed before its response was lost. Read the screen before deciding whether to retry.
+
+Pairing credentials are stored in `~/.codedroid/host.json`, readable only by your user account.
+Daemon logs are written to `~/.codedroid/daemon.log`.
+
+## Development
+
+From the package directory:
+
+```bash
+npm install
+npm test
+claude mcp add codedroid -- node "$PWD/src/index.js"
+```
+
+The npm tests run without a phone, relay server, or adb. In the monorepo, the Android app's MCP
+JVM tests also verify the bridge against the app's server implementation and export the tool
+fixture used by the skill tests. Install the package's npm dependencies before running those
+contract tests from `CodeDroid-app/`:
+
+```bash
+./gradlew :app:testDebugUnitTest --tests 'com.codedroid.app.mcp.*'
+```
+
+These tests export `test/fixtures/phone-tools.json` and run `test/phone-contract.mjs` against
+the app's MCP server through a test relay.
+

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "codedroid",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Drive your Android phone through CodeDroid, with MCP tools and device testing skills.",
   "mcpServers": {
     "codedroid": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@codedroid/mcp",
-  "version": "0.1.0",
-  "description": "Give Claude Code, Codex, Gemini CLI or any MCP client your Android phone, through CodeDroid: pair once with a code, then read the screen, tap and type, hand CodeDroid a whole task, and run adb.",
+  "version": "0.1.2",
+  "description": "MCP server for controlling Android devices through CodeDroid from Claude Code, Codex, Gemini CLI, and other MCP clients.",
   "type": "module",
   "main": "src/index.js",
   "bin": {
@@ -16,7 +16,8 @@
     "gemini-extension.json",
     ".mcp.json",
     "README.md",
-    "LICENSE.aura-mcp-connect"
+    "docs",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=20"
@@ -42,5 +43,6 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/codedroid-team/codedroid-mcp.git"
-  }
+  },
+  "license": "MIT"
 }

package/src/adb-tool.js

@@ -2,10 +2,8 @@
  * adb — a single generic MCP tool that runs an adb command against a phone
  * attached to THIS computer (USB, or Wireless Debugging).
  *
- * Forked from aura-mcp-connect's `aura-adb` (MIT, Copyright (c) 2026 Dinesh Kumar C;
- * see LICENSE.aura-mcp-connect). Changed: on by default, since the user is a developer
- * (CODEDROID_MCP_ADB=0 turns it off); marked destructive so clients ask before running
- * it; a per-call timeout.
+ * Enabled by default (CODEDROID_MCP_ADB=0 turns it off), with a per-call timeout.
+ * Marked destructive so clients ask before running it.
  *
  * It never touches the connection to CodeDroid: it shells out to this machine's
  * own `adb`, exactly like a developer typing `adb install app.apk` themselves.

package/src/daemon.js

@@ -3,9 +3,7 @@
  * CodeDroid on the phone (through the CodeDroid server's relay) and serves MCP over
  * Streamable HTTP on localhost.
  *
- * Forked from aura-mcp-connect (MIT, Copyright (c) 2026 Dinesh Kumar C; see
- * LICENSE.aura-mcp-connect): the link is a WebSocket relay instead of WebRTC, and the adb tool is
- * on by default.
+ * The phone connection uses a WebSocket relay. The adb tool is enabled by default.
  *
  * Every MCP client (Claude Code, Claude Desktop, Cursor, VS Code windows…)
  * connects to http://127.0.0.1:<port>/mcp and gets its own MCP session; tool

package/src/index.js

@@ -21,8 +21,6 @@
  * leaves out the adb tool. CODEDROID_SERIAL picks the adb tool's device when several are attached.
  *
  * All log output goes to stderr — stdout is reserved for MCP JSON-RPC frames.
- *
- * Forked from aura-mcp-connect (MIT, Copyright (c) 2026 Dinesh Kumar C; see LICENSE.aura-mcp-connect).
  */
 import { VERSION } from "./version.js";
 

package/src/proxy-core.js

@@ -2,10 +2,9 @@
  * proxy-core — builds an MCP Server that transparently forwards requests to a
  * backend MCP Client (the single phone connection).
  *
- * Forked from aura-mcp-connect (MIT, Copyright (c) 2026 Dinesh Kumar C; see
- * LICENSE.aura-mcp-connect). Changed: a session still opens when the phone cannot be
- * reached, serving the local tools (adb, codedroid_status) and saying why in its
- * instructions, and tools/list keeps trying the phone.
+ * A session still opens when the phone cannot be reached, serving the local tools
+ * (adb, codedroid_status) and saying why in its instructions. tools/list keeps
+ * trying the phone.
  *
  * Used twice:
  *   - daemon: one proxy Server per HTTP client session → phone client

package/src/skill.js

@@ -7,9 +7,6 @@
  *   or any directory (--dir).
  * - Change together: the skills name tools, so a renamed tool means editing them
  *   (test/skill.test.mjs checks every name they use exists).
- *
- * Forked from aura-mcp-connect's skill.js (MIT, Copyright (c) 2026 Dinesh Kumar C; see
- * LICENSE.aura-mcp-connect).
  */
 import fs from "fs";
 import os from "os";

package/src/stdio-shim.js

@@ -5,9 +5,6 @@
  *
  *   IDE ── stdio ── this shim ── HTTP ── daemon ── relay ── CodeDroid on the phone
  *
- * Forked from aura-mcp-connect (MIT, Copyright (c) 2026 Dinesh Kumar C; see
- * LICENSE.aura-mcp-connect).
- *
  * Any number of shims (one per IDE/window) share the one phone connection.
  */
 import { spawn } from "child_process";

package/src/version.js

@@ -1,2 +1,2 @@
 /** The bridge's version, sent to the phone in its hello and shown by `--version`. */
-export const VERSION = "0.1.0";
+export const VERSION = "0.1.2";