@codedroid/mcp 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/README.md +199 -120
  4. package/gemini-extension.json +1 -1
  5. package/package.json +2 -2
  6. package/src/version.js +1 -1
package/.claude-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codedroid",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "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.",
5
5
  "author": {
6
6
  "name": "CodeDroid"
package/.codex-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codedroid",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Drive your Android phone through CodeDroid, with MCP tools and device testing skills.",
5
5
  "author": {
6
6
  "name": "CodeDroid"
package/README.md CHANGED
@@ -1,54 +1,148 @@
1
1
  # CodeDroid MCP
2
2
 
3
- Gives Claude Code, Codex, Gemini CLI or any MCP client your Android phone, through the CodeDroid app on it:
4
- read the screen as numbered elements, tap and type, wait for things to appear, hand CodeDroid's
5
- own agent a whole task, and run adb. The app reads the screen through Android's accessibility
6
- service, so what the agent gets back is what is really on screen, not a guess from a screenshot
7
- or a `uiautomator` dump.
3
+ Connect Claude Code, Codex, Gemini CLI, and other MCP clients to your Android phone.
8
4
 
9
- It ships as a Claude Code plugin, Codex plugin, and Gemini CLI extension: this MCP server plus two skills, `codedroid-phone` (how to drive
10
- the phone) and `test-on-device` (build, install, drive, check logcat, report).
5
+ CodeDroid MCP provides tools for reading the screen, interacting with apps, taking screenshots,
6
+ and running tasks through the [CodeDroid Android app](https://get.codedroid.com). The phone and
7
+ computer can be on different networks. The optional `adb` tool requires a separate USB or
8
+ wireless debugging connection.
11
9
 
12
- ## What you need
10
+ ## Requirements
13
11
 
14
- - Node.js 20 or newer on this computer.
15
- - CodeDroid installed from https://get.codedroid.com, signed in, with its accessibility service on.
16
- The phone only needs to be online: no cable, no USB debugging, no shared network.
17
- - For the `adb` tool only: adb (Android platform-tools) on this computer, and the phone on it
18
- (USB debugging, or Wireless debugging: `adb pair <ip:port>`, then `adb connect <ip:port>`).
12
+ - Node.js 20 or later on your computer.
13
+ - CodeDroid installed on your phone, signed in, with its accessibility service enabled.
14
+ - An internet connection on both devices.
19
15
 
20
- ## Install
16
+ To use the optional `adb` tool, install [Android platform-tools](https://developer.android.com/tools/releases/platform-tools)
17
+ on your computer and connect the phone over USB or wireless debugging.
21
18
 
22
- Claude Code, as a plugin:
19
+ ## Installation
23
20
 
24
- ```
21
+ Choose your coding client below. Each plugin or extension includes the MCP server and two
22
+ skills: `codedroid-phone` for interacting with the phone, and `test-on-device` for building,
23
+ installing, and testing Android apps.
24
+
25
+ ### Claude Code
26
+
27
+ Run these commands in Claude Code:
28
+
29
+ ```text
25
30
  /plugin marketplace add codedroid-team/codedroid-mcp
26
31
  /plugin install codedroid@codedroid
27
32
  ```
28
33
 
29
- Or the MCP server alone:
34
+ ### Codex
35
+
36
+ Run these commands in your terminal with a current version of the Codex CLI:
30
37
 
31
38
  ```bash
32
- claude mcp add codedroid -- npx -y @codedroid/mcp
33
- npx @codedroid/mcp skill install # the two skills, into ~/.claude/skills
39
+ codex plugin marketplace add codedroid-team/codedroid-mcp
40
+ codex plugin add codedroid@codedroid
34
41
  ```
35
42
 
36
- Codex, as a plugin (current CLI):
43
+ ### Gemini CLI
37
44
 
38
45
  ```bash
39
- codex plugin marketplace add codedroid-team/codedroid-mcp
40
- codex plugin add codedroid@codedroid
46
+ gemini extensions install https://github.com/codedroid-team/codedroid-mcp
47
+ ```
48
+
49
+ Restart your coding client after installation, then pair your phone.
50
+
51
+ For a standalone MCP server or another client, see [MCP configuration](#mcp-configuration).
52
+
53
+ ## Pair your phone
54
+
55
+ 1. On the phone, open **CodeDroid → Settings → Computers → Pair a computer**.
56
+ 2. Run the command shown on the phone in your computer's terminal. For example:
57
+
58
+ ```bash
59
+ npx -y @codedroid/mcp pair ABCD-EFGH
60
+ ```
61
+
62
+ 3. Tap **Allow** on the phone when prompted.
63
+
64
+ Pairing codes expire after 10 minutes and can only be used once. Development builds include
65
+ `--server=<url>` in the pairing command; use the command exactly as displayed.
66
+
67
+ To verify the connection, ask your coding agent:
68
+
69
+ > Read the screen on my phone and describe what is open.
70
+
71
+ Or check from your terminal:
72
+
73
+ ```bash
74
+ npx -y @codedroid/mcp status
75
+ npx -y @codedroid/mcp call get_screen
76
+ ```
77
+
78
+ ## Usage
79
+
80
+ Ask your coding agent to work with the paired phone. For example:
81
+
82
+ - "Open Android Settings and check the Android version."
83
+ - "Open my app, navigate to the sign-in screen, and take a screenshot."
84
+ - "Install this APK, launch the app, and check logcat for crashes." (Requires `adb`.)
85
+
86
+ The agent can interact with the phone one step at a time or use `run_task` to delegate a goal
87
+ to CodeDroid's agent. `run_task` returns a task ID. Use `get_task` to wait for completion and
88
+ read progress, or `cancel_task` to stop the task.
89
+
90
+ ### Tools
91
+
92
+ | Tool | Description |
93
+ | --- | --- |
94
+ | `get_screen` | Read the current app and screen as numbered accessibility elements; optionally include a screenshot. |
95
+ | `take_screenshot` | Capture a JPEG screenshot. |
96
+ | `tap`, `long_press` | Interact with an element by node, text, resource ID, content description, or screen coordinates. |
97
+ | `type_text` | Enter text in the focused field; optionally clear it first or press Enter afterward. |
98
+ | `swipe` | Swipe or scroll between screen coordinates. |
99
+ | `press_key` | Press Back, Home, Enter, or Recents. |
100
+ | `open_app`, `list_apps` | Launch an app by package name or list installed apps. |
101
+ | `wait_for` | Wait for text to appear or disappear, or for an app to open. |
102
+ | `clipboard` | Read or update the clipboard. |
103
+ | `device_info` | Inspect the device model, Android version, user, screen, lock state, and CodeDroid readiness. |
104
+ | `run_task`, `get_task`, `cancel_task` | Start, monitor, or cancel a task run by CodeDroid's agent. |
105
+ | `adb` | Run local adb commands against the connected phone. |
106
+ | `codedroid_status` | Check the phone connection and get instructions for resolving connection problems. |
107
+
108
+ Screen interaction tools return an `after` observation with the current app, keyboard state,
109
+ screen changes, and visible elements. Phone tool errors include an error code, message, and
110
+ hint for recovery.
111
+
112
+ ## Manage access
113
+
114
+ Paired computers appear in **Settings → Computers** on the phone.
115
+
116
+ - **Remove** revokes a computer's access. Pair again to reconnect it.
117
+ - **Stop** disconnects the active computer and blocks it for one minute.
118
+ - **Allow computers to connect** turns computer access on or off.
119
+
120
+ CodeDroid displays the computer's name and a Stop button while it acts on the phone.
121
+
122
+ ## MCP configuration
123
+
124
+ Use these options when you want the MCP server without a plugin or extension. Configure one
125
+ installation method per client to avoid registering the tools twice.
126
+
127
+ ### Standalone Claude Code server
128
+
129
+ ```bash
130
+ claude mcp add codedroid -- npx -y @codedroid/mcp
131
+ npx -y @codedroid/mcp skill install
41
132
  ```
42
133
 
43
- Or the MCP server and skills separately:
134
+ The optional second command installs the two skills in `~/.claude/skills`.
135
+
136
+ ### Standalone Codex server
44
137
 
45
138
  ```bash
46
139
  codex mcp add codedroid -- npx -y @codedroid/mcp
47
- npx @codedroid/mcp skill install --codex # into ~/.codex/skills
140
+ npx -y @codedroid/mcp skill install --codex
48
141
  ```
49
142
 
50
- Codex stops a tool call after 60 s by default; `run_task` waits, test runs and installs can take
51
- longer. In `~/.codex/config.toml`:
143
+ The optional second command installs the skills in `~/.codex/skills`. For calls longer than Codex's
144
+ 60-second default timeout, such as APK installation, set `tool_timeout_sec` in
145
+ `~/.codex/config.toml`:
52
146
 
53
147
  ```toml
54
148
  [mcp_servers.codedroid]
@@ -57,129 +151,114 @@ args = ["-y", "@codedroid/mcp"]
57
151
  tool_timeout_sec = 300
58
152
  ```
59
153
 
60
- Gemini CLI, as an extension (includes the MCP server and both skills):
154
+ ### Standalone Gemini CLI server
61
155
 
62
156
  ```bash
63
- gemini extensions install https://github.com/codedroid-team/codedroid-mcp
157
+ gemini mcp add --scope user --timeout 300000 codedroid npx -y @codedroid/mcp
64
158
  ```
65
159
 
66
- Or the MCP server alone:
160
+ ### Other MCP clients
67
161
 
68
- ```bash
69
- gemini mcp add --scope user --timeout 300000 codedroid npx -y @codedroid/mcp
162
+ Add this server configuration to your client's MCP settings:
163
+
164
+ ```json
165
+ {
166
+ "mcpServers": {
167
+ "codedroid": {
168
+ "command": "npx",
169
+ "args": ["-y", "@codedroid/mcp"]
170
+ }
171
+ }
172
+ }
70
173
  ```
71
174
 
72
- Use the extension or the standalone MCP configuration, so the tools are registered once.
73
- Restart your client after installation, then pair this computer as described below.
175
+ Clients that support Streamable HTTP can also connect to `http://127.0.0.1:4826/mcp` while the
176
+ CodeDroid MCP daemon is running.
74
177
 
75
- Any other client: `{"mcpServers": {"codedroid": {"command": "npx", "args": ["-y", "@codedroid/mcp"]}}}`,
76
- or, with the daemon running, the streamable HTTP URL `http://127.0.0.1:4826/mcp`.
178
+ ### Environment variables
77
179
 
78
- ## Pair this computer
180
+ | Variable | Description |
181
+ | --- | --- |
182
+ | `CODEDROID_SERIAL` | Select an adb device when several are connected. `ANDROID_SERIAL` is also supported. |
183
+ | `CODEDROID_MCP_PORT` | Set the local daemon port. Default: `4826`. |
184
+ | `CODEDROID_MCP_ADB=0` | Disable the `adb` tool. |
185
+ | `CODEDROID_MCP_CLIENT` | Set the client name shown on the phone. |
186
+ | `ADB` | Set the path to the adb executable. |
187
+ | `CODEDROID_DEBUG=1` | Include stack traces in diagnostic output. |
79
188
 
80
- On the phone, open CodeDroid > Settings > Computers > **Pair a computer**. It shows a code and the
81
- command to run here, valid for 10 minutes:
189
+ ## CLI reference
82
190
 
83
191
  ```bash
84
- npx -y @codedroid/mcp pair ABCD-EFGH # then tap Allow on the phone
192
+ npx -y @codedroid/mcp pair ABCD-EFGH
193
+ npx -y @codedroid/mcp connect
194
+ npx -y @codedroid/mcp status
195
+ npx -y @codedroid/mcp call get_screen
196
+ npx -y @codedroid/mcp call tap '{"text": "Display"}'
197
+ npx -y @codedroid/mcp stop
85
198
  ```
86
199
 
87
- Development builds add `--server=<url>`; run the command as the phone shows it. It saves this
88
- computer's key in `~/.codedroid/host.json` (readable by you only) and connects once, so the phone
89
- asks whether to allow the computer while you are still there. `npx @codedroid/mcp connect`
90
- connects again by hand.
91
-
92
- Settings > Computers lists the paired computers; Remove revokes one's key, so it has to pair
93
- again. While an agent acts on the phone, CodeDroid shows "<computer> is using this phone" with a
94
- Stop button, which cuts the computer off for a minute. "Allow computers to connect" turns it all off.
95
-
96
- ## Tools
97
-
98
- | Tool | What it does |
99
- |---|---|
100
- | `get_screen` | The screen as numbered elements, with the app in front; optionally a screenshot |
101
- | `take_screenshot` | A JPEG of the screen |
102
- | `tap`, `long_press` | An element by node, text, resource id or content description (found again on the live screen), or a point |
103
- | `type_text` | Into the focused field, optionally clearing it first and pressing Enter after |
104
- | `swipe` | Between two points; also how to scroll |
105
- | `press_key` | back, home, enter, recents |
106
- | `open_app`, `list_apps` | Launch an app by package; find its package |
107
- | `wait_for` | Until text shows, text goes, or an app is in front |
108
- | `clipboard` | Read or set it |
109
- | `device_info` | Model, Android version and user, screen, locked, whether CodeDroid is ready |
110
- | `run_task`, `get_task`, `cancel_task` | CodeDroid's own agent does a goal on the phone and replies (needs CodeDroid signed in) |
111
- | `adb` | This computer's adb, for the phone when it is on USB or Wireless debugging (`CODEDROID_MCP_ADB=0` leaves it out) |
112
- | `codedroid_status` | Whether the phone is connected, and if not, exactly why |
113
-
114
- Every action answers with `after`: whether the screen changed, the app in front, the keyboard,
115
- and the first things to tap now. Every failure is JSON with `error`, `message` and `hint`.
116
-
117
- ## Command line
200
+ `connect` reconnects a paired computer. `stop` shuts down the local daemon.
118
201
 
119
- ```bash
120
- npx @codedroid/mcp pair ABCD-EFGH # pair with the phone showing the code
121
- npx @codedroid/mcp connect # connect now; tap Allow the first time
122
- npx @codedroid/mcp status # what the daemon sees
123
- npx @codedroid/mcp call get_screen # one tool call, for scripts and CI
124
- npx @codedroid/mcp call tap '{"text": "Display"}'
125
- npx @codedroid/mcp stop # stop the daemon
126
- ```
202
+ ## Troubleshooting
127
203
 
128
- | Environment | |
129
- |---|---|
130
- | `CODEDROID_SERIAL` | The device the `adb` tool uses when several are on adb (`ANDROID_SERIAL` works too) |
131
- | `CODEDROID_MCP_PORT` | The daemon's port (default 4826) |
132
- | `CODEDROID_MCP_ADB=0` | Leave out the `adb` tool |
133
- | `CODEDROID_MCP_CLIENT` | How the phone names your agent ("Claude Code on borna-mbp") |
134
- | `ADB` | The adb binary, if not on PATH |
135
- | `CODEDROID_DEBUG=1` | Stack traces on failure |
204
+ Run `npx -y @codedroid/mcp status` or call `codedroid_status` from your agent to diagnose a
205
+ connection problem.
136
206
 
137
- ## How it works
207
+ | Problem | Action |
208
+ | --- | --- |
209
+ | Computer is not paired, or pairing was removed | Create a new code in **Settings → Computers → Pair a computer** and run the displayed command. |
210
+ | Phone is not connected | Open CodeDroid, check its internet connection and sign-in, and enable **Allow computers to connect**. |
211
+ | Connection is awaiting approval | Tap **Allow** on the phone. |
212
+ | Connection was denied | Wait one minute, run `npx -y @codedroid/mcp connect`, then tap **Allow**. |
213
+ | Connection was stopped on the phone | Wait one minute before reconnecting. |
214
+ | adb cannot find the phone | Connect it over USB, or run `adb pair <ip:port>` followed by `adb connect <ip:port>` for wireless debugging. |
138
215
 
139
- ```
140
- MCP client ── stdio ── codedroid-mcp ── HTTP ── daemon (one per computer, 127.0.0.1:4826)
141
- ├── adb tool: this computer's adb
142
- └── wss://<CodeDroid server>/v1/mcp/connect
143
- └── relay ── CodeDroid on the phone (its own WebSocket)
216
+ Force-stopping or running instrumentation against `com.codedroid.app` disables its accessibility
217
+ service. Re-enable it in Android Accessibility settings afterward. Clearing the app's data also
218
+ signs it out. UiAutomator tests and `uiautomator dump` temporarily suspend CodeDroid's
219
+ accessibility access while they run.
220
+
221
+ ## Architecture
222
+
223
+ ```text
224
+ MCP client → stdio bridge → local daemon → CodeDroid relay → Android app
225
+ └── local adb
144
226
  ```
145
227
 
146
- - Each client's `codedroid-mcp` starts the shared daemon if it is not running and proxies to it,
147
- so every client on the computer shares one connection to the phone, and tool calls run one at
148
- a time. The daemon logs to `~/.codedroid/daemon.log`.
149
- - The phone keeps a WebSocket open to the CodeDroid server and opens it again by itself after a
150
- reboot or a network change. The daemon opens one too, with this computer's key from pairing,
151
- and the server relays between them. Nothing listens on the phone or on this computer's network.
152
- - The server tells the phone which computer is connecting; the phone answers (Allow, the first
153
- time), then each WebSocket message is one JSON-RPC message.
154
- - A call whose link drops mid-way is not retried: a tap whose answer was lost still happened.
155
- The agent is told so, and reads the screen before trying again.
228
+ All clients on a computer share a local daemon and its connection to the paired phone. The
229
+ phone and daemon each open an outbound WebSocket to the CodeDroid server. The phone reconnects
230
+ after a restart or network change. MCP screen interactions are serialized on the phone.
156
231
 
157
- ## When it does not connect
232
+ Calls interrupted by a connection loss are not automatically replayed: an action may have
233
+ completed before its response was lost. Read the screen before deciding whether to retry.
158
234
 
159
- Call `codedroid_status` (or `npx @codedroid/mcp status`): it says which of these it is.
235
+ Pairing credentials are stored in `~/.codedroid/host.json`, readable only by your user account.
236
+ Daemon logs are written to `~/.codedroid/daemon.log`.
160
237
 
161
- - "Not paired", or "pairing was removed": pair again from Settings > Computers > Pair a computer.
162
- - "The phone is not connected to CodeDroid": open CodeDroid on the phone, and check it is online,
163
- signed in, and "Allow computers to connect" is on in Settings > Computers.
164
- - "Not allowed on the phone" or "Stopped on the phone": the phone said no; wait a minute.
165
- - `am force-stop com.codedroid.app`, or `am instrument` against it, switches its accessibility
166
- off; turn it on again in Settings > Accessibility. (`pm clear` also signs it out.)
167
- - `uiautomator dump`, and tests that use UiAutomator, suspend CodeDroid's accessibility while they
168
- run; its tools work again once they finish.
238
+ ## Development
169
239
 
170
- ## Developing
240
+ From the package directory:
171
241
 
172
242
  ```bash
173
243
  npm install
174
- npm test # no phone, server or adb needed
244
+ npm test
175
245
  claude mcp add codedroid -- node "$PWD/src/index.js"
176
246
  ```
177
247
 
178
- The app's JVM tests (`./gradlew :app:testDebugUnitTest --tests 'com.codedroid.app.mcp.*'` in
179
- `CodeDroid-app/`) write `test/fixtures/phone-tools.json`, the phone's tool list the skill test
180
- checks the skills against, and run `test/phone-contract.mjs`: the bridge against the app's real
181
- MCP server code, through a stand-in relay. Run `npm install` here first or that test is skipped.
248
+ The npm tests run without a phone, relay server, or adb. In the monorepo, the Android app's MCP
249
+ JVM tests also verify the bridge against the app's server implementation and export the tool
250
+ fixture used by the skill tests. Install the package's npm dependencies before running those
251
+ contract tests from `CodeDroid-app/`:
252
+
253
+ ```bash
254
+ ./gradlew :app:testDebugUnitTest --tests 'com.codedroid.app.mcp.*'
255
+ ```
256
+
257
+ These tests export `test/fixtures/phone-tools.json` and run `test/phone-contract.mjs` against
258
+ the app's MCP server through a test relay.
259
+
260
+ ## Attribution
182
261
 
183
- `src/daemon.js`, `stdio-shim.js`, `proxy-core.js`, `adb-tool.js` and `skill.js` are derived from
262
+ Parts of the bridge are derived from
184
263
  [aura-mcp-connect](https://github.com/Dinesh210805/aura-android-use/tree/main/aura-mcp-connect)
185
- (MIT, Copyright (c) 2026 Dinesh Kumar C; `LICENSE.aura-mcp-connect`).
264
+ (MIT, Copyright (c) 2026 Dinesh Kumar C). See [LICENSE.aura-mcp-connect](LICENSE.aura-mcp-connect).
package/gemini-extension.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codedroid",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Drive your Android phone through CodeDroid, with MCP tools and device testing skills.",
5
5
  "mcpServers": {
6
6
  "codedroid": {
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@codedroid/mcp",
3
- "version": "0.1.0",
4
- "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.",
3
+ "version": "0.1.1",
4
+ "description": "MCP server for controlling Android devices through CodeDroid from Claude Code, Codex, Gemini CLI, and other MCP clients.",
5
5
  "type": "module",
6
6
  "main": "src/index.js",
7
7
  "bin": {
package/src/version.js CHANGED
@@ -1,2 +1,2 @@
1
1
  /** The bridge's version, sent to the phone in its hello and shown by `--version`. */
2
- export const VERSION = "0.1.0";
2
+ export const VERSION = "0.1.1";