@midscene/shared 1.9.7 → 1.9.8-beta-20260618014851.0

package/src/agent-tools/agent-behavior-init-args.ts

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+
+export interface AgentBehaviorInitArgs {
+  aiActContext?: string;
+  aiActionContext?: string;
+  replanningCycleLimit?: number;
+  waitAfterAction?: number;
+  screenshotShrinkFactor?: number;
+}
+
+type ExposedAgentBehaviorInitArgKey = Exclude<
+  keyof AgentBehaviorInitArgs,
+  'aiActionContext'
+>;
+
+export const agentBehaviorInitArgShape = {
+  aiActContext: z
+    .string()
+    .optional()
+    .describe(
+      'Background knowledge passed to aiAct. Default: no extra context.',
+    ),
+  replanningCycleLimit: z
+    .number()
+    .int()
+    .nonnegative()
+    .optional()
+    .describe(
+      'Maximum number of replanning cycles for aiAct. Default: model adapter default.',
+    ),
+  waitAfterAction: z
+    .number()
+    .nonnegative()
+    .optional()
+    .describe(
+      'Wait time in milliseconds after each action execution. Default: 300ms.',
+    ),
+  screenshotShrinkFactor: z
+    .number()
+    .min(1)
+    .optional()
+    .describe(
+      'Screenshot shrink factor before sending images to AI. Default: 1; high values may reduce recognition quality, especially on mobile.',
+    ),
+} satisfies Record<ExposedAgentBehaviorInitArgKey, z.ZodTypeAny>;
+
+export function extractAgentBehaviorInitArgs(
+  extracted: Partial<AgentBehaviorInitArgs> | undefined,
+): AgentBehaviorInitArgs | undefined {
+  if (!extracted) {
+    return undefined;
+  }
+
+  const agentOptions: AgentBehaviorInitArgs = {
+    ...(typeof extracted.aiActContext === 'string'
+      ? { aiActContext: extracted.aiActContext }
+      : {}),
+    ...(typeof extracted.aiActionContext === 'string'
+      ? { aiActionContext: extracted.aiActionContext }
+      : {}),
+    ...(typeof extracted.replanningCycleLimit === 'number'
+      ? { replanningCycleLimit: extracted.replanningCycleLimit }
+      : {}),
+    ...(typeof extracted.waitAfterAction === 'number'
+      ? { waitAfterAction: extracted.waitAfterAction }
+      : {}),
+    ...(typeof extracted.screenshotShrinkFactor === 'number'
+      ? { screenshotShrinkFactor: extracted.screenshotShrinkFactor }
+      : {}),
+  };
+
+  return Object.keys(agentOptions).length > 0 ? agentOptions : undefined;
+}
+
+function stableJsonValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(stableJsonValue);
+  }
+
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, nestedValue]) => [key, stableJsonValue(nestedValue)]),
+    );
+  }
+
+  return value;
+}
+
+export function getAgentInitArgsSignature(
+  initArgs: object | undefined,
+): string | undefined {
+  if (!initArgs || Object.keys(initArgs).length === 0) {
+    return undefined;
+  }
+
+  return JSON.stringify(stableJsonValue(initArgs));
+}
+
+export function shouldRebuildAgentForInitArgs(
+  currentSignature: string | undefined,
+  nextSignature: string | undefined,
+): boolean {
+  return (
+    currentSignature !== nextSignature &&
+    (currentSignature !== undefined || nextSignature !== undefined)
+  );
+}

package/src/{mcp → agent-tools}/base-tools.ts

@@ -1,6 +1,5 @@
 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 {
@@ -29,7 +28,7 @@ import type {
   ToolSchema,
 } from './types';
 
-const debug = getDebug('mcp:base-tools');
+const debug = getDebug('agent-tools:base-tools');
 
 /**
  * Declarative description of a platform's agent init args.
@@ -39,11 +38,11 @@ const debug = getDebug('mcp:base-tools');
 export interface InitArgSpec<TInitParam> {
   /** Arg namespace, e.g. `android`, `ios`. */
   namespace: string;
-  /** Zod shape describing the init args. Field names drive the MCP schema. */
+  /** Zod shape describing the init args. Field names drive the tool 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.
+   * single-platform CLIs but do not alter YAML protocol keys.
    */
   cli?: {
     /** Prefer bare `--device-id`-style options in platform CLI help output. */
@@ -61,7 +60,7 @@ export interface InitArgSpec<TInitParam> {
 }
 
 /**
- * Base class for platform-specific MCP tools.
+ * Base class for platform-specific Midscene 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.
@@ -71,20 +70,19 @@ export abstract class BaseMidsceneTools<
   TInitParam = unknown,
 > implements IMidsceneTools
 {
-  protected mcpServer?: McpServer;
   protected agent?: TAgent;
   protected toolDefinitions: ToolDefinition[] = [];
 
   /**
    * Default options injected into every generated tool call (e.g. forced deep
-   * locate / deep think). Set from server/CLI behavior flags before
+   * locate / deep think). Set from startup/CLI behavior flags before
    * `initTools()` so they are baked into the generated tool handlers.
    * See https://github.com/web-infra-dev/midscene/issues/2446.
    */
   protected toolDefaults: ToolDefaults = {};
 
   /**
-   * Declarative init-arg spec. Subclasses that accept CLI/MCP init args should
+   * Declarative init-arg spec. Subclasses that accept CLI init args should
    * set this once and get `extractAgentInitParam` / `sanitizeToolArgs` /
    * `getAgentInitArgSchema` auto-implemented.
    *
@@ -108,7 +106,7 @@ export abstract class BaseMidsceneTools<
   }
 
   /**
-   * Extract a platform-specific agent init parameter from CLI/MCP tool args.
+   * Extract a platform-specific agent init parameter from CLI tool args.
    */
   protected extractAgentInitParam(
     args: Record<string, unknown>,
@@ -161,7 +159,7 @@ export abstract class BaseMidsceneTools<
    * 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.
+   * YAML schema instead of the platform CLI surface.
    */
   protected getAgentInitArgCliMetadata(): ToolCliMetadata | undefined {
     if (!this.initArgSpec?.cli) {
@@ -272,7 +270,6 @@ export abstract class BaseMidsceneTools<
     this.toolDefinitions.push(...platformTools);
 
     // 2. Get action space: use pre-set agent if available, otherwise temp device.
-    //    When called via mcpKitForAgent(), agent is set before initTools().
     //    For CLI usage, agent is deferred to the first real command.
     let actionSpace: ActionSpaceItem[];
     if (this.agent) {
@@ -313,28 +310,6 @@ export abstract class BaseMidsceneTools<
     debug('Total tools prepared:', this.toolDefinitions.length);
   }
 
-  /**
-   * Attach to MCP server and register all tools
-   */
-  public attachToServer(server: McpServer): void {
-    this.mcpServer = server;
-
-    if (this.toolDefinitions.length === 0) {
-      debug('Warning: No tools to register. Tools may be initialized lazily.');
-    }
-
-    for (const toolDef of this.toolDefinitions) {
-      this.mcpServer.tool(
-        toolDef.name,
-        toolDef.description,
-        toolDef.schema,
-        toolDef.handler,
-      );
-    }
-
-    debug('Registered', this.toolDefinitions.length, 'tools');
-  }
-
   /**
    * Cleanup method - destroy agent and release resources
    */

package/src/{mcp → agent-tools}/chrome-path.ts

@@ -1,5 +1,13 @@
 import { existsSync } from 'node:fs';
-import { MIDSCENE_MCP_CHROME_PATH, globalConfigManager } from '../env';
+import {
+  MIDSCENE_CHROME_PATH,
+  MIDSCENE_MCP_CHROME_PATH,
+  globalConfigManager,
+} from '../env';
+import { getDebug } from '../logger';
+
+const warnChromePath = getDebug('agent-tools:chrome-path', { console: true });
+let hasWarnedLegacyChromePath = false;
 
 export function getSystemChromePath(): string | undefined {
   const platform = process.platform;
@@ -33,9 +41,18 @@ export function getSystemChromePath(): string | undefined {
 }
 
 export function resolveChromePath(): string {
-  const envPath = globalConfigManager.getEnvConfigValue(
+  const primaryEnvPath =
+    globalConfigManager.getEnvConfigValue(MIDSCENE_CHROME_PATH);
+  const legacyEnvPath = globalConfigManager.getEnvConfigValue(
     MIDSCENE_MCP_CHROME_PATH,
   );
+  const envPath = primaryEnvPath || legacyEnvPath;
+  if (!primaryEnvPath && legacyEnvPath && !hasWarnedLegacyChromePath) {
+    warnChromePath(
+      'MIDSCENE_MCP_CHROME_PATH is deprecated. Use MIDSCENE_CHROME_PATH instead.',
+    );
+    hasWarnedLegacyChromePath = true;
+  }
   if (envPath && envPath !== 'auto' && existsSync(envPath)) {
     return envPath;
   }
@@ -43,6 +60,6 @@ export function resolveChromePath(): string {
   if (systemPath) return systemPath;
 
   throw new Error(
-    'Chrome not found. Install Google Chrome or set MIDSCENE_MCP_CHROME_PATH environment variable.',
+    'Chrome not found. Install Google Chrome or set MIDSCENE_CHROME_PATH environment variable.',
   );
 }

package/src/{mcp → agent-tools}/index.ts

@@ -1,10 +1,8 @@
-export * from './base-server';
 export * from './base-tools';
 export * from './tool-defaults';
+export * from './agent-behavior-init-args';
 export * from './init-arg-utils';
 export * from './error-formatter';
 export * from './tool-generator';
 export * from './types';
-export * from './inject-report-html-plugin';
-export * from './launcher-helper';
 export * from './chrome-path';

package/src/{mcp → agent-tools}/init-arg-utils.ts

@@ -88,11 +88,11 @@ export function sanitizeNamespacedArgs(
 }
 
 /**
- * Build a flat MCP tool schema whose keys are dotted `"<namespace>.<field>"`.
+ * Build a flat 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:
+ * that CLI (`--android.device-id`) and `--help` output share the same spelling.
+ * `readNamespacedArg` understands all three input shapes:
  * nested namespace object, dotted flat key, and bare key fallback.
  */
 export function createNamespacedInitArgSchema(

package/src/{mcp → agent-tools}/tool-defaults.ts

@@ -1,10 +1,10 @@
 /**
  * Unified, declarative mechanism for "force a default option on every tool
- * call" behaviors exposed by MCP servers and the device / Agent Skill CLIs.
+ * call" behaviors exposed by device and Agent Skill CLIs.
  *
  * Adding a new behavior flag (e.g. `--deep-search`) is a one-line change to
  * {@link TOOL_BEHAVIOR_FLAGS}: declare which default-option "bag" it fills.
- * The tool generator, servers, tools managers and CLI parsing are all generic
+ * The tool generator, tools managers and CLI parsing are all generic
  * over {@link ToolDefaults} and never need to learn about individual flags.
  *
  * See https://github.com/web-infra-dev/midscene/issues/2446.
@@ -91,13 +91,12 @@ export function resolveToolDefaults(
  *
  * Behavior flags (e.g. `--deep-locate`) are global: they may appear anywhere
  * in argv and are not tied to a specific sub-command. They are recognized by
- * exact kebab-case match — the same surface the MCP `parseArgs` config exposes
- * — and removed so a strict per-command parser never sees them. Every other
+ * exact kebab-case match and removed so a strict per-command parser never sees them. Every other
  * token is returned untouched and in order for that per-command parser.
  *
  * This is the single place that knows how a behavior flag looks on the command
- * line; both the device / Agent Skill CLI and the MCP launch path resolve their
- * defaults from {@link TOOL_BEHAVIOR_FLAGS} through here / {@link resolveToolDefaults}.
+ * line; the device / Agent Skill CLI resolves defaults from
+ * {@link TOOL_BEHAVIOR_FLAGS} through here / {@link resolveToolDefaults}.
  */
 export function stripBehaviorFlags(argv: readonly string[]): {
   rawArgs: string[];

package/src/{mcp → agent-tools}/tool-generator.ts

@@ -21,10 +21,10 @@ import { composeUserPrompt, promptInputExtraSchema } from './user-prompt';
 export { composeUserPrompt };
 
 /**
- * Generate MCP tool description from ActionSpaceItem
+ * Generate tool description from ActionSpaceItem.
  * Format: "actionName action, description. Parameters: param1 (type) - desc; param2 (type) - desc"
  */
-function describeActionForMCP(action: ActionSpaceItem): string {
+function describeActionForTool(action: ActionSpaceItem): string {
   const actionDesc = action.description || `Execute ${action.name} action`;
 
   if (!action.paramSchema) {
@@ -129,6 +129,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 function makePromptOptional(
   shape: Record<string, z.ZodTypeAny>,
   wrapInOptional: boolean,
+  description?: string | null,
 ): z.ZodTypeAny {
   const newShape = { ...shape };
   newShape.prompt = shape.prompt.optional();
@@ -137,6 +138,9 @@ function makePromptOptional(
   if (wrapInOptional) {
     newSchema = newSchema.optional();
   }
+  if (description) {
+    newSchema = newSchema.describe(description);
+  }
   return newSchema;
 }
 
@@ -151,7 +155,10 @@ function transformSchemaField(
   const shape = getZodObjectShape(innerValue);
 
   if (shape && isMidsceneLocatorField(innerValue)) {
-    return [key, makePromptOptional(shape, isOptional)];
+    return [
+      key,
+      makePromptOptional(shape, isOptional, getZodDescription(value)),
+    ];
   }
   return [key, value];
 }
@@ -159,7 +166,7 @@ function transformSchemaField(
 /**
  * Extract and transform schema from action's paramSchema.
  *
- * CLI and MCP both expose parameters as named fields, so the only schema
+ * CLI tools expose parameters as named fields, so the only schema
  * shapes we can surface are ZodObject (any number of fields) or undefined
  * (the action takes no parameters). A primitive schema like `z.string()`
  * silently degraded to leaking the ZodString instance's prototype methods
@@ -181,7 +188,7 @@ function extractActionSchema(
       (paramSchema as unknown as { _def?: { typeName?: string } })?._def
         ?.typeName ?? 'unknown';
     throw new Error(
-      `Action "${actionName}" declared a non-object paramSchema (${typeName}). CLI and MCP tool schemas must be a ZodObject (e.g. z.object({ uri: z.string() })) or undefined. Wrap primitive fields in an object schema.`,
+      `Action "${actionName}" declared a non-object paramSchema (${typeName}). CLI tool schemas must be a ZodObject (e.g. z.object({ uri: z.string() })) or undefined. Wrap primitive fields in an object schema.`,
     );
   }
 
@@ -536,7 +543,7 @@ function mergeToolCliMetadata(
 }
 
 /**
- * Converts DeviceAction from actionSpace into MCP ToolDefinition
+ * Converts DeviceAction from actionSpace into ToolDefinition.
  * This is the core logic that removes need for hardcoded tool definitions
  */
 export function generateToolsFromActionSpace(
@@ -557,7 +564,7 @@ export function generateToolsFromActionSpace(
 
     return {
       name: action.name,
-      description: describeActionForMCP(action),
+      description: describeActionForTool(action),
       schema,
       cli: initArgCliMetadata,
       handler: async (args: Record<string, unknown>) => {

package/src/{mcp → agent-tools}/types.ts

@@ -1,4 +1,3 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { z } from 'zod';
 import type { ToolDefaults } from './tool-defaults';
 
@@ -12,7 +11,7 @@ export const defaultAppLoadingTimeoutMs = 10000;
 export const defaultAppLoadingCheckIntervalMs = 2000;
 
 /**
- * Content item types for tool results (MCP compatible)
+ * Content item types for tool results.
  */
 export type ToolResultContent =
   | { type: 'text'; text: string }
@@ -26,7 +25,7 @@ export type ToolResultContent =
     };
 
 /**
- * Result type for tool execution (MCP compatible)
+ * Result type for tool execution.
  */
 export interface ToolResult {
   [x: string]: unknown;
@@ -58,7 +57,7 @@ export interface ToolCliMetadata {
 }
 
 /**
- * Tool definition for MCP server
+ * Tool definition for Midscene CLI and Skill surfaces.
  */
 export interface ToolDefinition<T = Record<string, unknown>> {
   name: string;
@@ -68,9 +67,6 @@ export interface ToolDefinition<T = Record<string, unknown>> {
   cli?: ToolCliMetadata;
 }
 
-/**
- * Tool type for mcpKitForAgent return value
- */
 export type Tool = ToolDefinition;
 
 /**
@@ -100,6 +96,23 @@ export type UserPromptLike =
       convertHttpImage2Base64?: boolean;
     };
 
+export interface RecordToReportScreenshot {
+  /**
+   * PNG/JPEG data URI, or raw PNG base64 body.
+   */
+  base64: string;
+  description?: string;
+}
+
+export interface RecordToReportOptions {
+  content?: string;
+  /**
+   * @deprecated Use `screenshots: [{ base64 }]` instead.
+   */
+  screenshotBase64?: string;
+  screenshots?: RecordToReportScreenshot[];
+}
+
 /**
  * Base agent interface
  * Represents a platform-specific agent (Android, iOS, Web)
@@ -113,7 +126,7 @@ export interface BaseAgent {
   };
   recordToReport?: (
     title?: string,
-    opt?: { content?: string; screenshotBase64?: string },
+    opt?: RecordToReportOptions,
   ) => Promise<void>;
   callActionInActionSpace?: (
     actionName: string,
@@ -143,10 +156,9 @@ export interface BaseDevice {
 }
 
 /**
- * Interface for platform-specific MCP tools manager
+ * Interface for platform-specific tools manager.
  */
 export interface IMidsceneTools {
-  attachToServer(server: McpServer): void;
   initTools(): Promise<void>;
   destroy?(): Promise<void>;
   setToolDefaults?(toolDefaults: ToolDefaults): void;

package/src/cli/cli-args.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
+import type { ToolCliOption, ToolDefinition } from '../agent-tools/types';
 import { getKeyAliases } from '../key-alias-utils';
-import type { ToolCliOption, ToolDefinition } from '../mcp/types';
 import { CLIError } from './cli-error';
 
 export function parseValue(raw: string): unknown {

package/src/cli/cli-runner.ts

@@ -2,14 +2,14 @@ import { existsSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import dotenv from 'dotenv';
-import { getDebug } from '../logger';
-import type { BaseMidsceneTools } from '../mcp/base-tools';
-import { stripBehaviorFlags } from '../mcp/tool-defaults';
+import type { BaseMidsceneTools } from '../agent-tools/base-tools';
+import { stripBehaviorFlags } from '../agent-tools/tool-defaults';
 import type {
   ToolDefinition,
   ToolResult,
   ToolResultContent,
-} from '../mcp/types';
+} from '../agent-tools/types';
+import { getDebug } from '../logger';
 import {
   canonicalizeCliArgKeys,
   formatCliValidationError,

package/src/env/types.ts

@@ -8,10 +8,11 @@ export const MIDSCENE_DEBUG_MODEL_RESPONSE = 'MIDSCENE_DEBUG_MODEL_RESPONSE';
 export const MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG =
   'MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG';
 export const MIDSCENE_DEBUG_MODE = 'MIDSCENE_DEBUG_MODE';
-export const MIDSCENE_MCP_USE_PUPPETEER_MODE =
-  'MIDSCENE_MCP_USE_PUPPETEER_MODE';
+export const MIDSCENE_CHROME_PATH = 'MIDSCENE_CHROME_PATH';
+/**
+ * @deprecated Use MIDSCENE_CHROME_PATH instead. This is kept for backward compatibility.
+ */
 export const MIDSCENE_MCP_CHROME_PATH = 'MIDSCENE_MCP_CHROME_PATH';
-export const MIDSCENE_MCP_ANDROID_MODE = 'MIDSCENE_MCP_ANDROID_MODE';
 export const DOCKER_CONTAINER = 'DOCKER_CONTAINER';
 
 // Observability
@@ -166,8 +167,6 @@ export const BASIC_ENV_KEYS = [
 
 export const BOOLEAN_ENV_KEYS = [
   MIDSCENE_CACHE,
-  MIDSCENE_MCP_USE_PUPPETEER_MODE,
-  MIDSCENE_MCP_ANDROID_MODE,
   MIDSCENE_LANGSMITH_DEBUG,
   MIDSCENE_LANGFUSE_DEBUG,
   MIDSCENE_REPORT_QUIET,
@@ -188,6 +187,7 @@ export const STRING_ENV_KEYS = [
   MIDSCENE_REPORT_TAG_NAME,
   MIDSCENE_PREFERRED_LANGUAGE,
   MATCH_BY_POSITION,
+  MIDSCENE_CHROME_PATH,
   MIDSCENE_MCP_CHROME_PATH,
   DOCKER_CONTAINER,
 ] as const;

package/src/img/index.ts

@@ -21,6 +21,8 @@ export {
   createImgBase64ByFormat,
   inferBase64ImageFormat,
   normalizeBase64Image,
+  normalizeScreenshotBase64,
+  type NormalizeScreenshotBase64Options,
 } from './transform';
 export {
   processImageElementInfo,

package/src/img/transform.ts

@@ -157,6 +157,9 @@ export async function resizeAndConvertImgBuffer(
 export const normalizeBase64Body = (body: string) => body.replace(/\s/g, '');
 
 const base64ImageDataUrlPattern = /^data:image\/[a-zA-Z0-9.+-]+;base64,/i;
+const supportedScreenshotDataUriPattern =
+  /^data:image\/(png|jpe?g);base64,([\s\S]*)$/i;
+const rawBase64BodyPattern = /^[A-Za-z0-9+/=\s]+$/;
 
 export const inferBase64ImageFormat = (base64Body: string) => {
   if (base64Body.startsWith('iVBORw0KGgo')) {
@@ -207,6 +210,48 @@ export const createImgBase64ByFormat = (format: string, body: string) => {
   return `data:image/${format};base64,${normalizeBase64Body(body)}`;
 };
 
+export interface NormalizeScreenshotBase64Options {
+  label?: string;
+}
+
+export const normalizeScreenshotBase64 = (
+  base64: string,
+  options?: NormalizeScreenshotBase64Options,
+) => {
+  const label = options?.label ?? 'screenshot base64';
+  const trimmedBase64 = base64.trim();
+  if (!trimmedBase64) {
+    throw new Error(`${label} cannot be empty`);
+  }
+
+  const dataUriMatch = trimmedBase64.match(supportedScreenshotDataUriPattern);
+  if (dataUriMatch) {
+    const imageFormat =
+      dataUriMatch[1].toLowerCase() === 'jpg'
+        ? 'jpeg'
+        : dataUriMatch[1].toLowerCase();
+    const body = dataUriMatch[2];
+    if (!normalizeBase64Body(body)) {
+      throw new Error(`${label} cannot be empty`);
+    }
+    return createImgBase64ByFormat(imageFormat, body);
+  }
+
+  if (trimmedBase64.startsWith('data:')) {
+    throw new Error(
+      `${label} must be a PNG/JPEG data URI or raw PNG base64 string`,
+    );
+  }
+
+  if (!rawBase64BodyPattern.test(trimmedBase64)) {
+    throw new Error(
+      `${label} must be a PNG/JPEG data URI or raw PNG base64 string`,
+    );
+  }
+
+  return createImgBase64ByFormat('png', trimmedBase64);
+};
+
 export const normalizeBase64Image = (base64: string) => {
   const trimmedBase64 = base64.trim();
   if (base64ImageDataUrlPattern.test(trimmedBase64)) {

package/src/key-alias-utils.ts

@@ -1,7 +1,7 @@
 /**
- * Internal-only helpers for CLI/MCP argument key aliasing.
+ * Internal-only helpers for CLI argument key aliasing.
  * Not re-exported from the package entry point — keep consumers within
- * `cli/` and `mcp/`.
+ * `cli/`.
  */
 
 export function kebabToCamel(str: string): string {

package/src/utils.ts

@@ -64,17 +64,8 @@ export function assert(condition: any, message?: string): asserts condition {
   }
 }
 
-let isMcp = false;
-
-export function setIsMcp(value: boolean) {
-  isMcp = value;
-}
-
-//mcp need use obj format to console msg: https://github.com/modelcontextprotocol/typescript-sdk/issues/244
 export function logMsg(...message: Parameters<typeof console.log>) {
-  if (!isMcp) {
-    console.log(...message);
-  }
+  console.log(...message);
 }
 
 export async function repeat(