feat: improve error messages for unrecognized CLI tool params and accept camelCase aliases

Add parameter normalization layer (buildEnhancedToolSchema) that:
- Silently normalizes camelCase/snake_case keys to kebab-case equivalents
  (e.g. sourceRoot → source-root)
- Rejects truly unknown properties with the property name in the error
  and a "did you mean?" suggestion when a close match exists
- Applies to all 16+ CLI tools that use kebab-case parameter names

Closes #208 (Area 2)

Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/5ed1c1a7-10c5-4e53-8454-128d1d6e46ae

Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

Author: Copilot

server/dist/codeql-development-mcp-server.js

@@ -188583,6 +188583,56 @@ function getOrCreateLogDirectory(logDir) {
   return uniqueLogDir;
 }
 
+// src/lib/param-normalization.ts
+function camelToKebabCase(key) {
+  return key.replace(/[A-Z]/g, (ch) => "-" + ch.toLowerCase());
+}
+function kebabToCamelCase(key) {
+  return key.replace(/-([a-z])/g, (_match, ch) => ch.toUpperCase());
+}
+function suggestPropertyName(key, knownKeys) {
+  const kebab = camelToKebabCase(key);
+  if (kebab !== key && knownKeys.has(kebab)) return kebab;
+  const snakeToKebab = key.replace(/_/g, "-");
+  if (snakeToKebab !== key && knownKeys.has(snakeToKebab)) return snakeToKebab;
+  const camel = kebabToCamelCase(key);
+  if (camel !== key && knownKeys.has(camel)) return camel;
+  return void 0;
+}
+function buildEnhancedToolSchema(shape) {
+  const knownKeys = new Set(Object.keys(shape));
+  return external_exports.object(shape).passthrough().transform((data, ctx) => {
+    const normalized = {};
+    const unknownEntries = [];
+    for (const [key, value] of Object.entries(data)) {
+      if (knownKeys.has(key)) {
+        normalized[key] = value;
+      } else {
+        const suggestion = suggestPropertyName(key, knownKeys);
+        if (suggestion && !(suggestion in data) && !(suggestion in normalized)) {
+          normalized[suggestion] = value;
+        } else if (suggestion && (suggestion in data || suggestion in normalized)) {
+        } else {
+          unknownEntries.push({ key, value });
+        }
+      }
+    }
+    for (const { key } of unknownEntries) {
+      const hint = suggestPropertyName(key, knownKeys);
+      const message = hint ? `unknown property '${key}' \u2014 did you mean '${hint}'?` : `unknown property '${key}'`;
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        message,
+        path: [key]
+      });
+    }
+    if (unknownEntries.length > 0) {
+      return external_exports.NEVER;
+    }
+    return normalized;
+  });
+}
+
 // src/lib/query-resolver.ts
 init_package_paths();
 import { basename as basename3 } from "path";
@@ -193491,10 +193541,14 @@ function registerCLITool(server, definition) {
     inputSchema,
     resultProcessor = defaultCLIResultProcessor
   } = definition;
+  const enhancedSchema = buildEnhancedToolSchema(inputSchema);
   server.tool(
     name,
     description,
-    inputSchema,
+    // The enhanced schema is a pre-built ZodEffects (passthrough + transform).
+    // The MCP SDK's getZodSchemaObject() detects it as a Zod schema instance
+    // and passes it through without re-wrapping.
+    enhancedSchema,
     async (params) => {
       const tempDirsToCleanup = [];
       try {

server/dist/codeql-development-mcp-server.js.map

@@ -8,6 +8,7 @@ import { CLIExecutionResult, executeCodeQLCommand, executeQLTCommand } from './c
 import { readDatabaseMetadata, resolveDatabasePath } from './database-resolver';
 import { logger } from '../utils/logger';
 import { getOrCreateLogDirectory } from './log-directory-manager';
+import { buildEnhancedToolSchema } from './param-normalization';
 import { resolveQueryPath } from './query-resolver';
 import { cacheDatabaseAnalyzeResults, processQueryRunResults } from './result-processor';
 import { getUserWorkspaceDir, packageRootDir } from '../utils/package-paths';
@@ -91,7 +92,14 @@ export const defaultCLIResultProcessor = (
 };
 
 /**
- * Register a CLI tool with the MCP server
+ * Register a CLI tool with the MCP server.
+ *
+ * The raw `inputSchema` shape is wrapped by {@link buildEnhancedToolSchema}
+ * so that:
+ *  - camelCase / snake_case variants of kebab-case keys are silently
+ *    normalised (e.g. `sourceRoot` → `source-root`);
+ *  - truly unknown properties are rejected with a helpful error that names
+ *    the unrecognized key and, where possible, suggests the correct name.
  */
 export function registerCLITool(server: McpServer, definition: CLIToolDefinition): void {
   const {
@@ -103,10 +111,17 @@ export function registerCLITool(server: McpServer, definition: CLIToolDefinition
     resultProcessor = defaultCLIResultProcessor
   } = definition;
 
+  // Build enhanced schema that normalises property-name variants and
+  // produces actionable error messages for truly unknown keys.
+  const enhancedSchema = buildEnhancedToolSchema(inputSchema);
+
   server.tool(
     name,
     description,
-    inputSchema,
+    // The enhanced schema is a pre-built ZodEffects (passthrough + transform).
+    // The MCP SDK's getZodSchemaObject() detects it as a Zod schema instance
+    // and passes it through without re-wrapping.
+    enhancedSchema as unknown as Record<string, z.ZodTypeAny>,
     async (params: Record<string, unknown>) => {
       // Track temporary directories for cleanup
       const tempDirsToCleanup: string[] = [];

server/src/lib/cli-tool-registry.ts

@@ -0,0 +1,121 @@
+/**
+ * Parameter normalization utilities for CLI tool schemas.
+ *
+ * Provides camelCase → kebab-case key normalization and
+ * "did you mean?" suggestions for unrecognized property names.
+ */
+
+import { z } from 'zod';
+
+// ─── String-case conversion helpers ──────────────────────────────────────────
+
+/**
+ * Convert a camelCase string to kebab-case.
+ * Example: "sourceRoot" → "source-root"
+ */
+export function camelToKebabCase(key: string): string {
+  return key.replace(/[A-Z]/g, (ch) => '-' + ch.toLowerCase());
+}
+
+/**
+ * Convert a kebab-case string to camelCase.
+ * Example: "source-root" → "sourceRoot"
+ */
+export function kebabToCamelCase(key: string): string {
+  return key.replace(/-([a-z])/g, (_match, ch: string) => ch.toUpperCase());
+}
+
+// ─── Suggestion logic ────────────────────────────────────────────────────────
+
+/**
+ * Given an unrecognized property name and the set of known schema keys,
+ * return the most likely intended key (or `undefined` if no close match).
+ *
+ * Resolution order:
+ *  1. camelCase → kebab-case  (e.g. "sourceRoot" → "source-root")
+ *  2. snake_case → kebab-case (e.g. "source_root" → "source-root")
+ *  3. kebab-case → camelCase  (e.g. "source-root" → "sourceRoot")
+ */
+export function suggestPropertyName(
+  key: string,
+  knownKeys: ReadonlySet<string>,
+): string | undefined {
+  // 1. camelCase → kebab-case
+  const kebab = camelToKebabCase(key);
+  if (kebab !== key && knownKeys.has(kebab)) return kebab;
+
+  // 2. snake_case → kebab-case
+  const snakeToKebab = key.replace(/_/g, '-');
+  if (snakeToKebab !== key && knownKeys.has(snakeToKebab)) return snakeToKebab;
+
+  // 3. kebab-case → camelCase
+  const camel = kebabToCamelCase(key);
+  if (camel !== key && knownKeys.has(camel)) return camel;
+
+  return undefined;
+}
+
+// ─── Schema builder ──────────────────────────────────────────────────────────
+
+/**
+ * Build an enhanced Zod schema from a raw tool input shape.
+ *
+ * The returned schema:
+ *  - Accepts additional (unknown) properties without client-side rejection
+ *    (`passthrough` mode → JSON Schema `additionalProperties: true`).
+ *  - Normalizes camelCase / snake_case keys to their kebab-case equivalents
+ *    when a matching schema key exists.
+ *  - Rejects truly unknown properties with a helpful error that names the
+ *    unrecognized key and, when possible, suggests the correct name.
+ */
+export function buildEnhancedToolSchema(
+  shape: Record<string, z.ZodTypeAny>,
+): z.ZodTypeAny {
+  const knownKeys = new Set(Object.keys(shape));
+
+  return z
+    .object(shape)
+    .passthrough()
+    .transform((data, ctx) => {
+      const normalized: Record<string, unknown> = {};
+      const unknownEntries: Array<{ key: string; value: unknown }> = [];
+
+      for (const [key, value] of Object.entries(data)) {
+        if (knownKeys.has(key)) {
+          // Known key — keep as-is
+          normalized[key] = value;
+        } else {
+          // Try to find a kebab-case equivalent
+          const suggestion = suggestPropertyName(key, knownKeys);
+          if (suggestion && !(suggestion in data) && !(suggestion in normalized)) {
+            // Silently normalize to the canonical kebab-case key
+            normalized[suggestion] = value;
+          } else if (suggestion && (suggestion in data || suggestion in normalized)) {
+            // Both forms provided — prefer the canonical (kebab-case) key,
+            // silently ignore the alias
+          } else {
+            unknownEntries.push({ key, value });
+          }
+        }
+      }
+
+      // Report truly unknown properties with "did you mean?" hints
+      for (const { key } of unknownEntries) {
+        const hint = suggestPropertyName(key, knownKeys);
+        const message = hint
+          ? `unknown property '${key}' — did you mean '${hint}'?`
+          : `unknown property '${key}'`;
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message,
+          path: [key],
+        });
+      }
+
+      if (unknownEntries.length > 0) {
+        return z.NEVER;
+      }
+
+      return normalized;
+    });
+}

server/src/lib/param-normalization.ts

@@ -204,10 +204,11 @@ describe('registerCLITool', () => {
 
     registerCLITool(mockServer, definition);
 
+    // The enhanced schema wraps the raw shape in a ZodEffects (passthrough + transform)
     expect(mockServer.tool).toHaveBeenCalledWith(
       'test_codeql_tool',
       'Test CodeQL tool',
-      definition.inputSchema,
+      expect.objectContaining({ _def: expect.objectContaining({ typeName: 'ZodEffects' }) }),
       expect.any(Function)
     );
   });
@@ -226,10 +227,11 @@ describe('registerCLITool', () => {
 
     registerCLITool(mockServer, definition);
 
+    // The enhanced schema wraps the raw shape in a ZodEffects (passthrough + transform)
     expect(mockServer.tool).toHaveBeenCalledWith(
       'test_qlt_tool',
       'Test QLT tool',
-      definition.inputSchema,
+      expect.objectContaining({ _def: expect.objectContaining({ typeName: 'ZodEffects' }) }),
       expect.any(Function)
     );
   });