@codedroid/mcp 0.1.1 → 0.1.2
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.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/{LICENSE.aura-mcp-connect → LICENSE} +1 -1
- package/README.md +32 -216
- package/docs/reference.md +188 -0
- package/gemini-extension.json +1 -1
- package/package.json +5 -3
- package/src/adb-tool.js +2 -4
- package/src/daemon.js +1 -3
- package/src/index.js +0 -2
- package/src/proxy-core.js +3 -4
- package/src/skill.js +0 -3
- package/src/stdio-shim.js +0 -3
- package/src/version.js +1 -1
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "codedroid",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
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/README.md
CHANGED
|
@@ -1,264 +1,80 @@
|
|
|
1
1
|
# CodeDroid MCP
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Let Claude Code, Codex, Gemini CLI, or any MCP client use your Android phone.
|
|
4
|
+
Read the screen, interact with apps, take screenshots, and test what you build
|
|
5
|
+
through [CodeDroid](https://get.codedroid.com). Your phone and computer can be on different networks.
|
|
4
6
|
|
|
5
|
-
|
|
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.
|
|
7
|
+
## Get started
|
|
9
8
|
|
|
10
|
-
|
|
9
|
+
You'll need **Node.js 20+** and **CodeDroid on your Android phone**, signed in with
|
|
10
|
+
its accessibility service enabled. Both devices need internet access.
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
- CodeDroid installed on your phone, signed in, with its accessibility service enabled.
|
|
14
|
-
- An internet connection on both devices.
|
|
12
|
+
### 1. Install for your coding client
|
|
15
13
|
|
|
16
|
-
|
|
17
|
-
on your computer and connect the phone over USB or wireless debugging.
|
|
18
|
-
|
|
19
|
-
## Installation
|
|
20
|
-
|
|
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:
|
|
14
|
+
**Claude Code** — run inside Claude Code:
|
|
28
15
|
|
|
29
16
|
```text
|
|
30
17
|
/plugin marketplace add codedroid-team/codedroid-mcp
|
|
31
18
|
/plugin install codedroid@codedroid
|
|
32
19
|
```
|
|
33
20
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
Run these commands in your terminal with a current version of the Codex CLI:
|
|
21
|
+
**Codex** — run in your terminal:
|
|
37
22
|
|
|
38
23
|
```bash
|
|
39
24
|
codex plugin marketplace add codedroid-team/codedroid-mcp
|
|
40
25
|
codex plugin add codedroid@codedroid
|
|
41
26
|
```
|
|
42
27
|
|
|
43
|
-
|
|
28
|
+
**Gemini CLI** — run in your terminal:
|
|
44
29
|
|
|
45
30
|
```bash
|
|
46
31
|
gemini extensions install https://github.com/codedroid-team/codedroid-mcp
|
|
47
32
|
```
|
|
48
33
|
|
|
49
|
-
|
|
34
|
+
Each installation includes the MCP server and skills for phone control and Android app testing.
|
|
35
|
+
Restart your coding client after installing.
|
|
50
36
|
|
|
51
|
-
|
|
37
|
+
Using another client? See [manual MCP setup](docs/reference.md#mcp-configuration).
|
|
52
38
|
|
|
53
|
-
|
|
39
|
+
### 2. Pair your phone
|
|
54
40
|
|
|
55
|
-
1.
|
|
56
|
-
2. Run the command shown
|
|
41
|
+
1. Open **CodeDroid → Settings → Computers → Pair a computer** on your phone.
|
|
42
|
+
2. Run the command shown there in your computer's terminal. For example:
|
|
57
43
|
|
|
58
44
|
```bash
|
|
59
45
|
npx -y @codedroid/mcp pair ABCD-EFGH
|
|
60
46
|
```
|
|
61
47
|
|
|
62
|
-
3. Tap **Allow** on
|
|
48
|
+
3. Tap **Allow** on your phone when prompted.
|
|
63
49
|
|
|
64
|
-
Pairing codes expire after 10 minutes and
|
|
65
|
-
`--server=<url>` in the pairing command; use the command exactly as displayed.
|
|
50
|
+
Use the command exactly as shown. Pairing codes expire after 10 minutes and work once.
|
|
66
51
|
|
|
67
|
-
|
|
52
|
+
### 3. Ask your agent
|
|
68
53
|
|
|
69
54
|
> Read the screen on my phone and describe what is open.
|
|
70
55
|
|
|
71
|
-
|
|
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
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
The optional second command installs the two skills in `~/.claude/skills`.
|
|
135
|
-
|
|
136
|
-
### Standalone Codex server
|
|
137
|
-
|
|
138
|
-
```bash
|
|
139
|
-
codex mcp add codedroid -- npx -y @codedroid/mcp
|
|
140
|
-
npx -y @codedroid/mcp skill install --codex
|
|
141
|
-
```
|
|
142
|
-
|
|
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`:
|
|
146
|
-
|
|
147
|
-
```toml
|
|
148
|
-
[mcp_servers.codedroid]
|
|
149
|
-
command = "npx"
|
|
150
|
-
args = ["-y", "@codedroid/mcp"]
|
|
151
|
-
tool_timeout_sec = 300
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
### Standalone Gemini CLI server
|
|
155
|
-
|
|
156
|
-
```bash
|
|
157
|
-
gemini mcp add --scope user --timeout 300000 codedroid npx -y @codedroid/mcp
|
|
158
|
-
```
|
|
159
|
-
|
|
160
|
-
### Other MCP clients
|
|
56
|
+
Then try:
|
|
161
57
|
|
|
162
|
-
|
|
58
|
+
- “Open Android Settings and check the Android version.”
|
|
59
|
+
- “Open my app, navigate to sign-in, and take a screenshot.”
|
|
60
|
+
- “Install this APK, launch it, and check for crashes.”*
|
|
163
61
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
"mcpServers": {
|
|
167
|
-
"codedroid": {
|
|
168
|
-
"command": "npx",
|
|
169
|
-
"args": ["-y", "@codedroid/mcp"]
|
|
170
|
-
}
|
|
171
|
-
}
|
|
172
|
-
}
|
|
173
|
-
```
|
|
174
|
-
|
|
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.
|
|
62
|
+
*Installing APKs and using `adb` also requires Android platform-tools and a USB or wireless
|
|
63
|
+
debugging connection. See [adb setup](docs/reference.md#adb-setup).
|
|
177
64
|
|
|
178
|
-
|
|
65
|
+
## Need help?
|
|
179
66
|
|
|
180
|
-
|
|
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. |
|
|
188
|
-
|
|
189
|
-
## CLI reference
|
|
67
|
+
Check your connection:
|
|
190
68
|
|
|
191
69
|
```bash
|
|
192
|
-
npx -y @codedroid/mcp pair ABCD-EFGH
|
|
193
|
-
npx -y @codedroid/mcp connect
|
|
194
70
|
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
|
|
198
71
|
```
|
|
199
72
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
## Troubleshooting
|
|
203
|
-
|
|
204
|
-
Run `npx -y @codedroid/mcp status` or call `codedroid_status` from your agent to diagnose a
|
|
205
|
-
connection problem.
|
|
206
|
-
|
|
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. |
|
|
215
|
-
|
|
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
|
|
226
|
-
```
|
|
227
|
-
|
|
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.
|
|
231
|
-
|
|
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.
|
|
234
|
-
|
|
235
|
-
Pairing credentials are stored in `~/.codedroid/host.json`, readable only by your user account.
|
|
236
|
-
Daemon logs are written to `~/.codedroid/daemon.log`.
|
|
237
|
-
|
|
238
|
-
## Development
|
|
239
|
-
|
|
240
|
-
From the package directory:
|
|
241
|
-
|
|
242
|
-
```bash
|
|
243
|
-
npm install
|
|
244
|
-
npm test
|
|
245
|
-
claude mcp add codedroid -- node "$PWD/src/index.js"
|
|
246
|
-
```
|
|
247
|
-
|
|
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
|
-
```
|
|
73
|
+
Manage or revoke computer access in **CodeDroid → Settings → Computers**.
|
|
256
74
|
|
|
257
|
-
|
|
258
|
-
|
|
75
|
+
See the [reference guide](docs/reference.md) for tools, manual setup, configuration,
|
|
76
|
+
[troubleshooting](docs/reference.md#troubleshooting), and development.
|
|
259
77
|
|
|
260
|
-
##
|
|
78
|
+
## License
|
|
261
79
|
|
|
262
|
-
|
|
263
|
-
[aura-mcp-connect](https://github.com/Dinesh210805/aura-android-use/tree/main/aura-mcp-connect)
|
|
264
|
-
(MIT, Copyright (c) 2026 Dinesh Kumar C). See [LICENSE.aura-mcp-connect](LICENSE.aura-mcp-connect).
|
|
80
|
+
[MIT](LICENSE) © 2026 CodeDroid
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
# CodeDroid MCP reference
|
|
2
|
+
|
|
3
|
+
[Back to setup](../README.md)
|
|
4
|
+
|
|
5
|
+
## Tools
|
|
6
|
+
|
|
7
|
+
The agent can interact with the phone one step at a time or use `run_task` to delegate a goal
|
|
8
|
+
to CodeDroid's agent. `run_task` returns a task ID. Use `get_task` to wait for completion and
|
|
9
|
+
read progress, or `cancel_task` to stop the task.
|
|
10
|
+
|
|
11
|
+
| Tool | Description |
|
|
12
|
+
| --- | --- |
|
|
13
|
+
| `get_screen` | Read the current app and screen as numbered accessibility elements; optionally include a screenshot. |
|
|
14
|
+
| `take_screenshot` | Capture a JPEG screenshot. |
|
|
15
|
+
| `tap`, `long_press` | Interact with an element by node, text, resource ID, content description, or screen coordinates. |
|
|
16
|
+
| `type_text` | Enter text in the focused field; optionally clear it first or press Enter afterward. |
|
|
17
|
+
| `swipe` | Swipe or scroll between screen coordinates. |
|
|
18
|
+
| `press_key` | Press Back, Home, Enter, or Recents. |
|
|
19
|
+
| `open_app`, `list_apps` | Launch an app by package name or list installed apps. |
|
|
20
|
+
| `wait_for` | Wait for text to appear or disappear, or for an app to open. |
|
|
21
|
+
| `clipboard` | Read or update the clipboard. |
|
|
22
|
+
| `device_info` | Inspect the device model, Android version, user, screen, lock state, and CodeDroid readiness. |
|
|
23
|
+
| `run_task`, `get_task`, `cancel_task` | Start, monitor, or cancel a task run by CodeDroid's agent. |
|
|
24
|
+
| `adb` | Run local adb commands against the connected phone. |
|
|
25
|
+
| `codedroid_status` | Check the phone connection and get instructions for resolving connection problems. |
|
|
26
|
+
|
|
27
|
+
Screen interaction tools return an `after` observation with the current app, keyboard state,
|
|
28
|
+
screen changes, and visible elements. Phone tool errors include an error code, message, and
|
|
29
|
+
hint for recovery.
|
|
30
|
+
|
|
31
|
+
## Manage access
|
|
32
|
+
|
|
33
|
+
Paired computers appear in **Settings → Computers** on the phone.
|
|
34
|
+
|
|
35
|
+
- **Remove** revokes a computer's access. Pair again to reconnect it.
|
|
36
|
+
- **Stop** disconnects the active computer and blocks it for one minute.
|
|
37
|
+
- **Allow computers to connect** turns computer access on or off.
|
|
38
|
+
|
|
39
|
+
CodeDroid displays the computer's name and a Stop button while it acts on the phone.
|
|
40
|
+
|
|
41
|
+
## adb setup
|
|
42
|
+
|
|
43
|
+
The optional `adb` tool requires [Android platform-tools](https://developer.android.com/tools/releases/platform-tools)
|
|
44
|
+
on your computer and a USB or wireless debugging connection to your phone.
|
|
45
|
+
|
|
46
|
+
For USB, enable **USB debugging** in the phone's Developer options, connect the cable, and
|
|
47
|
+
accept the debugging prompt on the phone. Run `adb devices` to check the connection.
|
|
48
|
+
For wireless debugging, see [troubleshooting](#troubleshooting).
|
|
49
|
+
|
|
50
|
+
## MCP configuration
|
|
51
|
+
|
|
52
|
+
Use these options when you want the MCP server without a plugin or extension. Configure one
|
|
53
|
+
installation method per client to avoid registering the tools twice.
|
|
54
|
+
|
|
55
|
+
### Standalone Claude Code server
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
claude mcp add codedroid -- npx -y @codedroid/mcp
|
|
59
|
+
npx -y @codedroid/mcp skill install
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
The optional second command installs the two skills in `~/.claude/skills`.
|
|
63
|
+
|
|
64
|
+
### Standalone Codex server
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
codex mcp add codedroid -- npx -y @codedroid/mcp
|
|
68
|
+
npx -y @codedroid/mcp skill install --codex
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
The optional second command installs the skills in `~/.codex/skills`. For calls longer than Codex's
|
|
72
|
+
60-second default timeout, such as APK installation, set `tool_timeout_sec` in
|
|
73
|
+
`~/.codex/config.toml`:
|
|
74
|
+
|
|
75
|
+
```toml
|
|
76
|
+
[mcp_servers.codedroid]
|
|
77
|
+
command = "npx"
|
|
78
|
+
args = ["-y", "@codedroid/mcp"]
|
|
79
|
+
tool_timeout_sec = 300
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### Standalone Gemini CLI server
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
gemini mcp add --scope user --timeout 300000 codedroid npx -y @codedroid/mcp
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### Other MCP clients
|
|
89
|
+
|
|
90
|
+
Add this server configuration to your client's MCP settings:
|
|
91
|
+
|
|
92
|
+
```json
|
|
93
|
+
{
|
|
94
|
+
"mcpServers": {
|
|
95
|
+
"codedroid": {
|
|
96
|
+
"command": "npx",
|
|
97
|
+
"args": ["-y", "@codedroid/mcp"]
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Clients that support Streamable HTTP can also connect to `http://127.0.0.1:4826/mcp`.
|
|
104
|
+
After pairing, run `npx -y @codedroid/mcp connect` to start the shared daemon before connecting
|
|
105
|
+
an HTTP client.
|
|
106
|
+
|
|
107
|
+
### Environment variables
|
|
108
|
+
|
|
109
|
+
| Variable | Description |
|
|
110
|
+
| --- | --- |
|
|
111
|
+
| `CODEDROID_SERIAL` | Select an adb device when several are connected. `ANDROID_SERIAL` is also supported. |
|
|
112
|
+
| `CODEDROID_MCP_PORT` | Set the local daemon port. Default: `4826`. |
|
|
113
|
+
| `CODEDROID_MCP_ADB=0` | Disable the `adb` tool. |
|
|
114
|
+
| `CODEDROID_MCP_CLIENT` | Set the client name shown on the phone. |
|
|
115
|
+
| `ADB` | Set the path to the adb executable. |
|
|
116
|
+
| `CODEDROID_DEBUG=1` | Include stack traces in diagnostic output. |
|
|
117
|
+
|
|
118
|
+
## CLI reference
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
npx -y @codedroid/mcp pair ABCD-EFGH
|
|
122
|
+
npx -y @codedroid/mcp connect
|
|
123
|
+
npx -y @codedroid/mcp status
|
|
124
|
+
npx -y @codedroid/mcp call get_screen
|
|
125
|
+
npx -y @codedroid/mcp call tap '{"text": "Display"}'
|
|
126
|
+
npx -y @codedroid/mcp stop
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
`connect` reconnects a paired computer. `stop` shuts down the local daemon.
|
|
130
|
+
|
|
131
|
+
## Troubleshooting
|
|
132
|
+
|
|
133
|
+
Run `npx -y @codedroid/mcp status` or call `codedroid_status` from your agent to diagnose a
|
|
134
|
+
connection problem.
|
|
135
|
+
|
|
136
|
+
| Problem | Action |
|
|
137
|
+
| --- | --- |
|
|
138
|
+
| Computer is not paired, or pairing was removed | Create a new code in **Settings → Computers → Pair a computer** and run the displayed command. |
|
|
139
|
+
| Phone is not connected | Open CodeDroid, check its internet connection and sign-in, and enable **Allow computers to connect**. |
|
|
140
|
+
| Connection is awaiting approval | Tap **Allow** on the phone. |
|
|
141
|
+
| Connection was denied | Wait one minute, run `npx -y @codedroid/mcp connect`, then tap **Allow**. |
|
|
142
|
+
| Connection was stopped on the phone | Wait one minute before reconnecting. |
|
|
143
|
+
| adb cannot find the phone | Connect it over USB, or run `adb pair <ip:port>` followed by `adb connect <ip:port>` for wireless debugging. |
|
|
144
|
+
|
|
145
|
+
Force-stopping or running instrumentation against `com.codedroid.app` disables its accessibility
|
|
146
|
+
service. Re-enable it in Android Accessibility settings afterward. Clearing the app's data also
|
|
147
|
+
signs it out. UiAutomator tests and `uiautomator dump` temporarily suspend CodeDroid's
|
|
148
|
+
accessibility access while they run.
|
|
149
|
+
|
|
150
|
+
## Architecture
|
|
151
|
+
|
|
152
|
+
```text
|
|
153
|
+
MCP client → stdio bridge → local daemon → CodeDroid relay → Android app
|
|
154
|
+
└── local adb
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
All clients on a computer share a local daemon and its connection to the paired phone. The
|
|
158
|
+
phone and daemon each open an outbound WebSocket to the CodeDroid server. The phone reconnects
|
|
159
|
+
after a restart or network change. MCP screen interactions are serialized on the phone.
|
|
160
|
+
|
|
161
|
+
Calls interrupted by a connection loss are not automatically replayed: an action may have
|
|
162
|
+
completed before its response was lost. Read the screen before deciding whether to retry.
|
|
163
|
+
|
|
164
|
+
Pairing credentials are stored in `~/.codedroid/host.json`, readable only by your user account.
|
|
165
|
+
Daemon logs are written to `~/.codedroid/daemon.log`.
|
|
166
|
+
|
|
167
|
+
## Development
|
|
168
|
+
|
|
169
|
+
From the package directory:
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
npm install
|
|
173
|
+
npm test
|
|
174
|
+
claude mcp add codedroid -- node "$PWD/src/index.js"
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
The npm tests run without a phone, relay server, or adb. In the monorepo, the Android app's MCP
|
|
178
|
+
JVM tests also verify the bridge against the app's server implementation and export the tool
|
|
179
|
+
fixture used by the skill tests. Install the package's npm dependencies before running those
|
|
180
|
+
contract tests from `CodeDroid-app/`:
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
./gradlew :app:testDebugUnitTest --tests 'com.codedroid.app.mcp.*'
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
These tests export `test/fixtures/phone-tools.json` and run `test/phone-contract.mjs` against
|
|
187
|
+
the app's MCP server through a test relay.
|
|
188
|
+
|
package/gemini-extension.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@codedroid/mcp",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
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",
|
|
@@ -16,7 +16,8 @@
|
|
|
16
16
|
"gemini-extension.json",
|
|
17
17
|
".mcp.json",
|
|
18
18
|
"README.md",
|
|
19
|
-
"
|
|
19
|
+
"docs",
|
|
20
|
+
"LICENSE"
|
|
20
21
|
],
|
|
21
22
|
"engines": {
|
|
22
23
|
"node": ">=20"
|
|
@@ -42,5 +43,6 @@
|
|
|
42
43
|
"repository": {
|
|
43
44
|
"type": "git",
|
|
44
45
|
"url": "git+https://github.com/codedroid-team/codedroid-mcp.git"
|
|
45
|
-
}
|
|
46
|
+
},
|
|
47
|
+
"license": "MIT"
|
|
46
48
|
}
|
package/src/adb-tool.js
CHANGED
|
@@ -2,10 +2,8 @@
|
|
|
2
2
|
* adb — a single generic MCP tool that runs an adb command against a phone
|
|
3
3
|
* attached to THIS computer (USB, or Wireless Debugging).
|
|
4
4
|
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
* (CODEDROID_MCP_ADB=0 turns it off); marked destructive so clients ask before running
|
|
8
|
-
* it; a per-call timeout.
|
|
5
|
+
* Enabled by default (CODEDROID_MCP_ADB=0 turns it off), with a per-call timeout.
|
|
6
|
+
* Marked destructive so clients ask before running it.
|
|
9
7
|
*
|
|
10
8
|
* It never touches the connection to CodeDroid: it shells out to this machine's
|
|
11
9
|
* own `adb`, exactly like a developer typing `adb install app.apk` themselves.
|
package/src/daemon.js
CHANGED
|
@@ -3,9 +3,7 @@
|
|
|
3
3
|
* CodeDroid on the phone (through the CodeDroid server's relay) and serves MCP over
|
|
4
4
|
* Streamable HTTP on localhost.
|
|
5
5
|
*
|
|
6
|
-
*
|
|
7
|
-
* LICENSE.aura-mcp-connect): the link is a WebSocket relay instead of WebRTC, and the adb tool is
|
|
8
|
-
* on by default.
|
|
6
|
+
* The phone connection uses a WebSocket relay. The adb tool is enabled by default.
|
|
9
7
|
*
|
|
10
8
|
* Every MCP client (Claude Code, Claude Desktop, Cursor, VS Code windows…)
|
|
11
9
|
* connects to http://127.0.0.1:<port>/mcp and gets its own MCP session; tool
|
package/src/index.js
CHANGED
|
@@ -21,8 +21,6 @@
|
|
|
21
21
|
* leaves out the adb tool. CODEDROID_SERIAL picks the adb tool's device when several are attached.
|
|
22
22
|
*
|
|
23
23
|
* All log output goes to stderr — stdout is reserved for MCP JSON-RPC frames.
|
|
24
|
-
*
|
|
25
|
-
* Forked from aura-mcp-connect (MIT, Copyright (c) 2026 Dinesh Kumar C; see LICENSE.aura-mcp-connect).
|
|
26
24
|
*/
|
|
27
25
|
import { VERSION } from "./version.js";
|
|
28
26
|
|
package/src/proxy-core.js
CHANGED
|
@@ -2,10 +2,9 @@
|
|
|
2
2
|
* proxy-core — builds an MCP Server that transparently forwards requests to a
|
|
3
3
|
* backend MCP Client (the single phone connection).
|
|
4
4
|
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
* instructions, and tools/list keeps trying the phone.
|
|
5
|
+
* A session still opens when the phone cannot be reached, serving the local tools
|
|
6
|
+
* (adb, codedroid_status) and saying why in its instructions. tools/list keeps
|
|
7
|
+
* trying the phone.
|
|
9
8
|
*
|
|
10
9
|
* Used twice:
|
|
11
10
|
* - daemon: one proxy Server per HTTP client session → phone client
|
package/src/skill.js
CHANGED
|
@@ -7,9 +7,6 @@
|
|
|
7
7
|
* or any directory (--dir).
|
|
8
8
|
* - Change together: the skills name tools, so a renamed tool means editing them
|
|
9
9
|
* (test/skill.test.mjs checks every name they use exists).
|
|
10
|
-
*
|
|
11
|
-
* Forked from aura-mcp-connect's skill.js (MIT, Copyright (c) 2026 Dinesh Kumar C; see
|
|
12
|
-
* LICENSE.aura-mcp-connect).
|
|
13
10
|
*/
|
|
14
11
|
import fs from "fs";
|
|
15
12
|
import os from "os";
|
package/src/stdio-shim.js
CHANGED
|
@@ -5,9 +5,6 @@
|
|
|
5
5
|
*
|
|
6
6
|
* IDE ── stdio ── this shim ── HTTP ── daemon ── relay ── CodeDroid on the phone
|
|
7
7
|
*
|
|
8
|
-
* Forked from aura-mcp-connect (MIT, Copyright (c) 2026 Dinesh Kumar C; see
|
|
9
|
-
* LICENSE.aura-mcp-connect).
|
|
10
|
-
*
|
|
11
8
|
* Any number of shims (one per IDE/window) share the one phone connection.
|
|
12
9
|
*/
|
|
13
10
|
import { spawn } from "child_process";
|
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.
|
|
2
|
+
export const VERSION = "0.1.2";
|