@devicecloud.dev/dcd 5.11.0-beta.1 → 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

@@ -0,0 +1,36 @@
+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. */
+export declare function decodeDataUrl(dataUrl: string): {
+    bytes: Buffer;
+    ext: string;
+};
+/** `--env KEY=VALUE`, given once or several times. */
+export declare function parseEnvFlags(value: unknown): Record<string, string> | undefined;
+/** Every value of a repeatable flag; citty keeps only the last one. */
+export declare function collectFlagValues(flag: string, rawArgs: string[]): string[];
+/**
+ * citty drops a string flag's value when it starts with `-`, as a flow's
+ * first command does (`--yaml "- launchApp"`). Read it from argv instead.
+ */
+export declare function recoverFlagValue(flag: string, parsed: string | undefined, rawArgs: string[]): string | undefined;
+/**
+ * The lines of `next` that `prev` has not shown. Each fetch is the log's
+ * last N lines, so the overlap is the longest end of `prev` that `next`
+ * starts with. No overlap: everything in `next` is new.
+ */
+export declare function newLogLines(prev: string[], next: string[]): string[];
+export declare const deviceCommand: import("citty").CommandDef<import("citty").ArgsDef>;