@midscene/shared 1.7.5-beta-20260421030751.0 → 1.7.5

package/src/mcp/base-tools.ts

@@ -1,6 +1,13 @@
 import { parseBase64 } from '@midscene/shared/img';
 import { getDebug } from '@midscene/shared/logger';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { z } from 'zod';
+import { camelToKebab, getKeyAliases } from '../key-alias-utils';
+import {
+  createNamespacedInitArgSchema,
+  extractNamespacedArgs,
+  sanitizeNamespacedArgs,
+} from './init-arg-utils';
 import {
   generateCommonTools,
   generateToolsFromActionSpace,
@@ -10,22 +17,68 @@ import type {
   BaseAgent,
   BaseDevice,
   IMidsceneTools,
+  ToolCliMetadata,
   ToolDefinition,
+  ToolSchema,
 } from './types';
 
 const debug = getDebug('mcp:base-tools');
 
 /**
- * Base class for platform-specific MCP tools
- * Generic type TAgent allows subclasses to use their specific agent types
+ * Declarative description of a platform's agent init args.
+ * Collapses the `extractAgentInitParam` / `sanitizeToolArgs` /
+ * `getAgentInitArgSchema` trio into a single data declaration.
+ */
+export interface InitArgSpec<TInitParam> {
+  /** Arg namespace, e.g. `android`, `ios`. */
+  namespace: string;
+  /** Zod shape describing the init args. Field names drive the MCP schema. */
+  shape: Record<string, z.ZodTypeAny>;
+  /**
+   * Optional CLI presentation hints. These affect `--help` output for
+   * single-platform CLIs but do not alter MCP/YAML protocol keys.
+   */
+  cli?: {
+    /** Prefer bare `--device-id`-style options in platform CLI help output. */
+    preferBareKeys?: boolean;
+    /** Override the displayed option name for specific init arg fields. */
+    preferredNames?: Record<string, string>;
+  };
+  /**
+   * Adapt extracted namespaced args into the concrete `TInitParam` passed to
+   * `ensureAgent`. Defaults to returning the raw extracted record.
+   */
+  adapt?: (
+    extracted: Record<string, unknown> | undefined,
+  ) => TInitParam | undefined;
+}
+
+/**
+ * Base class for platform-specific MCP tools.
+ * @typeParam TAgent - Platform-specific agent type.
+ * @typeParam TInitParam - Platform-specific init parameter consumed by
+ *   `ensureAgent`. Defaults to `undefined` for platforms that take no args.
  */
-export abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseAgent>
-  implements IMidsceneTools
+export abstract class BaseMidsceneTools<
+  TAgent extends BaseAgent = BaseAgent,
+  TInitParam = unknown,
+> implements IMidsceneTools
 {
   protected mcpServer?: McpServer;
   protected agent?: TAgent;
   protected toolDefinitions: ToolDefinition[] = [];
 
+  /**
+   * Declarative init-arg spec. Subclasses that accept CLI/MCP init args should
+   * set this once and get `extractAgentInitParam` / `sanitizeToolArgs` /
+   * `getAgentInitArgSchema` auto-implemented.
+   *
+   * Declared with `declare` so that TS doesn't emit an `Object.defineProperty`
+   * for this field on the base constructor, which would otherwise overwrite
+   * a subclass field initializer under `useDefineForClassFields`.
+   */
+  protected declare readonly initArgSpec?: InitArgSpec<TInitParam>;
+
   /**
    * Ensure agent is initialized and ready for use.
    * Must be implemented by subclasses to create platform-specific agent.
@@ -33,7 +86,102 @@ export abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseAgent>
    * @returns Promise resolving to initialized agent instance
    * @throws Error if agent initialization fails
    */
-  protected abstract ensureAgent(initParam?: string): Promise<TAgent>;
+  protected abstract ensureAgent(initParam?: TInitParam): Promise<TAgent>;
+
+  private getInitArgKeys(): readonly string[] {
+    return this.initArgSpec ? Object.keys(this.initArgSpec.shape) : [];
+  }
+
+  /**
+   * Extract a platform-specific agent init parameter from CLI/MCP tool args.
+   */
+  protected extractAgentInitParam(
+    args: Record<string, unknown>,
+  ): TInitParam | undefined {
+    if (!this.initArgSpec) {
+      return undefined;
+    }
+    const extracted = extractNamespacedArgs(
+      args,
+      this.initArgSpec.namespace,
+      this.getInitArgKeys(),
+    );
+    if (this.initArgSpec.adapt) {
+      return this.initArgSpec.adapt(extracted);
+    }
+    return extracted as TInitParam | undefined;
+  }
+
+  /**
+   * Remove platform-specific init args before dispatching a tool payload to the action itself.
+   */
+  protected sanitizeToolArgs(
+    args: Record<string, unknown>,
+  ): Record<string, unknown> {
+    if (!this.initArgSpec) {
+      return args;
+    }
+    return sanitizeNamespacedArgs(
+      args,
+      this.initArgSpec.namespace,
+      this.getInitArgKeys(),
+    );
+  }
+
+  /**
+   * Expose platform-specific init args on action/common tool schemas.
+   */
+  protected getAgentInitArgSchema(): ToolSchema {
+    if (!this.initArgSpec) {
+      return {};
+    }
+    return createNamespacedInitArgSchema(
+      this.initArgSpec.namespace,
+      this.initArgSpec.shape,
+    );
+  }
+
+  /**
+   * Expose CLI-only metadata for platform init args so single-platform help can
+   * show ergonomic bare flags while the underlying schema stays namespaced.
+   * When `preferBareKeys` is enabled, single-platform CLIs only accept the
+   * bare spellings; namespaced dotted spellings remain available through the
+   * MCP/YAML schema instead of the platform CLI surface.
+   */
+  protected getAgentInitArgCliMetadata(): ToolCliMetadata | undefined {
+    if (!this.initArgSpec?.cli) {
+      return undefined;
+    }
+
+    const options = Object.fromEntries(
+      this.getInitArgKeys().map((key) => {
+        const canonicalKey = `${this.initArgSpec!.namespace}.${key}`;
+        const preferredName =
+          this.initArgSpec!.cli?.preferredNames?.[key] ??
+          (this.initArgSpec!.cli?.preferBareKeys
+            ? camelToKebab(key)
+            : canonicalKey);
+
+        const acceptedNames = new Set<string>([
+          preferredName,
+          ...(this.initArgSpec!.cli?.preferBareKeys
+            ? getKeyAliases(key)
+            : getKeyAliases(canonicalKey)),
+        ]);
+        acceptedNames.delete(preferredName);
+
+        return [
+          canonicalKey,
+          {
+            preferredName,
+            aliases: [...acceptedNames],
+          },
+        ];
+      }),
+    );
+
+    return { options };
+  }
 
   /**
    * Optional: prepare platform-specific tools (e.g., device connection)
@@ -83,13 +231,20 @@ export abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseAgent>
     }
 
     // 3. Generate tools from action space (core innovation)
-    const actionTools = generateToolsFromActionSpace(actionSpace, () =>
-      this.ensureAgent(),
+    const actionTools = generateToolsFromActionSpace(
+      actionSpace,
+      (args = {}) => this.ensureAgent(this.extractAgentInitParam(args)),
+      (args = {}) => this.sanitizeToolArgs(args),
+      this.getAgentInitArgSchema(),
+      this.getAgentInitArgCliMetadata(),
     );
 
     // 4. Add common tools (screenshot, waitFor)
-    const commonTools = generateCommonTools(() => this.ensureAgent());
-
+    const commonTools = generateCommonTools(
+      (args = {}) => this.ensureAgent(this.extractAgentInitParam(args)),
+      this.getAgentInitArgSchema(),
+      this.getAgentInitArgCliMetadata(),
+    );
     this.toolDefinitions.push(...actionTools, ...commonTools);
 
     debug('Total tools prepared:', this.toolDefinitions.length);

package/src/mcp/index.ts

@@ -1,5 +1,6 @@
 export * from './base-server';
 export * from './base-tools';
+export * from './init-arg-utils';
 export * from './error-formatter';
 export * from './tool-generator';
 export * from './types';

package/src/mcp/init-arg-utils.ts

@@ -0,0 +1,105 @@
+import type { z } from 'zod';
+import { getKeyAliases, isRecord } from '../key-alias-utils';
+import type { ToolSchema } from './types';
+
+function readAliasedValue(
+  args: Record<string, unknown>,
+  key: string,
+): unknown | undefined {
+  for (const alias of getKeyAliases(key)) {
+    if (alias in args) {
+      return args[alias];
+    }
+  }
+
+  return undefined;
+}
+
+function readNamespacedArg(
+  args: Record<string, unknown>,
+  namespace: string,
+  key: string,
+): unknown | undefined {
+  // Lookup order: namespace object first, then flat dotted form, then bare key
+  // fallback. Namespace-aware inputs win so multi-platform callers cannot be
+  // cross-contaminated by a top-level bare `deviceId` leaking into the wrong
+  // platform.
+  const namespacedArgs = readAliasedValue(args, namespace);
+  if (isRecord(namespacedArgs)) {
+    const nestedValue = readAliasedValue(namespacedArgs, key);
+    if (nestedValue !== undefined) {
+      return nestedValue;
+    }
+  }
+
+  const dottedValue = readAliasedValue(args, `${namespace}.${key}`);
+  if (dottedValue !== undefined) {
+    return dottedValue;
+  }
+
+  const directValue = readAliasedValue(args, key);
+  if (directValue !== undefined) {
+    return directValue;
+  }
+
+  return undefined;
+}
+
+export function extractNamespacedArgs<
+  TFieldName extends string,
+  TArgs extends Record<string, unknown> = Record<string, unknown>,
+>(
+  args: Record<string, unknown>,
+  namespace: string,
+  keys: readonly TFieldName[],
+): TArgs | undefined {
+  const extracted: Record<string, unknown> = {};
+
+  for (const key of keys) {
+    const value = readNamespacedArg(args, namespace, key);
+    if (value !== undefined) {
+      extracted[key] = value;
+    }
+  }
+
+  return Object.keys(extracted).length > 0 ? (extracted as TArgs) : undefined;
+}
+
+export function sanitizeNamespacedArgs(
+  args: Record<string, unknown>,
+  namespace: string,
+  keys: readonly string[],
+): Record<string, unknown> {
+  const excludedKeys = new Set<string>(getKeyAliases(namespace));
+
+  for (const key of keys) {
+    for (const alias of getKeyAliases(key)) {
+      excludedKeys.add(alias);
+    }
+
+    for (const alias of getKeyAliases(`${namespace}.${key}`)) {
+      excludedKeys.add(alias);
+    }
+  }
+
+  return Object.fromEntries(
+    Object.entries(args).filter(([key]) => !excludedKeys.has(key)),
+  );
+}
+
+/**
+ * Build a flat MCP tool schema whose keys are dotted `"<namespace>.<field>"`.
+ *
+ * We intentionally stay flat (rather than `{ namespace: z.object({...}) }`) so
+ * that CLI (`--android.device-id`), MCP clients, and `--help` output all share
+ * the same spelling. `readNamespacedArg` understands all three input shapes:
+ * nested namespace object, dotted flat key, and bare key fallback.
+ */
+export function createNamespacedInitArgSchema(
+  namespace: string,
+  shape: Record<string, z.ZodTypeAny>,
+): ToolSchema {
+  return Object.fromEntries(
+    Object.entries(shape).map(([key, value]) => [`${namespace}.${key}`, value]),
+  );
+}

package/src/mcp/tool-generator.ts

@@ -10,8 +10,10 @@ import { getErrorMessage } from './error-formatter';
 import type {
   ActionSpaceItem,
   BaseAgent,
+  ToolCliMetadata,
   ToolDefinition,
   ToolResult,
+  ToolSchema,
 } from './types';
 
 /**
@@ -447,25 +449,49 @@ async function captureFailureResult(
   }
 }
 
+function mergeToolCliMetadata(
+  base?: ToolCliMetadata,
+  extra?: ToolCliMetadata,
+): ToolCliMetadata | undefined {
+  const options = {
+    ...(base?.options ?? {}),
+    ...(extra?.options ?? {}),
+  };
+
+  return Object.keys(options).length > 0 ? { options } : undefined;
+}
+
 /**
  * Converts DeviceAction from actionSpace into MCP ToolDefinition
  * This is the core logic that removes need for hardcoded tool definitions
  */
 export function generateToolsFromActionSpace(
   actionSpace: ActionSpaceItem[],
-  getAgent: () => Promise<BaseAgent>,
+  getAgent: (args?: Record<string, unknown>) => Promise<BaseAgent>,
+  sanitizeArgs: (args: Record<string, unknown>) => Record<string, unknown> = (
+    args,
+  ) => args,
+  initArgSchema: ToolSchema = {},
+  initArgCliMetadata?: ToolCliMetadata,
 ): ToolDefinition[] {
   return actionSpace.map((action) => {
-    const schema = extractActionSchema(action.paramSchema as z.ZodTypeAny);
+    const schema = {
+      ...extractActionSchema(action.paramSchema as z.ZodTypeAny),
+      ...initArgSchema,
+    };
 
     return {
       name: action.name,
       description: describeActionForMCP(action),
       schema,
+      cli: initArgCliMetadata,
       handler: async (args: Record<string, unknown>) => {
         try {
-          const agent = await getAgent();
-          const normalizedArgs = normalizeActionArgs(args, action.paramSchema);
+          const agent = await getAgent(args);
+          const normalizedArgs = normalizeActionArgs(
+            sanitizeArgs(args),
+            action.paramSchema,
+          );
           let actionResult: unknown;
 
           try {
@@ -507,16 +533,23 @@ export function generateToolsFromActionSpace(
  * Generate common tools (screenshot, act)
  */
 export function generateCommonTools(
-  getAgent: () => Promise<BaseAgent>,
+  getAgent: (args?: Record<string, unknown>) => Promise<BaseAgent>,
+  initArgSchema: ToolSchema = {},
+  initArgCliMetadata?: ToolCliMetadata,
 ): ToolDefinition[] {
   return [
     {
       name: 'take_screenshot',
       description: 'Capture screenshot of current page/screen',
-      schema: {},
-      handler: async (): Promise<ToolResult> => {
+      schema: {
+        ...initArgSchema,
+      },
+      cli: initArgCliMetadata,
+      handler: async (
+        args: Record<string, unknown> = {},
+      ): Promise<ToolResult> => {
         try {
-          const agent = await getAgent();
+          const agent = await getAgent(args);
           const screenshot = await agent.page?.screenshotBase64();
           if (!screenshot) {
             return createErrorResult('Screenshot not available');
@@ -544,11 +577,15 @@ export function generateCommonTools(
           .describe(
             'Natural language description of the action to perform, e.g. "press Command+Space, type Safari, press Enter"',
           ),
+        ...initArgSchema,
       },
-      handler: async (args: Record<string, unknown>): Promise<ToolResult> => {
+      cli: mergeToolCliMetadata(undefined, initArgCliMetadata),
+      handler: async (
+        args: Record<string, unknown> = {},
+      ): Promise<ToolResult> => {
         const prompt = args.prompt as string;
         try {
-          const agent = await getAgent();
+          const agent = await getAgent(args);
           if (!agent.aiAction) {
             return createErrorResult('act is not supported by this agent');
           }

package/src/mcp/types.ts

@@ -47,6 +47,15 @@ export type ToolHandler<T = Record<string, unknown>> = (
  */
 export type ToolSchema = Record<string, z.ZodTypeAny>;
 
+export interface ToolCliOption {
+  preferredName?: string;
+  aliases?: string[];
+}
+
+export interface ToolCliMetadata {
+  options?: Record<string, ToolCliOption>;
+}
+
 /**
  * Tool definition for MCP server
  */
@@ -55,6 +64,7 @@ export interface ToolDefinition<T = Record<string, unknown>> {
   description: string;
   schema: ToolSchema;
   handler: ToolHandler<T>;
+  cli?: ToolCliMetadata;
 }
 
 /**