@kadi.build/core 0.0.1-alpha.1 → 0.0.1-alpha.11

package/dist/schemas/zod-helpers.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Zod-based Tool Creation Helpers
+ *
+ * This module provides high-level helper functions for creating tools using
+ * Zod schemas. These helpers provide excellent developer experience by:
+ * - Accepting Zod schemas for input/output validation
+ * - Automatically converting to MCP-compliant JSON Schema
+ * - Providing automatic runtime validation
+ * - Inferring TypeScript types from schemas
+ *
+ * @module schemas/zod-helpers
+ */
+import type { z } from 'zod';
+import type { ZodToolConfig, ZodToolResult } from '../types/zod-tools.js';
+/**
+ * Create a tool from Zod schemas with automatic validation
+ *
+ * This is the main developer-facing API for creating tools with Zod schemas.
+ * It provides:
+ * - Single source of truth (Zod schema)
+ * - Automatic TypeScript type inference
+ * - Automatic input/output validation
+ * - Conversion to MCP-compliant JSON Schema
+ * - Significantly less boilerplate than manual JSON Schema
+ *
+ * The function returns a tool object that can be registered with `client.registerTool()`.
+ *
+ * @typeParam TInput - Zod schema type for input
+ * @typeParam TOutput - Zod schema type for output
+ *
+ * @param config - Tool configuration with Zod schemas
+ * @returns Tool ready to register with KadiClient
+ *
+ * @throws {KadiError} If input/output schemas are not Zod object types
+ * @throws {KadiError} If schema conversion fails
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { z } from 'zod';
+ * import { createTool } from '@kadi.build/core';
+ *
+ * const addTool = createTool({
+ *   name: 'add',
+ *   description: 'Add two numbers',
+ *   version: '1.0.0',
+ *   input: z.object({
+ *     a: z.number().describe('First number'),
+ *     b: z.number().describe('Second number')
+ *   }),
+ *   output: z.object({
+ *     result: z.number().describe('Sum of a and b')
+ *   }),
+ *   handler: async ({ a, b }) => {
+ *     // Params are fully typed!
+ *     return { result: a + b };
+ *   }
+ * });
+ *
+ * // Register with client
+ * client.registerTool(addTool.definition, addTool.handler);
+ * ```
+ *
+ * @example Complex schemas with validation
+ * ```typescript
+ * const deployTool = createTool({
+ *   name: 'deployToAkash',
+ *   description: 'Deploy to Akash Network',
+ *   version: '1.0.0',
+ *   tags: ['deployment', 'cloud'],
+ *   networks: ['global', 'akash'],
+ *   input: z.object({
+ *     projectRoot: z.string().min(1).describe('Project root path'),
+ *     profile: z.string().min(1).describe('Deployment profile'),
+ *     network: z.enum(['mainnet', 'testnet', 'sandbox'])
+ *       .default('mainnet')
+ *       .describe('Akash network'),
+ *     verbose: z.boolean().default(false).describe('Verbose logging')
+ *   }),
+ *   output: z.object({
+ *     success: z.boolean(),
+ *     dseq: z.string().optional(),
+ *     error: z.string().optional()
+ *   }),
+ *   handler: async (params) => {
+ *     // Full type safety and validation
+ *     return await deployToAkash(params);
+ *   }
+ * });
+ * ```
+ *
+ * @example Destructuring for clean registration
+ * ```typescript
+ * const { definition, handler } = createTool({
+ *   name: 'greet',
+ *   input: z.object({ name: z.string() }),
+ *   output: z.object({ message: z.string() }),
+ *   handler: async ({ name }) => ({ message: `Hello, ${name}!` })
+ * });
+ *
+ * client.registerTool(definition, handler);
+ * ```
+ */
+export declare function createTool<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny>(config: ZodToolConfig<TInput, TOutput>): ZodToolResult<z.infer<TInput>, z.infer<TOutput>>;
+/**
+ * Create a simple tool with minimal configuration
+ *
+ * Convenience function for creating tools when you don't need all the
+ * configuration options. Good for quick prototyping or simple tools.
+ *
+ * @param name - Tool name
+ * @param input - Zod input schema
+ * @param output - Zod output schema
+ * @param handler - Tool handler function
+ * @returns Tool ready to register
+ *
+ * @example
+ * ```typescript
+ * const tool = createSimpleTool(
+ *   'add',
+ *   z.object({ a: z.number(), b: z.number() }),
+ *   z.object({ result: z.number() }),
+ *   async ({ a, b }) => ({ result: a + b })
+ * );
+ *
+ * client.registerTool(tool.definition, tool.handler);
+ * ```
+ */
+export declare function createSimpleTool<TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny>(name: string, input: TInput, output: TOutput, handler: (params: z.infer<TInput>) => Promise<z.infer<TOutput>> | z.infer<TOutput>): ZodToolResult<z.infer<TInput>, z.infer<TOutput>>;
+//# sourceMappingURL=zod-helpers.d.ts.map

package/dist/schemas/zod-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-helpers.d.ts","sourceRoot":"","sources":["../../src/schemas/zod-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAK1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,wBAAgB,UAAU,CACxB,MAAM,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,EAC1C,OAAO,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,EAE3C,MAAM,EAAE,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CA8HlD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,SAAS,CAAC,CAAC,UAAU,EAC3B,OAAO,SAAS,CAAC,CAAC,UAAU,EAE5B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,GACjF,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAOlD"}

package/dist/schemas/zod-helpers.js

@@ -0,0 +1,225 @@
+/**
+ * Zod-based Tool Creation Helpers
+ *
+ * This module provides high-level helper functions for creating tools using
+ * Zod schemas. These helpers provide excellent developer experience by:
+ * - Accepting Zod schemas for input/output validation
+ * - Automatically converting to MCP-compliant JSON Schema
+ * - Providing automatic runtime validation
+ * - Inferring TypeScript types from schemas
+ *
+ * @module schemas/zod-helpers
+ */
+import { zodToJsonSchema } from './zod-to-json-schema.js';
+import { KadiError, ErrorCode } from '../errors/index.js';
+/**
+ * Create a tool from Zod schemas with automatic validation
+ *
+ * This is the main developer-facing API for creating tools with Zod schemas.
+ * It provides:
+ * - Single source of truth (Zod schema)
+ * - Automatic TypeScript type inference
+ * - Automatic input/output validation
+ * - Conversion to MCP-compliant JSON Schema
+ * - Significantly less boilerplate than manual JSON Schema
+ *
+ * The function returns a tool object that can be registered with `client.registerTool()`.
+ *
+ * @typeParam TInput - Zod schema type for input
+ * @typeParam TOutput - Zod schema type for output
+ *
+ * @param config - Tool configuration with Zod schemas
+ * @returns Tool ready to register with KadiClient
+ *
+ * @throws {KadiError} If input/output schemas are not Zod object types
+ * @throws {KadiError} If schema conversion fails
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { z } from 'zod';
+ * import { createTool } from '@kadi.build/core';
+ *
+ * const addTool = createTool({
+ *   name: 'add',
+ *   description: 'Add two numbers',
+ *   version: '1.0.0',
+ *   input: z.object({
+ *     a: z.number().describe('First number'),
+ *     b: z.number().describe('Second number')
+ *   }),
+ *   output: z.object({
+ *     result: z.number().describe('Sum of a and b')
+ *   }),
+ *   handler: async ({ a, b }) => {
+ *     // Params are fully typed!
+ *     return { result: a + b };
+ *   }
+ * });
+ *
+ * // Register with client
+ * client.registerTool(addTool.definition, addTool.handler);
+ * ```
+ *
+ * @example Complex schemas with validation
+ * ```typescript
+ * const deployTool = createTool({
+ *   name: 'deployToAkash',
+ *   description: 'Deploy to Akash Network',
+ *   version: '1.0.0',
+ *   tags: ['deployment', 'cloud'],
+ *   networks: ['global', 'akash'],
+ *   input: z.object({
+ *     projectRoot: z.string().min(1).describe('Project root path'),
+ *     profile: z.string().min(1).describe('Deployment profile'),
+ *     network: z.enum(['mainnet', 'testnet', 'sandbox'])
+ *       .default('mainnet')
+ *       .describe('Akash network'),
+ *     verbose: z.boolean().default(false).describe('Verbose logging')
+ *   }),
+ *   output: z.object({
+ *     success: z.boolean(),
+ *     dseq: z.string().optional(),
+ *     error: z.string().optional()
+ *   }),
+ *   handler: async (params) => {
+ *     // Full type safety and validation
+ *     return await deployToAkash(params);
+ *   }
+ * });
+ * ```
+ *
+ * @example Destructuring for clean registration
+ * ```typescript
+ * const { definition, handler } = createTool({
+ *   name: 'greet',
+ *   input: z.object({ name: z.string() }),
+ *   output: z.object({ message: z.string() }),
+ *   handler: async ({ name }) => ({ message: `Hello, ${name}!` })
+ * });
+ *
+ * client.registerTool(definition, handler);
+ * ```
+ */
+export function createTool(config) {
+    // Validate tool name
+    if (!config.name || typeof config.name !== 'string' || config.name.trim().length === 0) {
+        throw new KadiError('Tool name must be a non-empty string', ErrorCode.INVALID_INPUT, 400, { config });
+    }
+    // Validate handler
+    if (typeof config.handler !== 'function') {
+        throw new KadiError(`Tool '${config.name}' handler must be a function`, ErrorCode.INVALID_INPUT, 400, { name: config.name, handlerType: typeof config.handler });
+    }
+    // Validate input schema exists
+    if (!config.input) {
+        throw new KadiError(`Tool '${config.name}' must have an input schema`, ErrorCode.INVALID_INPUT, 400, { name: config.name });
+    }
+    // Validate output schema exists
+    if (!config.output) {
+        throw new KadiError(`Tool '${config.name}' must have an output schema`, ErrorCode.INVALID_INPUT, 400, { name: config.name });
+    }
+    // Convert Zod schemas to JSON Schema
+    // This will throw KadiError if schemas are not objects or conversion fails
+    const inputSchema = zodToJsonSchema(config.input, {
+        name: `${config.name}Input`
+    });
+    const outputSchema = zodToJsonSchema(config.output, {
+        name: `${config.name}Output`
+    });
+    // Create tool definition with JSON Schema
+    // Type assertion needed because JSONSchema is more permissive than MCP's strict type
+    const definition = {
+        name: config.name,
+        description: config.description,
+        title: config.title,
+        version: config.version,
+        tags: config.tags,
+        networks: config.networks,
+        inputSchema: inputSchema,
+        outputSchema: outputSchema
+    };
+    // Create handler wrapper with automatic validation
+    // This wrapper:
+    // 1. Validates input using Zod (better error messages than AJV)
+    // 2. Calls original handler
+    // 3. Validates output using Zod
+    // 4. Returns validated result
+    const handler = async (params) => {
+        // Step 1: Validate input with Zod
+        // This provides much better error messages than JSON Schema validation
+        let validatedInput;
+        try {
+            validatedInput = config.input.parse(params);
+        }
+        catch (error) {
+            // Wrap Zod validation error in KadiError
+            throw new KadiError(`Input validation failed for tool '${config.name}': ${error instanceof Error ? error.message : String(error)}`, ErrorCode.INVALID_INPUT, 400, {
+                toolName: config.name,
+                input: params,
+                validationError: error
+            });
+        }
+        // Step 2: Call original handler with validated input
+        let result;
+        try {
+            result = await config.handler(validatedInput);
+        }
+        catch (error) {
+            // Re-throw handler errors (they should be handled by caller)
+            throw error;
+        }
+        // Step 3: Validate output with Zod
+        // This catches bugs in the handler implementation
+        try {
+            const validatedOutput = config.output.parse(result);
+            return validatedOutput;
+        }
+        catch (error) {
+            // Output validation failure indicates a bug in the handler
+            throw new KadiError(`Output validation failed for tool '${config.name}': ${error instanceof Error ? error.message : String(error)}`, ErrorCode.INTERNAL_ERROR, 500, {
+                toolName: config.name,
+                output: result,
+                validationError: error
+            });
+        }
+    };
+    // Return tool object ready for registration
+    return {
+        definition,
+        handler,
+        inputSchema: config.input,
+        outputSchema: config.output
+    };
+}
+/**
+ * Create a simple tool with minimal configuration
+ *
+ * Convenience function for creating tools when you don't need all the
+ * configuration options. Good for quick prototyping or simple tools.
+ *
+ * @param name - Tool name
+ * @param input - Zod input schema
+ * @param output - Zod output schema
+ * @param handler - Tool handler function
+ * @returns Tool ready to register
+ *
+ * @example
+ * ```typescript
+ * const tool = createSimpleTool(
+ *   'add',
+ *   z.object({ a: z.number(), b: z.number() }),
+ *   z.object({ result: z.number() }),
+ *   async ({ a, b }) => ({ result: a + b })
+ * );
+ *
+ * client.registerTool(tool.definition, tool.handler);
+ * ```
+ */
+export function createSimpleTool(name, input, output, handler) {
+    return createTool({
+        name,
+        input,
+        output,
+        handler
+    });
+}
+//# sourceMappingURL=zod-helpers.js.map

package/dist/schemas/zod-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-helpers.js","sourceRoot":"","sources":["../../src/schemas/zod-helpers.ts"],"names":[],"mappings":"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"}

package/dist/schemas/zod-to-json-schema.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Zod to JSON Schema Conversion Utilities
+ *
+ * This module provides utilities for converting Zod schemas to MCP-compliant
+ * JSON Schema. The conversion ensures that all generated schemas meet the
+ * requirements of the Model Context Protocol (MCP):
+ * - Root schemas must be type 'object'
+ * - All schemas must be valid JSON Schema Draft 7
+ * - No unsupported features (e.g., recursive types, transforms)
+ *
+ * @module schemas/zod-to-json-schema
+ */
+import { z } from 'zod';
+/**
+ * JSON Schema object type
+ *
+ * Represents a JSON Schema (Draft 7) object. We use a permissive type here
+ * since JSON Schema structure is flexible and validated at runtime by AJV.
+ */
+export type JSONSchema = {
+    type: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    [key: string]: unknown;
+};
+/**
+ * Options for Zod to JSON Schema conversion
+ *
+ * These options control how the conversion happens and what features are enabled.
+ */
+export interface ZodToJsonSchemaOptions {
+    /**
+     * Schema name for $ref resolution
+     *
+     * If provided, the schema will use this name in $ref definitions.
+     * If not provided, $ref will be inlined (recommended for simplicity).
+     *
+     * @default undefined (inlines all $refs)
+     */
+    name?: string;
+    /**
+     * Include schema $id field
+     *
+     * If true, adds a $id field to the root schema for identification.
+     *
+     * @default false
+     */
+    includeId?: boolean;
+    /**
+     * Target JSON Schema version
+     *
+     * Specifies which JSON Schema draft to target.
+     *
+     * @default 'draft-7' (most compatible)
+     */
+    target?: 'draft-4' | 'draft-7' | 'draft-2020-12' | 'openapi-3.0';
+    /**
+     * Enable strict mode
+     *
+     * If true, throws errors for Zod features that can't be fully represented
+     * in JSON Schema (e.g., transforms, refinements).
+     *
+     * @default false (converts best-effort)
+     */
+    strict?: boolean;
+}
+/**
+ * Convert Zod schema to MCP-compliant JSON Schema
+ *
+ * This function converts a Zod schema to JSON Schema format that complies with
+ * the Model Context Protocol (MCP) requirements:
+ * - Root schema must be type 'object'
+ * - No transforms or refinements (validation only)
+ * - Valid JSON Schema Draft 7
+ *
+ * The conversion preserves:
+ * - Type information (string, number, boolean, etc.)
+ * - Descriptions (from .describe())
+ * - Required/optional fields
+ * - Default values (from .default())
+ * - Enums (from z.enum())
+ * - Array items
+ * - Nested objects
+ *
+ * @param zodSchema - Zod schema to convert
+ * @param options - Conversion options
+ * @returns MCP-compliant JSON Schema
+ * @throws {KadiError} If schema is not an object type (MCP requirement)
+ * @throws {KadiError} If conversion fails
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({
+ *   name: z.string().describe('User name'),
+ *   age: z.number().int().positive().optional()
+ * });
+ *
+ * const jsonSchema = zodToJsonSchema(schema);
+ * // Result:
+ * // {
+ * //   type: 'object',
+ * //   properties: {
+ * //     name: { type: 'string', description: 'User name' },
+ * //     age: { type: 'integer', minimum: 0 }
+ * //   },
+ * //   required: ['name']
+ * // }
+ * ```
+ */
+export declare function zodToJsonSchema(zodSchema: z.ZodTypeAny, options?: ZodToJsonSchemaOptions): JSONSchema;
+/**
+ * Validate that a Zod schema can be converted to MCP-compliant JSON Schema
+ *
+ * This function checks whether a Zod schema can be successfully converted
+ * to JSON Schema without losing validation semantics. It's useful for
+ * providing early feedback to developers.
+ *
+ * Checks performed:
+ * - Schema is a Zod object type
+ * - No unsupported features (transforms, refinements with custom logic)
+ * - Can be converted to valid JSON Schema
+ *
+ * @param zodSchema - Zod schema to validate
+ * @returns Object with validation result and error message if invalid
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ name: z.string() });
+ * const result = validateZodSchema(schema);
+ *
+ * if (!result.valid) {
+ *   console.error('Invalid schema:', result.error);
+ * }
+ * ```
+ */
+export declare function validateZodSchema(zodSchema: z.ZodTypeAny): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Check if a value is a Zod schema
+ *
+ * Type guard to determine if a value is a Zod schema. Useful for
+ * runtime detection of schema type.
+ *
+ * @param value - Value to check
+ * @returns True if value is a Zod schema, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isZodSchema(value)) {
+ *   const jsonSchema = zodToJsonSchema(value);
+ * }
+ * ```
+ */
+export declare function isZodSchema(value: unknown): value is z.ZodTypeAny;
+//# sourceMappingURL=zod-to-json-schema.d.ts.map

package/dist/schemas/zod-to-json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-to-json-schema.d.ts","sourceRoot":"","sources":["../../src/schemas/zod-to-json-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,eAAe,GAAG,aAAa,CAAC;IAEjE;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,CAAC,CAAC,UAAU,EACvB,OAAO,GAAE,sBAA2B,GACnC,UAAU,CA8CZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,CAAC,CAAC,UAAU,GACtB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAepC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,CAAC,CAAC,UAAU,CAOjE"}

package/dist/schemas/zod-to-json-schema.js

@@ -0,0 +1,154 @@
+/**
+ * Zod to JSON Schema Conversion Utilities
+ *
+ * This module provides utilities for converting Zod schemas to MCP-compliant
+ * JSON Schema. The conversion ensures that all generated schemas meet the
+ * requirements of the Model Context Protocol (MCP):
+ * - Root schemas must be type 'object'
+ * - All schemas must be valid JSON Schema Draft 7
+ * - No unsupported features (e.g., recursive types, transforms)
+ *
+ * @module schemas/zod-to-json-schema
+ */
+import { z } from 'zod';
+import { KadiError, ErrorCode } from '../errors/index.js';
+/**
+ * Convert Zod schema to MCP-compliant JSON Schema
+ *
+ * This function converts a Zod schema to JSON Schema format that complies with
+ * the Model Context Protocol (MCP) requirements:
+ * - Root schema must be type 'object'
+ * - No transforms or refinements (validation only)
+ * - Valid JSON Schema Draft 7
+ *
+ * The conversion preserves:
+ * - Type information (string, number, boolean, etc.)
+ * - Descriptions (from .describe())
+ * - Required/optional fields
+ * - Default values (from .default())
+ * - Enums (from z.enum())
+ * - Array items
+ * - Nested objects
+ *
+ * @param zodSchema - Zod schema to convert
+ * @param options - Conversion options
+ * @returns MCP-compliant JSON Schema
+ * @throws {KadiError} If schema is not an object type (MCP requirement)
+ * @throws {KadiError} If conversion fails
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({
+ *   name: z.string().describe('User name'),
+ *   age: z.number().int().positive().optional()
+ * });
+ *
+ * const jsonSchema = zodToJsonSchema(schema);
+ * // Result:
+ * // {
+ * //   type: 'object',
+ * //   properties: {
+ * //     name: { type: 'string', description: 'User name' },
+ * //     age: { type: 'integer', minimum: 0 }
+ * //   },
+ * //   required: ['name']
+ * // }
+ * ```
+ */
+export function zodToJsonSchema(zodSchema, options = {}) {
+    try {
+        // Set default options for Zod 4's native toJSONSchema
+        const opts = {
+            target: options.target || 'draft-7',
+            unrepresentable: 'any', // Convert unsupported types to any
+            cycles: 'ref', // Use $ref for circular references
+            reused: 'inline' // Inline reused schemas
+        };
+        // Convert Zod schema to JSON Schema using Zod 4's native function
+        const jsonSchema = z.toJSONSchema(zodSchema, opts);
+        // MCP Requirement: Root schema must be type 'object'
+        if (jsonSchema.type !== 'object') {
+            throw new KadiError(`MCP requires schemas to be type 'object', got type '${jsonSchema.type}'. ` +
+                `Wrap your schema in z.object() if needed.`, ErrorCode.SCHEMA_VALIDATION_FAILED, 400, { schemaType: jsonSchema.type });
+        }
+        // Remove $schema field if present (not needed for MCP)
+        if ('$schema' in jsonSchema) {
+            delete jsonSchema.$schema;
+        }
+        return jsonSchema;
+    }
+    catch (error) {
+        // Re-throw KadiError as-is
+        if (error instanceof KadiError) {
+            throw error;
+        }
+        // Wrap other errors in KadiError
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new KadiError(`Failed to convert Zod schema to JSON Schema: ${errorMessage}`, ErrorCode.SCHEMA_VALIDATION_FAILED, 400, { originalError: error instanceof Error ? error.name : String(error) });
+    }
+}
+/**
+ * Validate that a Zod schema can be converted to MCP-compliant JSON Schema
+ *
+ * This function checks whether a Zod schema can be successfully converted
+ * to JSON Schema without losing validation semantics. It's useful for
+ * providing early feedback to developers.
+ *
+ * Checks performed:
+ * - Schema is a Zod object type
+ * - No unsupported features (transforms, refinements with custom logic)
+ * - Can be converted to valid JSON Schema
+ *
+ * @param zodSchema - Zod schema to validate
+ * @returns Object with validation result and error message if invalid
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ name: z.string() });
+ * const result = validateZodSchema(schema);
+ *
+ * if (!result.valid) {
+ *   console.error('Invalid schema:', result.error);
+ * }
+ * ```
+ */
+export function validateZodSchema(zodSchema) {
+    try {
+        // Attempt conversion
+        zodToJsonSchema(zodSchema);
+        // If conversion succeeds, schema is valid
+        return { valid: true };
+    }
+    catch (error) {
+        // Return validation error
+        return {
+            valid: false,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+/**
+ * Check if a value is a Zod schema
+ *
+ * Type guard to determine if a value is a Zod schema. Useful for
+ * runtime detection of schema type.
+ *
+ * @param value - Value to check
+ * @returns True if value is a Zod schema, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isZodSchema(value)) {
+ *   const jsonSchema = zodToJsonSchema(value);
+ * }
+ * ```
+ */
+export function isZodSchema(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        '_def' in value &&
+        typeof value._def === 'object');
+}
+//# sourceMappingURL=zod-to-json-schema.js.map

package/dist/schemas/zod-to-json-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-to-json-schema.js","sourceRoot":"","sources":["../../src/schemas/zod-to-json-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AA4D1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,UAAU,eAAe,CAC7B,SAAuB,EACvB,UAAkC,EAAE;IAEpC,IAAI,CAAC;QACH,sDAAsD;QACtD,MAAM,IAAI,GAAG;YACX,MAAM,EAAE,OAAO,CAAC,MAAM,IAAK,SAAmB;YAC9C,eAAe,EAAE,KAAc,EAAE,mCAAmC;YACpE,MAAM,EAAE,KAAc,EAAY,mCAAmC;YACrE,MAAM,EAAE,QAAiB,CAAS,wBAAwB;SAC3D,CAAC;QAEF,kEAAkE;QAClE,MAAM,UAAU,GAAG,CAAC,CAAC,YAAY,CAAC,SAAS,EAAE,IAAI,CAAe,CAAC;QAEjE,qDAAqD;QACrD,IAAI,UAAU,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACjC,MAAM,IAAI,SAAS,CACjB,uDAAuD,UAAU,CAAC,IAAI,KAAK;gBAC3E,2CAA2C,EAC3C,SAAS,CAAC,wBAAwB,EAClC,GAAG,EACH,EAAE,UAAU,EAAE,UAAU,CAAC,IAAI,EAAE,CAChC,CAAC;QACJ,CAAC;QAED,uDAAuD;QACvD,IAAI,SAAS,IAAI,UAAU,EAAE,CAAC;YAC5B,OAAO,UAAU,CAAC,OAAO,CAAC;QAC5B,CAAC;QAED,OAAO,UAAU,CAAC;IAEpB,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,2BAA2B;QAC3B,IAAI,KAAK,YAAY,SAAS,EAAE,CAAC;YAC/B,MAAM,KAAK,CAAC;QACd,CAAC;QAED,iCAAiC;QACjC,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5E,MAAM,IAAI,SAAS,CACjB,gDAAgD,YAAY,EAAE,EAC9D,SAAS,CAAC,wBAAwB,EAClC,GAAG,EACH,EAAE,aAAa,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACvE,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAuB;IAEvB,IAAI,CAAC;QACH,qBAAqB;QACrB,eAAe,CAAC,SAAS,CAAC,CAAC;QAE3B,0CAA0C;QAC1C,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAEzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,0BAA0B;QAC1B,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,CACL,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,MAAM,IAAI,KAAK;QACf,OAAQ,KAA4B,CAAC,IAAI,KAAK,QAAQ,CACvD,CAAC;AACJ,CAAC"}