@midscene/shared 1.7.5-beta-20260420035759.0 → 1.7.5-beta-20260420052829.0

package/dist/es/cli/cli-runner.mjs

@@ -2,6 +2,7 @@ import { existsSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import dotenv from "dotenv";
+import { z } from "zod";
 import { getKeyAliases, isRecord } from "../key-alias-utils.mjs";
 import { getDebug } from "../logger.mjs";
 function _define_property(obj, key, value) {
@@ -27,9 +28,29 @@ function parseValue(raw) {
     if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
     return raw;
 }
+function walkCliArgs(args, setArgValue) {
+    for(let i = 0; i < args.length; i++){
+        const arg = args[i];
+        if (!arg.startsWith('--')) continue;
+        const body = arg.slice(2);
+        const eqIdx = body.indexOf('=');
+        if (eqIdx >= 0) setArgValue(body.slice(0, eqIdx), parseValue(body.slice(eqIdx + 1)));
+        else if (args[i + 1] && !args[i + 1].startsWith('--')) {
+            i++;
+            setArgValue(body, parseValue(args[i]));
+        } else setArgValue(body, true);
+    }
+}
+function parseRawCliArgs(args) {
+    const result = {};
+    walkCliArgs(args, (key, value)=>{
+        result[key] = value;
+    });
+    return result;
+}
 function parseCliArgs(args) {
     const result = {};
-    const setArgValue = (key, value)=>{
+    walkCliArgs(args, (key, value)=>{
         if (!key.includes('.')) {
             result[key] = value;
             return;
@@ -48,18 +69,7 @@ function parseCliArgs(args) {
         }
         const leafSegment = segments[segments.length - 1];
         for (const alias of getKeyAliases(leafSegment))current[alias] = value;
-    };
-    for(let i = 0; i < args.length; i++){
-        const arg = args[i];
-        if (!arg.startsWith('--')) continue;
-        const body = arg.slice(2);
-        const eqIdx = body.indexOf('=');
-        if (eqIdx >= 0) setArgValue(body.slice(0, eqIdx), parseValue(body.slice(eqIdx + 1)));
-        else if (args[i + 1] && !args[i + 1].startsWith('--')) {
-            i++;
-            setArgValue(body, parseValue(args[i]));
-        } else setArgValue(body, true);
-    }
+    });
     return result;
 }
 function outputContentItem(item, isError) {
@@ -100,28 +110,59 @@ function getCliOptionDisplay(key, cliOption) {
         aliases
     };
 }
-function validateRestrictedCliArgSpellings(args, scriptName, commandName, def) {
+function getAcceptedCliOptionNames(key, cliOption) {
+    return [
+        ...new Set(cliOption ? [
+            cliOption.preferredName ?? key,
+            ...cliOption.aliases ?? []
+        ] : [
+            key,
+            ...getKeyAliases(key)
+        ])
+    ];
+}
+function toOptionalCliSchemaField(field) {
+    if ('object' == typeof field && null !== field && 'function' == typeof field.optional) return field.optional();
+    const description = 'object' == typeof field && null !== field && "description" in field && 'string' == typeof field.description ? field.description : void 0;
+    return description ? z.any().describe(description) : z.any();
+}
+function buildCliArgSchema(def) {
+    return Object.fromEntries(Object.entries(def.schema).flatMap(([key, zodType])=>getAcceptedCliOptionNames(key, def.cli?.options?.[key]).map((cliKey)=>[
+                cliKey,
+                toOptionalCliSchemaField(zodType)
+            ])));
+}
+function buildDisallowedCliSpellings(def) {
     const disallowedSpellings = new Map();
     for (const [key] of Object.entries(def.schema)){
         const cliOption = def.cli?.options?.[key];
-        if (!cliOption?.acceptedNames?.length) continue;
-        const acceptedNames = new Set(cliOption.acceptedNames);
-        const preferredLabel = formatCliOptionName(cliOption.preferredName ?? key);
+        const preferredLabel = formatCliOptionName(cliOption?.preferredName ?? key);
+        const acceptedNames = new Set(getAcceptedCliOptionNames(key, cliOption));
         const knownSpellings = new Set([
             key,
             ...getKeyAliases(key),
-            cliOption.preferredName ?? key,
-            ...cliOption.aliases ?? [],
-            ...cliOption.acceptedNames
+            ...cliOption?.preferredName ? getKeyAliases(cliOption.preferredName) : [],
+            ...cliOption?.aliases ?? []
         ]);
         for (const spelling of knownSpellings)if (!acceptedNames.has(spelling)) disallowedSpellings.set(spelling, preferredLabel);
     }
-    for (const arg of args){
-        if (!arg.startsWith('--')) continue;
-        const key = arg.slice(2).split('=')[0];
+    return disallowedSpellings;
+}
+function formatCliValidationError(scriptName, commandName, def, rawArgs) {
+    if (0 === Object.keys(def.schema).length) return;
+    const cliSchema = z.object(buildCliArgSchema(def)).strict();
+    const parsed = cliSchema.safeParse(rawArgs);
+    if (parsed.success) return;
+    const disallowedSpellings = buildDisallowedCliSpellings(def);
+    const unknownKeys = parsed.error.issues.flatMap((issue)=>'unrecognized_keys' === issue.code ? issue.keys : []);
+    if (unknownKeys.length > 0) return unknownKeys.map((key)=>{
         const preferredLabel = disallowedSpellings.get(key);
-        if (preferredLabel) throw new CLIError(`Unsupported option "--${key}" for ${scriptName} ${commandName}. Use "${preferredLabel}" instead.`);
-    }
+        if (preferredLabel) return `Unsupported option "--${key}" for ${scriptName} ${commandName}. Use "${preferredLabel}" instead.`;
+        return `Unknown option "--${key}" for ${scriptName} ${commandName}.`;
+    }).join('\n');
+    const [issue] = parsed.error.issues;
+    const optionName = 'string' == typeof issue?.path[0] ? `--${issue.path[0]}` : 'CLI arguments';
+    return `Invalid value for "${optionName}" in ${scriptName} ${commandName}: ${issue?.message ?? parsed.error.message}`;
 }
 function printCommandHelp(scriptName, cmd) {
     const { def } = cmd;
@@ -196,14 +237,16 @@ async function runToolsCLI(tools, scriptName, options) {
         printHelp(scriptName, commands, cliVersion);
         throw new CLIError(`Unknown command: ${commandName}`);
     }
-    validateRestrictedCliArgSpellings(restArgs, scriptName, match.name, match.def);
-    const parsedArgs = parseCliArgs(restArgs);
-    debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
-    if (true === parsedArgs.help) {
+    const rawCliArgs = parseRawCliArgs(restArgs);
+    if (true === rawCliArgs.help) {
         debug('showing command help for: %s', match.name);
         printCommandHelp(scriptName, match);
         return;
     }
+    const cliValidationError = formatCliValidationError(scriptName, match.name, match.def, rawCliArgs);
+    if (cliValidationError) throw new CLIError(cliValidationError);
+    const parsedArgs = parseCliArgs(restArgs);
+    debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
     const result = await match.def.handler(parsedArgs);
     debug('command %s completed, isError: %s', match.name, result.isError ?? false);
     outputResult(result);

package/dist/es/mcp/base-tools.mjs

@@ -37,26 +37,18 @@ class BaseMidsceneTools {
         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 = this.initArgSpec.cli?.preferBareKeys ? [
-                ...new Set([
-                    preferredName,
-                    ...getKeyAliases(key)
-                ])
-            ] : void 0;
-            const aliases = new Set(acceptedNames ?? getKeyAliases(key));
-            if (this.initArgSpec.cli?.preferBareKeys) aliases.delete(preferredName);
-            else {
-                for (const alias of getKeyAliases(canonicalKey))aliases.add(alias);
-                aliases.delete(preferredName);
-            }
+            const acceptedNames = new Set([
+                preferredName,
+                ...this.initArgSpec.cli?.preferBareKeys ? getKeyAliases(key) : getKeyAliases(canonicalKey)
+            ]);
+            acceptedNames.delete(preferredName);
             return [
                 canonicalKey,
                 {
                     preferredName,
                     aliases: [
-                        ...aliases
-                    ],
-                    acceptedNames
+                        ...acceptedNames
+                    ]
                 }
             ];
         }));

package/dist/lib/cli/cli-runner.js

@@ -44,6 +44,7 @@ const external_node_os_namespaceObject = require("node:os");
 const external_node_path_namespaceObject = require("node:path");
 const external_dotenv_namespaceObject = require("dotenv");
 var external_dotenv_default = /*#__PURE__*/ __webpack_require__.n(external_dotenv_namespaceObject);
+const external_zod_namespaceObject = require("zod");
 const external_key_alias_utils_js_namespaceObject = require("../key-alias-utils.js");
 const external_logger_js_namespaceObject = require("../logger.js");
 function _define_property(obj, key, value) {
@@ -69,9 +70,29 @@ function parseValue(raw) {
     if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
     return raw;
 }
+function walkCliArgs(args, setArgValue) {
+    for(let i = 0; i < args.length; i++){
+        const arg = args[i];
+        if (!arg.startsWith('--')) continue;
+        const body = arg.slice(2);
+        const eqIdx = body.indexOf('=');
+        if (eqIdx >= 0) setArgValue(body.slice(0, eqIdx), parseValue(body.slice(eqIdx + 1)));
+        else if (args[i + 1] && !args[i + 1].startsWith('--')) {
+            i++;
+            setArgValue(body, parseValue(args[i]));
+        } else setArgValue(body, true);
+    }
+}
+function parseRawCliArgs(args) {
+    const result = {};
+    walkCliArgs(args, (key, value)=>{
+        result[key] = value;
+    });
+    return result;
+}
 function parseCliArgs(args) {
     const result = {};
-    const setArgValue = (key, value)=>{
+    walkCliArgs(args, (key, value)=>{
         if (!key.includes('.')) {
             result[key] = value;
             return;
@@ -90,18 +111,7 @@ function parseCliArgs(args) {
         }
         const leafSegment = segments[segments.length - 1];
         for (const alias of (0, external_key_alias_utils_js_namespaceObject.getKeyAliases)(leafSegment))current[alias] = value;
-    };
-    for(let i = 0; i < args.length; i++){
-        const arg = args[i];
-        if (!arg.startsWith('--')) continue;
-        const body = arg.slice(2);
-        const eqIdx = body.indexOf('=');
-        if (eqIdx >= 0) setArgValue(body.slice(0, eqIdx), parseValue(body.slice(eqIdx + 1)));
-        else if (args[i + 1] && !args[i + 1].startsWith('--')) {
-            i++;
-            setArgValue(body, parseValue(args[i]));
-        } else setArgValue(body, true);
-    }
+    });
     return result;
 }
 function outputContentItem(item, isError) {
@@ -142,28 +152,59 @@ function getCliOptionDisplay(key, cliOption) {
         aliases
     };
 }
-function validateRestrictedCliArgSpellings(args, scriptName, commandName, def) {
+function getAcceptedCliOptionNames(key, cliOption) {
+    return [
+        ...new Set(cliOption ? [
+            cliOption.preferredName ?? key,
+            ...cliOption.aliases ?? []
+        ] : [
+            key,
+            ...(0, external_key_alias_utils_js_namespaceObject.getKeyAliases)(key)
+        ])
+    ];
+}
+function toOptionalCliSchemaField(field) {
+    if ('object' == typeof field && null !== field && 'function' == typeof field.optional) return field.optional();
+    const description = 'object' == typeof field && null !== field && "description" in field && 'string' == typeof field.description ? field.description : void 0;
+    return description ? external_zod_namespaceObject.z.any().describe(description) : external_zod_namespaceObject.z.any();
+}
+function buildCliArgSchema(def) {
+    return Object.fromEntries(Object.entries(def.schema).flatMap(([key, zodType])=>getAcceptedCliOptionNames(key, def.cli?.options?.[key]).map((cliKey)=>[
+                cliKey,
+                toOptionalCliSchemaField(zodType)
+            ])));
+}
+function buildDisallowedCliSpellings(def) {
     const disallowedSpellings = new Map();
     for (const [key] of Object.entries(def.schema)){
         const cliOption = def.cli?.options?.[key];
-        if (!cliOption?.acceptedNames?.length) continue;
-        const acceptedNames = new Set(cliOption.acceptedNames);
-        const preferredLabel = formatCliOptionName(cliOption.preferredName ?? key);
+        const preferredLabel = formatCliOptionName(cliOption?.preferredName ?? key);
+        const acceptedNames = new Set(getAcceptedCliOptionNames(key, cliOption));
         const knownSpellings = new Set([
             key,
             ...(0, external_key_alias_utils_js_namespaceObject.getKeyAliases)(key),
-            cliOption.preferredName ?? key,
-            ...cliOption.aliases ?? [],
-            ...cliOption.acceptedNames
+            ...cliOption?.preferredName ? (0, external_key_alias_utils_js_namespaceObject.getKeyAliases)(cliOption.preferredName) : [],
+            ...cliOption?.aliases ?? []
         ]);
         for (const spelling of knownSpellings)if (!acceptedNames.has(spelling)) disallowedSpellings.set(spelling, preferredLabel);
     }
-    for (const arg of args){
-        if (!arg.startsWith('--')) continue;
-        const key = arg.slice(2).split('=')[0];
+    return disallowedSpellings;
+}
+function formatCliValidationError(scriptName, commandName, def, rawArgs) {
+    if (0 === Object.keys(def.schema).length) return;
+    const cliSchema = external_zod_namespaceObject.z.object(buildCliArgSchema(def)).strict();
+    const parsed = cliSchema.safeParse(rawArgs);
+    if (parsed.success) return;
+    const disallowedSpellings = buildDisallowedCliSpellings(def);
+    const unknownKeys = parsed.error.issues.flatMap((issue)=>'unrecognized_keys' === issue.code ? issue.keys : []);
+    if (unknownKeys.length > 0) return unknownKeys.map((key)=>{
         const preferredLabel = disallowedSpellings.get(key);
-        if (preferredLabel) throw new CLIError(`Unsupported option "--${key}" for ${scriptName} ${commandName}. Use "${preferredLabel}" instead.`);
-    }
+        if (preferredLabel) return `Unsupported option "--${key}" for ${scriptName} ${commandName}. Use "${preferredLabel}" instead.`;
+        return `Unknown option "--${key}" for ${scriptName} ${commandName}.`;
+    }).join('\n');
+    const [issue] = parsed.error.issues;
+    const optionName = 'string' == typeof issue?.path[0] ? `--${issue.path[0]}` : 'CLI arguments';
+    return `Invalid value for "${optionName}" in ${scriptName} ${commandName}: ${issue?.message ?? parsed.error.message}`;
 }
 function printCommandHelp(scriptName, cmd) {
     const { def } = cmd;
@@ -238,14 +279,16 @@ async function runToolsCLI(tools, scriptName, options) {
         printHelp(scriptName, commands, cliVersion);
         throw new CLIError(`Unknown command: ${commandName}`);
     }
-    validateRestrictedCliArgSpellings(restArgs, scriptName, match.name, match.def);
-    const parsedArgs = parseCliArgs(restArgs);
-    debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
-    if (true === parsedArgs.help) {
+    const rawCliArgs = parseRawCliArgs(restArgs);
+    if (true === rawCliArgs.help) {
         debug('showing command help for: %s', match.name);
         printCommandHelp(scriptName, match);
         return;
     }
+    const cliValidationError = formatCliValidationError(scriptName, match.name, match.def, rawCliArgs);
+    if (cliValidationError) throw new CLIError(cliValidationError);
+    const parsedArgs = parseCliArgs(restArgs);
+    debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
     const result = await match.def.handler(parsedArgs);
     debug('command %s completed, isError: %s', match.name, result.isError ?? false);
     outputResult(result);

package/dist/lib/mcp/base-tools.js

@@ -65,26 +65,18 @@ class BaseMidsceneTools {
         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 ? (0, external_key_alias_utils_js_namespaceObject.camelToKebab)(key) : canonicalKey);
-            const acceptedNames = this.initArgSpec.cli?.preferBareKeys ? [
-                ...new Set([
-                    preferredName,
-                    ...(0, external_key_alias_utils_js_namespaceObject.getKeyAliases)(key)
-                ])
-            ] : void 0;
-            const aliases = new Set(acceptedNames ?? (0, external_key_alias_utils_js_namespaceObject.getKeyAliases)(key));
-            if (this.initArgSpec.cli?.preferBareKeys) aliases.delete(preferredName);
-            else {
-                for (const alias of (0, external_key_alias_utils_js_namespaceObject.getKeyAliases)(canonicalKey))aliases.add(alias);
-                aliases.delete(preferredName);
-            }
+            const acceptedNames = new Set([
+                preferredName,
+                ...this.initArgSpec.cli?.preferBareKeys ? (0, external_key_alias_utils_js_namespaceObject.getKeyAliases)(key) : (0, external_key_alias_utils_js_namespaceObject.getKeyAliases)(canonicalKey)
+            ]);
+            acceptedNames.delete(preferredName);
             return [
                 canonicalKey,
                 {
                     preferredName,
                     aliases: [
-                        ...aliases
-                    ],
-                    acceptedNames
+                        ...acceptedNames
+                    ]
                 }
             ];
         }));

package/dist/types/mcp/types.d.ts

@@ -52,7 +52,6 @@ export type ToolSchema = Record<string, z.ZodTypeAny>;
 export interface ToolCliOption {
     preferredName?: string;
     aliases?: string[];
-    acceptedNames?: string[];
 }
 export interface ToolCliMetadata {
     options?: Record<string, ToolCliOption>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/shared",
-  "version": "1.7.5-beta-20260420035759.0",
+  "version": "1.7.5-beta-20260420052829.0",
   "repository": "https://github.com/web-infra-dev/midscene",
   "homepage": "https://midscenejs.com/",
   "types": "./dist/types/index.d.ts",

package/src/cli/cli-runner.ts

@@ -2,6 +2,7 @@ import { existsSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import dotenv from 'dotenv';
+import { z } from 'zod';
 import { getKeyAliases, isRecord } from '../key-alias-utils';
 import { getDebug } from '../logger';
 import type { BaseMidsceneTools } from '../mcp/base-tools';
@@ -61,10 +62,43 @@ export function parseValue(raw: string): unknown {
   return raw;
 }
 
+function walkCliArgs(
+  args: string[],
+  setArgValue: (key: string, value: unknown) => void,
+): void {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) continue;
+
+    const body = arg.slice(2);
+    const eqIdx = body.indexOf('=');
+
+    if (eqIdx >= 0) {
+      // --key=value
+      setArgValue(body.slice(0, eqIdx), parseValue(body.slice(eqIdx + 1)));
+    } else if (args[i + 1] && !args[i + 1].startsWith('--')) {
+      // --key value
+      i++;
+      setArgValue(body, parseValue(args[i]));
+    } else {
+      // --flag (boolean)
+      setArgValue(body, true);
+    }
+  }
+}
+
+function parseRawCliArgs(args: string[]): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  walkCliArgs(args, (key, value) => {
+    result[key] = value;
+  });
+  return result;
+}
+
 export function parseCliArgs(args: string[]): Record<string, unknown> {
   const result: Record<string, unknown> = {};
 
-  const setArgValue = (key: string, value: unknown) => {
+  walkCliArgs(args, (key, value) => {
     if (!key.includes('.')) {
       result[key] = value;
       return;
@@ -98,27 +132,7 @@ export function parseCliArgs(args: string[]): Record<string, unknown> {
     for (const alias of getKeyAliases(leafSegment)) {
       current[alias] = value;
     }
-  };
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (!arg.startsWith('--')) continue;
-
-    const body = arg.slice(2);
-    const eqIdx = body.indexOf('=');
-
-    if (eqIdx >= 0) {
-      // --key=value
-      setArgValue(body.slice(0, eqIdx), parseValue(body.slice(eqIdx + 1)));
-    } else if (args[i + 1] && !args[i + 1].startsWith('--')) {
-      // --key value
-      i++;
-      setArgValue(body, parseValue(args[i]));
-    } else {
-      // --flag (boolean)
-      setArgValue(body, true);
-    }
-  }
+  });
 
   return result;
 }
@@ -175,28 +189,63 @@ function getCliOptionDisplay(
   return { label, aliases };
 }
 
-function validateRestrictedCliArgSpellings(
-  args: string[],
-  scriptName: string,
-  commandName: string,
-  def: ToolDefinition,
-): void {
+function getAcceptedCliOptionNames(
+  key: string,
+  cliOption?: ToolCliOption,
+): string[] {
+  return [
+    ...new Set(
+      cliOption
+        ? [cliOption.preferredName ?? key, ...(cliOption.aliases ?? [])]
+        : [key, ...getKeyAliases(key)],
+    ),
+  ];
+}
+
+function toOptionalCliSchemaField(field: unknown): z.ZodTypeAny {
+  if (
+    typeof field === 'object' &&
+    field !== null &&
+    typeof (field as z.ZodTypeAny).optional === 'function'
+  ) {
+    return (field as z.ZodTypeAny).optional();
+  }
+
+  const description =
+    typeof field === 'object' &&
+    field !== null &&
+    'description' in field &&
+    typeof (field as { description?: unknown }).description === 'string'
+      ? (field as { description: string }).description
+      : undefined;
+  return description ? z.any().describe(description) : z.any();
+}
+
+function buildCliArgSchema(def: ToolDefinition): Record<string, z.ZodTypeAny> {
+  return Object.fromEntries(
+    Object.entries(def.schema).flatMap(([key, zodType]) =>
+      getAcceptedCliOptionNames(key, def.cli?.options?.[key]).map((cliKey) => [
+        cliKey,
+        toOptionalCliSchemaField(zodType),
+      ]),
+    ),
+  );
+}
+
+function buildDisallowedCliSpellings(def: ToolDefinition): Map<string, string> {
   const disallowedSpellings = new Map<string, string>();
 
   for (const [key] of Object.entries(def.schema)) {
     const cliOption = def.cli?.options?.[key];
-    if (!cliOption?.acceptedNames?.length) {
-      continue;
-    }
-
-    const acceptedNames = new Set(cliOption.acceptedNames);
-    const preferredLabel = formatCliOptionName(cliOption.preferredName ?? key);
+    const preferredLabel = formatCliOptionName(cliOption?.preferredName ?? key);
+    const acceptedNames = new Set(getAcceptedCliOptionNames(key, cliOption));
     const knownSpellings = new Set<string>([
       key,
       ...getKeyAliases(key),
-      cliOption.preferredName ?? key,
-      ...(cliOption.aliases ?? []),
-      ...cliOption.acceptedNames,
+      ...(cliOption?.preferredName
+        ? getKeyAliases(cliOption.preferredName)
+        : []),
+      ...(cliOption?.aliases ?? []),
     ]);
 
     for (const spelling of knownSpellings) {
@@ -206,21 +255,46 @@ function validateRestrictedCliArgSpellings(
     }
   }
 
-  for (const arg of args) {
-    if (!arg.startsWith('--')) {
-      continue;
-    }
+  return disallowedSpellings;
+}
 
-    const key = arg.slice(2).split('=')[0];
-    const preferredLabel = disallowedSpellings.get(key);
-    if (!preferredLabel) {
-      continue;
-    }
+function formatCliValidationError(
+  scriptName: string,
+  commandName: string,
+  def: ToolDefinition,
+  rawArgs: Record<string, unknown>,
+): string | undefined {
+  if (Object.keys(def.schema).length === 0) {
+    return undefined;
+  }
 
-    throw new CLIError(
-      `Unsupported option "--${key}" for ${scriptName} ${commandName}. Use "${preferredLabel}" instead.`,
-    );
+  const cliSchema = z.object(buildCliArgSchema(def)).strict();
+  const parsed = cliSchema.safeParse(rawArgs);
+  if (parsed.success) {
+    return undefined;
   }
+
+  const disallowedSpellings = buildDisallowedCliSpellings(def);
+  const unknownKeys = parsed.error.issues.flatMap((issue) =>
+    issue.code === 'unrecognized_keys' ? issue.keys : [],
+  );
+
+  if (unknownKeys.length > 0) {
+    return unknownKeys
+      .map((key) => {
+        const preferredLabel = disallowedSpellings.get(key);
+        if (preferredLabel) {
+          return `Unsupported option "--${key}" for ${scriptName} ${commandName}. Use "${preferredLabel}" instead.`;
+        }
+        return `Unknown option "--${key}" for ${scriptName} ${commandName}.`;
+      })
+      .join('\n');
+  }
+
+  const [issue] = parsed.error.issues;
+  const optionName =
+    typeof issue?.path[0] === 'string' ? `--${issue.path[0]}` : 'CLI arguments';
+  return `Invalid value for "${optionName}" in ${scriptName} ${commandName}: ${issue?.message ?? parsed.error.message}`;
 }
 
 function printCommandHelp(scriptName: string, cmd: CLICommand): void {
@@ -343,21 +417,26 @@ export async function runToolsCLI(
     throw new CLIError(`Unknown command: ${commandName}`);
   }
 
-  validateRestrictedCliArgSpellings(
-    restArgs,
+  const rawCliArgs = parseRawCliArgs(restArgs);
+  if (rawCliArgs.help === true) {
+    debug('showing command help for: %s', match.name);
+    printCommandHelp(scriptName, match);
+    return;
+  }
+
+  const cliValidationError = formatCliValidationError(
     scriptName,
     match.name,
     match.def,
+    rawCliArgs,
   );
+  if (cliValidationError) {
+    throw new CLIError(cliValidationError);
+  }
+
   const parsedArgs = parseCliArgs(restArgs);
   debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
 
-  if (parsedArgs.help === true) {
-    debug('showing command help for: %s', match.name);
-    printCommandHelp(scriptName, match);
-    return;
-  }
-
   const result = await match.def.handler(parsedArgs);
   debug(
     'command %s completed, isError: %s',

package/src/mcp/base-tools.ts

@@ -162,25 +162,19 @@ export abstract class BaseMidsceneTools<
             ? camelToKebab(key)
             : canonicalKey);
 
-        const acceptedNames = this.initArgSpec!.cli?.preferBareKeys
-          ? [...new Set([preferredName, ...getKeyAliases(key)])]
-          : undefined;
-        const aliases = new Set<string>(acceptedNames ?? getKeyAliases(key));
-        if (this.initArgSpec!.cli?.preferBareKeys) {
-          aliases.delete(preferredName);
-        } else {
-          for (const alias of getKeyAliases(canonicalKey)) {
-            aliases.add(alias);
-          }
-          aliases.delete(preferredName);
-        }
+        const acceptedNames = new Set<string>([
+          preferredName,
+          ...(this.initArgSpec!.cli?.preferBareKeys
+            ? getKeyAliases(key)
+            : getKeyAliases(canonicalKey)),
+        ]);
+        acceptedNames.delete(preferredName);
 
         return [
           canonicalKey,
           {
             preferredName,
-            aliases: [...aliases],
-            acceptedNames,
+            aliases: [...acceptedNames],
           },
         ];
       }),

package/src/mcp/types.ts

@@ -50,7 +50,6 @@ export type ToolSchema = Record<string, z.ZodTypeAny>;
 export interface ToolCliOption {
   preferredName?: string;
   aliases?: string[];
-  acceptedNames?: string[];
 }
 
 export interface ToolCliMetadata {