io.github.Clousd-Android/clousd-mcp

The account: plan and phones, money left, what is about to renew, and warnings. Check it before starting phones or long work, and tell the user every warning in plain words with the top_up link.

Do one thing on the phone yourself, then wait until the screen settles. Prefer element numbers from observe over coordinates; tap_text taps the element whose text contains `text`. Typing goes into the focused field (tap it first) and works in any language. "the screen did not change" means the action probably missed - observe again. Read without touching the screen: installed (apps), notifications (the shade), clipboard, app_info (version, installer, running), crashes (recent app crashes and ANRs), health (running, booted, network exit, last check). For a whole goal, prefer run: it does all the steps for you.

Reply to a run that waits for you: answer its question with text, or allow / decline the step it asks permission for. If the question is something only the user knows, ask the user first. The run goes on at once.

The user's own apps on Clousd: APKs they uploaded, kept in their private storage. Upload an APK once (op=upload), then install it by id on any of their phones (op=install), as often as needed. Clousd has no catalog of other people's apps - for apps from Google Play, open the Play Store on the phone. Every APK is checked on upload (a real Android app, 64-bit ARM code, no root or system tools) and refused with the reason otherwise. To have an app on the phone before a task, pass its id in run(files=...).

Saved logins of the account: package, name and which fields are set (username, email, password, phone, totp...). Values are never shown. Pass one to run as "package/name"; the agent types it on the phone without seeing it. The user adds logins in the dashboard (Tasks → Sign-in) - do not ask them for passwords in the chat.

Phones this key can use. op=list: name, label (the name people see in the dashboard, e.g. "Phone #3"), number, state (running / stopped / starting), Android version and network exit. Every tool takes the name, the label or the number. op=start / op=stop / op=restart with device: start a stopped phone (one to three minutes until it has booted), stop one (it keeps its apps and data) or restart it. op=reset with device: back to a fresh state - apps and data wiped, same Android version; works whether the phone runs or is stopped. Ask the user before reset. op=rename with device and label: give a phone a name (empty = back to "Phone #N"). op=delete with device: the phone moves to Trash for 14 days - stopped, not billed, apps and data kept - and op=restore brings it back (stopped). forever=true deletes it with all its data at once and cannot be undone: only when the user says so. op=trash: what is in Trash (name, label, android, deleted_at, purge_at, reason). op=restore with device: back from Trash (the name or label as shown by op=trash).

The user's Library on Clousd: every file they want on their phones lives here once (photos, videos, documents, apps) and is used by id. op=list shows it; op=upload adds a local file and returns its id; op=send copies files to phones right away (photos and videos into the gallery as if taken there, documents into Downloads, apks installed). For a task that needs a file, prefer run(files=...) - the file is placed on the phone before the first step.

Look at the phone yourself: a fresh screenshot, the app on screen and (with_text) every labelled or tappable element with a number. Act on an element by its number (act element=N); coordinates, when needed, are in this image's pixels.

Give phones a task. Clousd's agent looks at the screen, taps and types until the goal is reached, and finishes with an answer. Several devices = the same task on each, all at once (one run per phone under one parent). Returns the run with its status; if it is still going, follow it with run_status. A run in mode=ask may stop with waiting_for: reply with answer. Logins: never ask the user for passwords - pass credentials; their values are typed on the phone without you or the model seeing them. A task that needs a file (post this photo, fill this form from this PDF, install this app): upload it once with the library tool and pass its id in files - do not push files by hand each time.

Follow a run. op=status: status (queued, running, paused = waits for an answer, completed, failed, cancelled), the answer or error, the last steps, per-device results for a run on several phones, and a replay link for the user. op=list: recent runs of this key. op=cancel: stop it. op=message: tell the running agent something (it reads it before its next step).

Tasks that run by themselves. op=list: id, name, task, phones, at, days, tz, enabled and the runs it started last time. op=add: run `task` on `devices` at `at` on `days`, or every hour (every=hour), or only on demand (trigger=api); each firing starts runs like the run tool. op=run: start it now. op=toggle: pause or resume. op=delete: remove it.