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

package/README.md

@@ -50,26 +50,51 @@ There are three ways to connect:
 
 `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:
+**Set it up with `dcd mcp install`.** Install the CLI (see the top of this page), sign in, then add the server to your AI tool:
 
 ```sh-session
-$ claude mcp add devicecloud -- npx -y @devicecloud.dev/dcd mcp
+$ dcd login
+$ dcd mcp install cursor     # or claude-code, claude-desktop, vscode
 ```
 
-Other clients:
+Leave out the client name to pick from a list. Add `--read-only` for a server that only offers tools that change nothing, or `--print` to see what would be added without changing anything. For Claude Code and VS Code it runs `claude mcp add` and `code --add-mcp`. For Claude Desktop and Cursor it adds an entry to their JSON config file and keeps everything else in it. Restart the app afterwards.
+
+**Setting it up by hand.** Start dcd by its **full path**. Desktop apps such as Claude Desktop and Cursor are usually opened from the Dock or Start menu, so they don't see the PATH your shell sets up, and a bare `dcd` gives "command not found". The installer prints the path at the end; it's `~/.dcd/bin/dcd` by default, written out in full because config files don't expand `~`.
+
+Claude Desktop (`claude_desktop_config.json`) and Cursor (`~/.cursor/mcp.json`):
 
 ```jsonc
 {
   "mcpServers": {
     "devicecloud": {
-      "command": "npx",
-      "args": ["-y", "@devicecloud.dev/dcd", "mcp"]
+      "command": "/Users/you/.dcd/bin/dcd",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+VS Code (`.vscode/mcp.json`, or the user `mcp.json`) uses `servers` and a `type`:
+
+```jsonc
+{
+  "servers": {
+    "devicecloud": {
+      "type": "stdio",
+      "command": "/Users/you/.dcd/bin/dcd",
+      "args": ["mcp"]
     }
   }
 }
 ```
 
-If the CLI is installed globally, use `"command": "dcd", "args": ["mcp"]` instead.
+Claude Code, run from a terminal, does see your PATH:
+
+```sh-session
+$ claude mcp add --scope user devicecloud -- dcd mcp
+```
+
+If you use the npm package instead of the standalone binary, the command is `npx` with `"args": ["-y", "@devicecloud.dev/dcd", "mcp"]`. That needs Node 22 or newer on the app's PATH, and it checks npm each time it starts.
 
 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.
 

package/dist/commands/mcp.d.ts

@@ -1,7 +1,8 @@
 /**
  * `dcd mcp`: the MCP server over stdio, for MCP clients to launch. It serves
  * the dcd_* cloud-test tools and the device tools (see src/mcp/bridge.ts).
- * Nothing but JSON-RPC may reach stdout.
+ * Nothing but JSON-RPC may reach stdout. `dcd mcp install` adds it to a
+ * client's config.
  */
 export declare const mcpCommand: import("citty").CommandDef<{
     readonly 'read-only': {

package/dist/commands/mcp.js

@@ -1,12 +1,158 @@
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import * as p from '@clack/prompts';
 import { defineCommand } from 'citty';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { jsonFlag } from '../config/flags/output.flags.js';
 import { createBridgeServer } from '../mcp/bridge.js';
 import { isReadOnly, logStderr } from '../mcp/context.js';
 import { telemetry } from '../services/telemetry.service.js';
+import { apiKeyOverride } from '../utils/auth.js';
+import { canPrompt } from '../utils/ci.js';
+import { CliError, getInstallMethod, logger } from '../utils/cli.js';
+import { readConfig } from '../utils/config-store.js';
+import { CLIENT_LABELS, claudeCodeAddArgs, clientConfigPath, MCP_CLIENTS, mcpServersSnippet, SERVER_NAME, serverLaunch, shellLine, stableNodePath, vscodeAddArgs, writeClientConfig, } from '../utils/mcp-install.js';
+import { colors } from '../utils/styling.js';
+import { ui } from '../utils/ui.js';
+const RELOAD_HINT = {
+    'claude-code': 'Start a new Claude Code session to load it.',
+    'claude-desktop': 'Restart Claude Desktop to load it.',
+    cursor: 'Restart Cursor, or reload its MCP servers, to load it.',
+    vscode: 'VS Code asks you to trust the server the first time it starts.',
+};
+/** Run another tool's CLI without a shell. Undefined when it isn't installed. */
+function runTool(command, args) {
+    const result = spawnSync(command, args, { encoding: 'utf8' });
+    if (result.error?.code === 'ENOENT')
+        return undefined;
+    return { ok: result.status === 0, output: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim() };
+}
+async function pickClient(value) {
+    if (value) {
+        if (MCP_CLIENTS.includes(value))
+            return value;
+        throw new CliError(`Unknown client "${value}". Pick one of: ${MCP_CLIENTS.join(', ')}.`);
+    }
+    if (!canPrompt()) {
+        throw new CliError(`Say which client to set up: dcd mcp install <${MCP_CLIENTS.join('|')}>.`);
+    }
+    const picked = await p.select({
+        message: 'Which AI tool should use DeviceCloud?',
+        options: MCP_CLIENTS.map((c) => ({ value: c, label: CLIENT_LABELS[c] })),
+    });
+    if (p.isCancel(picked))
+        throw new CliError('Cancelled.');
+    return picked;
+}
+/** Add the server to `client`, through its CLI or its JSON config file. */
+function install(client, launch) {
+    if (client === 'claude-code') {
+        const add = claudeCodeAddArgs(launch);
+        const removed = runTool('claude', ['mcp', 'remove', '--scope', 'user', SERVER_NAME]);
+        if (!removed) {
+            throw new CliError(`The claude command isn't on PATH. Run this where it is:\n  ${shellLine('claude', add)}`);
+        }
+        const added = runTool('claude', add);
+        if (!added.ok)
+            throw new CliError(`claude mcp add failed: ${added.output}`);
+        return { target: shellLine('claude', add), replaced: removed.ok };
+    }
+    if (client === 'vscode') {
+        const add = vscodeAddArgs(launch);
+        const added = runTool('code', add);
+        if (!added) {
+            throw new CliError(`The code command isn't on PATH (in VS Code: "Shell Command: Install 'code' command in PATH"). Or run:\n  ${shellLine('code', add)}`);
+        }
+        if (!added.ok)
+            throw new CliError(`code --add-mcp failed: ${added.output}`);
+        return { target: shellLine('code', add), replaced: false };
+    }
+    const file = clientConfigPath(client);
+    if (!file) {
+        throw new CliError(`${CLIENT_LABELS[client]} has no known config file on ${process.platform}. Add this to it by hand:\n${JSON.stringify(mcpServersSnippet(launch), null, 2)}`);
+    }
+    return { target: file, ...writeClientConfig(file, launch) };
+}
+/** What `--print` shows: the command to run, or the file and the entry for it. */
+function preview(client, launch) {
+    if (client === 'claude-code')
+        return { target: 'command', text: shellLine('claude', claudeCodeAddArgs(launch)) };
+    if (client === 'vscode')
+        return { target: 'command', text: shellLine('code', vscodeAddArgs(launch)) };
+    return {
+        target: clientConfigPath(client) ?? 'your MCP config file',
+        text: JSON.stringify(mcpServersSnippet(launch), null, 2),
+    };
+}
+const installSub = defineCommand({
+    meta: {
+        name: 'install',
+        description: 'Add the DeviceCloud MCP server to Claude Code, Claude Desktop, Cursor or VS Code',
+    },
+    args: {
+        client: {
+            type: 'positional',
+            required: false,
+            description: `One of ${MCP_CLIENTS.join(', ')}. Asked when left out.`,
+        },
+        'read-only': {
+            type: 'boolean',
+            default: false,
+            description: 'Have the server offer only tools that change nothing',
+        },
+        print: {
+            type: 'boolean',
+            default: false,
+            description: 'Show what would be added, and change nothing',
+        },
+        json: jsonFlag,
+    },
+    async run({ args }) {
+        telemetry.setCommand('mcp install');
+        const client = await pickClient(args.client);
+        const installMethod = getInstallMethod();
+        const launch = serverLaunch({
+            installMethod,
+            execPath: installMethod === 'binary' ? process.execPath : stableNodePath(process.execPath),
+            // As started, not resolved: a global npm install's bin link keeps
+            // working across `npm install -g` upgrades.
+            scriptPath: process.argv[1] ? path.resolve(process.argv[1]) : undefined,
+            readOnly: Boolean(args['read-only']),
+        });
+        if (args.print) {
+            const shown = preview(client, launch);
+            if (args.json) {
+                logger.json({ status: 'SUCCESS', client, launch, target: shown.target, text: shown.text, written: false });
+                return;
+            }
+            logger.log(ui.section(`${CLIENT_LABELS[client]} config`));
+            logger.log(ui.branch(ui.fields([['add to', shown.target]])));
+            logger.log(shown.text);
+            return;
+        }
+        const result = install(client, launch);
+        const signedIn = Boolean(readConfig()?.session) || Boolean(apiKeyOverride());
+        if (args.json) {
+            logger.json({ status: 'SUCCESS', client, launch, target: result.target, replaced: result.replaced, written: true, signedIn });
+            return;
+        }
+        logger.log(ui.success(`${result.replaced ? 'Updated' : 'Added'} DeviceCloud in ${CLIENT_LABELS[client]}`));
+        const rows = [
+            [client === 'claude-code' || client === 'vscode' ? 'ran' : 'wrote', result.target],
+            ['starts', colors.highlight(shellLine(launch.command, launch.args))],
+        ];
+        logger.log(ui.branch(ui.fields(rows)));
+        logger.log(ui.info(RELOAD_HINT[client]));
+        if (!signedIn) {
+            logger.log(ui.warn(`Not signed in. Run ${colors.highlight('dcd login')} so the server can use your account.`));
+        }
+    },
+});
 /**
  * `dcd mcp`: the MCP server over stdio, for MCP clients to launch. It serves
  * the dcd_* cloud-test tools and the device tools (see src/mcp/bridge.ts).
- * Nothing but JSON-RPC may reach stdout.
+ * Nothing but JSON-RPC may reach stdout. `dcd mcp install` adds it to a
+ * client's config.
  */
 export const mcpCommand = defineCommand({
     meta: {
@@ -20,7 +166,12 @@ export const mcpCommand = defineCommand({
             description: 'Serve only tools that change nothing (also DCD_MCP_READONLY=1)',
         },
     },
-    async run() {
+    subCommands: { install: installSub },
+    async run({ rawArgs }) {
+        // citty runs this after a subcommand too; `dcd mcp install` must not
+        // then start a server.
+        if (rawArgs.some((arg) => !arg.startsWith('-')))
+            return;
         telemetry.setCommand('mcp');
         const server = await createBridgeServer();
         await server.connect(new StdioServerTransport());

package/dist/utils/mcp-install.d.ts

@@ -0,0 +1,50 @@
+import { type InstallMethod } from './cli.js';
+/** The server's name in every client's config. */
+export declare const SERVER_NAME = "devicecloud";
+export declare const MCP_CLIENTS: readonly ["claude-code", "claude-desktop", "cursor", "vscode"];
+export type McpClient = (typeof MCP_CLIENTS)[number];
+export declare const CLIENT_LABELS: Record<McpClient, string>;
+export interface ServerLaunch {
+    command: string;
+    args: string[];
+}
+/**
+ * The command that starts `dcd mcp` from this install. The standalone binary
+ * is one file. An npm install is node plus the CLI's script; both are named
+ * by full path, so a different node on PATH, or none, doesn't matter.
+ */
+export declare function serverLaunch(opts: {
+    installMethod: InstallMethod;
+    execPath: string;
+    scriptPath: string | undefined;
+    readOnly: boolean;
+}): ServerLaunch;
+/**
+ * The `node` on PATH that is this same node, else `execPath`. execPath is
+ * the resolved file, which can be a versioned folder (Homebrew's Cellar) that
+ * an upgrade removes; the PATH entry (/opt/homebrew/bin/node) survives it.
+ */
+export declare function stableNodePath(execPath: string, pathEnv?: string | undefined, platform?: NodeJS.Platform): string;
+/**
+ * The JSON config file a client reads, or undefined when it is configured
+ * through its own CLI (Claude Code, VS Code) or has no known location here.
+ */
+export declare function clientConfigPath(client: McpClient, platform?: NodeJS.Platform, home?: string, env?: NodeJS.ProcessEnv): string | undefined;
+/** The `mcpServers` block Claude Desktop and Cursor read, with ours in it. */
+export declare function mcpServersSnippet(launch: ServerLaunch): {
+    mcpServers: Record<string, ServerLaunch>;
+};
+/**
+ * Add our entry to a client's JSON config and write it back, keeping every
+ * other key. Returns whether an entry was already there (and is replaced).
+ * A file that isn't plain JSON (comments, say) is left alone.
+ */
+export declare function writeClientConfig(file: string, launch: ServerLaunch): {
+    replaced: boolean;
+};
+/** `claude mcp add` arguments, at user scope so it works in every project. */
+export declare function claudeCodeAddArgs(launch: ServerLaunch): string[];
+/** `code --add-mcp` arguments, which add the server to the VS Code user profile. */
+export declare function vscodeAddArgs(launch: ServerLaunch): string[];
+/** A command line to show a person, quoting the parts that need it. */
+export declare function shellLine(command: string, args: string[]): string;

package/dist/utils/mcp-install.js

@@ -0,0 +1,132 @@
+/**
+ * What `dcd mcp install` writes: how an MCP client starts this dcd, and the
+ * config entry each client wants.
+ *
+ * Desktop apps (Claude Desktop, Cursor) are usually started from the Dock or
+ * Start menu, so they don't read the shell rc that put dcd on PATH. Every
+ * entry therefore names this dcd by its full path, never a bare `dcd`.
+ */
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { CliError } from './cli.js';
+/** The server's name in every client's config. */
+export const SERVER_NAME = 'devicecloud';
+export const MCP_CLIENTS = ['claude-code', 'claude-desktop', 'cursor', 'vscode'];
+export const CLIENT_LABELS = {
+    'claude-code': 'Claude Code',
+    'claude-desktop': 'Claude Desktop',
+    cursor: 'Cursor',
+    vscode: 'VS Code',
+};
+/**
+ * The command that starts `dcd mcp` from this install. The standalone binary
+ * is one file. An npm install is node plus the CLI's script; both are named
+ * by full path, so a different node on PATH, or none, doesn't matter.
+ */
+export function serverLaunch(opts) {
+    const tail = ['mcp', ...(opts.readOnly ? ['--read-only'] : [])];
+    if (opts.installMethod === 'binary')
+        return { command: opts.execPath, args: tail };
+    if (!opts.scriptPath || /\.[cm]?ts$/.test(opts.scriptPath)) {
+        throw new CliError('Run `dcd mcp install` from an installed dcd, not from source: the config it writes must start a built dcd.');
+    }
+    if (opts.scriptPath.split(/[/\\]/).includes('_npx')) {
+        throw new CliError('This dcd runs from the npx cache, which gets cleared, so a config pointing at it would stop working. Install dcd (curl -fsSL https://get.devicecloud.dev/install.sh | sh, or npm install -g @devicecloud.dev/dcd), then run `dcd mcp install`.');
+    }
+    return { command: opts.execPath, args: [opts.scriptPath, ...tail] };
+}
+/**
+ * The `node` on PATH that is this same node, else `execPath`. execPath is
+ * the resolved file, which can be a versioned folder (Homebrew's Cellar) that
+ * an upgrade removes; the PATH entry (/opt/homebrew/bin/node) survives it.
+ */
+export function stableNodePath(execPath, pathEnv = process.env.PATH, platform = process.platform) {
+    const exe = platform === 'win32' ? 'node.exe' : 'node';
+    let target;
+    try {
+        target = realpathSync(execPath);
+    }
+    catch {
+        return execPath;
+    }
+    for (const dir of (pathEnv ?? '').split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, exe);
+        try {
+            if (realpathSync(candidate) === target)
+                return candidate;
+        }
+        catch {
+            // not there
+        }
+    }
+    return execPath;
+}
+/**
+ * The JSON config file a client reads, or undefined when it is configured
+ * through its own CLI (Claude Code, VS Code) or has no known location here.
+ */
+export function clientConfigPath(client, platform = process.platform, home = os.homedir(), env = process.env) {
+    if (client === 'cursor')
+        return path.join(home, '.cursor', 'mcp.json');
+    if (client !== 'claude-desktop')
+        return undefined;
+    if (platform === 'darwin') {
+        return path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+    }
+    if (platform === 'win32') {
+        const appData = env.APPDATA ?? path.join(home, 'AppData', 'Roaming');
+        return path.join(appData, 'Claude', 'claude_desktop_config.json');
+    }
+    return undefined;
+}
+/** The `mcpServers` block Claude Desktop and Cursor read, with ours in it. */
+export function mcpServersSnippet(launch) {
+    return { mcpServers: { [SERVER_NAME]: launch } };
+}
+/**
+ * Add our entry to a client's JSON config and write it back, keeping every
+ * other key. Returns whether an entry was already there (and is replaced).
+ * A file that isn't plain JSON (comments, say) is left alone.
+ */
+export function writeClientConfig(file, launch) {
+    let config = {};
+    if (existsSync(file)) {
+        const text = readFileSync(file, 'utf8');
+        if (text.trim()) {
+            try {
+                const parsed = JSON.parse(text);
+                if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                    throw new Error('not an object');
+                config = parsed;
+            }
+            catch {
+                throw new CliError(`${file} isn't plain JSON, so it was left as it is. Add this to it by hand:\n${JSON.stringify(mcpServersSnippet(launch), null, 2)}`);
+            }
+        }
+    }
+    const servers = config.mcpServers && typeof config.mcpServers === 'object' && !Array.isArray(config.mcpServers)
+        ? config.mcpServers
+        : {};
+    const replaced = SERVER_NAME in servers;
+    config.mcpServers = { ...servers, [SERVER_NAME]: launch };
+    mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`);
+    renameSync(tmp, file);
+    return { replaced };
+}
+/** `claude mcp add` arguments, at user scope so it works in every project. */
+export function claudeCodeAddArgs(launch) {
+    return ['mcp', 'add', '--scope', 'user', SERVER_NAME, '--', launch.command, ...launch.args];
+}
+/** `code --add-mcp` arguments, which add the server to the VS Code user profile. */
+export function vscodeAddArgs(launch) {
+    return ['--add-mcp', JSON.stringify({ name: SERVER_NAME, ...launch })];
+}
+/** A command line to show a person, quoting the parts that need it. */
+export function shellLine(command, args) {
+    return [command, ...args].map((part) => (/^[\w@%+=:,./-]+$/.test(part) ? part : `'${part.replaceAll("'", String.raw `'\''`)}'`)).join(' ');
+}

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.3",
+  "version": "5.11.0-beta.4",
   "bugs": {
     "url": "https://discord.gg/gm3mJwcNw8"
   },