android-device-control 0.1.0__tar.gz
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.
- android_device_control-0.1.0/LICENSE +21 -0
- android_device_control-0.1.0/MANIFEST.in +1 -0
- android_device_control-0.1.0/PKG-INFO +151 -0
- android_device_control-0.1.0/README.md +137 -0
- android_device_control-0.1.0/__init__.py +1 -0
- android_device_control-0.1.0/android_device_control.egg-info/PKG-INFO +151 -0
- android_device_control-0.1.0/android_device_control.egg-info/SOURCES.txt +28 -0
- android_device_control-0.1.0/android_device_control.egg-info/dependency_links.txt +1 -0
- android_device_control-0.1.0/android_device_control.egg-info/entry_points.txt +6 -0
- android_device_control-0.1.0/android_device_control.egg-info/requires.txt +3 -0
- android_device_control-0.1.0/android_device_control.egg-info/top_level.txt +1 -0
- android_device_control-0.1.0/android_mcp.py +107 -0
- android_device_control-0.1.0/device_info.py +182 -0
- android_device_control-0.1.0/messages.py +164 -0
- android_device_control-0.1.0/phone.py +568 -0
- android_device_control-0.1.0/pyproject.toml +31 -0
- android_device_control-0.1.0/receipts.py +224 -0
- android_device_control-0.1.0/requirements-mcp.txt +1 -0
- android_device_control-0.1.0/setup.cfg +4 -0
- android_device_control-0.1.0/tests/test_android_mcp.py +116 -0
- android_device_control-0.1.0/tests/test_device_info.py +133 -0
- android_device_control-0.1.0/tests/test_messages.py +123 -0
- android_device_control-0.1.0/tests/test_phone.py +419 -0
- android_device_control-0.1.0/tests/test_receipts.py +126 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 lisn0
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
include requirements-mcp.txt
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: android-device-control
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Inspect and operate authorized Android devices through ADB.
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Repository, https://github.com/lisn0/android-device-control
|
|
7
|
+
Project-URL: Issues, https://github.com/lisn0/android-device-control/issues
|
|
8
|
+
Requires-Python: >=3.10
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Provides-Extra: mcp
|
|
12
|
+
Requires-Dist: mcp<2,>=1.28; extra == "mcp"
|
|
13
|
+
Dynamic: license-file
|
|
14
|
+
|
|
15
|
+
# Android Control
|
|
16
|
+
|
|
17
|
+
A local command-line tool for inspecting and operating an authorized Android
|
|
18
|
+
device through ADB. Inspect the current app, select visible controls, and verify
|
|
19
|
+
the result after each action. The repository includes read-only device and SMS
|
|
20
|
+
diagnostics and a guide for manually setting up social accounts.
|
|
21
|
+
|
|
22
|
+
## Install
|
|
23
|
+
|
|
24
|
+
Python 3.10 or newer is required. Install `adb` from
|
|
25
|
+
[Android SDK Platform-Tools](https://developer.android.com/tools/releases/platform-tools)
|
|
26
|
+
and put it on your PATH. In your Python environment, install the CLI.
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
python -m pip install android-device-control
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The CLI uses the Python standard library. If you are working from a clone, you
|
|
33
|
+
can run the scripts directly with `python3 -B phone.py`, `device_info.py`,
|
|
34
|
+
`messages.py`, and `receipts.py`.
|
|
35
|
+
|
|
36
|
+
## Get started
|
|
37
|
+
|
|
38
|
+
1. Connect your test device over USB, enable USB debugging, and approve your
|
|
39
|
+
computer on the device. See Google's [ADB setup guide](https://developer.android.com/tools/adb)
|
|
40
|
+
for USB troubleshooting and wireless pairing.
|
|
41
|
+
2. List devices and run a read-only check. Replace
|
|
42
|
+
`DEVICE_SERIAL` with the serial shown for your authorized device.
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
android-control devices
|
|
46
|
+
android-control-device-info --device DEVICE_SERIAL
|
|
47
|
+
android-control foreground --device DEVICE_SERIAL
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Open an ordinary test screen on the device to read its accessibility tree.
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
android-control snapshot --device DEVICE_SERIAL
|
|
54
|
+
android-control --help
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Use `android-control-sms --help` for SMS diagnostics and
|
|
58
|
+
`android-control-receipts --help` for the local setup receipt ledger.
|
|
59
|
+
|
|
60
|
+
## Optional MCP server
|
|
61
|
+
|
|
62
|
+
An MCP client can launch Android Control locally over stdio. The server only
|
|
63
|
+
needs the optional MCP SDK and access to `adb` on its PATH.
|
|
64
|
+
|
|
65
|
+
```sh
|
|
66
|
+
python -m pip install 'android-device-control[mcp]'
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
For a client that uses `mcpServers` JSON, use the installed command on its PATH
|
|
70
|
+
or set `command` to the full path to the executable.
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"mcpServers": {
|
|
75
|
+
"android-control": {
|
|
76
|
+
"command": "android-control-mcp"
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
With `uvx` on the client's PATH, use `"command": "uvx"` and
|
|
83
|
+
`"args": ["--from", "android-device-control[mcp]", "android-control-mcp"]`.
|
|
84
|
+
|
|
85
|
+
### Run from a checkout
|
|
86
|
+
|
|
87
|
+
Create a Python environment with the MCP SDK.
|
|
88
|
+
|
|
89
|
+
```sh
|
|
90
|
+
python3 -m venv .venv
|
|
91
|
+
.venv/bin/python -m pip install -r requirements-mcp.txt
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Replace the example paths with the absolute paths to the environment's Python
|
|
95
|
+
executable and `android_mcp.py`.
|
|
96
|
+
|
|
97
|
+
```json
|
|
98
|
+
{
|
|
99
|
+
"mcpServers": {
|
|
100
|
+
"android-control": {
|
|
101
|
+
"command": "/absolute/path/to/android-control/.venv/bin/python",
|
|
102
|
+
"args": ["/absolute/path/to/android-control/android_mcp.py"]
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Scope tools to a device
|
|
109
|
+
|
|
110
|
+
The default tools are `list_devices` (authorized serials and ADB states),
|
|
111
|
+
`foreground` (focused package and activity), and `snapshot` (guarded UI summary).
|
|
112
|
+
Supply the target `serial` to `foreground` and `snapshot`. To scope every tool
|
|
113
|
+
to one phone, append `"--device", "DEVICE_SERIAL"` to `args`, using the serial
|
|
114
|
+
shown by `android-control devices` or `python3 -B phone.py devices`. The scoped
|
|
115
|
+
read tools can then omit `serial`.
|
|
116
|
+
|
|
117
|
+
To enable `tap_label`, append `"--allow-input"` after the device arguments. The
|
|
118
|
+
tool acts only on that configured phone and requires a single enabled clickable
|
|
119
|
+
match for the exact accessibility label. Inspect the screen again after a tap
|
|
120
|
+
to verify its effect.
|
|
121
|
+
|
|
122
|
+
Use a trusted local client and a test screen. Snapshots can contain private app
|
|
123
|
+
content. Handle sensitive prompts manually and keep login, messaging, and
|
|
124
|
+
payment screens out of the MCP workflow.
|
|
125
|
+
|
|
126
|
+
## Workflows
|
|
127
|
+
|
|
128
|
+
- [App navigation and UI interaction](https://github.com/lisn0/android-device-control/blob/main/docs/workflows.md)
|
|
129
|
+
- [Device diagnostics and SMS inspection](https://github.com/lisn0/android-device-control/blob/main/docs/device-information.md)
|
|
130
|
+
- [Manual social-account setup and receipts](https://github.com/lisn0/android-device-control/blob/main/docs/social-account-setup.md)
|
|
131
|
+
- [Design references](https://github.com/lisn0/android-device-control/blob/main/docs/research.md)
|
|
132
|
+
|
|
133
|
+
The authentication guard uses English accessibility labels and password-field
|
|
134
|
+
metadata. It can miss unlabeled or non-English screens. Handle passwords,
|
|
135
|
+
verification codes, recovery, identity, and payment prompts directly on the device.
|
|
136
|
+
Keep secrets out of command arguments and receipts.
|
|
137
|
+
|
|
138
|
+
## Tests and bug reports
|
|
139
|
+
|
|
140
|
+
```sh
|
|
141
|
+
python3 -B -m unittest discover -s tests -v
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
The tests use mock ADB responses. For a bug report, provide the command, Android
|
|
145
|
+
and ADB versions, and a sanitized error or synthetic reproduction. Device lists,
|
|
146
|
+
snapshots, screenshots, and SMS output can contain serials, account identifiers,
|
|
147
|
+
private messages, or codes. Remove those details before sharing.
|
|
148
|
+
|
|
149
|
+
## License
|
|
150
|
+
|
|
151
|
+
[MIT](https://github.com/lisn0/android-device-control/blob/main/LICENSE)
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# Android Control
|
|
2
|
+
|
|
3
|
+
A local command-line tool for inspecting and operating an authorized Android
|
|
4
|
+
device through ADB. Inspect the current app, select visible controls, and verify
|
|
5
|
+
the result after each action. The repository includes read-only device and SMS
|
|
6
|
+
diagnostics and a guide for manually setting up social accounts.
|
|
7
|
+
|
|
8
|
+
## Install
|
|
9
|
+
|
|
10
|
+
Python 3.10 or newer is required. Install `adb` from
|
|
11
|
+
[Android SDK Platform-Tools](https://developer.android.com/tools/releases/platform-tools)
|
|
12
|
+
and put it on your PATH. In your Python environment, install the CLI.
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
python -m pip install android-device-control
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
The CLI uses the Python standard library. If you are working from a clone, you
|
|
19
|
+
can run the scripts directly with `python3 -B phone.py`, `device_info.py`,
|
|
20
|
+
`messages.py`, and `receipts.py`.
|
|
21
|
+
|
|
22
|
+
## Get started
|
|
23
|
+
|
|
24
|
+
1. Connect your test device over USB, enable USB debugging, and approve your
|
|
25
|
+
computer on the device. See Google's [ADB setup guide](https://developer.android.com/tools/adb)
|
|
26
|
+
for USB troubleshooting and wireless pairing.
|
|
27
|
+
2. List devices and run a read-only check. Replace
|
|
28
|
+
`DEVICE_SERIAL` with the serial shown for your authorized device.
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
android-control devices
|
|
32
|
+
android-control-device-info --device DEVICE_SERIAL
|
|
33
|
+
android-control foreground --device DEVICE_SERIAL
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Open an ordinary test screen on the device to read its accessibility tree.
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
android-control snapshot --device DEVICE_SERIAL
|
|
40
|
+
android-control --help
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Use `android-control-sms --help` for SMS diagnostics and
|
|
44
|
+
`android-control-receipts --help` for the local setup receipt ledger.
|
|
45
|
+
|
|
46
|
+
## Optional MCP server
|
|
47
|
+
|
|
48
|
+
An MCP client can launch Android Control locally over stdio. The server only
|
|
49
|
+
needs the optional MCP SDK and access to `adb` on its PATH.
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
python -m pip install 'android-device-control[mcp]'
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
For a client that uses `mcpServers` JSON, use the installed command on its PATH
|
|
56
|
+
or set `command` to the full path to the executable.
|
|
57
|
+
|
|
58
|
+
```json
|
|
59
|
+
{
|
|
60
|
+
"mcpServers": {
|
|
61
|
+
"android-control": {
|
|
62
|
+
"command": "android-control-mcp"
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
With `uvx` on the client's PATH, use `"command": "uvx"` and
|
|
69
|
+
`"args": ["--from", "android-device-control[mcp]", "android-control-mcp"]`.
|
|
70
|
+
|
|
71
|
+
### Run from a checkout
|
|
72
|
+
|
|
73
|
+
Create a Python environment with the MCP SDK.
|
|
74
|
+
|
|
75
|
+
```sh
|
|
76
|
+
python3 -m venv .venv
|
|
77
|
+
.venv/bin/python -m pip install -r requirements-mcp.txt
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Replace the example paths with the absolute paths to the environment's Python
|
|
81
|
+
executable and `android_mcp.py`.
|
|
82
|
+
|
|
83
|
+
```json
|
|
84
|
+
{
|
|
85
|
+
"mcpServers": {
|
|
86
|
+
"android-control": {
|
|
87
|
+
"command": "/absolute/path/to/android-control/.venv/bin/python",
|
|
88
|
+
"args": ["/absolute/path/to/android-control/android_mcp.py"]
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### Scope tools to a device
|
|
95
|
+
|
|
96
|
+
The default tools are `list_devices` (authorized serials and ADB states),
|
|
97
|
+
`foreground` (focused package and activity), and `snapshot` (guarded UI summary).
|
|
98
|
+
Supply the target `serial` to `foreground` and `snapshot`. To scope every tool
|
|
99
|
+
to one phone, append `"--device", "DEVICE_SERIAL"` to `args`, using the serial
|
|
100
|
+
shown by `android-control devices` or `python3 -B phone.py devices`. The scoped
|
|
101
|
+
read tools can then omit `serial`.
|
|
102
|
+
|
|
103
|
+
To enable `tap_label`, append `"--allow-input"` after the device arguments. The
|
|
104
|
+
tool acts only on that configured phone and requires a single enabled clickable
|
|
105
|
+
match for the exact accessibility label. Inspect the screen again after a tap
|
|
106
|
+
to verify its effect.
|
|
107
|
+
|
|
108
|
+
Use a trusted local client and a test screen. Snapshots can contain private app
|
|
109
|
+
content. Handle sensitive prompts manually and keep login, messaging, and
|
|
110
|
+
payment screens out of the MCP workflow.
|
|
111
|
+
|
|
112
|
+
## Workflows
|
|
113
|
+
|
|
114
|
+
- [App navigation and UI interaction](https://github.com/lisn0/android-device-control/blob/main/docs/workflows.md)
|
|
115
|
+
- [Device diagnostics and SMS inspection](https://github.com/lisn0/android-device-control/blob/main/docs/device-information.md)
|
|
116
|
+
- [Manual social-account setup and receipts](https://github.com/lisn0/android-device-control/blob/main/docs/social-account-setup.md)
|
|
117
|
+
- [Design references](https://github.com/lisn0/android-device-control/blob/main/docs/research.md)
|
|
118
|
+
|
|
119
|
+
The authentication guard uses English accessibility labels and password-field
|
|
120
|
+
metadata. It can miss unlabeled or non-English screens. Handle passwords,
|
|
121
|
+
verification codes, recovery, identity, and payment prompts directly on the device.
|
|
122
|
+
Keep secrets out of command arguments and receipts.
|
|
123
|
+
|
|
124
|
+
## Tests and bug reports
|
|
125
|
+
|
|
126
|
+
```sh
|
|
127
|
+
python3 -B -m unittest discover -s tests -v
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
The tests use mock ADB responses. For a bug report, provide the command, Android
|
|
131
|
+
and ADB versions, and a sanitized error or synthetic reproduction. Device lists,
|
|
132
|
+
snapshots, screenshots, and SMS output can contain serials, account identifiers,
|
|
133
|
+
private messages, or codes. Remove those details before sharing.
|
|
134
|
+
|
|
135
|
+
## License
|
|
136
|
+
|
|
137
|
+
[MIT](https://github.com/lisn0/android-device-control/blob/main/LICENSE)
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Android device controls and diagnostics for authorized ADB devices."""
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: android-device-control
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Inspect and operate authorized Android devices through ADB.
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Repository, https://github.com/lisn0/android-device-control
|
|
7
|
+
Project-URL: Issues, https://github.com/lisn0/android-device-control/issues
|
|
8
|
+
Requires-Python: >=3.10
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Provides-Extra: mcp
|
|
12
|
+
Requires-Dist: mcp<2,>=1.28; extra == "mcp"
|
|
13
|
+
Dynamic: license-file
|
|
14
|
+
|
|
15
|
+
# Android Control
|
|
16
|
+
|
|
17
|
+
A local command-line tool for inspecting and operating an authorized Android
|
|
18
|
+
device through ADB. Inspect the current app, select visible controls, and verify
|
|
19
|
+
the result after each action. The repository includes read-only device and SMS
|
|
20
|
+
diagnostics and a guide for manually setting up social accounts.
|
|
21
|
+
|
|
22
|
+
## Install
|
|
23
|
+
|
|
24
|
+
Python 3.10 or newer is required. Install `adb` from
|
|
25
|
+
[Android SDK Platform-Tools](https://developer.android.com/tools/releases/platform-tools)
|
|
26
|
+
and put it on your PATH. In your Python environment, install the CLI.
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
python -m pip install android-device-control
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The CLI uses the Python standard library. If you are working from a clone, you
|
|
33
|
+
can run the scripts directly with `python3 -B phone.py`, `device_info.py`,
|
|
34
|
+
`messages.py`, and `receipts.py`.
|
|
35
|
+
|
|
36
|
+
## Get started
|
|
37
|
+
|
|
38
|
+
1. Connect your test device over USB, enable USB debugging, and approve your
|
|
39
|
+
computer on the device. See Google's [ADB setup guide](https://developer.android.com/tools/adb)
|
|
40
|
+
for USB troubleshooting and wireless pairing.
|
|
41
|
+
2. List devices and run a read-only check. Replace
|
|
42
|
+
`DEVICE_SERIAL` with the serial shown for your authorized device.
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
android-control devices
|
|
46
|
+
android-control-device-info --device DEVICE_SERIAL
|
|
47
|
+
android-control foreground --device DEVICE_SERIAL
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Open an ordinary test screen on the device to read its accessibility tree.
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
android-control snapshot --device DEVICE_SERIAL
|
|
54
|
+
android-control --help
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Use `android-control-sms --help` for SMS diagnostics and
|
|
58
|
+
`android-control-receipts --help` for the local setup receipt ledger.
|
|
59
|
+
|
|
60
|
+
## Optional MCP server
|
|
61
|
+
|
|
62
|
+
An MCP client can launch Android Control locally over stdio. The server only
|
|
63
|
+
needs the optional MCP SDK and access to `adb` on its PATH.
|
|
64
|
+
|
|
65
|
+
```sh
|
|
66
|
+
python -m pip install 'android-device-control[mcp]'
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
For a client that uses `mcpServers` JSON, use the installed command on its PATH
|
|
70
|
+
or set `command` to the full path to the executable.
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"mcpServers": {
|
|
75
|
+
"android-control": {
|
|
76
|
+
"command": "android-control-mcp"
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
With `uvx` on the client's PATH, use `"command": "uvx"` and
|
|
83
|
+
`"args": ["--from", "android-device-control[mcp]", "android-control-mcp"]`.
|
|
84
|
+
|
|
85
|
+
### Run from a checkout
|
|
86
|
+
|
|
87
|
+
Create a Python environment with the MCP SDK.
|
|
88
|
+
|
|
89
|
+
```sh
|
|
90
|
+
python3 -m venv .venv
|
|
91
|
+
.venv/bin/python -m pip install -r requirements-mcp.txt
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Replace the example paths with the absolute paths to the environment's Python
|
|
95
|
+
executable and `android_mcp.py`.
|
|
96
|
+
|
|
97
|
+
```json
|
|
98
|
+
{
|
|
99
|
+
"mcpServers": {
|
|
100
|
+
"android-control": {
|
|
101
|
+
"command": "/absolute/path/to/android-control/.venv/bin/python",
|
|
102
|
+
"args": ["/absolute/path/to/android-control/android_mcp.py"]
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Scope tools to a device
|
|
109
|
+
|
|
110
|
+
The default tools are `list_devices` (authorized serials and ADB states),
|
|
111
|
+
`foreground` (focused package and activity), and `snapshot` (guarded UI summary).
|
|
112
|
+
Supply the target `serial` to `foreground` and `snapshot`. To scope every tool
|
|
113
|
+
to one phone, append `"--device", "DEVICE_SERIAL"` to `args`, using the serial
|
|
114
|
+
shown by `android-control devices` or `python3 -B phone.py devices`. The scoped
|
|
115
|
+
read tools can then omit `serial`.
|
|
116
|
+
|
|
117
|
+
To enable `tap_label`, append `"--allow-input"` after the device arguments. The
|
|
118
|
+
tool acts only on that configured phone and requires a single enabled clickable
|
|
119
|
+
match for the exact accessibility label. Inspect the screen again after a tap
|
|
120
|
+
to verify its effect.
|
|
121
|
+
|
|
122
|
+
Use a trusted local client and a test screen. Snapshots can contain private app
|
|
123
|
+
content. Handle sensitive prompts manually and keep login, messaging, and
|
|
124
|
+
payment screens out of the MCP workflow.
|
|
125
|
+
|
|
126
|
+
## Workflows
|
|
127
|
+
|
|
128
|
+
- [App navigation and UI interaction](https://github.com/lisn0/android-device-control/blob/main/docs/workflows.md)
|
|
129
|
+
- [Device diagnostics and SMS inspection](https://github.com/lisn0/android-device-control/blob/main/docs/device-information.md)
|
|
130
|
+
- [Manual social-account setup and receipts](https://github.com/lisn0/android-device-control/blob/main/docs/social-account-setup.md)
|
|
131
|
+
- [Design references](https://github.com/lisn0/android-device-control/blob/main/docs/research.md)
|
|
132
|
+
|
|
133
|
+
The authentication guard uses English accessibility labels and password-field
|
|
134
|
+
metadata. It can miss unlabeled or non-English screens. Handle passwords,
|
|
135
|
+
verification codes, recovery, identity, and payment prompts directly on the device.
|
|
136
|
+
Keep secrets out of command arguments and receipts.
|
|
137
|
+
|
|
138
|
+
## Tests and bug reports
|
|
139
|
+
|
|
140
|
+
```sh
|
|
141
|
+
python3 -B -m unittest discover -s tests -v
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
The tests use mock ADB responses. For a bug report, provide the command, Android
|
|
145
|
+
and ADB versions, and a sanitized error or synthetic reproduction. Device lists,
|
|
146
|
+
snapshots, screenshots, and SMS output can contain serials, account identifiers,
|
|
147
|
+
private messages, or codes. Remove those details before sharing.
|
|
148
|
+
|
|
149
|
+
## License
|
|
150
|
+
|
|
151
|
+
[MIT](https://github.com/lisn0/android-device-control/blob/main/LICENSE)
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
MANIFEST.in
|
|
3
|
+
README.md
|
|
4
|
+
__init__.py
|
|
5
|
+
android_mcp.py
|
|
6
|
+
device_info.py
|
|
7
|
+
messages.py
|
|
8
|
+
phone.py
|
|
9
|
+
pyproject.toml
|
|
10
|
+
receipts.py
|
|
11
|
+
requirements-mcp.txt
|
|
12
|
+
./__init__.py
|
|
13
|
+
./android_mcp.py
|
|
14
|
+
./device_info.py
|
|
15
|
+
./messages.py
|
|
16
|
+
./phone.py
|
|
17
|
+
./receipts.py
|
|
18
|
+
android_device_control.egg-info/PKG-INFO
|
|
19
|
+
android_device_control.egg-info/SOURCES.txt
|
|
20
|
+
android_device_control.egg-info/dependency_links.txt
|
|
21
|
+
android_device_control.egg-info/entry_points.txt
|
|
22
|
+
android_device_control.egg-info/requires.txt
|
|
23
|
+
android_device_control.egg-info/top_level.txt
|
|
24
|
+
tests/test_android_mcp.py
|
|
25
|
+
tests/test_device_info.py
|
|
26
|
+
tests/test_messages.py
|
|
27
|
+
tests/test_phone.py
|
|
28
|
+
tests/test_receipts.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
[console_scripts]
|
|
2
|
+
android-control = android_device_control.phone:main
|
|
3
|
+
android-control-device-info = android_device_control.device_info:main
|
|
4
|
+
android-control-mcp = android_device_control.android_mcp:main
|
|
5
|
+
android-control-receipts = android_device_control.receipts:main
|
|
6
|
+
android-control-sms = android_device_control.messages:main
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
android_device_control
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Serve guarded Android Control tools over local MCP stdio."""
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import re
|
|
7
|
+
from typing import TYPE_CHECKING
|
|
8
|
+
|
|
9
|
+
if __package__:
|
|
10
|
+
from . import phone
|
|
11
|
+
else:
|
|
12
|
+
import phone
|
|
13
|
+
|
|
14
|
+
if TYPE_CHECKING:
|
|
15
|
+
from mcp.server.fastmcp import FastMCP
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
SERIAL = re.compile(r"[A-Za-z0-9._:-]+")
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def authorized_devices(device: str | None = None) -> list[dict[str, str]]:
|
|
22
|
+
devices = []
|
|
23
|
+
for line in phone.devices().splitlines():
|
|
24
|
+
fields = line.split(maxsplit=2)
|
|
25
|
+
if len(fields) < 2:
|
|
26
|
+
continue
|
|
27
|
+
serial, state = fields[:2]
|
|
28
|
+
if state == "device" and SERIAL.fullmatch(serial) and (device is None or serial == device):
|
|
29
|
+
devices.append({"serial": serial, "state": state})
|
|
30
|
+
return devices
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def require_device(requested: str | None, configured: str | None) -> str:
|
|
34
|
+
if configured is not None and requested not in (None, configured):
|
|
35
|
+
raise phone.PhoneError("device is outside the server's configured scope")
|
|
36
|
+
serial = configured if configured is not None else requested
|
|
37
|
+
if not serial or not SERIAL.fullmatch(serial):
|
|
38
|
+
raise phone.PhoneError("provide an explicit valid device serial")
|
|
39
|
+
if not authorized_devices(serial):
|
|
40
|
+
raise phone.PhoneError("device is not connected and authorized in ADB")
|
|
41
|
+
return serial
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def create_server(device: str | None = None, *, allow_input: bool = False) -> FastMCP:
|
|
45
|
+
if device is not None and not SERIAL.fullmatch(device):
|
|
46
|
+
raise phone.PhoneError("--device requires an explicit valid device serial")
|
|
47
|
+
if allow_input and device is None:
|
|
48
|
+
raise phone.PhoneError("--allow-input requires --device")
|
|
49
|
+
|
|
50
|
+
try:
|
|
51
|
+
from mcp.server.fastmcp import FastMCP
|
|
52
|
+
from mcp.types import ToolAnnotations
|
|
53
|
+
except ModuleNotFoundError as exc:
|
|
54
|
+
if exc.name not in ("mcp", "mcp.server.fastmcp"):
|
|
55
|
+
raise
|
|
56
|
+
install_command = (
|
|
57
|
+
"python -m pip install 'android-device-control[mcp]'"
|
|
58
|
+
if __package__
|
|
59
|
+
else "python -m pip install -r requirements-mcp.txt"
|
|
60
|
+
)
|
|
61
|
+
raise phone.PhoneError(f"install the optional MCP SDK with {install_command}") from exc
|
|
62
|
+
|
|
63
|
+
server = FastMCP("Android Control")
|
|
64
|
+
read_only = ToolAnnotations(readOnlyHint=True)
|
|
65
|
+
|
|
66
|
+
@server.tool(annotations=read_only)
|
|
67
|
+
def list_devices() -> list[dict[str, str]]:
|
|
68
|
+
"""List connected, ADB-authorized devices by serial and state within the server scope."""
|
|
69
|
+
return authorized_devices(device)
|
|
70
|
+
|
|
71
|
+
@server.tool(annotations=read_only)
|
|
72
|
+
def foreground(serial: str | None = None) -> str:
|
|
73
|
+
"""Read the focused Android package and activity. Supply a serial on an unscoped server."""
|
|
74
|
+
return phone.foreground(require_device(serial, device))
|
|
75
|
+
|
|
76
|
+
@server.tool(annotations=read_only)
|
|
77
|
+
def snapshot(serial: str | None = None) -> str:
|
|
78
|
+
"""Read the guarded UI summary. Supply a serial on an unscoped server."""
|
|
79
|
+
target = require_device(serial, device)
|
|
80
|
+
root, _ = phone.stable_tree(target)
|
|
81
|
+
lines, _ = phone.build_refs(root)
|
|
82
|
+
return "\n".join(lines)
|
|
83
|
+
|
|
84
|
+
if allow_input:
|
|
85
|
+
@server.tool(annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=True))
|
|
86
|
+
def tap_label(label: str) -> str:
|
|
87
|
+
"""Tap one exact accessibility label on the configured device. Inspect the result separately."""
|
|
88
|
+
return phone.tap_label(require_device(None, device), label)
|
|
89
|
+
|
|
90
|
+
return server
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def main(argv: list[str] | None = None) -> int:
|
|
94
|
+
parser = argparse.ArgumentParser(description=__doc__)
|
|
95
|
+
parser.add_argument("--device", help="scope the server to one explicit ADB serial")
|
|
96
|
+
parser.add_argument("--allow-input", action="store_true", help="enable exact-label taps on --device")
|
|
97
|
+
args = parser.parse_args(argv)
|
|
98
|
+
try:
|
|
99
|
+
server = create_server(args.device, allow_input=args.allow_input)
|
|
100
|
+
except phone.PhoneError as exc:
|
|
101
|
+
parser.error(str(exc))
|
|
102
|
+
server.run(transport="stdio")
|
|
103
|
+
return 0
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
if __name__ == "__main__":
|
|
107
|
+
raise SystemExit(main())
|