Shipvo is an MCP server published by io.github.shipvo, hosted at sim.shipvo.dev. When last checked on 2026-11-21 it was working: it answers and lists its tools. It declares 110 tools, including a11y_audit, a2ui_actions, a2ui_open, a2ui_send, app_activity.
Open a React Native app in a simulated phone: read the screen, tap, type, set device state.
Nothing else in the archive shares these values.
Squares are this server's values; dots are other servers sharing them. A shared address or publisher is a lead, not proof of a common operator.
Inferred from the host name and headers: what a server runs on, not who runs it.
Check the current screen for controls TalkBack and VoiceOver users cannot use. Lists every button, link, field or other control with no accessible name (missing_label) and every tap target under the platform minimum (small_target: 48 dp wide or high on the Android style, 44 pt on the iPhone style). Each issue has ref, role, code and message. Fails with sizes_unavailable when the simulator cannot report sizes.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "a11y_audit",
"description": "Check the current screen for controls TalkBack and VoiceOver users cannot use. Lists every button, link, field or other control with no accessible name (missing_label) and every tap target under the platform minimum (small_target: 48 dp wide or high on the Android style, 44 pt on the iPhone style). Each issue has ref, role, code and message. Fails with sizes_unavailable when the simulator cannot report sizes.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}What an A2UI session sent to the agent: the action messages from buttons the person pressed, with their context read from the data model. Pass `since` (the `next` of the last call) to get only newer ones.
| Parameter | Type | Description |
|---|---|---|
| since | integer | Return messages after this position (the `next` of an earlier call) |
| session * | string | Session from open_app |
{
"name": "a2ui_actions",
"description": "What an A2UI session sent to the agent: the action messages from buttons the person pressed, with their context read from the data model. Pass `since` (the `next` of the last call) to get only newer ones.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"since": {
"type": "integer",
"minimum": 0,
"description": "Return messages after this position (the `next` of an earlier call)"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Open A2UI v1.0 messages as a screen on a phone and return it as a tree. The messages are the agent's own: createSurface, updateComponents, updateDataModel, deleteSurface. Needs no app. Then use screen, tap, type and screenshot on the session like any app, a2ui_send to change the screen and a2ui_actions to read what the person did.
| Parameter | Type | Description |
|---|---|---|
| model | string | Phone model from phone_models, for example 'iPhone 16 Pro' (default: Pixel 8) |
| session | string | Session name (default: generated) |
| messages * | array | A2UI messages, each { version: "1.0", createSurface | updateComponents | updateDataModel | deleteSurface: {...} } |
{
"name": "a2ui_open",
"description": "Open A2UI v1.0 messages as a screen on a phone and return it as a tree. The messages are the agent's own: createSurface, updateComponents, updateDataModel, deleteSurface. Needs no app. Then use screen, tap, type and screenshot on the session like any app, a2ui_send to change the screen and a2ui_actions to read what the person did.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"messages"
],
"properties": {
"model": {
"type": "string",
"description": "Phone model from phone_models, for example 'iPhone 16 Pro' (default: Pixel 8)"
},
"session": {
"type": "string",
"description": "Session name (default: generated)"
},
"messages": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"description": "A2UI messages, each { version: \"1.0\", createSurface | updateComponents | updateDataModel | deleteSurface: {...} }"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Send more A2UI messages to a session from a2ui_open and return the screen after them. The result says how many were applied and lists each refused message with the reason.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
| messages * | array | A2UI messages to apply in order |
{
"name": "a2ui_send",
"description": "Send more A2UI messages to a session from a2ui_open and return the screen after them. The result says how many were applied and lists each refused message with the reason.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"messages"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
},
"messages": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"description": "A2UI messages to apply in order"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}What was built and changed on the phone: for each app made with create_app, its versions with a plain line for what changed in each (added, removed or changed screens, actions and data), its http data sources and how often each refreshes, and its events (create, update, action, data refresh). Pass id for one app. Fails with not_installed.
| Parameter | Type | Description |
|---|---|---|
| id | string | App id; omit for every app |
| limit | integer | Most recent events per app (default 50) |
| session * | string | Session from open_app |
{
"name": "app_activity",
"description": "What was built and changed on the phone: for each app made with create_app, its versions with a plain line for what changed in each (added, removed or changed screens, actions and data), its http data sources and how often each refreshes, and its events (create, update, action, data refresh). Pass id for one app. Fails with not_installed.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"id": {
"type": "string",
"description": "App id; omit for every app"
},
"limit": {
"type": "integer",
"maximum": 200,
"minimum": 1,
"description": "Most recent events per app (default 50)"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Apply the ready release: the app restarts on the new bundle, like restart. After 3 boots that throw, the phone goes back to the old release and the state is reverted with reason crash_loop. Fails with not_ready unless the state is ready. Simulated; logged in device_log.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "apply_update",
"description": "Apply the ready release: the app restarts on the new bundle, like restart. After 3 boots that throw, the phone goes back to the old release and the state is reverted with reason crash_loop. Fails with not_ready unless the state is ready. Simulated; logged in device_log.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Approve a held promote so it goes live. The proposer cannot approve it, and an agent cannot approve an agent's proposal: that is refused with rule self_approval. Ask the owner to approve in that case. Both outcomes are audited.
| Parameter | Type | Description |
|---|---|---|
| id * | string | Hold id from approvals_list |
| app * | string |
{
"name": "approval_approve",
"description": "Approve a held promote so it goes live. The proposer cannot approve it, and an agent cannot approve an agent's proposal: that is refused with rule self_approval. Ask the owner to approve in that case. Both outcomes are audited.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app",
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Hold id from approvals_list"
},
"app": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true
}
}List what waits for an owner. approvals: promotes held above the app's policy band (hold id, release, band, proposer, age). challenges: owner commands waiting for the owner to approve in the admin (id, command, plan, expiry, approval_url). Agents cannot approve either. Needs an owner token.
| Parameter | Type | Description |
|---|---|---|
| app * | string |
{
"name": "approvals_list",
"description": "List what waits for an owner. approvals: promotes held above the app's policy band (hold id, release, band, proposer, age). challenges: owner commands waiting for the owner to approve in the admin (id, command, plan, expiry, approval_url). Agents cannot approve either. Needs an owner token.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app"
],
"properties": {
"app": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Lay out an installed app on the home screen: pinned (first), hidden (not on the home screen, still opens with switch_app), position (0 first) and schedule (days, from, to: the app shows only then, e.g. a weekly planner Monday to Friday 08:00-18:00 and weekend plans on Saturday). Leave days out or pass an empty list for every day. Add timezone (an IANA name such as Europe/Berlin) to read the window in that zone. Pass schedule: null to always show. Fails with not_installed, bad_placement or bad_timezone. The home screen text says which apps are showing and why one is not. Logged in device_log.
| Parameter | Type | Description |
|---|---|---|
| id * | string | App id |
| hidden | boolean | |
| pinned | boolean | |
| session * | string | Session from open_app |
| position | any | |
| schedule | any |
{
"name": "arrange_apps",
"description": "Lay out an installed app on the home screen: pinned (first), hidden (not on the home screen, still opens with switch_app), position (0 first) and schedule (days, from, to: the app shows only then, e.g. a weekly planner Monday to Friday 08:00-18:00 and weekend plans on Saturday). Leave days out or pass an empty list for every day. Add timezone (an IANA name such as Europe/Berlin) to read the window in that zone. Pass schedule: null to always show. Fails with not_installed, bad_placement or bad_timezone. The home screen text says which apps are showing and why one is not. Logged in device_log.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"id"
],
"properties": {
"id": {
"type": "string",
"description": "App id"
},
"hidden": {
"type": "boolean"
},
"pinned": {
"type": "boolean"
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"position": {
"anyOf": [
{
"type": "integer",
"maximum": 99,
"minimum": 0
},
{
"type": "null"
}
]
},
"schedule": {
"anyOf": [
{
"type": "object",
"properties": {
"to": {
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
},
"days": {
"type": "array",
"items": {
"enum": [
"sun",
"mon",
"tue",
"wed",
"thu",
"fri",
"sat"
],
"type": "string"
}
},
"from": {
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
},
"timezone": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Attach to the phone of a live `shipvo run` in this project (read from .shipvo/run.json) and return its screen. The person sees every action in their browser. Same as open_app with attach: 'always', without needing the app id.
| Parameter | Type | Description |
|---|---|---|
| app | string | App id; default: the app of the live run |
| session | string | Session name (default: generated) |
{
"name": "attach_session",
"description": "Attach to the phone of a live `shipvo run` in this project (read from .shipvo/run.json) and return its screen. The person sees every action in their browser. Same as open_app with attach: 'always', without needing the app id.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"app": {
"type": "string",
"description": "App id; default: the app of the live run"
},
"session": {
"type": "string",
"description": "Session name (default: generated)"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Read the app's release audit log, newest first: who (actor) did what (action) to which release (subject) and when (at). Read-only. Needs an owner token.
| Parameter | Type | Description |
|---|---|---|
| app * | string | |
| limit | integer | Rows to return (default 50, max 200; values outside are clamped) |
| action | string | Only rows with this action, for example rollback |
{
"name": "audit_log",
"description": "Read the app's release audit log, newest first: who (actor) did what (action) to which release (subject) and when (at). Read-only. Needs an owner token.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app"
],
"properties": {
"app": {
"type": "string"
},
"limit": {
"type": "integer",
"description": "Rows to return (default 50, max 200; values outside are clamped)"
},
"action": {
"type": "string",
"description": "Only rows with this action, for example rollback"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Go back one screen. The result starts with 'Change: none | content changed | new screen | scrolled'.
| Parameter | Type | Description |
|---|---|---|
| settle | boolean | Wait until the screen stops changing (two equal reads 100 ms apart), up to timeout_ms. Use after any action that starts work. A slow result can still follow a pause, so prefer wait_for when you know the expected text. |
| compact | boolean | When the change is 'content changed', the result lists only the lines that changed (+ added, - removed, ~ changed), with refs as on the full screen. This is the default. Pass false to get the whole screen. |
| session * | string | Session from open_app |
| wait_for | object | Use after any action that starts work. Wait until this appears (a ref, a text, or role+name), or disappears with gone: true. The result says Waited: matched or timed out. |
| timeout_ms | integer | How long wait_for and settle may take, in ms (default 2000) |
{
"name": "back",
"description": "Go back one screen. The result starts with 'Change: none | content changed | new screen | scrolled'.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"settle": {
"type": "boolean",
"description": "Wait until the screen stops changing (two equal reads 100 ms apart), up to timeout_ms. Use after any action that starts work. A slow result can still follow a pause, so prefer wait_for when you know the expected text."
},
"compact": {
"type": "boolean",
"description": "When the change is 'content changed', the result lists only the lines that changed (+ added, - removed, ~ changed), with refs as on the full screen. This is the default. Pass false to get the whole screen."
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"wait_for": {
"type": "object",
"properties": {
"ref": {
"type": "string",
"pattern": "^(?:p\\d+|f\\d+)?e\\d+$"
},
"gone": {
"type": "boolean"
},
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"text": {
"type": "string"
}
},
"description": "Use after any action that starts work. Wait until this appears (a ref, a text, or role+name), or disappears with gone: true. The result says Waited: matched or timed out.",
"additionalProperties": false
},
"timeout_ms": {
"type": "integer",
"maximum": 30000,
"minimum": 0,
"description": "How long wait_for and settle may take, in ms (default 2000)"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Back up the whole phone as one JSON object, on Android and iOS: every app you built with its spec, data, settings, home-screen place and permission answers; every Store app with its listing and permission answers; the system settings; and the clipboard. Saved keys in the vault are never in it. Pass the object to restore_phone on this phone or another. Changes nothing.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "backup_phone",
"description": "Back up the whole phone as one JSON object, on Android and iOS: every app you built with its spec, data, settings, home-screen place and permission answers; every Store app with its listing and permission answers; the system settings; and the clipboard. Saved keys in the vault are never in it. Pass the object to restore_phone on this phone or another. Changes nothing.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Go back one page in the phone browser. Returns the snapshot.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "browser_back",
"description": "Go back one page in the phone browser. Returns the snapshot.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Click an element of the phone browser's page by ref from browser_snapshot. Returns the new snapshot.
| Parameter | Type | Description |
|---|---|---|
| ref * | string | Element ref from browser_snapshot, e.g. e12 or f1e12 |
| session * | string | Session from open_app |
{
"name": "browser_click",
"description": "Click an element of the phone browser's page by ref from browser_snapshot. Returns the new snapshot.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"ref"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^(?:f\\d+)?e\\d+$",
"description": "Element ref from browser_snapshot, e.g. e12 or f1e12"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}
}Close a tab of the phone browser by its index from browser_tabs. Returns the remaining tabs.
| Parameter | Type | Description |
|---|---|---|
| index * | integer | |
| session * | string | Session from open_app |
{
"name": "browser_close_tab",
"description": "Close a tab of the phone browser by its index from browser_tabs. Returns the remaining tabs.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"index"
],
"properties": {
"index": {
"type": "integer",
"minimum": 0
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Open a web page in the phone's Chromium (separate from the app) and return its snapshot. Private hosts (localhost, 127.x, 10.x, 192.168.x, 169.254.x, CGNAT, .local, .internal) are refused with host_not_allowed unless you opt in.
| Parameter | Type | Description |
|---|---|---|
| url * | string | http or https URL |
| session * | string | Session from open_app |
| allow_hosts | array | Allow only these host names |
| allow_private | boolean | Allow every private host |
{
"name": "browser_open",
"description": "Open a web page in the phone's Chromium (separate from the app) and return its snapshot. Private hosts (localhost, 127.x, 10.x, 192.168.x, 169.254.x, CGNAT, .local, .internal) are refused with host_not_allowed unless you opt in.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"url"
],
"properties": {
"url": {
"type": "string",
"description": "http or https URL"
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"allow_hosts": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allow only these host names"
},
"allow_private": {
"type": "boolean",
"description": "Allow every private host"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}
}A PNG of the phone browser's page.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "browser_screenshot",
"description": "A PNG of the phone browser's page.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Scroll the phone browser's page by dy CSS pixels (positive is down) and dx (positive is right). Returns the snapshot.
| Parameter | Type | Description |
|---|---|---|
| dx | number | |
| dy | number | Default 400 |
| session * | string | Session from open_app |
{
"name": "browser_scroll",
"description": "Scroll the phone browser's page by dy CSS pixels (positive is down) and dx (positive is right). Returns the snapshot.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"dx": {
"type": "number",
"maximum": 5000,
"minimum": -5000
},
"dy": {
"type": "number",
"maximum": 5000,
"minimum": -5000,
"description": "Default 400"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}The phone browser's page as an accessibility tree with refs, marked source "web" (untrusted).
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "browser_snapshot",
"description": "The phone browser's page as an accessibility tree with refs, marked source \"web\" (untrusted).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}List the phone browser's tabs (index, url, title, which is active). Titles are untrusted web content.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "browser_tabs",
"description": "List the phone browser's tabs (index, url, title, which is active). Titles are untrusted web content.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Type into a field of the phone browser's page by ref (replaces its content). Returns the new snapshot.
| Parameter | Type | Description |
|---|---|---|
| ref * | string | Element ref from browser_snapshot, e.g. e12 or f1e12 |
| text * | string | |
| enter | boolean | Press Enter afterwards |
| session * | string | Session from open_app |
{
"name": "browser_type",
"description": "Type into a field of the phone browser's page by ref (replaces its content). Returns the new snapshot.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"ref",
"text"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^(?:f\\d+)?e\\d+$",
"description": "Element ref from browser_snapshot, e.g. e12 or f1e12"
},
"text": {
"type": "string"
},
"enter": {
"type": "boolean",
"description": "Press Enter afterwards"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}
}Wait until text appears in the phone browser's page, or is gone (gone: true). Fails with code timeout. Returns the snapshot.
| Parameter | Type | Description |
|---|---|---|
| gone | boolean | |
| text * | string | |
| session * | string | Session from open_app |
| timeout_ms | integer | Default 5000 |
{
"name": "browser_wait_for",
"description": "Wait until text appears in the phone browser's page, or is gone (gone: true). Fails with code timeout. Returns the snapshot.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"text"
],
"properties": {
"gone": {
"type": "boolean"
},
"text": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"timeout_ms": {
"type": "integer",
"maximum": 30000,
"minimum": 100,
"description": "Default 5000"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Cancel a reminder by id. Returns whether it existed.
| Parameter | Type | Description |
|---|---|---|
| id * | string | |
| session * | string | Session from open_app |
{
"name": "cancel_reminder",
"description": "Cancel a reminder by id. Returns whether it existed.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"id"
],
"properties": {
"id": {
"type": "string"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Ask the update source for a newer release: checks its signature and hash and downloads it. Ends in ready, or idle with reason verify_failed or download_failed (the release is never applied). Fails with no_update when nothing newer exists or no source is set. Simulated; each state change is logged in device_log.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "check_for_update",
"description": "Ask the update source for a newer release: checks its signature and hash and downloads it. Ends in ready, or idle with reason verify_failed or download_failed (the release is never applied). Fails with no_update when nothing newer exists or no source is set. Simulated; each state change is logged in device_log.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Remove an app's schedule so pin and hide decide again whether it shows. Fails with not_installed.
| Parameter | Type | Description |
|---|---|---|
| id * | string | App id |
| session * | string | Session from open_app |
{
"name": "clear_schedule",
"description": "Remove an app's schedule so pin and hide decide again whether it shows. Fails with not_installed.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"id"
],
"properties": {
"id": {
"type": "string",
"description": "App id"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Stop waking an assistant by webhook. Returns whether one was registered.
| Parameter | Type | Description |
|---|---|---|
| name * | string | |
| session * | string | Session from open_app |
{
"name": "clear_wakeup",
"description": "Stop waking an assistant by webhook. Returns whether one was registered.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"name"
],
"properties": {
"name": {
"type": "string"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Close the notification shade, Notification Center or Control Center (swipe up).
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "close_panels",
"description": "Close the notification shade, Notification Center or Control Center (swipe up).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Describe an app and it appears on the phone. Pass an app spec (JSON, shipvo.app/v0: data, actions, screens). The spec is checked first: every problem comes back with its path and a fix, and nothing is installed until it is valid. A valid spec is started, gets an icon on the home screen, and opens (pass open: false to stay where you are). Every control is labelled, so tap, type, scroll and screen work on it like any app, and each action can be run by name with run_app_action. Fails with invalid_spec, bad_app_id or already_installed. Logged in device_log as a real create.
| Parameter | Type | Description |
|---|---|---|
| id * | string | App id: lowercase letters, digits and dashes, up to 40 |
| name | string | Name under the icon. Default: app.name in the spec |
| open | boolean | Open the app right away (default true) |
| spec * | object | The app spec (shipvo.app/v0) |
| style | string | Look of the app. Default android |
| session * | string | Session from open_app |
{
"name": "create_app",
"description": "Describe an app and it appears on the phone. Pass an app spec (JSON, shipvo.app/v0: data, actions, screens). The spec is checked first: every problem comes back with its path and a fix, and nothing is installed until it is valid. A valid spec is started, gets an icon on the home screen, and opens (pass open: false to stay where you are). Every control is labelled, so tap, type, scroll and screen work on it like any app, and each action can be run by name with run_app_action. Fails with invalid_spec, bad_app_id or already_installed. Logged in device_log as a real create.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"id",
"spec"
],
"properties": {
"id": {
"type": "string",
"description": "App id: lowercase letters, digits and dashes, up to 40"
},
"name": {
"type": "string",
"description": "Name under the icon. Default: app.name in the spec"
},
"open": {
"type": "boolean",
"description": "Open the app right away (default true)"
},
"spec": {
"type": "object",
"description": "The app spec (shipvo.app/v0)",
"additionalProperties": {}
},
"style": {
"enum": [
"android",
"ios"
],
"type": "string",
"description": "Look of the app. Default android"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}What the app did with the device in this session: permission prompts and answers, location reads, scans, fingerprint checks, payments, notifications, shares.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "device_log",
"description": "What the app did with the device in this session: permission prompts and answers, location reads, scans, fingerprint checks, payments, notifications, shares.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Put the simulated phone back to a known state (permissions undetermined, default location, nothing in front of the camera, log cleared), optionally with a new profile.
| Parameter | Type | Description |
|---|---|---|
| api | number | |
| session * | string | Session from open_app |
| platform | string | one of ["android","ios"] |
{
"name": "device_reset",
"description": "Put the simulated phone back to a known state (permissions undetermined, default location, nothing in front of the camera, log cleared), optionally with a new profile.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"api": {
"type": "number"
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"platform": {
"enum": [
"android",
"ios"
],
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Swipe a notification away in the open shade (newest if no id), or Clear all with all: true.
| Parameter | Type | Description |
|---|---|---|
| id | string | |
| all | boolean | |
| session * | string | Session from open_app |
{
"name": "dismiss_notification",
"description": "Swipe a notification away in the open shade (newest if no id), or Clear all with all: true.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"id": {
"type": "string"
},
"all": {
"type": "boolean"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Close the session and get a report: steps taken, and the orders the app sent to its backend during the session.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "end_session",
"description": "Close the session and get a report: steps taken, and the orders the app sent to its backend during the session.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true
}
}Copy the spec apps (made with create_app) out of the phone. Returns JSON with, per app, id, name, style (android or ios), spec, data (what was entered into its collections), settings and its home-screen layout (placement: pinned, hidden, position, schedule) when it has one. Pass ids to export only some. Vault secrets and keys are never included. Give the result to import_phone_apps on another phone to recreate the apps. Fails with not_installed (an id is not a spec app).
| Parameter | Type | Description |
|---|---|---|
| ids | array | App ids to export. Default: every spec app |
| session * | string | Session from open_app |
{
"name": "export_phone_apps",
"description": "Copy the spec apps (made with create_app) out of the phone. Returns JSON with, per app, id, name, style (android or ios), spec, data (what was entered into its collections), settings and its home-screen layout (placement: pinned, hidden, position, schedule) when it has one. Pass ids to export only some. Vault secrets and keys are never included. Give the result to import_phone_apps on another phone to recreate the apps. Fails with not_installed (an id is not a spec app).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "App ids to export. Default: every spec app"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Turn the steps taken in this session (tap, type, scroll, back, set_device) into a @shipvo/test script and return its source. Read-only. Targets are named by their visible text; ambiguous ones become TODO comments and password fields use an environment variable instead of the typed value.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "export_test",
"description": "Turn the steps taken in this session (tap, type, scroll, back, set_device) into a @shipvo/test script and return its source. Read-only. Targets are named by their visible text; ambiguous ones become TODO comments and password fields use an environment variable instead of the typed value.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Search the Store by need, for example "split bills". Matches the query against app name, description and tags (case-insensitive, word based) and filters by country, language and currency when an app declares them; apps that declare nothing for a filter still match. Returns up to limit apps (default 10, max 25) with id, name, one-line description, version and whether it is installed, best match first. An empty list means nothing matched. Fails with store_unreachable when the marketplace cannot be reached (nothing is guessed). Install a result on the simulator with install_app, or on the person's own phone with request_app_install. Logged in device_log as simulated.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Most results to return (default 10, max 25) |
| query * | string | What the person needs, for example "split bills" |
| country | string | Country code, for example FR |
| session * | string | Session from open_app |
| currency | string | Currency code, for example EUR |
| language | string | Language code, for example fr |
{
"name": "find_apps",
"description": "Search the Store by need, for example \"split bills\". Matches the query against app name, description and tags (case-insensitive, word based) and filters by country, language and currency when an app declares them; apps that declare nothing for a filter still match. Returns up to limit apps (default 10, max 25) with id, name, one-line description, version and whether it is installed, best match first. An empty list means nothing matched. Fails with store_unreachable when the marketplace cannot be reached (nothing is guessed). Install a result on the simulator with install_app, or on the person's own phone with request_app_install. Logged in device_log as simulated.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"query"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 25,
"minimum": 1,
"description": "Most results to return (default 10, max 25)"
},
"query": {
"type": "string",
"description": "What the person needs, for example \"split bills\""
},
"country": {
"type": "string",
"description": "Country code, for example FR"
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"currency": {
"type": "string",
"description": "Currency code, for example EUR"
},
"language": {
"type": "string",
"description": "Language code, for example fr"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}The text on the phone's clipboard, the same one apps copy to and paste from on Android and iOS.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "get_clipboard",
"description": "The text on the phone's clipboard, the same one apps copy to and paste from on Android and iOS.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}The phone's Wi-Fi, mobile data and airplane mode switches, and the network every app sees from them: online and type (wifi, cellular or none). Android and iOS.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "get_connectivity",
"description": "The phone's Wi-Fi, mobile data and airplane mode switches, and the network every app sees from them: online and type (wifi, cellular or none). Android and iOS.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Read the phone's current network profile name (online until set_network_profile or phone.json changes it).
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "get_network_profile",
"description": "Read the phone's current network profile name (online until set_network_profile or phone.json changes it).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Read the phone's system settings from the Settings screen: dark_mode, font_size (small, default, large, largest), bold_text, reduce_motion, language (en, fr, ar) and rtl. Returns each setting and the screen as rows.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "get_settings",
"description": "Read the phone's system settings from the Settings screen: dark_mode, font_size (small, default, large, largest), bold_text, reduce_motion, language (en, fr, ar) and rtl. Returns each setting and the screen as rows.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}The phone's OTA update state: idle, checking, downloading, ready, applied or reverted, the running release, the held release, and the last reason (verify_failed, download_failed or crash_loop). Simulated and logged in device_log.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "get_update_state",
"description": "The phone's OTA update state: idle, checking, downloading, ready, applied or reverted, the running release, the held release, and the last reason (verify_failed, download_failed or crash_loop). Simulated and logged in device_log.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Hide an installed app from the home screen and the app list, or show it again with hidden: false. The app keeps its data and still opens with switch_app and run_app_action. Works for Store apps and apps made with create_app, and survives update_app. Fails with not_installed. Logged in device_log.
| Parameter | Type | Description |
|---|---|---|
| id * | string | Installed app id |
| hidden * | boolean | true to hide, false to show |
| session * | string | Session from open_app |
{
"name": "hide_app",
"description": "Hide an installed app from the home screen and the app list, or show it again with hidden: false. The app keeps its data and still opens with switch_app and run_app_action. Works for Store apps and apps made with create_app, and survives update_app. Fails with not_installed. Logged in device_log.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"id",
"hidden"
],
"properties": {
"id": {
"type": "string",
"description": "Installed app id"
},
"hidden": {
"type": "boolean",
"description": "true to hide, false to show"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Put apps from export_phone_apps on this phone, with their data, settings and home-screen layout. Every spec is checked first: all problems come back with their path (for example apps[1].spec.screens) and nothing is installed unless all are valid. An id that is already installed fails with already_installed unless replace is true. Android and iOS styles are kept. Fails with invalid_spec or already_installed.
| Parameter | Type | Description |
|---|---|---|
| apps * | array | The apps array from export_phone_apps |
| replace | boolean | Overwrite apps with the same id (default false) |
| session * | string | Session from open_app |
{
"name": "import_phone_apps",
"description": "Put apps from export_phone_apps on this phone, with their data, settings and home-screen layout. Every spec is checked first: all problems come back with their path (for example apps[1].spec.screens) and nothing is installed unless all are valid. An id that is already installed fails with already_installed unless replace is true. Android and iOS styles are kept. Fails with invalid_spec or already_installed.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"apps"
],
"properties": {
"apps": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"description": "The apps array from export_phone_apps"
},
"replace": {
"type": "boolean",
"description": "Overwrite apps with the same id (default false)"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Empty this session's private inbox. Returns how many messages were removed.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "inbox_clear",
"description": "Empty this session's private inbox. Returns how many messages were removed.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Read this session's private inbox: its address and every message, oldest first, each with from, subject, text, codes (4 to 8 digits) and links. Reading changes nothing: a second call returns the same result.
| Parameter | Type | Description |
|---|---|---|
| from | string | Only mail whose sender contains this |
| session * | string | Session from open_app |
| subject | string | Only mail whose subject contains this |
{
"name": "inbox_read",
"description": "Read this session's private inbox: its address and every message, oldest first, each with from, subject, text, codes (4 to 8 digits) and links. Reading changes nothing: a second call returns the same result.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"from": {
"type": "string",
"description": "Only mail whose sender contains this"
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"subject": {
"type": "string",
"description": "Only mail whose subject contains this"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Show the Assistant Inbox of this phone live in the chat: every message and task between assistants, who you are, and what waits for you. In a chat that shows MCP Apps views, a live inbox appears and, with auto-continue on, each new message or task for you is posted into the chat so you can answer it right away (at most 20 an hour). Install the Assistant Inbox first (create_app, id inbox). Changes nothing.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "inbox_view",
"description": "Show the Assistant Inbox of this phone live in the chat: every message and task between assistants, who you are, and what waits for you. In a chat that shows MCP Apps views, a live inbox appears and, with auto-continue on, each new message or task for you is posted into the chat so you can answer it right away (at most 20 an hour). Install the Assistant Inbox first (create_app, id inbox). Changes nothing.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Wait for mail in this session's private inbox (its address is in the result; type it into the app's email field). Returns the first message that matches, already there or arriving within timeout_ms: from, subject, text, the 4 to 8 digit codes and the links in it. Use it to finish an emailed code or magic-link sign-in. Fails with inbox_timeout when nothing matches in time. Only this session can read this inbox; mail is kept in memory and removed when the session ends.
| Parameter | Type | Description |
|---|---|---|
| from | string | Only mail whose sender contains this |
| session * | string | Session from open_app |
| subject | string | Only mail whose subject contains this (not case sensitive) |
| timeout_ms | integer | How long to wait, in ms (default 10000) |
{
"name": "inbox_wait",
"description": "Wait for mail in this session's private inbox (its address is in the result; type it into the app's email field). Returns the first message that matches, already there or arriving within timeout_ms: from, subject, text, the 4 to 8 digit codes and the links in it. Use it to finish an emailed code or magic-link sign-in. Fails with inbox_timeout when nothing matches in time. Only this session can read this inbox; mail is kept in memory and removed when the session ends.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"from": {
"type": "string",
"description": "Only mail whose sender contains this"
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"subject": {
"type": "string",
"description": "Only mail whose subject contains this (not case sensitive)"
},
"timeout_ms": {
"type": "integer",
"maximum": 25000,
"minimum": 0,
"description": "How long to wait, in ms (default 10000)"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Install a Store app on the phone, as tapping Install in the Store screen does. The app icon appears on the home screen. Fails with unknown_app (not in the Store) or already_installed. If the marketplace is unreachable the phone's own Store list is used. Logged in device_log as simulated: nothing real is installed.
| Parameter | Type | Description |
|---|---|---|
| id * | string | App id from list_store_apps |
| session * | string | Session from open_app |
{
"name": "install_app",
"description": "Install a Store app on the phone, as tapping Install in the Store screen does. The app icon appears on the home screen. Fails with unknown_app (not in the Store) or already_installed. If the marketplace is unreachable the phone's own Store list is used. Logged in device_log as simulated: nothing real is installed.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"id"
],
"properties": {
"id": {
"type": "string",
"description": "App id from list_store_apps"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Read a slow job started by publish_preview or upload_build. Returns { status: running | done | failed, job } with the result when done or a typed error { code, error } when failed. Pass wait_ms to wait for it (long poll, default 0, max 55000). A job id from another key is not found. Jobs are kept for 15 minutes after they finish.
| Parameter | Type | Description |
|---|---|---|
| job * | string | Job id from a tool that returned status running |
| wait_ms | integer | How long to wait while it is still running (default 0) |
{
"name": "job_status",
"description": "Read a slow job started by publish_preview or upload_build. Returns { status: running | done | failed, job } with the result when done or a typed error { code, error } when failed. Pass wait_ms to wait for it (long poll, default 0, max 55000). A job id from another key is not found. Jobs are kept for 15 minutes after they finish.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"job"
],
"properties": {
"job": {
"type": "string",
"description": "Job id from a tool that returned status running"
},
"wait_ms": {
"type": "integer",
"maximum": 55000,
"minimum": 0,
"description": "How long to wait while it is still running (default 0)"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Swipe the app's card away in the app switcher (call open_recents first). The app is killed: the next resume_app is a cold start, with storage kept. Fails with recents_not_open otherwise.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "kill_app",
"description": "Swipe the app's card away in the app switcher (call open_recents first). The app is killed: the next resume_app is a cold start, with storage kept. Fails with recents_not_open otherwise.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Apps this server can open, with what each one does. Optional query filters by name, description or category (e.g. 'shop', 'douala').
| Parameter | Type | Description |
|---|---|---|
| query | string |
{
"name": "list_apps",
"description": "Apps this server can open, with what each one does. Optional query filters by name, description or category (e.g. 'shop', 'douala').",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"query": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}List the apps installed on the person's persistent phone, the same in every chat and assistant. Needs PN_ASSISTANT_TOKEN.
No parameters.
{
"name": "list_installed_apps",
"description": "List the apps installed on the person's persistent phone, the same in every chat and assistant. Needs PN_ASSISTANT_TOKEN.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {}
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}The reminders waiting on the phone (id, title, next time, repeat) and the last ones that fired with whether each was delivered.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "list_reminders",
"description": "The reminders waiting on the phone (id, title, next time, repeat) and the last ones that fired with whether each was delivered.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Open simulator sessions (phones) on this server: id, app, platform, room, who opened it (the MCP client name), start time and current screen title. Use to resume after a reconnect or to see who shares a room.
No parameters.
{
"name": "list_sessions",
"description": "Open simulator sessions (phones) on this server: id, app, platform, room, who opened it (the MCP client name), start time and current screen title. Use to resume after a reconnect or to see who shares a room.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {}
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}List the apps in the phone's Store: the marketplace apps from the control plane, each with id, name, bundle url and version. Fails with store_unreachable when the marketplace cannot be reached (nothing is guessed). Install one with install_app.
No parameters.
{
"name": "list_store_apps",
"description": "List the apps in the phone's Store: the marketplace apps from the control plane, each with id, name, bundle url and version. Fails with store_unreachable when the marketplace cannot be reached (nothing is guessed). Install one with install_app.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {}
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}The wake-up URLs registered on this phone: assistant name, URL and events (never the secret).
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "list_wakeups",
"description": "The wake-up URLs registered on this phone: assistant name, URL and events (never the secret).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Press the power button: the simulated phone locks and shows the lock screen. The app and its screen are kept. While locked, tap, type, scroll and back fail with phone_locked. Logged in device_log as simulated.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "lock",
"description": "Press the power button: the simulated phone locks and shows the lock screen. The app and its screen are kept. While locked, tap, type, scroll and back fail with phone_locked. Logged in device_log as simulated.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}The notification shade: notifications delivered to the simulated phone in this session (their banners vanish after 5 s, like a heads-up on a real phone).
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "notifications",
"description": "The notification shade: notifications delivered to the simulated phone in this session (their banners vanish after 5 s, like a heads-up on a real phone).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Opens the phone in the user's browser so they can watch. Opens an app in a phone-sized session and returns its first screen. With no live `shipvo run` for the project, it starts one (pick platform: 'android' or 'ios') when the project has `shipvo` installed, or when show is true, and only from a local (stdio) server. A live run on the other platform is attached as it is and the result says so. screen, tap, type, scroll, back and screenshot work on that phone. The result says whether the phone is visible and its URL.
| Parameter | Type | Description |
|---|---|---|
| app * | string | App id from list_apps, optionally with a release: 'tide' (local build), 'tide@latest' or 'tide@r13' (the published release phones run), or 'tide@build:<id>' (a build from upload_build, on the hosted phone) |
| dark | boolean | Dark mode |
| room | string | Room name. Every session opened with the same room on the same simulator shares one backend (orders, content, telemetry), read and written through the same store. Without room, each session has its own. 1 to 64 letters, digits, _ or -. |
| show | boolean | true: open the phone in the user's browser so they can watch (default on a computer with a desktop, when the project has `shipvo` installed; a server over HTTP never starts a run). false: headless, nobody sees it (default in CI). |
| model | string | Phone model for a headless session, from phone_models, for example 'iPhone 16 Pro' or 'Galaxy S24'. The session gets that phone's screen size, pixel ratio, user agent and platform. Ignored when a live run is attached. |
| attach | string | 'auto' (default): drive the phone of a live `shipvo run` in this project if there is one, else a headless session. 'never': always headless. 'always': error if there is no live `shipvo run`. |
iPhone only: swipe down from the top right to open Control Center (airplane, Wi-Fi, mobile data, focus, orientation lock, brightness, dark mode). Android fails with no_control_center: use open_notifications.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "open_control_center",
"description": "iPhone only: swipe down from the top right to open Control Center (airplane, Wi-Fi, mobile data, focus, orientation lock, brightness, dark mode). Android fails with no_control_center: use open_notifications.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Tap a notification from the shade (newest if no id is given): the app handles it exactly as if its banner was tapped.
| Parameter | Type | Description |
|---|---|---|
| id | string | |
| session * | string | Session from open_app |
{
"name": "open_notification",
"description": "Tap a notification from the shade (newest if no id is given): the app handles it exactly as if its banner was tapped.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"id": {
"type": "string"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Pull down from the top. Android: the first call opens the notification shade (a few quick-settings tiles and the notifications); a second call expands all tiles. iPhone: opens Notification Center (grouped by app). Returns the tiles and notifications.
| Parameter | Type | Description |
|---|---|---|
| expand | boolean | Android: go straight to all tiles |
| session * | string | Session from open_app |
{
"name": "open_notifications",
"description": "Pull down from the top. Android: the first call opens the notification shade (a few quick-settings tiles and the notifications); a second call expands all tiles. iPhone: opens Notification Center (grouped by app). Returns the tiles and notifications.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"expand": {
"type": "boolean",
"description": "Android: go straight to all tiles"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Open the app switcher: the app goes to the background and its card is shown. resume_app opens the card again; kill_app swipes it away.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "open_recents",
"description": "Open the app switcher: the app goes to the background and its card is shown. resume_app opens the card again; kill_app swipes it away.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Open a deep link (such as myapp://item/3) in the running app, as a push tap, auth callback or share link would. Fails with invalid_url if the text has no scheme, or no_handler if apps declare URL schemes and none matches; a match returns the owning app id. Otherwise fails with no_url_listener if the app does not listen for URLs.
| Parameter | Type | Description |
|---|---|---|
| url * | string | The URL to deliver, e.g. myapp://item/3 |
| session * | string | Session from open_app |
{
"name": "open_url",
"description": "Open a deep link (such as myapp://item/3) in the running app, as a push tap, auth callback or share link would. Fails with invalid_url if the text has no scheme, or no_handler if apps declare URL schemes and none matches; a match returns the owning app id. Otherwise fails with no_url_listener if the app does not listen for URLs.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"url"
],
"properties": {
"url": {
"type": "string",
"description": "The URL to deliver, e.g. myapp://item/3"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"title": "Open a deep link",
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": false
}
}Run an owner command against the live app (changes are audited). Commands that cannot be undone or reach users (publish, prices, offers, deletes, API keys) do nothing and return { code: "needs_confirm", plan } first: show the plan to the owner, then ask the owner to approve the returned challenge in the admin (approval_url). You cannot approve it yourself, and confirm: true alone does nothing. Once approved, call again with the same args and approval: <challenge id>. An approval works once, for 10 minutes, for exactly those args.
| Parameter | Type | Description |
|---|---|---|
| app * | string | |
| args | object | |
| command * | string | |
| approval | string | Challenge id the owner approved; pass the same args |
{
"name": "owner_command",
"description": "Run an owner command against the live app (changes are audited). Commands that cannot be undone or reach users (publish, prices, offers, deletes, API keys) do nothing and return { code: \"needs_confirm\", plan } first: show the plan to the owner, then ask the owner to approve the returned challenge in the admin (approval_url). You cannot approve it yourself, and confirm: true alone does nothing. Once approved, call again with the same args and approval: <challenge id>. An approval works once, for 10 minutes, for exactly those args.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app",
"command"
],
"properties": {
"app": {
"type": "string"
},
"args": {
"type": "object",
"additionalProperties": {}
},
"command": {
"type": "string"
},
"approval": {
"type": "string",
"description": "Challenge id the owner approved; pass the same args"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true
}
}List the owner commands of an app (content, prices, offers, orders, publish). Needs PN_OWNER_TOKEN.
| Parameter | Type | Description |
|---|---|---|
| app * | string |
{
"name": "owner_describe",
"description": "List the owner commands of an app (content, prices, offers, orders, publish). Needs PN_OWNER_TOKEN.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app"
],
"properties": {
"app": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Every device permission decision on the phone, oldest first, on Android and iOS: when an app was granted or denied a permission (by install, import, update or the Settings switch), when a permission was removed, and each time an app action used a permission or was blocked by a denial, with the assistant that called it. Filter by app, permission or event. Changes nothing.
| Parameter | Type | Description |
|---|---|---|
| app | string | Only this app id |
| event | string | one of ["granted","denied","removed","used","blocked"] |
| limit | integer | Most recent entries to return (default 100) |
| session * | string | Session from open_app |
| permission | string | Only this permission, such as camera or notifications |
{
"name": "permission_log",
"description": "Every device permission decision on the phone, oldest first, on Android and iOS: when an app was granted or denied a permission (by install, import, update or the Settings switch), when a permission was removed, and each time an app action used a permission or was blocked by a denial, with the assistant that called it. Filter by app, permission or event. Changes nothing.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"app": {
"type": "string",
"description": "Only this app id"
},
"event": {
"enum": [
"granted",
"denied",
"removed",
"used",
"blocked"
],
"type": "string"
},
"limit": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Most recent entries to return (default 100)"
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"permission": {
"type": "string",
"description": "Only this permission, such as camera or notifications"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}The phone models a headless session can be, each with its platform, screen size in CSS pixels and pixel ratio, and the default model for android and ios. Pass a name to open_app as `model`.
No parameters.
{
"name": "phone_models",
"description": "The phone models a headless session can be, each with its platform, screen size in CSS pixels and pixel ratio, and the default model for android and ios. Pass a name to open_app as `model`.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {}
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Pin an installed app to the top of the home screen (Android and iOS style), after any apps pinned before it, or unpin it with pinned: false. Works for Store apps and apps made with create_app, and survives update_app. Fails with not_installed. Logged in device_log.
| Parameter | Type | Description |
|---|---|---|
| id * | string | Installed app id |
| pinned * | boolean | true to pin, false to unpin |
| session * | string | Session from open_app |
{
"name": "pin_app",
"description": "Pin an installed app to the top of the home screen (Android and iOS style), after any apps pinned before it, or unpin it with pinned: false. Works for Store apps and apps made with create_app, and survives update_app. Fails with not_installed. Logged in device_log.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"id",
"pinned"
],
"properties": {
"id": {
"type": "string",
"description": "Installed app id"
},
"pinned": {
"type": "boolean",
"description": "true to pin, false to unpin"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Press Home: the app goes to the background (it receives AppState "background") and the phone shows the home screen with the app icon. While there, tap, type, scroll and back fail with app_not_foreground. Call resume_app to bring the app back (AppState "active"). Logged as simulated.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "press_home",
"description": "Press Home: the app goes to the background (it receives AppState \"background\") and the phone shows the home screen with the app icon. While there, tap, type, scroll and back fail with app_not_foreground. Call resume_app to bring the app back (AppState \"active\"). Logged as simulated.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Build the app in PN_APP_DIR (or the current folder) with the simulated device and publish a shareable web preview to here.now, no account. The link is PUBLIC and expires in 24 hours; claimUrl keeps it. Returns { url, claimUrl, expiresAt }. Needs @shipvo/cli (npx). Slow: waits up to wait_ms (default 20000), then returns { status: "running", job }; call job_status with that job. Calling again while it runs returns the same job.
| Parameter | Type | Description |
|---|---|---|
| wait_ms | integer | How long to wait for the result before returning { status: "running", job } (default 20000). Read it later with job_status. |
{
"name": "publish_preview",
"description": "Build the app in PN_APP_DIR (or the current folder) with the simulated device and publish a shareable web preview to here.now, no account. The link is PUBLIC and expires in 24 hours; claimUrl keeps it. Returns { url, claimUrl, expiresAt }. Needs @shipvo/cli (npx). Slow: waits up to wait_ms (default 20000), then returns { status: \"running\", job }; call job_status with that job. Calling again while it runs returns the same job.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"wait_ms": {
"type": "integer",
"maximum": 55000,
"minimum": 0,
"description": "How long to wait for the result before returning { status: \"running\", job } (default 20000). Read it later with job_status."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Publish a public preview",
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}
}Deliver a push notification to the simulated phone; it appears as a banner the agent can tap. The app receives it only if notification permission is granted; otherwise nothing is delivered.
| Parameter | Type | Description |
|---|---|---|
| body * | string | |
| data | object | |
| title * | string | |
| session * | string | Session from open_app |
{
"name": "push_notification",
"description": "Deliver a push notification to the simulated phone; it appears as a banner the agent can tap. The app receives it only if notification permission is granted; otherwise nothing is delivered.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"title",
"body"
],
"properties": {
"body": {
"type": "string"
},
"data": {
"type": "object",
"additionalProperties": {}
},
"title": {
"type": "string"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Add a chapter at the current time of the running recording.
| Parameter | Type | Description |
|---|---|---|
| caption * | string |
{
"name": "record_marker",
"description": "Add a chapter at the current time of the running recording.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"caption"
],
"properties": {
"caption": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Start recording the phone frame to an MP4 under .shipvo/recordings/. Use record_marker for chapters and record_stop to finish.
| Parameter | Type | Description |
|---|---|---|
| fps | number | Frames per second (default 30) |
| lumi | boolean | Include Lumi and its step captions in the video (default true for recordings; set false for a plain phone). |
| title | string | Used in the file name |
| format | string | Video shape (default 9:16: 1080x1920; 16:9 is 1920x1080; 1:1 is 1080x1080) |
| show_taps | boolean | Draw a finger dot and ripple on taps and a trail on scrolls (default true) |
| background | string | Behind the phone: "brand", "plain" (white) or a CSS colour such as "#102030" |
| lumi_voice | boolean | Lumi speaks its short step lines with the energetic voice preset (default false). Needs python3, ffmpeg and network access for the voice. Ignored when record_stop gets a narration file. |
{
"name": "record_start",
"description": "Start recording the phone frame to an MP4 under .shipvo/recordings/. Use record_marker for chapters and record_stop to finish.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"fps": {
"enum": [
30,
60
],
"type": "number",
"description": "Frames per second (default 30)"
},
"lumi": {
"type": "boolean",
"description": "Include Lumi and its step captions in the video (default true for recordings; set false for a plain phone)."
},
"title": {
"type": "string",
"description": "Used in the file name"
},
"format": {
"enum": [
"9:16",
"16:9",
"1:1"
],
"type": "string",
"description": "Video shape (default 9:16: 1080x1920; 16:9 is 1920x1080; 1:1 is 1080x1080)"
},
"show_taps": {
"type": "boolean",
"description": "Draw a finger dot and ripple on taps and a trail on scrolls (default true)"
},
"background": {
"type": "string",
"minLength": 1,
"description": "Behind the phone: \"brand\", \"plain\" (white) or a CSS colour such as \"#102030\""
},
"lumi_voice": {
"type": "boolean",
"description": "Lumi speaks its short step lines with the energetic voice preset (default false). Needs python3, ffmpeg and network access for the voice. Ignored when record_stop gets a narration file."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Stop the recording and write the MP4. Returns the file, duration in seconds, size and chapters. With music: true, mixes a ducked music bed under the video and writes a credits JSON next to it (credit the track where you publish).
| Parameter | Type | Description |
|---|---|---|
| music | boolean | Mix a music bed under the video (default false). Needs python3, ffmpeg and ffprobe; picks a track from Jamendo unless SHIPVO_MUSIC_FILE is set. |
| narration | string | Path to a wav with a voice track. It is mixed over the video, trimmed to the video length (the result says so), and ducks the music when music is true. |
{
"name": "record_stop",
"description": "Stop the recording and write the MP4. Returns the file, duration in seconds, size and chapters. With music: true, mixes a ducked music bed under the video and writes a credits JSON next to it (credit the track where you publish).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"music": {
"type": "boolean",
"description": "Mix a music bed under the video (default false). Needs python3, ffmpeg and ffprobe; picks a track from Jamendo unless SHIPVO_MUSIC_FILE is set."
},
"narration": {
"type": "string",
"description": "Path to a wav with a voice track. It is mixed over the video, trimmed to the video length (the result says so), and ducks the music when music is true."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Fetch the data of a spec app now (its http data sources) and redraw the open screen if anything changed. Apps with a refresh interval in the spec also refresh by themselves. The result lists the sources that changed and any errors; a source that fails keeps its last good data. Fails with not_installed. Logged in device_log as data_refresh.
| Parameter | Type | Description |
|---|---|---|
| id * | string | App id |
| session * | string | Session from open_app |
{
"name": "refresh_app",
"description": "Fetch the data of a spec app now (its http data sources) and redraw the open screen if anything changed. Apps with a refresh interval in the spec also refresh by themselves. The result lists the sources that changed and any errors; a source that fails keeps its last good data. Fails with not_installed. Logged in device_log as data_refresh.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"id"
],
"properties": {
"id": {
"type": "string",
"description": "App id"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Wake an assistant that is not in a turn: when a new message or task arrives for `name` in the Assistant Inbox app, the phone POSTs a small signed JSON note to `url` (who it is for, whether it is a message or a task, a one-line summary and the ids; never the message text). The URL can be a Claude Code scheduled task, a GitHub repository_dispatch, an OpenAI background run, Slack or Zapier. Only arrivals after this call wake it. A failed call is retried twice, and every delivery is in device_log. The signature is in the x-shipvo-signature header as `t=<unix seconds>,v1=<hex hmac-sha256 of "<t>.<body>">` using the secret; leave `secret` out and one is generated and returned once. Private and local addresses are refused unless allow_private is true. To tell the person instead of an assistant (for a chat that cannot be started by a URL), point the URL at a push or chat service and set format to text or slack: it sends one line such as "ChatGPT has 1 new message on the phone. Open your chat with ChatGPT to pick it up." Calling it again for the same name replaces the URL.
| Parameter | Type | Description |
|---|---|---|
| url * | string | http or https URL that receives the POST |
| name * | string | The assistant to wake, such as chatgpt or claude (the same names check_inbox uses) |
| events | array | What wakes it (default: both) |
| format | string | What is sent (default json). text: one plain line for a push service such as ntfy, so the person is told to open their chat. slack: {"text": line} for a Slack-style incoming webhook |
| secret | string | Shared secret, at least 16 characters (default: generated and returned once) |
| session * | string |
Ask to add an app to the person's own persistent phone (not the simulator). Returns a consent card: app name, publisher, the permissions it asks for, and approve_url and decline_url. Show the card to the person and tell them to open a link themselves: you cannot approve, and nothing is installed until they do. A card expires after 15 minutes. Fails with unknown_app, already_installed or unauthorized. Needs PN_ASSISTANT_TOKEN.
| Parameter | Type | Description |
|---|---|---|
| app * | string | App id |
{
"name": "request_app_install",
"description": "Ask to add an app to the person's own persistent phone (not the simulator). Returns a consent card: app name, publisher, the permissions it asks for, and approve_url and decline_url. Show the card to the person and tell them to open a link themselves: you cannot approve, and nothing is installed until they do. A card expires after 15 minutes. Fails with unknown_app, already_installed or unauthorized. Needs PN_ASSISTANT_TOKEN.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app"
],
"properties": {
"app": {
"type": "string",
"description": "App id"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Ask the person for an API key without it passing through this chat. Returns a one-time link to the Shipvo vault page (valid 10 minutes, works once) and a notice to show the person. The key goes straight into the vault: you never see it. Tell the person to open the link, then call secret_status to learn whether it was saved. Needs an owner token.
| Parameter | Type | Description |
|---|---|---|
| app * | string | |
| name * | string | Name for the key, e.g. STRIPE_KEY (letters, digits and underscores) |
| access | string | Access the key should have (default read) |
| purpose * | string | Why the app needs it, in plain English; shown to the person on the vault page |
| service * | string | Service name (stripe) or its domain (api.example.com) |
{
"name": "request_secret",
"description": "Ask the person for an API key without it passing through this chat. Returns a one-time link to the Shipvo vault page (valid 10 minutes, works once) and a notice to show the person. The key goes straight into the vault: you never see it. Tell the person to open the link, then call secret_status to learn whether it was saved. Needs an owner token.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app",
"name",
"purpose",
"service"
],
"properties": {
"app": {
"type": "string"
},
"name": {
"type": "string",
"description": "Name for the key, e.g. STRIPE_KEY (letters, digits and underscores)"
},
"access": {
"enum": [
"read",
"write"
],
"type": "string",
"description": "Access the key should have (default read)"
},
"purpose": {
"type": "string",
"maxLength": 200,
"description": "Why the app needs it, in plain English; shown to the person on the vault page"
},
"service": {
"type": "string",
"minLength": 1,
"description": "Service name (stripe) or its domain (api.example.com)"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Restart the simulated phone from the power menu: a boot screen, then the app starts fresh (cold start). Storage is kept. Returns the first screen. Logged in device_log as simulated.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "restart",
"description": "Restart the simulated phone from the power menu: a boot screen, then the app starts fresh (cold start). Storage is kept. Returns the first screen. Logged in device_log as simulated.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Put a backup from backup_phone on this phone: apps with their data and layout, Store apps with their permission answers, system settings and the clipboard. Every part is checked first, and a bad backup changes nothing. Apps you built that are already on the phone need replace: true. A Store app that is already installed is skipped and listed in skipped.
| Parameter | Type | Description |
|---|---|---|
| backup * | object | The backup object from backup_phone |
| replace | boolean | Replace apps already on the phone (default false) |
| session * | string | Session from open_app |
{
"name": "restore_phone",
"description": "Put a backup from backup_phone on this phone: apps with their data and layout, Store apps with their permission answers, system settings and the clipboard. Every part is checked first, and a bad backup changes nothing. Apps you built that are already on the phone need replace: true. A Store app that is already installed is skipped and listed in skipped.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"backup"
],
"properties": {
"backup": {
"type": "object",
"description": "The backup object from backup_phone",
"additionalProperties": {}
},
"replace": {
"type": "boolean",
"description": "Replace apps already on the phone (default false)"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Tap the app icon on the home screen, or its card in the app switcher: the app comes back (AppState "active") with its screen kept. Fails with app_in_foreground if it is already in front.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "resume_app",
"description": "Tap the app icon on the home screen, or its card in the app switcher: the app comes back (AppState \"active\") with its screen kept. Fails with app_in_foreground if it is already in front.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}What the sessions in one room did, oldest first: time, session, agent, tool, target and the change line, plus notes from room_note. Pass since (the cursor from the last call) to get only newer entries. Returns the entries and the next cursor.
| Parameter | Type | Description |
|---|---|---|
| room * | string | Room name used in open_app |
| since | string | Cursor from an earlier room_log; only newer entries come back |
{
"name": "room_log",
"description": "What the sessions in one room did, oldest first: time, session, agent, tool, target and the change line, plus notes from room_note. Pass since (the cursor from the last call) to get only newer entries. Returns the entries and the next cursor.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"room"
],
"properties": {
"room": {
"type": "string",
"description": "Room name used in open_app"
},
"since": {
"type": "string",
"description": "Cursor from an earlier room_log; only newer entries come back"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Post a short plain-text note (up to 500 characters) to a room so the other agents see it in room_log.
| Parameter | Type | Description |
|---|---|---|
| room * | string | Room name used in open_app |
| text * | string | The note, plain text, up to 500 characters |
{
"name": "room_note",
"description": "Post a short plain-text note (up to 500 characters) to a room so the other agents see it in room_log.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"room",
"text"
],
"properties": {
"room": {
"type": "string",
"description": "Room name used in open_app"
},
"text": {
"type": "string",
"description": "The note, plain text, up to 500 characters"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}One summary per session in a room: agent, steps, seconds, errors, last screen title and notes. Use it to collect every sub-agent's result in one call.
| Parameter | Type | Description |
|---|---|---|
| room * | string | Room name used in open_app |
{
"name": "room_report",
"description": "One summary per session in a room: agent, steps, seconds, errors, last screen title and notes. Use it to collect every sub-agent's result in one call.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"room"
],
"properties": {
"room": {
"type": "string",
"description": "Room name used in open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Run one action of an app made with create_app, by name, with its input (for example add_task with { title }). The action changes the app's data the same way tapping its form does, and the open screen shows the result. Fails with not_installed (no such spec app) or action_failed (the action refused the input, with the reason).
| Parameter | Type | Description |
|---|---|---|
| id * | string | App id |
| input | object | The action's input |
| action * | string | Action name from the spec |
| session * | string | Session from open_app |
{
"name": "run_app_action",
"description": "Run one action of an app made with create_app, by name, with its input (for example add_task with { title }). The action changes the app's data the same way tapping its form does, and the open screen shows the result. Fails with not_installed (no such spec app) or action_failed (the action refused the input, with the reason).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"id",
"action"
],
"properties": {
"id": {
"type": "string",
"description": "App id"
},
"input": {
"type": "object",
"description": "The action's input",
"additionalProperties": {}
},
"action": {
"type": "string",
"description": "Action name from the spec"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Show an installed app only in a daily time window, by the phone's clock (see set_phone_time) or in the time zone you give, for example your Tasks app from 08:00 to 10:00 on weekdays. from and to are HH:MM (default 00:00 and 23:59); a window that crosses midnight belongs to the day it starts. Leave days out for every day. timezone is an optional IANA name such as Europe/Berlin or America/New_York: from, to and days are then read in that zone, whatever the phone clock is. Pin and hide still apply. Same schedule as arrange_apps. Fails with not_installed, bad_placement or bad_timezone.
| Parameter | Type | Description |
|---|---|---|
| id * | string | App id |
| to | string | |
| days | array | |
| from | string | |
| session * | string | Session from open_app |
| timezone | string | IANA time zone name, for example Europe/Berlin |
{
"name": "schedule_app",
"description": "Show an installed app only in a daily time window, by the phone's clock (see set_phone_time) or in the time zone you give, for example your Tasks app from 08:00 to 10:00 on weekdays. from and to are HH:MM (default 00:00 and 23:59); a window that crosses midnight belongs to the day it starts. Leave days out for every day. timezone is an optional IANA name such as Europe/Berlin or America/New_York: from, to and days are then read in that zone, whatever the phone clock is. Pin and hide still apply. Same schedule as arrange_apps. Fails with not_installed, bad_placement or bad_timezone.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"id"
],
"properties": {
"id": {
"type": "string",
"description": "App id"
},
"to": {
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
},
"days": {
"type": "array",
"items": {
"enum": [
"sun",
"mon",
"tue",
"wed",
"thu",
"fri",
"sat"
],
"type": "string"
}
},
"from": {
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"timezone": {
"type": "string",
"description": "IANA time zone name, for example Europe/Berlin"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}The current screen as an accessibility tree with refs.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "screen",
"description": "The current screen as an accessibility tree with refs.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}A PNG of the phone screen (for checking layout, colours, images). The result says `source`: tab-capture (the person's live tab), rendered (the page drawn to an image; it lists what it could not draw) or headless. The tree from `screen` is usually enough to act.
| Parameter | Type | Description |
|---|---|---|
| frame | boolean | true: the whole phone, the app inside its Android or iPhone frame with the status bar, for showing a person. Headless sessions only. Default false: the app's screen alone. |
| session * | string | Session from open_app |
{
"name": "screenshot",
"description": "A PNG of the phone screen (for checking layout, colours, images). The result says `source`: tab-capture (the person's live tab), rendered (the page drawn to an image; it lists what it could not draw) or headless. The tree from `screen` is usually enough to act.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"frame": {
"type": "boolean",
"description": "true: the whole phone, the app inside its Android or iPhone frame with the status bar, for showing a person. Headless sessions only. Default false: the app's screen alone."
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Scroll the page (down/up) or a horizontal rail (right/left, give the rail's ref). Returns the new screen. The result starts with 'Change: none | content changed | new screen | scrolled'.
| Parameter | Type | Description |
|---|---|---|
| ref | string | Scroll inside this element (a rail or list); omit for the page |
| settle | boolean | Wait until the screen stops changing (two equal reads 100 ms apart), up to timeout_ms. Use after any action that starts work. A slow result can still follow a pause, so prefer wait_for when you know the expected text. |
| compact | boolean | When the change is 'content changed', the result lists only the lines that changed (+ added, - removed, ~ changed), with refs as on the full screen. This is the default. Pass false to get the whole screen. |
| session * | string | Session from open_app |
| wait_for | object | Use after any action that starts work. Wait until this appears (a ref, a text, or role+name), or disappears with gone: true. The result says Waited: matched or timed out. |
| direction * | string | one of ["down","up","left","right"] |
| timeout_ms | integer | How long wait_for and settle may take, in ms (default 2000) |
Find text anywhere on the phone in one call: rows in every app's data (contacts, messages, alarms, notes, tasks and any app you built) and notifications. Not case sensitive. Each hit says the app, the collection, the row id, the field that matched and a short snippet, with the full row. Use app to look in one app, or 'notifications'. Changes nothing.
| Parameter | Type | Description |
|---|---|---|
| app | string | Only this app id, or 'notifications' |
| limit | integer | Most results to return (default 20) |
| query * | string | Text to look for, up to 200 characters |
| session * | string | Session from open_app |
{
"name": "search_phone",
"description": "Find text anywhere on the phone in one call: rows in every app's data (contacts, messages, alarms, notes, tasks and any app you built) and notifications. Not case sensitive. Each hit says the app, the collection, the row id, the field that matched and a short snippet, with the full row. Use app to look in one app, or 'notifications'. Changes nothing.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"query"
],
"properties": {
"app": {
"type": "string",
"description": "Only this app id, or 'notifications'"
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Most results to return (default 20)"
},
"query": {
"type": "string",
"description": "Text to look for, up to 200 characters"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Whether a key is saved in the vault, as { saved, valid, access }. Never returns the key. valid is null when it was not checked. Needs an owner token.
| Parameter | Type | Description |
|---|---|---|
| app * | string | |
| name * | string |
{
"name": "secret_status",
"description": "Whether a key is saved in the vault, as { saved, valid, access }. Never returns the key. valid is null when it was not checked. Needs an owner token.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app",
"name"
],
"properties": {
"app": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Put text on the phone's clipboard so the next paste in any app gets it. It stays when you switch apps.
| Parameter | Type | Description |
|---|---|---|
| text * | string | Up to 20000 characters |
| session * | string | Session from open_app |
{
"name": "set_clipboard",
"description": "Put text on the phone's clipboard so the next paste in any app gets it. It stays when you switch apps.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"text"
],
"properties": {
"text": {
"type": "string",
"description": "Up to 20000 characters"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Turn Wi-Fi, mobile data or airplane mode on or off for the whole phone, as in quick settings on Android and iOS. Airplane mode turns both radios off; Wi-Fi can come back on during it, and leaving it restores the radios as they were. Every app sees the result: apps you built read it as {{ network.online }} and {{ network.type }}, and their web data does not load while the phone is offline. The open app's screen is drawn again. Logged in device_log as "connectivity".
| Parameter | Type | Description |
|---|---|---|
| wifi | boolean | |
| session * | string | Session from open_app |
| airplane | boolean | |
| mobile_data | boolean |
{
"name": "set_connectivity",
"description": "Turn Wi-Fi, mobile data or airplane mode on or off for the whole phone, as in quick settings on Android and iOS. Airplane mode turns both radios off; Wi-Fi can come back on during it, and leaving it restores the radios as they were. Every app sees the result: apps you built read it as {{ network.online }} and {{ network.type }}, and their web data does not load while the phone is offline. The open app's screen is drawn again. Logged in device_log as \"connectivity\".",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"wifi": {
"type": "boolean"
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"airplane": {
"type": "boolean"
},
"mobile_data": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Change what the simulated phone has: location, the address book (contacts), calendar events, files for the file picker, a barcode in front of the camera, permission states, whether the fingerprint will match, whether a payment will be approved, network on/off. Takes effect for the next action.
| Parameter | Type | Description |
|---|---|---|
| dnd | boolean | Do Not Disturb: notifications go to the shade without a banner |
| wifi | boolean | |
| files | array | Replace the files the file picker offers |
| camera | object | |
| online | boolean | |
| source | string | "simulated" forces the simulated camera, microphone and location even when a person could grant the real ones, for reproducible runs |
| payment | object | |
| session * | string | Session from open_app |
| airplane | boolean | |
| calendar | array | Replace the calendar events the app can read (needs calendar permission) |
| contacts | array | Replace the address book the app can read (needs contacts permission) |
Make the phone's network behave like a named profile: online, offline, 2g, 3g, slow-4g, spotty or low-end-4g. The app's fetch and XHR calls wait and fail as the profile says (offline rejects every call). The numbers are simulation settings, not measurements of a real network. Mock rules from set_network_mocks still win. Fails with unknown_profile for a name that does not exist. Logged in device_log as simulated.
| Parameter | Type | Description |
|---|---|---|
| profile * | string | online, offline, 2g, 3g, slow-4g, spotty or low-end-4g |
| session * | string | Session from open_app |
{
"name": "set_network_profile",
"description": "Make the phone's network behave like a named profile: online, offline, 2g, 3g, slow-4g, spotty or low-end-4g. The app's fetch and XHR calls wait and fail as the profile says (offline rejects every call). The numbers are simulation settings, not measurements of a real network. Mock rules from set_network_mocks still win. Fails with unknown_profile for a name that does not exist. Logged in device_log as simulated.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"profile"
],
"properties": {
"profile": {
"type": "string",
"description": "online, offline, 2g, 3g, slow-4g, spotty or low-end-4g"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Set the phone's clock to a time like 2026-11-14T09:00:00 so scheduled apps show or hide as they would then, or pass null to go back to the real time. The clock stays at the time you set; it does not tick. Fails with bad_time.
| Parameter | Type | Description |
|---|---|---|
| at * | ["string","null"] | ISO time without a zone, or null for the real time |
| session * | string | Session from open_app |
{
"name": "set_phone_time",
"description": "Set the phone's clock to a time like 2026-11-14T09:00:00 so scheduled apps show or hide as they would then, or pass null to go back to the real time. The clock stays at the time you set; it does not tick. Fails with bad_time.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"at"
],
"properties": {
"at": {
"type": [
"string",
"null"
],
"description": "ISO time without a zone, or null for the real time"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Set a reminder on the phone: at the time you give (on the phone's clock, see set_phone_time) a notification with the title and body arrives, whether or not an app is open. Give at (a time like 2026-11-14T09:00) or in_minutes, not both. repeat is none, daily or weekly. With Do Not Disturb or Focus on, it is kept in the notification shade without a banner. It arrives whatever the app notification permissions say, as a phone's own reminders do. Read what arrived with notifications. Fails with bad_time, bad_title, too_long, bad_repeat or too_many.
| Parameter | Type | Description |
|---|---|---|
| at | string | Phone-clock time such as 2026-11-14T09:00 |
| body | string | More detail (up to 1000 characters) |
| title * | string | What to remind (up to 200 characters) |
| repeat | string | one of ["none","daily","weekly"] |
| session * | string | Session from open_app |
| in_minutes | number | Minutes from now on the phone's clock (0 to 525600) |
{
"name": "set_reminder",
"description": "Set a reminder on the phone: at the time you give (on the phone's clock, see set_phone_time) a notification with the title and body arrives, whether or not an app is open. Give at (a time like 2026-11-14T09:00) or in_minutes, not both. repeat is none, daily or weekly. With Do Not Disturb or Focus on, it is kept in the notification shade without a banner. It arrives whatever the app notification permissions say, as a phone's own reminders do. Read what arrived with notifications. Fails with bad_time, bad_title, too_long, bad_repeat or too_many.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"title"
],
"properties": {
"at": {
"type": "string",
"description": "Phone-clock time such as 2026-11-14T09:00"
},
"body": {
"type": "string",
"description": "More detail (up to 1000 characters)"
},
"title": {
"type": "string",
"description": "What to remind (up to 200 characters)"
},
"repeat": {
"enum": [
"none",
"daily",
"weekly"
],
"type": "string"
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"in_minutes": {
"type": "number",
"description": "Minutes from now on the phone's clock (0 to 525600)"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Change one system setting, as a person would in the phone's Settings screen. The app sees it through Appearance (dark_mode), PixelRatio.getFontScale (font_size), AccessibilityInfo (bold_text, reduce_motion), I18nManager (rtl) and Intl (language). Setting language to ar turns rtl on; en and fr turn it off. Fails with unknown_setting for a key that does not exist and bad_value for a value it does not take. Logged in device_log as simulated.
| Parameter | Type | Description |
|---|---|---|
| key * | string | dark_mode, font_size, bold_text, reduce_motion, language or rtl |
| value * | ["boolean","string"] | true or false for switches; small, default, large or largest for font_size; en, fr or ar for language |
| session * | string | Session from open_app |
{
"name": "set_setting",
"description": "Change one system setting, as a person would in the phone's Settings screen. The app sees it through Appearance (dark_mode), PixelRatio.getFontScale (font_size), AccessibilityInfo (bold_text, reduce_motion), I18nManager (rtl) and Intl (language). Setting language to ar turns rtl on; en and fr turn it off. Fails with unknown_setting for a key that does not exist and bad_value for a value it does not take. Logged in device_log as simulated.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"key",
"value"
],
"properties": {
"key": {
"type": "string",
"description": "dark_mode, font_size, bold_text, reduce_motion, language or rtl"
},
"value": {
"type": [
"boolean",
"string"
],
"description": "true or false for switches; small, default, large or largest for font_size; en, fr or ar for language"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Share text into another app on the phone, like picking it in the share sheet: the text goes into that app's share action (for example a new note in Notes and Tasks). A title input that is not the share input gets `title`, or the first line of the text. Logged in app_activity as "share". Use share_targets to see which apps take shared text.
| Parameter | Type | Description |
|---|---|---|
| to * | string | App id from share_targets |
| from | string | The app the text is shared from, for the activity log |
| text * | string | The text to share, up to 5000 characters |
| title | string | A title for the shared item (default: the first line of the text) |
| action | string | The share action, when the app has more than one (from share_targets) |
| session * | string | Session from open_app |
{
"name": "share",
"description": "Share text into another app on the phone, like picking it in the share sheet: the text goes into that app's share action (for example a new note in Notes and Tasks). A title input that is not the share input gets `title`, or the first line of the text. Logged in app_activity as \"share\". Use share_targets to see which apps take shared text.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"to",
"text"
],
"properties": {
"to": {
"type": "string",
"description": "App id from share_targets"
},
"from": {
"type": "string",
"description": "The app the text is shared from, for the activity log"
},
"text": {
"type": "string",
"description": "The text to share, up to 5000 characters"
},
"title": {
"type": "string",
"description": "A title for the shared item (default: the first line of the text)"
},
"action": {
"type": "string",
"description": "The share action, when the app has more than one (from share_targets)"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}The apps on this phone that take shared text, like the share sheet on Android and iOS: app id and name, the action and the input that receives the text.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "share_targets",
"description": "The apps on this phone that take shared text, like the share sheet on Android and iOS: app id and name, the action and the input that receives the text.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Open an installed app (tap its icon on the home screen): it becomes current_app and comes to the front. Fails with not_installed. Logged in device_log as simulated.
| Parameter | Type | Description |
|---|---|---|
| id * | string | Installed app id |
| session * | string | Session from open_app |
{
"name": "switch_app",
"description": "Open an installed app (tap its icon on the home screen): it becomes current_app and comes to the front. Fails with not_installed. Logged in device_log as simulated.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Installed app id"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Tap a button, link or choice by ref. Returns the new screen, or only the lines that changed when the screen stayed the same one. The result starts with 'Change: none | content changed | new screen | scrolled'. Work that starts on a tap (paying, saving, loading) can finish after this returns, so the screen may show 'Paying...' or a spinner. Do not report that as the result: pass wait_for with the text you expect (and gone: true for the spinner), or settle: true, before you read the outcome or do anything else. To tap a known path in one call, pass `then` with the next things to tap, by visible name or ref.
| Parameter | Type | Description |
|---|---|---|
| ref * | string | Element ref from the screen, e.g. e42. After a restart refs can carry a prefix, such as f1e42; use them exactly as the screen shows them. |
| then | array | More taps to make after this one, in order: each is the visible name of the element to tap on the screen that follows (for example ["Settings", "Dark theme"]) or a ref. The path stops at the first step that is not on the screen. |
| settle | boolean | Wait until the screen stops changing (two equal reads 100 ms apart), up to timeout_ms. Use after any action that starts work. A slow result can still follow a pause, so prefer wait_for when you know the expected text. |
| compact | boolean | When the change is 'content changed', the result lists only the lines that changed (+ added, - removed, ~ changed), with refs as on the full screen. This is the default. Pass false to get the whole screen. |
| session * | string | Session from open_app |
| approved | boolean | Only after a tap answered approval_needed and the person said yes in chat: true repeats the tap with their approval. Never set it on your own. |
Flip a quick-settings tile in the open shade or Control Center. It changes the simulated device like set_device: Wi-Fi and mobile data both off take the network offline, dark_mode changes the app's colour scheme, dnd stops banners. Tiles: wifi, mobile_data, airplane, location, dark_mode, dnd, auto_rotate, flashlight (Android); airplane, wifi, mobile_data, focus, orientation_lock, brightness, dark_mode (iPhone). Fails with tile_not_visible if the panel is closed.
| Parameter | Type | Description |
|---|---|---|
| tile * | string | |
| value | ["boolean","number"] | true or false; 0 to 100 for brightness. Omit to flip. |
| session * | string | Session from open_app |
{
"name": "toggle_tile",
"description": "Flip a quick-settings tile in the open shade or Control Center. It changes the simulated device like set_device: Wi-Fi and mobile data both off take the network offline, dark_mode changes the app's colour scheme, dnd stops banners. Tiles: wifi, mobile_data, airplane, location, dark_mode, dnd, auto_rotate, flashlight (Android); airplane, wifi, mobile_data, focus, orientation_lock, brightness, dark_mode (iPhone). Fails with tile_not_visible if the panel is closed.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"tile"
],
"properties": {
"tile": {
"type": "string"
},
"value": {
"type": [
"boolean",
"number"
],
"description": "true or false; 0 to 100 for brightness. Omit to flip."
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Type into a text field by ref (replaces its content). Returns the new screen, or only the lines that changed. The result starts with 'Change: none | content changed | new screen | scrolled'. Also gives the field's value after typing.
| Parameter | Type | Description |
|---|---|---|
| ref * | string | Element ref from the screen, e.g. e42. After a restart refs can carry a prefix, such as f1e42; use them exactly as the screen shows them. |
| text * | string | |
| enter | boolean | Press Enter afterwards |
| secret | boolean | true: the text is a password, a one-time code or another secret. It is typed, and kept out of the result, the watch page, the room log and exported tests. Password fields are treated this way without it. |
| settle | boolean | Wait until the screen stops changing (two equal reads 100 ms apart), up to timeout_ms. Use after any action that starts work. A slow result can still follow a pause, so prefer wait_for when you know the expected text. |
| compact | boolean | When the change is 'content changed', the result lists only the lines that changed (+ added, - removed, ~ changed), with refs as on the full screen. This is the default. Pass false to get the whole screen. |
| session * | string | Session from open_app |
| wait_for | object | Use after any action that starts work. Wait until this appears (a ref, a text, or role+name), or disappears with gone: true. The result says Waited: matched or timed out. |
Remove an installed app from the phone. If it was open, the phone returns to the home screen. Fails with not_installed. Logged in device_log as simulated.
| Parameter | Type | Description |
|---|---|---|
| id * | string | Installed app id |
| session * | string | Session from open_app |
{
"name": "uninstall_app",
"description": "Remove an installed app from the phone. If it was open, the phone returns to the home screen. Fails with not_installed. Logged in device_log as simulated.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Installed app id"
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true
}
}Swipe up on the lock screen. Returns to the same screen as before the lock. Fails with not_locked if the phone is not locked. Logged in device_log as simulated.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
{
"name": "unlock",
"description": "Swipe up on the lock screen. Returns to the same screen as before the lock. Fails with not_locked if the phone is not locked. Logged in device_log as simulated.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Change an app made with create_app by giving its new spec. The change is a new version of the same app: the data and settings the person entered stay, and the open screen shows the new look right away. A spec with problems comes back with each problem's path and a fix, and the running version is not touched. Fails with not_installed (no such spec app) or invalid_spec. Logged in device_log with the old and new version.
| Parameter | Type | Description |
|---|---|---|
| id * | string | App id from create_app |
| name | string | New name under the icon |
| spec * | object | The whole new spec (shipvo.app/v0) |
| session * | string | Session from open_app |
{
"name": "update_app",
"description": "Change an app made with create_app by giving its new spec. The change is a new version of the same app: the data and settings the person entered stay, and the open screen shows the new look right away. A spec with problems comes back with each problem's path and a fix, and the running version is not touched. Fails with not_installed (no such spec app) or invalid_spec. Logged in device_log with the old and new version.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"id",
"spec"
],
"properties": {
"id": {
"type": "string",
"description": "App id from create_app"
},
"name": {
"type": "string",
"description": "New name under the icon"
},
"spec": {
"type": "object",
"description": "The whole new spec (shipvo.app/v0)",
"additionalProperties": {}
},
"session": {
"type": "string",
"description": "Session from open_app"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}Build the app in this project with the simulated device (the same build `shipvo sim` makes), upload it to the hosted phone for this key, and return a build id. Then call open_app("<app>@build:<id>") on the hosted server. The build is private to your account and is deleted when it expires. Runs only on the local (stdio) server, because it reads your project.
| Parameter | Type | Description |
|---|---|---|
| app | string | App id (default: read from the project's shipvo config) |
| dir | string | Project folder (default: the server's working directory) |
| wait_ms | integer | How long to wait for the result before returning { status: "running", job } (default 20000). Read it later with job_status. |
| skip_build | boolean | Upload the existing sim-dist folder without building again |
{
"name": "upload_build",
"description": "Build the app in this project with the simulated device (the same build `shipvo sim` makes), upload it to the hosted phone for this key, and return a build id. Then call open_app(\"<app>@build:<id>\") on the hosted server. The build is private to your account and is deleted when it expires. Runs only on the local (stdio) server, because it reads your project.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"app": {
"type": "string",
"description": "App id (default: read from the project's shipvo config)"
},
"dir": {
"type": "string",
"description": "Project folder (default: the server's working directory)"
},
"wait_ms": {
"type": "integer",
"maximum": 55000,
"minimum": 0,
"description": "How long to wait for the result before returning { status: \"running\", job } (default 20000). Read it later with job_status."
},
"skip_build": {
"type": "boolean",
"description": "Upload the existing sim-dist folder without building again"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": true,
"destructiveHint": false
}
}Wait until something new arrives for you in the Assistant Inbox app on this phone: a message or a task. Returns when a message or task you have not been told about yet is waiting (at once if one already is), and `nothing yet` after timeout_ms (up to 25000, default 25000) when not. structuredContent.pending lists the new message ids and task ids. When it returns an event, read it with check_inbox or my_tasks, then call wait_for_event again to listen for the next one: items already returned do not wake you again.
| Parameter | Type | Description |
|---|---|---|
| session * | string | Session from open_app |
| timeout_ms | integer | How long to wait, in ms (default 25000) |
{
"name": "wait_for_event",
"description": "Wait until something new arrives for you in the Assistant Inbox app on this phone: a message or a task. Returns when a message or task you have not been told about yet is waiting (at once if one already is), and `nothing yet` after timeout_ms (up to 25000, default 25000) when not. structuredContent.pending lists the new message ids and task ids. When it returns an event, read it with check_inbox or my_tasks, then call wait_for_event again to listen for the next one: items already returned do not wake you again.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"session": {
"type": "string",
"description": "Session from open_app"
},
"timeout_ms": {
"type": "integer",
"maximum": 25000,
"minimum": 0,
"description": "How long to wait, in ms (default 25000)"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false
}
}Shipvo lets an assistant use a React Native app in a simulated phone. Tools that open or act on an app need an API key: Authorization: Bearer <key> (run `npx @shipvo/cli login`). https://shipvo.dev/docs/test-with-an-assistant/
Names, descriptions and schemas were written by the server and are shown as data.
Pattern matches on what the server declares. They show what it says it can do, not what it does.
None yet. Changes appear after a server's second daily check.
| restart | boolean | Only with a session id that is already open: true starts that session over, empty, with this app. By default the open session is reused: the phone switches to this app and keeps its other apps and data. |
| session | string | Session name (default: generated). One session is one phone. |
| platform | string | Which phone to show: 'android' or 'ios' (default: the live run's, else android). Ignored when no phone is started (show false, attach never, or a live run is attached as it is) |
| seed_cart | array | Start with these items already in the cart (test shortcut). Each line: { product_id, quantity }; { id, qty } also works. |
{
"name": "open_app",
"description": "Opens the phone in the user's browser so they can watch. Opens an app in a phone-sized session and returns its first screen. With no live `shipvo run` for the project, it starts one (pick platform: 'android' or 'ios') when the project has `shipvo` installed, or when show is true, and only from a local (stdio) server. A live run on the other platform is attached as it is and the result says so. screen, tap, type, scroll, back and screenshot work on that phone. The result says whether the phone is visible and its URL.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"app"
],
"properties": {
"app": {
"type": "string",
"description": "App id from list_apps, optionally with a release: 'tide' (local build), 'tide@latest' or 'tide@r13' (the published release phones run), or 'tide@build:<id>' (a build from upload_build, on the hosted phone)"
},
"dark": {
"type": "boolean",
"description": "Dark mode"
},
"room": {
"type": "string",
"description": "Room name. Every session opened with the same room on the same simulator shares one backend (orders, content, telemetry), read and written through the same store. Without room, each session has its own. 1 to 64 letters, digits, _ or -."
},
"show": {
"type": "boolean",
"description": "true: open the phone in the user's browser so they can watch (default on a computer with a desktop, when the project has `shipvo` installed; a server over HTTP never starts a run). false: headless, nobody sees it (default in CI)."
},
"model": {
"type": "string",
"description": "Phone model for a headless session, from phone_models, for example 'iPhone 16 Pro' or 'Galaxy S24'. The session gets that phone's screen size, pixel ratio, user agent and platform. Ignored when a live run is attached."
},
"attach": {
"enum": [
"auto",
"never",
"always"
],
"type": "string",
"description": "'auto' (default): drive the phone of a live `shipvo run` in this project if there is one, else a headless session. 'never': always headless. 'always': error if there is no live `shipvo run`."
},
"restart": {
"type": "boolean",
"description": "Only with a session id that is already open: true starts that session over, empty, with this app. By default the open session is reused: the phone switches to this app and keeps its other apps and data."
},
"session": {
"type": "string",
"description": "Session name (default: generated). One session is one phone."
},
"platform": {
"enum": [
"android",
"ios"
],
"type": "string",
"description": "Which phone to show: 'android' or 'ios' (default: the live run's, else android). Ignored when no phone is started (show false, attach never, or a live run is attached as it is)"
},
"seed_cart": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"qty": {
"type": "integer",
"exclusiveMinimum": 0
},
"quantity": {
"type": "integer",
"exclusiveMinimum": 0
},
"product_id": {
"type": "string"
}
},
"additionalProperties": false
},
"description": "Start with these items already in the cart (test shortcut). Each line: { product_id, quantity }; { id, qty } also works."
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}| Session from open_app |
| allow_private | boolean | Allow a private or local address (for a service you run yourself) |
{
"name": "register_wakeup",
"description": "Wake an assistant that is not in a turn: when a new message or task arrives for `name` in the Assistant Inbox app, the phone POSTs a small signed JSON note to `url` (who it is for, whether it is a message or a task, a one-line summary and the ids; never the message text). The URL can be a Claude Code scheduled task, a GitHub repository_dispatch, an OpenAI background run, Slack or Zapier. Only arrivals after this call wake it. A failed call is retried twice, and every delivery is in device_log. The signature is in the x-shipvo-signature header as `t=<unix seconds>,v1=<hex hmac-sha256 of \"<t>.<body>\">` using the secret; leave `secret` out and one is generated and returned once. Private and local addresses are refused unless allow_private is true. To tell the person instead of an assistant (for a chat that cannot be started by a URL), point the URL at a push or chat service and set format to text or slack: it sends one line such as \"ChatGPT has 1 new message on the phone. Open your chat with ChatGPT to pick it up.\" Calling it again for the same name replaces the URL.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"name",
"url"
],
"properties": {
"url": {
"type": "string",
"description": "http or https URL that receives the POST"
},
"name": {
"type": "string",
"description": "The assistant to wake, such as chatgpt or claude (the same names check_inbox uses)"
},
"events": {
"type": "array",
"items": {
"enum": [
"message",
"task"
],
"type": "string"
},
"description": "What wakes it (default: both)"
},
"format": {
"enum": [
"json",
"text",
"slack"
],
"type": "string",
"description": "What is sent (default json). text: one plain line for a push service such as ntfy, so the person is told to open their chat. slack: {\"text\": line} for a Slack-style incoming webhook"
},
"secret": {
"type": "string",
"description": "Shared secret, at least 16 characters (default: generated and returned once)"
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"allow_private": {
"type": "boolean",
"description": "Allow a private or local address (for a service you run yourself)"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}{
"name": "scroll",
"description": "Scroll the page (down/up) or a horizontal rail (right/left, give the rail's ref). Returns the new screen. The result starts with 'Change: none | content changed | new screen | scrolled'.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"direction"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^(?:p\\d+|f\\d+)?e\\d+$",
"description": "Scroll inside this element (a rail or list); omit for the page"
},
"settle": {
"type": "boolean",
"description": "Wait until the screen stops changing (two equal reads 100 ms apart), up to timeout_ms. Use after any action that starts work. A slow result can still follow a pause, so prefer wait_for when you know the expected text."
},
"compact": {
"type": "boolean",
"description": "When the change is 'content changed', the result lists only the lines that changed (+ added, - removed, ~ changed), with refs as on the full screen. This is the default. Pass false to get the whole screen."
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"wait_for": {
"type": "object",
"properties": {
"ref": {
"type": "string",
"pattern": "^(?:p\\d+|f\\d+)?e\\d+$"
},
"gone": {
"type": "boolean"
},
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"text": {
"type": "string"
}
},
"description": "Use after any action that starts work. Wait until this appears (a ref, a text, or role+name), or disappears with gone: true. The result says Waited: matched or timed out.",
"additionalProperties": false
},
"direction": {
"enum": [
"down",
"up",
"left",
"right"
],
"type": "string"
},
"timeout_ms": {
"type": "integer",
"maximum": 30000,
"minimum": 0,
"description": "How long wait_for and settle may take, in ms (default 2000)"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}| darkMode | boolean | The app's colour scheme (prefers-color-scheme) |
| location | object |
| autoRotate | boolean |
| biometrics | object |
| brightness | number |
| flashlight | boolean |
| microphone | object |
| mobileData | boolean |
| permissions | object |
| orientationLock | boolean |
| locationServices | boolean |
{
"name": "set_device",
"description": "Change what the simulated phone has: location, the address book (contacts), calendar events, files for the file picker, a barcode in front of the camera, permission states, whether the fingerprint will match, whether a payment will be approved, network on/off. Takes effect for the next action.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session"
],
"properties": {
"dnd": {
"type": "boolean",
"description": "Do Not Disturb: notifications go to the shade without a banner"
},
"wifi": {
"type": "boolean"
},
"files": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"mimeType",
"content"
],
"properties": {
"name": {
"type": "string"
},
"content": {
"type": "string",
"description": "The file's text"
},
"mimeType": {
"type": "string"
}
},
"additionalProperties": false
},
"description": "Replace the files the file picker offers"
},
"camera": {
"type": "object",
"properties": {
"barcode": {
"anyOf": [
{
"type": "object",
"required": [
"type",
"data"
],
"properties": {
"data": {
"type": "string"
},
"type": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"delayMs": {
"type": "number"
}
},
"additionalProperties": false
},
"online": {
"type": "boolean"
},
"source": {
"enum": [
"auto",
"simulated"
],
"type": "string",
"description": "\"simulated\" forces the simulated camera, microphone and location even when a person could grant the real ones, for reproducible runs"
},
"payment": {
"type": "object",
"properties": {
"pin": {
"type": "string"
},
"nextResult": {
"enum": [
"approve",
"decline",
"timeout",
"insufficient_funds",
"cancel"
],
"type": "string"
}
},
"additionalProperties": false
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"airplane": {
"type": "boolean"
},
"calendar": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"title",
"start",
"end"
],
"properties": {
"id": {
"type": "string"
},
"end": {
"type": "string",
"description": "ISO 8601"
},
"notes": {
"type": "string"
},
"start": {
"type": "string",
"description": "ISO 8601"
},
"title": {
"type": "string"
},
"allDay": {
"type": "boolean"
},
"location": {
"type": "string"
}
},
"additionalProperties": false
},
"description": "Replace the calendar events the app can read (needs calendar permission)"
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"emails": {
"type": "array",
"items": {
"type": "string"
}
},
"phoneNumbers": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"description": "Replace the address book the app can read (needs contacts permission)"
},
"darkMode": {
"type": "boolean",
"description": "The app's colour scheme (prefers-color-scheme)"
},
"location": {
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"accuracy": {
"type": "number"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
}
},
"additionalProperties": false
},
"autoRotate": {
"type": "boolean"
},
"biometrics": {
"type": "object",
"properties": {
"enrolled": {
"type": "boolean"
},
"nextResult": {
"enum": [
"success",
"fail",
"cancel"
],
"type": "string"
}
},
"additionalProperties": false
},
"brightness": {
"type": "number",
"maximum": 100,
"minimum": 0
},
"flashlight": {
"type": "boolean"
},
"microphone": {
"type": "object",
"properties": {
"level": {
"type": "number",
"maximum": 1,
"minimum": 0
}
},
"additionalProperties": false
},
"mobileData": {
"type": "boolean"
},
"permissions": {
"type": "object",
"properties": {
"camera": {
"enum": [
"granted",
"denied",
"undetermined"
],
"type": "string"
},
"calendar": {
"enum": [
"granted",
"denied",
"undetermined"
],
"type": "string"
},
"contacts": {
"enum": [
"granted",
"denied",
"undetermined"
],
"type": "string"
},
"location": {
"enum": [
"granted",
"denied",
"undetermined"
],
"type": "string"
},
"notifications": {
"enum": [
"granted",
"denied",
"undetermined"
],
"type": "string"
}
},
"additionalProperties": false
},
"orientationLock": {
"type": "boolean"
},
"locationServices": {
"type": "boolean"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}| wait_for | object | Use after any action that starts work. Wait until this appears (a ref, a text, or role+name), or disappears with gone: true. The result says Waited: matched or timed out. |
| timeout_ms | integer | How long wait_for and settle may take, in ms (default 2000) |
{
"name": "tap",
"description": "Tap a button, link or choice by ref. Returns the new screen, or only the lines that changed when the screen stayed the same one. The result starts with 'Change: none | content changed | new screen | scrolled'. Work that starts on a tap (paying, saving, loading) can finish after this returns, so the screen may show 'Paying...' or a spinner. Do not report that as the result: pass wait_for with the text you expect (and gone: true for the spinner), or settle: true, before you read the outcome or do anything else. To tap a known path in one call, pass `then` with the next things to tap, by visible name or ref.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"ref"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^(?:p\\d+|f\\d+)?e\\d+$",
"description": "Element ref from the screen, e.g. e42. After a restart refs can carry a prefix, such as f1e42; use them exactly as the screen shows them."
},
"then": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"maxItems": 8,
"description": "More taps to make after this one, in order: each is the visible name of the element to tap on the screen that follows (for example [\"Settings\", \"Dark theme\"]) or a ref. The path stops at the first step that is not on the screen."
},
"settle": {
"type": "boolean",
"description": "Wait until the screen stops changing (two equal reads 100 ms apart), up to timeout_ms. Use after any action that starts work. A slow result can still follow a pause, so prefer wait_for when you know the expected text."
},
"compact": {
"type": "boolean",
"description": "When the change is 'content changed', the result lists only the lines that changed (+ added, - removed, ~ changed), with refs as on the full screen. This is the default. Pass false to get the whole screen."
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"approved": {
"type": "boolean",
"description": "Only after a tap answered approval_needed and the person said yes in chat: true repeats the tap with their approval. Never set it on your own."
},
"wait_for": {
"type": "object",
"properties": {
"ref": {
"type": "string",
"pattern": "^(?:p\\d+|f\\d+)?e\\d+$"
},
"gone": {
"type": "boolean"
},
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"text": {
"type": "string"
}
},
"description": "Use after any action that starts work. Wait until this appears (a ref, a text, or role+name), or disappears with gone: true. The result says Waited: matched or timed out.",
"additionalProperties": false
},
"timeout_ms": {
"type": "integer",
"maximum": 30000,
"minimum": 0,
"description": "How long wait_for and settle may take, in ms (default 2000)"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}| timeout_ms | integer | How long wait_for and settle may take, in ms (default 2000) |
{
"name": "type",
"description": "Type into a text field by ref (replaces its content). Returns the new screen, or only the lines that changed. The result starts with 'Change: none | content changed | new screen | scrolled'. Also gives the field's value after typing.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session",
"ref",
"text"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^(?:p\\d+|f\\d+)?e\\d+$",
"description": "Element ref from the screen, e.g. e42. After a restart refs can carry a prefix, such as f1e42; use them exactly as the screen shows them."
},
"text": {
"type": "string"
},
"enter": {
"type": "boolean",
"description": "Press Enter afterwards"
},
"secret": {
"type": "boolean",
"description": "true: the text is a password, a one-time code or another secret. It is typed, and kept out of the result, the watch page, the room log and exported tests. Password fields are treated this way without it."
},
"settle": {
"type": "boolean",
"description": "Wait until the screen stops changing (two equal reads 100 ms apart), up to timeout_ms. Use after any action that starts work. A slow result can still follow a pause, so prefer wait_for when you know the expected text."
},
"compact": {
"type": "boolean",
"description": "When the change is 'content changed', the result lists only the lines that changed (+ added, - removed, ~ changed), with refs as on the full screen. This is the default. Pass false to get the whole screen."
},
"session": {
"type": "string",
"description": "Session from open_app"
},
"wait_for": {
"type": "object",
"properties": {
"ref": {
"type": "string",
"pattern": "^(?:p\\d+|f\\d+)?e\\d+$"
},
"gone": {
"type": "boolean"
},
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"text": {
"type": "string"
}
},
"description": "Use after any action that starts work. Wait until this appears (a ref, a text, or role+name), or disappears with gone: true. The result says Waited: matched or timed out.",
"additionalProperties": false
},
"timeout_ms": {
"type": "integer",
"maximum": 30000,
"minimum": 0,
"description": "How long wait_for and settle may take, in ms (default 2000)"
}
},
"additionalProperties": false
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false
}
}