@devicecloud.dev/dcd 5.0.0-beta.0 → 5.0.0-beta.1

package/README.md

@@ -34,6 +34,41 @@ $ dcd cloud --apiKey <apiKey> <appFile> .myFlows/
 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.
+
+Add it to your MCP client config:
+
+```jsonc
+{
+  "mcpServers": {
+    "devicecloud": {
+      "command": "npx",
+      "args": ["-y", "@devicecloud.dev/dcd", "dcd-mcp"],
+      "env": { "DEVICE_CLOUD_API_KEY": "<your-api-key>" }
+    }
+  }
+}
+```
+
+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**
+
+| Tool | What it does |
+| --- | --- |
+| `dcd_list_devices` | Discover available devices, OS versions, and Maestro versions |
+| `dcd_list_runs` | List recent test runs (filter by name/date, paginated) |
+| `dcd_get_status` | Get the status + per-test results of a run |
+| `dcd_download_artifacts` | Download a run's artifacts/report to disk |
+| `dcd_run_cloud_test` | Submit a flow to run on the cloud (**billable**) |
+
+**Read-only mode.** `dcd_run_cloud_test` consumes test minutes, so it is annotated as non-read-only/destructive (clients can prompt before calling it). To hide it entirely — recommended for autonomous or untrusted agents — pass `--read-only` in `args`, or set `DCD_MCP_READONLY=1` in `env`.
+
+By default `dcd_run_cloud_test` is async: it returns an `uploadId` immediately, which you poll with `dcd_get_status`. Pass `wait: true` (bounded by `waitTimeoutSeconds`) to block until completion, or `dryRun: true` to preview the flows without submitting.
+
+
 ## Development
 
 Requires Node 22+ and [pnpm](https://pnpm.io). `pnpm install` builds the CLI and installs the git hooks automatically.

package/dist/commands/artifacts.d.ts

@@ -1,44 +1,44 @@
 export declare const artifactsCommand: import("citty").CommandDef<{
-    debug: {
-        type: "boolean";
-        default: false;
-        description: string;
+    readonly debug: {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly description: "Enable detailed debug logging for troubleshooting issues";
     };
-    'upload-id': {
-        type: "string";
-        required: true;
-        description: string;
+    readonly 'upload-id': {
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "UUID of the completed upload to download artifacts for";
     };
-    'download-artifacts': {
-        type: "string";
-        description: string;
+    readonly 'download-artifacts': {
+        readonly type: "string";
+        readonly description: "Download a zip containing the logs, screenshots and videos for this run (options: ALL, FAILED)";
     };
-    'artifacts-path': {
-        type: "string";
-        description: string;
+    readonly 'artifacts-path': {
+        readonly type: "string";
+        readonly description: "Custom file path for downloaded artifacts (default: ./artifacts.zip). Requires --download-artifacts.";
     };
-    report: {
-        type: "string";
-        description: string;
+    readonly report: {
+        readonly type: "string";
+        readonly description: "Download a test report in the specified format (options: allure, html, html-detailed, junit)";
     };
-    'allure-path': {
-        type: "string";
-        description: string;
+    readonly 'allure-path': {
+        readonly type: "string";
+        readonly description: "Custom file path for downloaded Allure report (default: ./report.html)";
     };
-    'html-path': {
-        type: "string";
-        description: string;
+    readonly 'html-path': {
+        readonly type: "string";
+        readonly description: "Custom file path for downloaded HTML report (default: ./report.html)";
     };
-    'junit-path': {
-        type: "string";
-        description: string;
+    readonly 'junit-path': {
+        readonly type: "string";
+        readonly description: "Custom file path for downloaded JUnit report (default: ./report.xml)";
     };
-    'api-key': {
+    readonly 'api-key': {
         readonly type: "string";
         readonly alias: ["apiKey"];
         readonly description: "API key for devicecloud.dev (find this in the console UI). You can also set the DEVICE_CLOUD_API_KEY environment variable.";
     };
-    'api-url': {
+    readonly 'api-url': {
         readonly type: "string";
         readonly alias: ["apiURL", "apiUrl"];
         readonly description: "API base URL (defaults to the URL stored by `dcd login`, else prod)";

package/dist/commands/artifacts.js

@@ -1,21 +1,18 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.artifactsCommand = void 0;
-const citty_1 = require("citty");
-const api_flags_1 = require("../config/flags/api.flags");
-const report_download_service_1 = require("../services/report-download.service");
-const auth_1 = require("../utils/auth");
-const cli_1 = require("../utils/cli");
-const config_store_1 = require("../utils/config-store");
+import { defineCommand } from 'citty';
+import { apiFlags } from '../config/flags/api.flags.js';
+import { ReportDownloadService } from '../services/report-download.service.js';
+import { resolveAuth } from '../utils/auth.js';
+import { CliError, logger, validateEnum } from '../utils/cli.js';
+import { resolveApiUrl } from '../utils/config-store.js';
 const DOWNLOAD_OPTIONS = ['ALL', 'FAILED'];
 const REPORT_OPTIONS = ['allure', 'html', 'html-detailed', 'junit'];
-exports.artifactsCommand = (0, citty_1.defineCommand)({
+export const artifactsCommand = defineCommand({
     meta: {
         name: 'artifacts',
         description: 'Download artifacts or reports for a completed test run',
     },
     args: {
-        ...api_flags_1.apiFlags,
+        ...apiFlags,
         debug: {
             type: 'boolean',
             default: false,
@@ -53,23 +50,23 @@ exports.artifactsCommand = (0, citty_1.defineCommand)({
     },
     async run({ args }) {
         const apiKeyFlag = args['api-key'];
-        const apiUrl = (0, config_store_1.resolveApiUrl)(args['api-url']);
+        const apiUrl = resolveApiUrl(args['api-url']);
         const debug = Boolean(args.debug);
         const uploadId = args['upload-id'];
-        const downloadArtifacts = (0, cli_1.validateEnum)(args['download-artifacts'], DOWNLOAD_OPTIONS, 'download-artifacts');
+        const downloadArtifacts = validateEnum(args['download-artifacts'], DOWNLOAD_OPTIONS, 'download-artifacts');
         const artifactsPath = args['artifacts-path'];
-        const report = (0, cli_1.validateEnum)(args.report, REPORT_OPTIONS, 'report');
+        const report = validateEnum(args.report, REPORT_OPTIONS, 'report');
         const allurePath = args['allure-path'];
         const htmlPath = args['html-path'];
         const junitPath = args['junit-path'];
-        const auth = await (0, auth_1.resolveAuth)({ apiKeyFlag });
+        const auth = await resolveAuth({ apiKeyFlag });
         if (downloadArtifacts && report) {
-            throw new cli_1.CliError('--download-artifacts cannot also be provided when using --report (flags are mutually exclusive).');
+            throw new CliError('--download-artifacts cannot also be provided when using --report (flags are mutually exclusive).');
         }
         if (!downloadArtifacts && !report) {
-            throw new cli_1.CliError('Either --download-artifacts or --report must be specified.');
+            throw new CliError('Either --download-artifacts or --report must be specified.');
         }
-        const service = new report_download_service_1.ReportDownloadService();
+        const service = new ReportDownloadService();
         if (downloadArtifacts) {
             await service.downloadArtifacts({
                 auth,
@@ -77,9 +74,9 @@ exports.artifactsCommand = (0, citty_1.defineCommand)({
                 artifactsPath: artifactsPath ?? './artifacts.zip',
                 debug,
                 downloadType: downloadArtifacts,
-                logger: (m) => cli_1.logger.log(m),
+                logger: (m) => logger.log(m),
                 uploadId,
-                warnLogger: (m) => cli_1.logger.warn(m),
+                warnLogger: (m) => logger.warn(m),
             });
         }
         if (report) {
@@ -90,12 +87,12 @@ exports.artifactsCommand = (0, citty_1.defineCommand)({
                 debug,
                 htmlPath,
                 junitPath,
-                logger: (m) => cli_1.logger.log(m),
+                logger: (m) => logger.log(m),
                 reportType: report,
                 uploadId,
-                warnLogger: (m) => cli_1.logger.warn(m),
+                warnLogger: (m) => logger.warn(m),
             });
         }
     },
 });
-exports.default = exports.artifactsCommand;
+export default artifactsCommand;

package/dist/commands/cloud.d.ts

@@ -11,227 +11,227 @@
  * Replaces `maestro cloud` with DeviceCloud-specific functionality.
  */
 export declare const cloudCommand: import("citty").CommandDef<{
-    firstFile: {
-        type: "positional";
-        required: false;
-        description: string;
+    readonly firstFile: {
+        readonly type: "positional";
+        readonly required: false;
+        readonly description: "The binary file of the app to run your flow against, e.g. test.apk for android or test.app/.zip for ios";
     };
-    secondFile: {
-        type: "positional";
-        required: false;
-        description: string;
+    readonly secondFile: {
+        readonly type: "positional";
+        readonly required: false;
+        readonly description: "The flow file to run against the app, e.g. test.yaml";
     };
-    'artifacts-path': {
+    readonly 'artifacts-path': {
         readonly type: "string";
         readonly description: "Custom file path for downloaded artifacts (default: ./artifacts.zip). Requires --download-artifacts.";
     };
-    'junit-path': {
+    readonly 'junit-path': {
         readonly type: "string";
         readonly description: "Custom file path for downloaded JUnit report (requires --report junit, default: ./report.xml)";
     };
-    'allure-path': {
+    readonly 'allure-path': {
         readonly type: "string";
         readonly description: "Custom file path for downloaded Allure report (requires --report allure, default: ./report.html)";
     };
-    'html-path': {
+    readonly 'html-path': {
         readonly type: "string";
         readonly description: "Custom file path for downloaded HTML report (requires --report html, default: ./report.html)";
     };
-    async: {
+    readonly async: {
         readonly type: "boolean";
         readonly description: "Immediately return (exit code 0) from the command without waiting for the results of the run (useful for saving CI minutes)";
     };
-    debug: {
+    readonly debug: {
         readonly type: "boolean";
         readonly default: false;
         readonly description: "Enable detailed debug logging for troubleshooting issues";
     };
-    'download-artifacts': {
+    readonly 'download-artifacts': {
         readonly type: "string";
         readonly description: "Download a zip containing the logs, screenshots and videos for each result in this run (options: ALL, FAILED)";
     };
-    'dry-run': {
+    readonly 'dry-run': {
         readonly type: "boolean";
         readonly default: false;
         readonly description: "Simulate the run without actually triggering the upload/test, useful for debugging workflow issues.";
     };
-    json: {
+    readonly json: {
         readonly type: "boolean";
         readonly description: "Output results in JSON format. Exit codes: 0 on success, 2 if the test run fails, 1 on CLI/infrastructure errors";
     };
-    'json-file': {
+    readonly 'json-file': {
         readonly type: "boolean";
         readonly description: "Write JSON output to a file. File will be called <upload_id>_dcd.json unless you supply the --json-file-name flag - note: exits with code 0 even if the test run fails (CLI/infrastructure errors still exit 1)";
     };
-    'json-file-name': {
+    readonly 'json-file-name': {
         readonly type: "string";
         readonly description: "A custom name for the JSON file (can also include relative path). Requires --json-file.";
     };
-    quiet: {
+    readonly quiet: {
         readonly type: "boolean";
         readonly alias: ["q"];
         readonly default: false;
         readonly description: "Quieter console output that won't provide progress updates";
     };
-    report: {
+    readonly report: {
         readonly type: "string";
         readonly alias: ["format"];
         readonly description: "Generate and download test reports in the specified format (options: allure, junit, html, html-detailed). Use \"allure\" for a complete HTML report.";
     };
-    branch: {
+    readonly branch: {
         readonly type: "string";
         readonly description: "Git branch name for this run (stored as gh_branch metadata)";
     };
-    'commit-sha': {
+    readonly 'commit-sha': {
         readonly type: "string";
         readonly description: "Git commit SHA for this run (stored as gh_sha metadata)";
     };
-    'repo-name': {
+    readonly 'repo-name': {
         readonly type: "string";
         readonly description: "Repository in owner/repo format (stored as gh_repo metadata, e.g. \"acme/my-app\")";
     };
-    'pr-number': {
+    readonly 'pr-number': {
         readonly type: "string";
         readonly description: "Pull request number for this run (stored as gh_pr_number metadata)";
     };
-    'pr-url': {
+    readonly 'pr-url': {
         readonly type: "string";
         readonly description: "Pull request URL for this run (stored as gh_pr_url metadata)";
     };
-    config: {
+    readonly config: {
         readonly type: "string";
         readonly description: "Path to custom config.yaml file. If not provided, defaults to config.yaml in root flows folders.";
         readonly valueHint: "path";
     };
-    'exclude-flows': {
+    readonly 'exclude-flows': {
         readonly type: "string";
         readonly description: "Sub directories to ignore when building the flow file list (comma-separated, may be repeated)";
     };
-    'exclude-tags': {
+    readonly 'exclude-tags': {
         readonly type: "string";
         readonly description: "Flows which have these tags will be excluded from the run (comma-separated, may be repeated)";
     };
-    flows: {
+    readonly flows: {
         readonly type: "string";
         readonly description: "The path to the flow file or folder containing your flows";
     };
-    'include-tags': {
+    readonly 'include-tags': {
         readonly type: "string";
         readonly description: "Only flows which have these tags will be included in the run (comma-separated, may be repeated)";
     };
-    'maestro-version': {
+    readonly 'maestro-version': {
         readonly type: "string";
         readonly alias: ["maestroVersion"];
         readonly description: "Maestro version to run your flow against. Use \"latest\" for the most recent version. See https://docs.devicecloud.dev/configuration/maestro-versions for supported versions.";
     };
-    retry: {
+    readonly retry: {
         readonly type: "string";
         readonly description: "Automatically retry the run up to the number of times specified (same as pressing retry in the UI) - this is free of charge";
     };
-    'runner-type': {
+    readonly 'runner-type': {
         readonly type: "string";
         readonly default: "default";
         readonly description: "[experimental] The type of runner to use (options: default, m4, m1, gpu1, cpu1) - note: anything other than default or cpu1 will incur premium pricing tiers, see https://docs.devicecloud.dev/configuration/runner-type for more information.";
     };
-    env: {
+    readonly env: {
         readonly type: "string";
         readonly alias: ["e"];
         readonly description: "One or more environment variables to inject into your flows (format: KEY=VALUE, may be repeated)";
         readonly valueHint: "KEY=VALUE";
     };
-    metadata: {
+    readonly metadata: {
         readonly type: "string";
         readonly alias: ["m"];
         readonly description: "Arbitrary key-value metadata to include with your test run (format: key=value, may be repeated)";
     };
-    mitmHost: {
+    readonly mitmHost: {
         readonly type: "string";
         readonly description: "used for mitmproxy support, enterprise only, contact support if interested";
     };
-    mitmPath: {
+    readonly mitmPath: {
         readonly type: "string";
         readonly description: "used for mitmproxy support, enterprise only, contact support if interested";
     };
-    'moropo-v1-api-key': {
+    readonly 'moropo-v1-api-key': {
         readonly type: "string";
         readonly description: "API key for Moropo v1 integration";
     };
-    name: {
+    readonly name: {
         readonly type: "string";
         readonly description: "A custom name for your upload (useful for tagging commits etc)";
     };
-    'android-api-level': {
+    readonly 'android-api-level': {
         readonly type: "string";
         readonly description: `[Android only] Android API level to run your flow against (options: ${string})`;
     };
-    'android-device': {
+    readonly 'android-device': {
         readonly type: "string";
         readonly description: `[Android only] Android device to run your flow against (options: ${string})`;
     };
-    'device-locale': {
+    readonly 'device-locale': {
         readonly type: "string";
         readonly description: "Locale that will be set to a device, ISO-639-1 code and uppercase ISO-3166-1 code e.g. \"de_DE\" for Germany";
     };
-    'google-play': {
+    readonly 'google-play': {
         readonly type: "boolean";
         readonly default: false;
         readonly description: "[Android only] Run your flow against Google Play devices";
     };
-    'ios-device': {
+    readonly 'ios-device': {
         readonly type: "string";
         readonly description: `[iOS only] iOS device to run your flow against (options: ${string})`;
     };
-    'ios-version': {
+    readonly 'ios-version': {
         readonly type: "string";
         readonly description: `[iOS only] iOS version to run your flow against (options: ${string})`;
     };
-    orientation: {
+    readonly orientation: {
         readonly type: "string";
         readonly description: "[Android only] The orientation of the device to run your flow against (0 = portrait, 90 = landscape)";
     };
-    'show-crosshairs': {
+    readonly 'show-crosshairs': {
         readonly type: "boolean";
         readonly default: false;
         readonly description: "[Android only] Display crosshairs for screen interactions during test execution";
     };
-    'maestro-chrome-onboarding': {
+    readonly 'maestro-chrome-onboarding': {
         readonly type: "boolean";
         readonly default: false;
         readonly description: "[Android only] Force Maestro-based Chrome onboarding - note: this will slow your tests but can fix browser related crashes. See https://docs.devicecloud.dev/advanced/chrome-onboarding for more information.";
     };
-    'android-no-snapshot': {
+    readonly 'android-no-snapshot': {
         readonly type: "boolean";
         readonly default: false;
         readonly description: "[Android only] Force cold boot instead of using snapshot boot. This is automatically enabled for API 35+ but can be used to force cold boot on older API levels.";
     };
-    'disable-animations': {
+    readonly 'disable-animations': {
         readonly type: "boolean";
         readonly default: false;
         readonly description: "Disable device animations during test execution. On Android, disables system animation scales. On iOS, enables Reduce Motion. Reduces CPU load and may improve test reliability.";
     };
-    'app-binary-id': {
+    readonly 'app-binary-id': {
         readonly type: "string";
         readonly description: "The ID of the app binary previously uploaded to devicecloud.dev";
     };
-    'app-file': {
+    readonly 'app-file': {
         readonly type: "string";
         readonly description: "App binary to run your flows against";
         readonly valueHint: "path";
     };
-    'app-url': {
+    readonly 'app-url': {
         readonly type: "string";
         readonly description: "Signed URL to an Expo iOS build (.tar.gz). The archive is downloaded and extracted automatically. Expo signed URLs expire after ~1 hour.";
     };
-    'ignore-sha-check': {
+    readonly 'ignore-sha-check': {
         readonly type: "boolean";
         readonly description: "Ignore the sha hash check and upload the binary regardless of whether it already exists (not recommended)";
     };
-    'api-key': {
+    readonly 'api-key': {
         readonly type: "string";
         readonly alias: ["apiKey"];
         readonly description: "API key for devicecloud.dev (find this in the console UI). You can also set the DEVICE_CLOUD_API_KEY environment variable.";
     };
-    'api-url': {
+    readonly 'api-url': {
         readonly type: "string";
         readonly alias: ["apiURL", "apiUrl"];
         readonly description: "API base URL (defaults to the URL stored by `dcd login`, else prod)";