@devicecloud.dev/dcd 5.11.0-beta.2 → 5.11.0-beta.3

package/README.md

@@ -36,9 +36,56 @@ See full documentation: [Docs](https://docs.devicecloud.dev)
 
 ## MCP server
 
-The same npm package ships an [MCP](https://modelcontextprotocol.io) server (`dcd-mcp` bin) so AI agents — Claude, Cursor, VS Code — can drive devicecloud.dev directly.
+devicecloud.dev has an [MCP](https://modelcontextprotocol.io) server, so AI agents (Claude, Cursor, VS Code) can run cloud tests and drive cloud devices. You don't run it yourself. You add it to your MCP client's config, and the client starts it.
 
-Add it to your MCP client config:
+There are three ways to connect:
+
+| | Install | Tools | Use it when |
+| --- | --- | --- | --- |
+| **`dcd mcp`** (recommended) | the CLI | device tools + `dcd_*` cloud-test tools | you want everything, including installing a local build or running local flow files |
+| **Hosted** `https://api.devicecloud.dev/mcp` | nothing | device tools | the agent only drives devices, with apps and flows that are already uploaded or at a URL |
+| **`dcd-mcp`** | the CLI | `dcd_*` cloud-test tools | you only run cloud tests (the older server; `dcd mcp` covers it) |
+
+### `dcd mcp`
+
+`dcd mcp` connects to the hosted server and passes its device tools through. It adds what only a local process can do: `install_app` takes `app_path` (a build on your machine, uploaded first) and `run` takes `path` (a flow file, or a directory uploaded as a bundle). It also serves the `dcd_*` tools below.
+
+Claude Code:
+
+```sh-session
+$ claude mcp add devicecloud -- npx -y @devicecloud.dev/dcd mcp
+```
+
+Other clients:
+
+```jsonc
+{
+  "mcpServers": {
+    "devicecloud": {
+      "command": "npx",
+      "args": ["-y", "@devicecloud.dev/dcd", "mcp"]
+    }
+  }
+}
+```
+
+If the CLI is installed globally, use `"command": "dcd", "args": ["mcp"]` instead.
+
+It signs in the same way as the CLI: run `dcd login` once, or set `DEVICE_CLOUD_API_KEY` in `env`. Add `--read-only` to the args (or set `DCD_MCP_READONLY=1`) to serve only the tools that change nothing. If the hosted server can't be reached, it serves the `dcd_*` tools only and says why on stderr.
+
+**Device tools:** `list_devices`, `start_device`, `get_device_status`, `install_app`, `launch_app`, `inspect_screen`, `take_screenshot`, `run`, `get_command_status`, `get_logs`, `request_human`, `get_human_status`, `stop_device`, and `cheat_sheet` (Maestro syntax for the agent).
+
+### Hosted
+
+Point an HTTP-capable client at the URL. It signs you in through the browser (OAuth), and you can disconnect it later under Settings → Connected apps.
+
+```sh-session
+$ claude mcp add --transport http devicecloud https://api.devicecloud.dev/mcp
+```
+
+### `dcd-mcp`
+
+The older server, with the `dcd_*` tools only. Add it to your MCP client config:
 
 ```jsonc
 {
@@ -56,7 +103,7 @@ Add it to your MCP client config:
 
 Auth is inherited from the CLI: set `DEVICE_CLOUD_API_KEY` as above, or run `dcd login` once and the server picks up the stored session. Point it at a non-prod environment with `DCD_API_URL`.
 
-**Tools**
+**`dcd_*` tools** (served by both `dcd mcp` and `dcd-mcp`)
 
 | Tool | What it does |
 | --- | --- |

package/dist/commands/device.d.ts

@@ -1,10 +1,16 @@
-import { type DeviceCatalogue, type DeviceScreenElement } from '../types/domain/device-session.types.js';
+import { type DeviceCatalogue, type DeviceScreenElement, type DeviceSession } from '../types/domain/device-session.types.js';
 /**
  * The platform a `--model` belongs to, from GET /device/models. Matches the
  * model id (iphone-16) or its name (iPhone 16), ignoring case. Unknown, or on
  * both platforms: a usage error that says to pass --platform.
  */
 export declare function platformOfModel(catalogue: DeviceCatalogue, model: string): 'android' | 'ios';
+/**
+ * The "Next steps" `dcd device start` prints. They follow the session: a
+ * device that isn't ready yet can't be inspected, so that comes first, and
+ * a session with no app gets the install step.
+ */
+export declare function startNextSteps(session: DeviceSession, hasApp: boolean): [string, string][];
 /** One element on one line: what to target it by, then its bounds. */
 export declare function formatElement(el: DeviceScreenElement): string;
 /** `data:image/jpeg;base64,...` to bytes and a file extension. */

package/dist/commands/device.js

@@ -159,6 +159,22 @@ export function platformOfModel(catalogue, model) {
     }
     throw new CliError(`"${model}" is a model on both iOS and Android. Pass --platform ios or --platform android.`);
 }
+/**
+ * The "Next steps" `dcd device start` prints. They follow the session: a
+ * device that isn't ready yet can't be inspected, so that comes first, and
+ * a session with no app gets the install step.
+ */
+export function startNextSteps(session, hasApp) {
+    const { id } = session;
+    const steps = [];
+    if (!USABLE_STATES.has(session.state)) {
+        steps.push(['check it is ready', `dcd device status ${id}`]);
+    }
+    if (!hasApp)
+        steps.push(['install an app', `dcd device install ${id} <app>`]);
+    steps.push(['inspect the screen', `dcd device inspect ${id}`], ['run a flow', `dcd device run ${id} flow.yaml`], ['stop', `dcd device stop ${id}`], ['all commands', 'dcd device --help']);
+    return steps;
+}
 const startSub = defineCommand({
     meta: { name: 'start', description: 'Start a device session' },
     args: {
@@ -289,11 +305,12 @@ const startSub = defineCommand({
                     logger.log(ui.section('Device session'));
                     printSession(session);
                     logger.log(ui.section('Next steps'));
-                    logger.log(ui.branch(ui.fields([
-                        ['inspect the screen', colors.highlight(`dcd device inspect ${session.id}`)],
-                        ['run a flow', colors.highlight(`dcd device run ${session.id} flow.yaml`)],
-                        ['stop', colors.highlight(`dcd device stop ${session.id}`)],
-                    ])));
+                    const hasApp = Boolean(installedId ?? uploadedId);
+                    const steps = startNextSteps(session, hasApp);
+                    logger.log(ui.branch(ui.fields(steps.map(([label, cmd]) => [label, colors.highlight(cmd)]))));
+                    if (!USABLE_STATES.has(session.state)) {
+                        logger.log(ui.info('Next time, `dcd device start --wait` waits until the device is ready.'));
+                    }
                 },
             };
         });
@@ -886,7 +903,7 @@ const openSub = defineCommand({
             const id = await resolveSessionId(ctx.apiUrl, ctx.auth, args.id);
             const { session } = await DeviceGateway.status(ctx.apiUrl, ctx.auth, id);
             // Only a person at a terminal gets a browser; a script gets the URL.
-            const opened = interactive(json) && openBrowser(session.monitor_url);
+            const opened = interactive(json) && (await openBrowser(session.monitor_url));
             return {
                 session,
                 data: { url: session.monitor_url, opened },

package/dist/commands/login.js

@@ -149,7 +149,7 @@ export const loginCommand = defineCommand({
             rows.push(ui.note('Open this URL in a browser to finish login:'), colors.highlight(loginUrl));
         }
         else {
-            const opened = openBrowser(loginUrl);
+            const opened = await openBrowser(loginUrl);
             rows.push(ui.note(opened
                 ? 'Opening your browser…'
                 : 'Could not launch a browser. Open this URL manually:'));

package/dist/commands/mcp.js

@@ -11,7 +11,7 @@ import { telemetry } from '../services/telemetry.service.js';
 export const mcpCommand = defineCommand({
     meta: {
         name: 'mcp',
-        description: 'Run the DeviceCloud MCP server on stdio (cloud tests and cloud devices)',
+        description: 'MCP server for AI agents, started by your MCP client (Claude, Cursor, VS Code)',
     },
     args: {
         'read-only': {

package/dist/mcp/bridge.js

@@ -10,8 +10,8 @@
  *   a bundle).
  *
  * Auth is the CLI's: an API key or a `dcd login` session (getContext). The
- * hosted endpoint accepts both. A session is renewed before it expires, and
- * the remote connection is remade with it.
+ * hosted endpoint accepts both. A session is renewed before it expires; the
+ * one shared connection re-reads the auth on every request (RemoteDevices).
  *
  * stdout is the JSON-RPC channel: everything else goes to stderr.
  */

package/dist/utils/browser.d.ts

@@ -1,10 +1,16 @@
 /**
  * Open `url` in the default browser. False if it isn't an http(s) URL or no
- * opener could be started.
+ * opener could be started (none installed, as on a headless box).
  *
  * Only http(s) is opened, so a URL can't name a local file or start with `-`
  * and be read as an option. No opener goes through a shell: Windows uses
  * rundll32, because `cmd /c start` parses the URL again and treats its `&`
  * as a command separator.
  */
-export declare function openBrowser(url: string): boolean;
+export declare function openBrowser(url: string): Promise<boolean>;
+/**
+ * Start `bin` detached. False if it couldn't be started. A missing program is
+ * reported as an 'error' event, not thrown, and with no listener it would
+ * crash the process, so this waits for 'spawn' or 'error' to know.
+ */
+export declare function startOpener(bin: string, args: string[]): Promise<boolean>;

package/dist/utils/browser.js

@@ -1,14 +1,14 @@
 import { spawn } from 'node:child_process';
 /**
  * Open `url` in the default browser. False if it isn't an http(s) URL or no
- * opener could be started.
+ * opener could be started (none installed, as on a headless box).
  *
  * Only http(s) is opened, so a URL can't name a local file or start with `-`
  * and be read as an option. No opener goes through a shell: Windows uses
  * rundll32, because `cmd /c start` parses the URL again and treats its `&`
  * as a command separator.
  */
-export function openBrowser(url) {
+export async function openBrowser(url) {
     let href;
     try {
         const parsed = new URL(url);
@@ -24,12 +24,25 @@ export function openBrowser(url) {
         : process.platform === 'win32'
             ? { bin: 'rundll32', args: ['url.dll,FileProtocolHandler', href] }
             : { bin: 'xdg-open', args: [href] };
-    try {
-        const child = spawn(cmd.bin, cmd.args, { detached: true, stdio: 'ignore' });
-        child.unref();
-        return true;
-    }
-    catch {
-        return false;
-    }
+    return startOpener(cmd.bin, cmd.args);
+}
+/**
+ * Start `bin` detached. False if it couldn't be started. A missing program is
+ * reported as an 'error' event, not thrown, and with no listener it would
+ * crash the process, so this waits for 'spawn' or 'error' to know.
+ */
+export function startOpener(bin, args) {
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(bin, args, { detached: true, stdio: 'ignore' });
+            child.once('spawn', () => {
+                child.unref();
+                resolve(true);
+            });
+            child.once('error', () => resolve(false));
+        }
+        catch {
+            resolve(false);
+        }
+    });
 }

package/package.json

@@ -68,7 +68,7 @@
     "test:unit": "node scripts/test-runner.mjs --unit",
     "typecheck": "tsc --noEmit -p tsconfig.test.json"
   },
-  "version": "5.11.0-beta.2",
+  "version": "5.11.0-beta.3",
   "bugs": {
     "url": "https://discord.gg/gm3mJwcNw8"
   },