feat: expose semantic MCP tools

Author: thymikee

README.md

@@ -83,7 +83,7 @@ Snapshots assign refs like `@e1`, `@e2`, and `@e3` to elements on the current sc
 
 ## Next Steps
 
-- **Set up your agent**: run the CLI from Cursor, Codex, Claude Code, Windsurf, or another agent terminal. For skills, rules, MCP discovery, and client-specific setup, see [AI Agent Setup](https://incubator.callstack.com/agent-device/docs/agent-setup).
+- **Set up your agent**: run the CLI from Cursor, Codex, Claude Code, Windsurf, or another agent terminal. For skills, rules, direct MCP tools, and client-specific setup, see [AI Agent Setup](https://incubator.callstack.com/agent-device/docs/agent-setup).
 - **Try the sample app**: clone the repo and run the bundled Expo fixture when you want a guided first dogfood run with screenshots, replay, and performance evidence. See [Quick Start](https://incubator.callstack.com/agent-device/docs/quick-start).
 - **Go deeper**: use [Commands](https://incubator.callstack.com/agent-device/docs/commands), [Replay & E2E](https://incubator.callstack.com/agent-device/docs/replay-e2e), and [Debugging & Profiling](https://incubator.callstack.com/agent-device/docs/debugging-profiling) for production workflows.
 

docs/prds/semantic-command-contracts-for-cli-node-mcp.md

@@ -24,25 +24,17 @@ test('command catalog owns daemon routing groups', () => {
   assert.equal(DAEMON_COMMAND_GROUPS.replay.has(PUBLIC_COMMANDS.test), true);
 });
 
-test('wait codec preserves CLI bare text and client selector forms', () => {
+test('wait codec preserves CLI bare text forms', () => {
   const options = waitCommandCodec.decode(['Continue', '1500'], BASE_FLAGS);
   assert.equal(options.text, 'Continue');
   assert.equal(options.timeoutMs, 1500);
-  assert.deepEqual(
-    waitCommandCodec.encode({
-      selector: 'id=submit',
-      timeoutMs: 2000,
-    }),
-    ['id=submit', '2000'],
-  );
 });
 
 test('interaction and fill codecs share ref, selector, and point grammar', () => {
   assert.deepEqual(interactionTargetCodec.decode(['@e3', 'Email']), {
     ref: '@e3',
     label: 'Email',
   });
-  assert.deepEqual(interactionTargetCodec.encode({ selector: 'id=submit' }), ['id=submit']);
   assert.deepEqual(fillCommandCodec.decode(['id=email', 'qa@example.com']), {
     kind: 'selector',
     target: { selector: 'id=email' },
@@ -58,14 +50,6 @@ test('interaction and fill codecs share ref, selector, and point grammar', () =>
     target: { x: 10, y: 20 },
     text: 'hello',
   });
-  assert.deepEqual(
-    fillCommandCodec.encode({
-      ref: '@e4',
-      label: 'Email',
-      text: 'qa@example.com',
-    }),
-    ['@e4', 'Email', 'qa@example.com'],
-  );
   assert.deepEqual(longPressCommandCodec.decode(['@e4', '800']), {
     ref: '@e4',
     durationMs: 800,
@@ -75,13 +59,9 @@ test('interaction and fill codecs share ref, selector, and point grammar', () =>
     y: 20,
     durationMs: 800,
   });
-  assert.deepEqual(
-    longPressCommandCodec.encode({ selector: 'label="Last message"', durationMs: 800 }),
-    ['label="Last message"', '800'],
-  );
 });
 
-test('find and is codecs round-trip command action positionals', () => {
+test('find and is codecs decode command action positionals', () => {
   const findOptions = findCommandCodec.decode(['label', 'Continue', 'wait', '3000'], {
     ...BASE_FLAGS,
     platform: 'ios',
@@ -93,16 +73,14 @@ test('find and is codecs round-trip command action positionals', () => {
   assert.equal(findOptions.action, 'wait');
   assert.equal(findOptions.timeoutMs, 3000);
   assert.equal(findOptions.first, true);
-  assert.deepEqual(findCommandCodec.encode(findOptions), ['label', 'Continue', 'wait', '3000']);
 
   const isOptions = isCommandCodec.decode(['text', 'id=title', 'Welcome'], BASE_FLAGS);
   assert.equal(isOptions.predicate, 'text');
   assert.equal(isOptions.selector, 'id=title');
   assert.equal(isOptions.value, 'Welcome');
-  assert.deepEqual(isCommandCodec.encode(isOptions), ['text', 'id=title', 'Welcome']);
 });
 
-test('settings codec owns positional grammar for command and client paths', () => {
+test('settings codec owns positional grammar for CLI commands', () => {
   const location = settingsCommandCodec.decode(['location', 'set', '37.3349', '-122.009'], {
     ...BASE_FLAGS,
     platform: 'ios',
@@ -112,20 +90,4 @@ test('settings codec owns positional grammar for command and client paths', () =
   assert.equal(location.state, 'set');
   assert.equal(location.latitude, 37.3349);
   assert.equal(location.longitude, -122.009);
-  assert.deepEqual(settingsCommandCodec.encode(location), [
-    'location',
-    'set',
-    '37.3349',
-    '-122.009',
-  ]);
-
-  assert.deepEqual(
-    settingsCommandCodec.encode({
-      setting: 'permission',
-      state: 'grant',
-      permission: 'camera',
-      mode: 'limited',
-    }),
-    ['permission', 'grant', 'camera', 'limited'],
-  );
 });

src/__tests__/command-codecs.test.ts

@@ -1,13 +1,16 @@
-import { buildSelectionOptions, writeCommandOutput } from './shared.ts';
+import { runSemanticCliCommand } from '../../commands/semantic-cli.ts';
+import { writeCommandOutput } from './shared.ts';
 import { assertResolvedAppsFilter } from '../../commands/app-inventory-contract.ts';
 import type { ClientCommandHandler } from './router-types.ts';
 
 export const appsCommand: ClientCommandHandler = async ({ flags, client }) => {
   const appsFilter = assertResolvedAppsFilter(flags.appsFilter);
-  const apps = await client.apps.list({
-    ...buildSelectionOptions(flags),
-    appsFilter,
-  });
+  const apps = (await runSemanticCliCommand({
+    client,
+    command: 'apps',
+    positionals: [],
+    flags,
+  })) as unknown as string[];
   const data = { apps };
   writeCommandOutput(flags, data, () => {
     if (!flags.json) {

src/cli/commands/apps.ts

@@ -1,104 +1,111 @@
 import type {
-  AlertCommandOptions,
   AppStateCommandResult,
-  ClipboardCommandOptions,
   ClipboardCommandResult,
-  KeyboardCommandOptions,
   KeyboardCommandResult,
-  RotateCommandOptions,
 } from '../../client.ts';
 import type { CliFlags } from '../../utils/command-schema.ts';
-import { AppError } from '../../utils/errors.ts';
 import { readCommandMessage } from '../../utils/success-text.ts';
-import { waitCommandCodec } from '../../command-codecs.ts';
-import { parseDeviceRotation } from '../../core/device-rotation.ts';
-import { buildSelectionOptions, writeCommandMessage, writeCommandOutput } from './shared.ts';
+import { runSemanticCliCommand, type SemanticCliCommand } from '../../commands/semantic-cli.ts';
+import { writeCommandMessage, writeCommandOutput } from './shared.ts';
 import type { ClientCommandHandlerMap } from './router-types.ts';
 
 export const clientCommandMethodHandlers = {
   wait: async ({ positionals, flags, client }) => {
     writeCommandMessage(
       flags,
-      await client.command.wait(waitCommandCodec.decode(positionals, flags)),
+      await runClientCommand({ command: 'wait', positionals, flags, client }),
     );
     return true;
   },
   alert: async ({ positionals, flags, client }) => {
-    writeCommandMessage(flags, await client.command.alert(readAlertOptions(positionals, flags)));
+    writeCommandMessage(
+      flags,
+      await runClientCommand({ command: 'alert', positionals, flags, client }),
+    );
     return true;
   },
   appstate: async ({ flags, client }) => {
-    const result = await client.command.appState(buildSelectionOptions(flags));
+    const result = (await runClientCommand({
+      command: 'appstate',
+      positionals: [],
+      flags,
+      client,
+    })) as AppStateCommandResult;
     writeCommandOutput(flags, result, () => formatAppState(result));
     return true;
   },
   back: async ({ flags, client }) => {
     writeCommandMessage(
       flags,
-      await client.command.back({ ...buildSelectionOptions(flags), mode: flags.backMode }),
+      await runClientCommand({ command: 'back', positionals: [], flags, client }),
     );
     return true;
   },
   home: async ({ flags, client }) => {
-    writeCommandMessage(flags, await client.command.home(buildSelectionOptions(flags)));
+    writeCommandMessage(
+      flags,
+      await runClientCommand({ command: 'home', positionals: [], flags, client }),
+    );
     return true;
   },
   rotate: async ({ positionals, flags, client }) => {
-    writeCommandMessage(flags, await client.command.rotate(readRotateOptions(positionals, flags)));
+    writeCommandMessage(
+      flags,
+      await runClientCommand({ command: 'rotate', positionals, flags, client }),
+    );
     return true;
   },
   'app-switcher': async ({ flags, client }) => {
-    writeCommandMessage(flags, await client.command.appSwitcher(buildSelectionOptions(flags)));
+    writeCommandMessage(
+      flags,
+      await runClientCommand({ command: 'app-switcher', positionals: [], flags, client }),
+    );
     return true;
   },
   keyboard: async ({ positionals, flags, client }) => {
     writeKeyboardOutput(
       flags,
-      await client.command.keyboard(readKeyboardOptions(positionals, flags)),
+      (await runClientCommand({
+        command: 'keyboard',
+        positionals,
+        flags,
+        client,
+      })) as KeyboardCommandResult,
     );
     return true;
   },
   clipboard: async ({ positionals, flags, client }) => {
     writeClipboardOutput(
       flags,
-      await client.command.clipboard(readClipboardOptions(positionals, flags)),
+      (await runClientCommand({
+        command: 'clipboard',
+        positionals,
+        flags,
+        client,
+      })) as ClipboardCommandResult,
     );
     return true;
   },
 } satisfies ClientCommandHandlerMap;
 
-function readAlertOptions(positionals: string[], flags: CliFlags): AlertCommandOptions {
-  if (positionals.length > 2) {
-    throw new AppError('INVALID_ARGS', 'alert accepts at most action and timeout arguments.');
-  }
-  const action = readAlertAction(positionals[0]);
-  const timeoutMs = readFiniteNumber(positionals[1], 'alert timeout');
-  return {
-    ...buildSelectionOptions(flags),
-    ...(action ? { action } : {}),
-    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-  };
-}
-
-function readRotateOptions(positionals: string[], flags: CliFlags): RotateCommandOptions {
-  if (positionals.length > 1) {
-    throw new AppError('INVALID_ARGS', 'rotate accepts exactly one orientation argument.');
-  }
-  return {
-    ...buildSelectionOptions(flags),
-    orientation: parseDeviceRotation(positionals[0]),
-  };
-}
-
-function readKeyboardOptions(positionals: string[], flags: CliFlags): KeyboardCommandOptions {
-  if (positionals.length > 1) {
-    throw new AppError('INVALID_ARGS', 'keyboard accepts at most one action argument.');
-  }
-  const action = readKeyboardAction(positionals[0]);
-  return {
-    ...buildSelectionOptions(flags),
-    ...(action ? { action } : {}),
-  };
+function runClientCommand(options: {
+  command: Extract<
+    SemanticCliCommand,
+    | 'wait'
+    | 'alert'
+    | 'appstate'
+    | 'back'
+    | 'home'
+    | 'rotate'
+    | 'app-switcher'
+    | 'keyboard'
+    | 'clipboard'
+  >;
+  positionals: string[];
+  flags: CliFlags;
+  client: Parameters<typeof runSemanticCliCommand>[0]['client'];
+}) {
+  return runSemanticCliCommand(options);
 }
 
 function writeKeyboardOutput(flags: CliFlags, result: KeyboardCommandResult): void {
@@ -132,60 +139,6 @@ function androidKeyboardNextAction(
   return 'Keyboard is hidden; focus an app field before type, or use fill with a concrete target.';
 }
 
-function readClipboardOptions(positionals: string[], flags: CliFlags): ClipboardCommandOptions {
-  const action = positionals[0]?.toLowerCase();
-  if (action !== 'read' && action !== 'write') {
-    throw new AppError('INVALID_ARGS', 'clipboard requires a subcommand: read or write.');
-  }
-  const base = buildSelectionOptions(flags);
-  if (action === 'read') {
-    if (positionals.length !== 1) {
-      throw new AppError('INVALID_ARGS', 'clipboard read does not accept additional arguments.');
-    }
-    return { ...base, action };
-  }
-  if (positionals.length < 2) {
-    throw new AppError('INVALID_ARGS', 'clipboard write requires text.');
-  }
-  return {
-    ...base,
-    action,
-    text: positionals.slice(1).join(' '),
-  };
-}
-
-function readAlertAction(value: string | undefined): AlertCommandOptions['action'] | undefined {
-  const action = value?.toLowerCase();
-  if (
-    action === undefined ||
-    action === 'get' ||
-    action === 'accept' ||
-    action === 'dismiss' ||
-    action === 'wait'
-  ) {
-    return action;
-  }
-  throw new AppError('INVALID_ARGS', 'alert action must be get, accept, dismiss, or wait.');
-}
-
-function readKeyboardAction(
-  value: string | undefined,
-): KeyboardCommandOptions['action'] | undefined {
-  const action = value?.toLowerCase();
-  if (action === 'get') return 'status';
-  if (action === undefined || action === 'status' || action === 'dismiss') {
-    return action;
-  }
-  throw new AppError('INVALID_ARGS', 'keyboard action must be status, get, or dismiss.');
-}
-
-function readFiniteNumber(value: string | undefined, label: string): number | undefined {
-  if (value === undefined) return undefined;
-  const parsed = Number(value);
-  if (Number.isFinite(parsed)) return parsed;
-  throw new AppError('INVALID_ARGS', `${label} must be a finite number.`);
-}
-
 function formatAppState(data: AppStateCommandResult): string | null {
   if (data.platform === 'ios') {
     const lines = [`Foreground app: ${data.appName ?? data.appBundleId ?? 'unknown'}`];

src/cli/commands/client-command.ts

@@ -1,10 +1,16 @@
 import { serializeDevice } from '../../client-shared.ts';
 import type { AgentDeviceDevice } from '../../client.ts';
-import { buildSelectionOptions, writeCommandOutput } from './shared.ts';
+import { runSemanticCliCommand } from '../../commands/semantic-cli.ts';
+import { writeCommandOutput } from './shared.ts';
 import type { ClientCommandHandler } from './router-types.ts';
 
 export const devicesCommand: ClientCommandHandler = async ({ flags, client }) => {
-  const devices = await client.devices.list(buildSelectionOptions(flags));
+  const devices = (await runSemanticCliCommand({
+    client,
+    command: 'devices',
+    positionals: [],
+    flags,
+  })) as unknown as AgentDeviceDevice[];
   const data = { devices: devices.map(serializeDevice) };
   writeCommandOutput(flags, data, () => devices.map(formatDeviceLine).join('\n'));
   return true;