feat: Update version to 0.3.9, add ajv-errors support, and refactor JSON schema creation

Author: yaonyan

deno.lock

@@ -1,6 +1,6 @@
 {
   "name": "@mcpc/core",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mcpc-tech/mcpc.git"
@@ -29,6 +29,7 @@
     "@segment/ajv-human-errors": "npm:@segment/ajv-human-errors@^2.15.0",
     "@std/assert": "jsr:@std/assert@1",
     "ajv": "npm:ajv@^8.17.1",
+    "ajv-errors": "npm:ajv-errors@^3.0.0",
     "ajv-formats": "npm:ajv-formats@^3.0.1",
     "cheerio": "npm:cheerio@^1.0.0",
     "jsonrepair": "npm:jsonrepair@^3.13.0"

packages/core/deno.json

@@ -104,6 +104,15 @@ export class AgenticExecutor {
 
         const result: CallToolResult = { content: [] };
         this.appendToolSchemas(result, definitionsOf, hasDefinitions);
+        
+        // If no schemas were added (all requested tools already in hasDefinitions), give feedback
+        if (result.content.length === 0 && definitionsOf.length > 0) {
+          result.content.push({
+            type: "text",
+            text: `All requested tool schemas are already in hasDefinitions. You can now call a tool using "${this.USE_TOOL_KEY}".`,
+          });
+        }
+        
         return result;
       }
 
@@ -221,7 +230,8 @@ export class AgenticExecutor {
         }
       }
 
-      // Tool not found
+      // Tool not found - this should not happen if schema validation is working
+      // but keep as a fallback for safety
       if (executeSpan) {
         executeSpan.setAttributes({
           toolType: "not_found",
@@ -230,17 +240,15 @@ export class AgenticExecutor {
         endSpan(executeSpan);
       }
 
-      this.logger.warning({
-        message: "Tool not found",
-        useTool,
-        availableTools: this.allToolNames,
-      });
-
-      const result: CallToolResult = {
-        content: [],
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Tool "${useTool}" not found. Available tools: ${this.allToolNames.join(", ")}.`,
+          },
+        ],
+        isError: true,
       };
-      this.appendToolSchemas(result, definitionsOf, hasDefinitions);
-      return result;
     } catch (error) {
       // Catch any unexpected errors
       if (executeSpan) {

packages/core/src/executors/agentic/agentic-executor.ts

@@ -1,6 +1,6 @@
 import { jsonSchema } from "../../utils/schema.ts";
 import type { SamplingConfig } from "../../types.ts";
-import { createGoogleCompatibleJSONSchema } from "../../utils/common/provider.ts";
+import { createModelCompatibleJSONSchema } from "../../utils/common/provider.ts";
 import type { ComposableMCPServer } from "../../compose.ts";
 import { CompiledPrompts } from "../../prompts/index.ts";
 import { SamplingExecutor } from "../sampling/agentic-sampling-executor.ts";
@@ -62,7 +62,7 @@ export function registerAgenticSamplingTool(
     name,
     description,
     jsonSchema<Record<string, unknown>>(
-      createGoogleCompatibleJSONSchema(schema as Record<string, unknown>),
+      createModelCompatibleJSONSchema(schema as Record<string, unknown>),
     ),
     async (args: Record<string, unknown>) => {
       return await samplingExecutor.executeSampling(

packages/core/src/executors/agentic/agentic-sampling-registrar.ts

@@ -1,6 +1,6 @@
 import { jsonSchema, type Schema } from "../../utils/schema.ts";
 import type { RegisterToolParams } from "../../types.ts";
-import { createGoogleCompatibleJSONSchema } from "../../utils/common/provider.ts";
+import { createModelCompatibleJSONSchema } from "../../utils/common/provider.ts";
 import type { ComposableMCPServer } from "../../compose.ts";
 import { CompiledPrompts } from "../../prompts/index.ts";
 import { AgenticExecutor } from "./agentic-executor.ts";
@@ -51,7 +51,7 @@ export function registerAgenticTool(
     name,
     description,
     jsonSchema<Record<string, unknown>>(
-      createGoogleCompatibleJSONSchema(schema as Record<string, unknown>),
+      createModelCompatibleJSONSchema(schema as Record<string, unknown>),
     ),
     async (args: Record<string, unknown>) => {
       return await agenticExecutor.execute(

packages/core/src/executors/agentic/agentic-tool-registrar.ts

@@ -2,7 +2,7 @@ import { jsonSchema } from "../../utils/schema.ts";
 import type { SamplingConfig } from "../../types.ts";
 import type { MCPCStep } from "../../utils/state.ts";
 import { WorkflowState } from "../../utils/state.ts";
-import { createGoogleCompatibleJSONSchema } from "../../utils/common/provider.ts";
+import { createModelCompatibleJSONSchema } from "../../utils/common/provider.ts";
 import type { ComposableMCPServer } from "../../compose.ts";
 import { CompiledPrompts } from "../../prompts/index.ts";
 import { createArgsDefFactory } from "../../factories/args-def-factory.ts";
@@ -75,7 +75,7 @@ export function registerWorkflowSamplingTool(
     name,
     baseDescription,
     jsonSchema<Record<string, unknown>>(
-      createGoogleCompatibleJSONSchema(schema as Record<string, unknown>),
+      createModelCompatibleJSONSchema(schema as Record<string, unknown>),
     ),
     async (args: Record<string, unknown>) => {
       try {

packages/core/src/executors/workflow/workflow-sampling-registrar.ts

@@ -1,7 +1,7 @@
 import { jsonSchema } from "../../utils/schema.ts";
 import type { RegisterWorkflowToolParams } from "../../types.ts";
 import { WorkflowState } from "../../utils/state.ts";
-import { createGoogleCompatibleJSONSchema } from "../../utils/common/provider.ts";
+import { createModelCompatibleJSONSchema } from "../../utils/common/provider.ts";
 import { WorkflowExecutor } from "./workflow-executor.ts";
 import type { ComposableMCPServer } from "../../compose.ts";
 import { CompiledPrompts } from "../../prompts/index.ts";
@@ -65,7 +65,7 @@ export function registerAgenticWorkflowTool(
     name,
     toolDescription,
     jsonSchema<Record<string, unknown>>(
-      createGoogleCompatibleJSONSchema(argsDef),
+      createModelCompatibleJSONSchema(argsDef),
     ),
     async (args: Record<string, unknown>) => {
       try {

packages/core/src/executors/workflow/workflow-tool-registrar.ts

@@ -171,41 +171,6 @@ Workflow step definitions - provide ONLY on initial call.
       USE_TOOL_KEY: string = "useTool",
     ): JSONSchema {
       const allOf = [
-        // When hasDefinitions is empty, definitionsOf must be provided
-        {
-          if: {
-            properties: {
-              hasDefinitions: {
-                type: "array",
-                maxItems: 0,
-              },
-            },
-            required: ["hasDefinitions"],
-          },
-          then: {
-            required: ["definitionsOf"],
-          },
-        },
-        // When useTool is present, hasDefinitions must contain that tool
-        ...toolNameToDetailList.map(
-          ([toolName, _toolDetail]: [string, unknown]) => {
-            return {
-              if: {
-                properties: { [USE_TOOL_KEY]: { const: toolName } },
-                required: [USE_TOOL_KEY],
-              },
-              then: {
-                properties: {
-                  hasDefinitions: {
-                    type: "array",
-                    contains: { const: toolName },
-                  },
-                },
-                required: ["hasDefinitions"],
-              },
-            };
-          },
-        ),
         // When a specific tool is selected, its parameters must be provided
         ...toolNameToDetailList.map(
           ([toolName, _toolDetail]: [string, unknown]) => {
@@ -216,6 +181,11 @@ Workflow step definitions - provide ONLY on initial call.
               },
               then: {
                 required: [toolName],
+                errorMessage: {
+                  required: {
+                    [toolName]: `Tool "${toolName}" is selected but its parameters are missing. Please provide "${toolName}": { ...parameters }.`,
+                  },
+                },
               },
             };
           },
@@ -234,6 +204,9 @@ Workflow step definitions - provide ONLY on initial call.
           type: "string",
           enum: allToolNames,
           description: useToolDescription,
+          errorMessage: {
+            enum: `Invalid tool name. Available tools: ${allToolNames.join(", ")}.`,
+          },
         },
         hasDefinitions: {
           type: "array",
@@ -264,6 +237,28 @@ Workflow step definitions - provide ONLY on initial call.
         schema.allOf = allOf;
       }
 
+      // Add conditional validation: if definitionsOf is empty/missing, useTool is required
+      if (allToolNames.length > 0) {
+        const thenClause = {
+          required: [USE_TOOL_KEY],
+          errorMessage: {
+            required: {
+              [USE_TOOL_KEY]: `No tool selected. Please specify "${USE_TOOL_KEY}" to select one of: ${allToolNames.join(", ")}. Or use "definitionsOf" with tool names to get their schemas first.`,
+            },
+          },
+        };
+        Object.assign(schema, {
+          if: {
+            // definitionsOf is not provided OR is empty array
+            anyOf: [
+              { not: { required: ["definitionsOf"] } },
+              { properties: { definitionsOf: { type: "array", maxItems: 0 } } },
+            ],
+          },
+          then: thenClause,
+        });
+      }
+
       return schema;
     },
 

packages/core/src/factories/args-def-factory.ts

@@ -36,36 +36,48 @@ export const createGoogleJSONSchema = (
 };
 
 /**
- * Creates a Google-compatible JSON schema by removing unsupported features
+ * Creates a model-compatible JSON schema by removing validation-only features
  *
- * Google provider restrictions:
+ * Always removes:
+ * - errorMessage: AJV-specific custom error messages, not part of JSON Schema spec
+ *
+ * Google provider restrictions (when GEMINI_PREFERRED_FORMAT is enabled):
  * - Does not support additionalProperties in schema definitions (at any level)
  * - Does not support oneOf, allOf, or anyOf at the top level in input_schema
  * @see https://ai.google.dev/api/caching#Schema
  */
-export const createGoogleCompatibleJSONSchema = (
+export const createModelCompatibleJSONSchema = (
   schema: Record<string, unknown>,
 ): Record<string, unknown> => {
-  if (!GEMINI_PREFERRED_FORMAT) {
-    return schema;
-  }
+  // Keys to always remove (not part of JSON Schema spec, used by validators only)
+  const validatorOnlyKeys = ["errorMessage"];
+
+  // Keys to remove only for Gemini
+  const geminiRestrictedKeys = GEMINI_PREFERRED_FORMAT
+    ? ["additionalProperties"]
+    : [];
 
-  // Remove top-level composition keywords
-  const { oneOf: _oneOf, allOf: _allOf, anyOf: _anyOf, ...cleanSchema } =
-    schema;
+  const keysToRemove = new Set([...validatorOnlyKeys, ...geminiRestrictedKeys]);
+
+  // Remove top-level composition keywords for Gemini
+  let cleanSchema = schema;
+  if (GEMINI_PREFERRED_FORMAT) {
+    const { oneOf: _oneOf, allOf: _allOf, anyOf: _anyOf, ...rest } = schema;
+    cleanSchema = rest;
+  }
 
-  // Recursively remove additionalProperties at all levels
-  const removeAdditionalProperties = (obj: any): any => {
+  // Recursively clean schema
+  const cleanRecursively = (obj: unknown): unknown => {
     if (Array.isArray(obj)) {
-      return obj.map(removeAdditionalProperties);
+      return obj.map(cleanRecursively);
     }
 
     if (obj && typeof obj === "object") {
       const result: Record<string, unknown> = {};
 
       for (const [key, value] of Object.entries(obj)) {
-        if (key !== "additionalProperties") {
-          result[key] = removeAdditionalProperties(value);
+        if (!keysToRemove.has(key)) {
+          result[key] = cleanRecursively(value);
         }
       }
 
@@ -75,5 +87,5 @@ export const createGoogleCompatibleJSONSchema = (
     return obj;
   };
 
-  return removeAdditionalProperties(cleanSchema);
+  return cleanRecursively(cleanSchema) as Record<string, unknown>;
 };

packages/core/src/utils/common/provider.ts

@@ -1,25 +1,40 @@
 import { Ajv } from "ajv";
 import addFormats from "ajv-formats";
+import ajvErrors from "ajv-errors";
 import { AggregateAjvError } from "@segment/ajv-human-errors";
 
-// Singleton Ajv instance
+// Singleton Ajv instance with custom error message support
 const ajv = new Ajv({
   allErrors: true,
   verbose: true,
 });
 
 addFormats.default(ajv);
+ajvErrors.default(ajv);
 
 export function validateSchema(
   args: Record<string, unknown>,
   schema: Record<string, unknown>,
 ): { valid: boolean; error?: string } {
   const validate = ajv.compile(schema);
   if (!validate(args)) {
-    const errors = new AggregateAjvError(validate.errors!);
+    const errors = validate.errors!;
+    
+    // If there are custom errorMessage errors, use only those
+    const customErrors = errors.filter((err) => err.keyword === "errorMessage");
+    if (customErrors.length > 0) {
+      const messages = [...new Set(customErrors.map((err) => err.message))];
+      return {
+        valid: false,
+        error: messages.join("; "),
+      };
+    }
+    
+    // Fallback to human-readable error formatting
+    const aggregateError = new AggregateAjvError(errors);
     return {
       valid: false,
-      error: errors.message,
+      error: aggregateError.message,
     };
   }
   return { valid: true };