@mcp-web/core 0.1.0

package/dist/zod-to-tools.d.ts

@@ -0,0 +1,49 @@
+import type { ToolDefinition } from '@mcp-web/types';
+import { z } from 'zod';
+import type { MCPWeb } from './web.js';
+export interface ToolGenerationOptions {
+    name: string;
+    description: string;
+    get: () => unknown;
+    set: (value: unknown) => void;
+    schema: z.ZodTypeAny;
+}
+export interface GeneratedTools {
+    tools: ToolDefinition[];
+    warnings: string[];
+}
+export interface SchemaShape {
+    type: 'fixed' | 'dynamic' | 'mixed' | 'unsupported';
+    subtype: 'object' | 'array' | 'record' | 'primitive' | 'tuple' | 'unknown';
+    hasOptionalFields: boolean;
+    optionalPaths: string[];
+    fixedPaths: string[];
+    dynamicPaths: string[];
+}
+export interface KeyFieldResult {
+    type: 'explicit' | 'none';
+    field?: string;
+}
+/**
+ * Generates MCP tools for a schema based on its shape.
+ * - Fixed-shape schemas → get + set with deep merge
+ * - Dynamic-shape schemas → get + add + set + delete (arrays) or get + set + delete (records)
+ * - Mixed schemas → asymmetric get/set + collection tools
+ */
+export declare function generateToolsForSchema(options: ToolGenerationOptions, mcpWeb: MCPWeb): GeneratedTools;
+/**
+ * Analyzes a schema to determine its shape characteristics.
+ */
+export declare function analyzeSchemaShape(schema: z.ZodTypeAny): SchemaShape;
+/**
+ * Detects the ID field in an object schema.
+ * Returns information about explicit id() markers.
+ * Throws an error if multiple id() markers are found.
+ */
+export declare function isIdField(schema: z.ZodObject<z.ZodRawShape>): KeyFieldResult;
+/**
+ * Validates that a schema only uses supported types.
+ * Throws an error if unsupported types are found.
+ */
+export declare function validateSupportedTypes(schema: z.ZodTypeAny, path?: string): string[];
+//# sourceMappingURL=zod-to-tools.d.ts.map

package/dist/zod-to-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-to-tools.d.ts","sourceRoot":"","sources":["../src/zod-to-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAMvC,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,OAAO,CAAC;IACnB,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9B,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,CAAC;IACpD,OAAO,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,CAAC;IAC3E,iBAAiB,EAAE,OAAO,CAAC;IAC3B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,MAAM,GACb,cAAc,CAsDhB;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,WAAW,CAmFpE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,cAAc,CAuB5E;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,IAAI,SAAS,GAAG,MAAM,EAAE,CA0CpF"}

package/dist/zod-to-tools.js

@@ -0,0 +1,623 @@
+import { z } from 'zod';
+import { deriveAddInputSchema, deriveSetInputSchema, isKeyField, unwrapSchema, validateSystemFields, } from './schema-helpers.js';
+// ============================================================================
+// Main Entry Point
+// ============================================================================
+/**
+ * Generates MCP tools for a schema based on its shape.
+ * - Fixed-shape schemas → get + set with deep merge
+ * - Dynamic-shape schemas → get + add + set + delete (arrays) or get + set + delete (records)
+ * - Mixed schemas → asymmetric get/set + collection tools
+ */
+export function generateToolsForSchema(options, mcpWeb) {
+    const { name, schema } = options;
+    const tools = [];
+    const warnings = [];
+    // Validate schema
+    const unwrapped = unwrapSchema(schema);
+    // Validate system fields if it's an object
+    if (unwrapped instanceof z.ZodObject) {
+        validateSystemFields(unwrapped);
+    }
+    // Analyze schema shape
+    const shape = analyzeSchemaShape(schema);
+    // Warn about optional fields (once)
+    if (shape.hasOptionalFields) {
+        warnings.push(`⚠️ Warning: Schema for '${name}' uses optional() on field(s): ${shape.optionalPaths.join(', ')}.\n\n` +
+            `Problem: optional() creates ambiguity in partial updates:\n` +
+            `- Is the field missing because AI didn't provide it? (keep current)\n` +
+            `- Or because AI wants to clear it? (set to undefined)\n\n` +
+            `Solution: Use nullable() instead:\n` +
+            `- fieldName: z.string().nullable()\n\n` +
+            `This makes intent explicit:\n` +
+            `- Omit field → keep current value\n` +
+            `- Pass null → clear the value`);
+    }
+    // Generate tools based on schema type
+    if (shape.type === 'fixed') {
+        // Fixed-shape: primitives, tuples, or objects with only fixed props
+        tools.push(...generateFixedShapeTools(options, shape, mcpWeb));
+    }
+    else if (shape.type === 'dynamic') {
+        // Dynamic-shape: arrays or records at root, or objects with only dynamic props
+        if (shape.subtype === 'array') {
+            tools.push(...generateArrayTools(options, mcpWeb));
+        }
+        else if (shape.subtype === 'record') {
+            tools.push(...generateRecordTools(options, mcpWeb));
+        }
+    }
+    else if (shape.type === 'mixed') {
+        // Mixed: objects with both fixed and dynamic props
+        tools.push(...generateMixedObjectTools(options, shape, mcpWeb));
+    }
+    else {
+        // Unsupported type
+        warnings.push(`⚠️ Warning: Schema for '${name}' contains unsupported types.\n` +
+            `Only JSON-compatible types are supported (objects, arrays, records, primitives).`);
+    }
+    return { tools, warnings };
+}
+// ============================================================================
+// Schema Analysis
+// ============================================================================
+/**
+ * Analyzes a schema to determine its shape characteristics.
+ */
+export function analyzeSchemaShape(schema) {
+    const unwrapped = unwrapSchema(schema);
+    // Default result
+    const result = {
+        type: 'unsupported',
+        subtype: 'unknown',
+        hasOptionalFields: false,
+        optionalPaths: [],
+        fixedPaths: [],
+        dynamicPaths: [],
+    };
+    // Primitives
+    if (unwrapped instanceof z.ZodString ||
+        unwrapped instanceof z.ZodNumber ||
+        unwrapped instanceof z.ZodBoolean ||
+        unwrapped instanceof z.ZodLiteral ||
+        unwrapped instanceof z.ZodEnum) {
+        result.type = 'fixed';
+        result.subtype = 'primitive';
+        return result;
+    }
+    // Tuples
+    if (unwrapped instanceof z.ZodTuple) {
+        result.type = 'fixed';
+        result.subtype = 'tuple';
+        return result;
+    }
+    // Arrays
+    if (unwrapped instanceof z.ZodArray) {
+        result.type = 'dynamic';
+        result.subtype = 'array';
+        return result;
+    }
+    // Records
+    if (unwrapped instanceof z.ZodRecord) {
+        result.type = 'dynamic';
+        result.subtype = 'record';
+        return result;
+    }
+    // Objects - analyze further
+    if (unwrapped instanceof z.ZodObject) {
+        result.subtype = 'object';
+        const shape = unwrapped.shape;
+        for (const [key, field] of Object.entries(shape)) {
+            const zodField = field;
+            const unwrappedField = unwrapSchema(zodField);
+            // Check for optional fields
+            if (zodField instanceof z.ZodOptional) {
+                result.hasOptionalFields = true;
+                result.optionalPaths.push(key);
+            }
+            // Check if field is dynamic (array or record)
+            if (unwrappedField instanceof z.ZodArray || unwrappedField instanceof z.ZodRecord) {
+                result.dynamicPaths.push(key);
+            }
+            else {
+                result.fixedPaths.push(key);
+            }
+        }
+        // Determine object type
+        if (result.dynamicPaths.length > 0 && result.fixedPaths.length > 0) {
+            result.type = 'mixed';
+        }
+        else if (result.dynamicPaths.length > 0) {
+            result.type = 'dynamic';
+        }
+        else {
+            result.type = 'fixed';
+        }
+        return result;
+    }
+    return result;
+}
+/**
+ * Detects the ID field in an object schema.
+ * Returns information about explicit id() markers.
+ * Throws an error if multiple id() markers are found.
+ */
+export function isIdField(schema) {
+    const shape = schema.shape;
+    let explicitKey = null;
+    for (const [name, field] of Object.entries(shape)) {
+        if (isKeyField(field)) {
+            // Error if multiple id() markers
+            if (explicitKey) {
+                throw new Error(`Multiple fields marked with id(): '${explicitKey}' and '${name}'.\n` +
+                    `Only one field can be the ID. For compound keys, use index-based addressing.`);
+            }
+            explicitKey = name;
+        }
+    }
+    if (explicitKey) {
+        return { type: 'explicit', field: explicitKey };
+    }
+    // No id() marker → use index-based addressing
+    return { type: 'none' };
+}
+/**
+ * Validates that a schema only uses supported types.
+ * Throws an error if unsupported types are found.
+ */
+export function validateSupportedTypes(schema, path = 'root') {
+    const errors = [];
+    const unwrapped = unwrapSchema(schema);
+    const supported = [
+        z.ZodObject,
+        z.ZodArray,
+        z.ZodRecord,
+        z.ZodString,
+        z.ZodNumber,
+        z.ZodBoolean,
+        z.ZodLiteral,
+        z.ZodEnum,
+        z.ZodTuple,
+        z.ZodDate,
+        z.ZodBigInt,
+        z.ZodNull,
+        z.ZodUndefined,
+    ];
+    const isSupported = supported.some((type) => unwrapped instanceof type);
+    if (!isSupported) {
+        errors.push(`Unsupported type at '${path}': ${unwrapped.constructor.name}`);
+    }
+    // Recurse for nested schemas
+    if (unwrapped instanceof z.ZodObject) {
+        for (const [key, field] of Object.entries(unwrapped.shape)) {
+            errors.push(...validateSupportedTypes(field, `${path}.${key}`));
+        }
+    }
+    else if (unwrapped instanceof z.ZodArray) {
+        errors.push(...validateSupportedTypes(unwrapped.element, `${path}[]`));
+    }
+    else if (unwrapped instanceof z.ZodRecord) {
+        const def = unwrapped._def;
+        const valueType = def.valueType;
+        if (valueType) {
+            errors.push(...validateSupportedTypes(valueType, `${path}{}`));
+        }
+    }
+    return errors;
+}
+// ============================================================================
+// Tool Generators
+// ============================================================================
+/**
+ * Generates getter and setter tools for fixed-shape schemas.
+ * Fixed-shape includes: primitives, tuples, and objects with only fixed props.
+ */
+function generateFixedShapeTools(options, shape, _mcpWeb) {
+    const { name, description, get, set, schema } = options;
+    const tools = [];
+    const unwrapped = unwrapSchema(schema);
+    // Getter tool
+    tools.push({
+        name: `get_${name}`,
+        description: `Get the current ${description}`,
+        inputSchema: z.object({}),
+        handler: async () => {
+            return get();
+        },
+    });
+    // Setter tool - behavior depends on subtype
+    if (shape.subtype === 'primitive' || shape.subtype === 'tuple') {
+        // Full replacement for primitives and tuples
+        tools.push({
+            name: `set_${name}`,
+            description: `Set the ${description}`,
+            inputSchema: z.object({ value: schema }),
+            handler: async (input) => {
+                const validated = schema.parse(input.value);
+                set(validated);
+                return { success: true, value: validated };
+            },
+        });
+    }
+    else if (shape.subtype === 'object') {
+        // Partial update with deep merge for objects
+        const objectSchema = unwrapped;
+        const setInputSchema = deriveSetInputSchema(objectSchema);
+        tools.push({
+            name: `set_${name}`,
+            description: `Update the ${description} (partial update with deep merge)`,
+            inputSchema: setInputSchema,
+            handler: async (input) => {
+                const current = get();
+                const { deepMerge } = await import('./utils.js');
+                const merged = deepMerge(current, input);
+                const validated = schema.parse(merged);
+                set(validated);
+                return { success: true, value: validated };
+            },
+        });
+    }
+    return tools;
+}
+/**
+ * Generates tools for array schemas.
+ * Creates 4 tools: get, add, set, delete
+ * Uses index-based addressing by default, ID-based when id() marker present.
+ */
+function generateArrayTools(options, _mcpWeb) {
+    const { name, description, get, set, schema } = options;
+    const tools = [];
+    const unwrapped = unwrapSchema(schema);
+    const elementSchema = unwrapped.element;
+    // Check if element is an object with id() marker
+    const elementUnwrapped = unwrapSchema(elementSchema);
+    let idField = { type: 'none' };
+    if (elementUnwrapped instanceof z.ZodObject) {
+        idField = isIdField(elementUnwrapped);
+    }
+    const useIdBased = idField.type === 'explicit';
+    // Derive input schemas (exclude system fields)
+    let addInputSchema = elementSchema;
+    let setInputSchema = elementSchema;
+    if (elementUnwrapped instanceof z.ZodObject) {
+        addInputSchema = deriveAddInputSchema(elementUnwrapped);
+        setInputSchema = deriveSetInputSchema(elementUnwrapped);
+    }
+    // GET tool
+    if (useIdBased) {
+        const keyField = idField.field; // Safe because useIdBased checks type === 'explicit'
+        tools.push({
+            name: `get_${name}`,
+            description: `Get ${description} by ID, or get all if no ID provided`,
+            inputSchema: z.object({ id: z.string().optional() }),
+            handler: async (input) => {
+                const array = get();
+                if (input.id !== undefined) {
+                    return array.find((item) => item[keyField] === input.id);
+                }
+                return array;
+            },
+        });
+    }
+    else {
+        tools.push({
+            name: `get_${name}`,
+            description: `Get ${description} by index, or get all if no index provided`,
+            inputSchema: z.object({ index: z.number().int().min(0).optional() }),
+            handler: async (input) => {
+                const array = get();
+                if (input.index !== undefined) {
+                    return array[input.index];
+                }
+                return array;
+            },
+        });
+    }
+    // ADD tool
+    if (useIdBased) {
+        tools.push({
+            name: `add_${name}`,
+            description: `Add a new item to ${description}`,
+            inputSchema: z.object({ value: addInputSchema }),
+            handler: async (input) => {
+                const array = get();
+                const parsed = elementSchema.parse(input.value);
+                array.push(parsed);
+                set(array);
+                return { success: true, value: parsed };
+            },
+        });
+    }
+    else {
+        tools.push({
+            name: `add_${name}`,
+            description: `Add a new item to ${description} at the specified index (default: end)`,
+            inputSchema: z.object({
+                value: addInputSchema,
+                index: z.number().int().min(0).optional()
+            }),
+            handler: async (input) => {
+                const array = get();
+                const parsed = elementSchema.parse(input.value);
+                if (input.index !== undefined) {
+                    array.splice(input.index, 0, parsed);
+                }
+                else {
+                    array.push(parsed);
+                }
+                set(array);
+                return { success: true, value: parsed };
+            },
+        });
+    }
+    // SET tool (partial update with deep merge)
+    if (useIdBased) {
+        const keyField = idField.field; // Safe because useIdBased checks type === 'explicit'
+        tools.push({
+            name: `set_${name}`,
+            description: `Update an item in ${description} by ID (partial update with deep merge)`,
+            inputSchema: z.object({
+                id: z.string(),
+                value: setInputSchema
+            }),
+            handler: async (input) => {
+                const array = get();
+                const index = array.findIndex((item) => item[keyField] === input.id);
+                if (index === -1) {
+                    throw new Error(`Item with id '${input.id}' not found in ${name}`);
+                }
+                const { deepMerge } = await import('./utils.js');
+                const merged = deepMerge(array[index], input.value);
+                const validated = elementSchema.parse(merged);
+                array[index] = validated;
+                set(array);
+                return { success: true, value: validated };
+            },
+        });
+    }
+    else {
+        tools.push({
+            name: `set_${name}`,
+            description: `Update an item in ${description} by index (partial update with deep merge)`,
+            inputSchema: z.object({
+                index: z.number().int().min(0),
+                value: setInputSchema
+            }),
+            handler: async (input) => {
+                const array = get();
+                if (input.index >= array.length) {
+                    throw new Error(`Index ${input.index} out of bounds for ${name} (length: ${array.length})`);
+                }
+                const { deepMerge } = await import('./utils.js');
+                const merged = deepMerge(array[input.index], input.value);
+                const validated = elementSchema.parse(merged);
+                array[input.index] = validated;
+                set(array);
+                return { success: true, value: validated };
+            },
+        });
+    }
+    // DELETE tool
+    if (useIdBased) {
+        const keyField = idField.field; // Safe because useIdBased checks type === 'explicit'
+        tools.push({
+            name: `delete_${name}`,
+            description: `Delete an item from ${description} by ID, or delete all items`,
+            inputSchema: z.union([
+                z.object({ id: z.string() }),
+                z.object({ all: z.literal(true) })
+            ]),
+            handler: async (input) => {
+                const array = get();
+                if (input.all) {
+                    set([]);
+                }
+                else if (input.id) {
+                    const index = array.findIndex((item) => item[keyField] === input.id);
+                    if (index !== -1) {
+                        array.splice(index, 1);
+                        set(array);
+                    }
+                }
+                return { success: true };
+            },
+        });
+    }
+    else {
+        tools.push({
+            name: `delete_${name}`,
+            description: `Delete an item from ${description} by index, or delete all items`,
+            inputSchema: z.union([
+                z.object({ index: z.number().int().min(0) }),
+                z.object({ all: z.literal(true) })
+            ]),
+            handler: async (input) => {
+                const array = get();
+                if (input.all) {
+                    set([]);
+                }
+                else if (input.index !== undefined) {
+                    if (input.index < array.length) {
+                        array.splice(input.index, 1);
+                        set(array);
+                    }
+                }
+                return { success: true };
+            },
+        });
+    }
+    return tools;
+}
+/**
+ * Generates tools for record schemas.
+ * Creates 3 tools: get, set (upsert), delete
+ * Records use string keys naturally, no ID marker needed.
+ */
+function generateRecordTools(options, _mcpWeb) {
+    const { name, description, get, set, schema } = options;
+    const tools = [];
+    const unwrapped = unwrapSchema(schema);
+    const def = unwrapped._def;
+    const valueSchema = def.valueType || z.unknown();
+    // Derive input schemas (exclude system fields if value is object)
+    const valueUnwrapped = unwrapSchema(valueSchema);
+    let setInputSchema = valueSchema;
+    if (valueUnwrapped instanceof z.ZodObject) {
+        setInputSchema = deriveSetInputSchema(valueUnwrapped);
+    }
+    // GET tool
+    tools.push({
+        name: `get_${name}`,
+        description: `Get ${description} by key, or get all if no key provided`,
+        inputSchema: z.object({ key: z.string().optional() }),
+        handler: async (input) => {
+            const record = get();
+            if (input.key !== undefined) {
+                return record[input.key];
+            }
+            return record;
+        },
+    });
+    // SET tool (upsert: add or update)
+    tools.push({
+        name: `set_${name}`,
+        description: `Set (add or update) an entry in ${description} (partial update with deep merge for objects)`,
+        inputSchema: z.object({
+            key: z.string(),
+            value: setInputSchema
+        }),
+        handler: async (input) => {
+            const record = get();
+            // If value schema is object and entry exists, deep merge
+            if (valueUnwrapped instanceof z.ZodObject && record[input.key] !== undefined) {
+                const { deepMerge } = await import('./utils.js');
+                const merged = deepMerge(record[input.key], input.value);
+                const validated = valueSchema.parse(merged);
+                record[input.key] = validated;
+                set(record);
+                return { success: true, value: validated };
+            }
+            // Otherwise, full replacement (upsert)
+            const validated = valueSchema.parse(input.value);
+            record[input.key] = validated;
+            set(record);
+            return { success: true, value: validated };
+        },
+    });
+    // DELETE tool
+    tools.push({
+        name: `delete_${name}`,
+        description: `Delete an entry from ${description} by key, or delete all entries`,
+        inputSchema: z.union([
+            z.object({ key: z.string() }),
+            z.object({ all: z.literal(true) })
+        ]),
+        handler: async (input) => {
+            const record = get();
+            if (input.all) {
+                set({});
+            }
+            else if (input.key) {
+                delete record[input.key];
+                set(record);
+            }
+            return { success: true };
+        },
+    });
+    return tools;
+}
+/**
+ * Generates tools for mixed objects (both fixed and dynamic props).
+ * Creates asymmetric get/set:
+ * - get() returns full state (including collections)
+ * - set() only updates fixed-shape props
+ * - Separate tools for each collection
+ */
+function generateMixedObjectTools(options, _shape, mcpWeb) {
+    const { name, description, get, set, schema } = options;
+    const tools = [];
+    const unwrapped = unwrapSchema(schema);
+    // Split into fixed and dynamic parts
+    const fixedShape = {};
+    const dynamicFields = [];
+    for (const [key, field] of Object.entries(unwrapped.shape)) {
+        const zodField = field;
+        const unwrappedField = unwrapSchema(zodField);
+        if (unwrappedField instanceof z.ZodArray || unwrappedField instanceof z.ZodRecord) {
+            dynamicFields.push({ key, field: zodField });
+        }
+        else {
+            fixedShape[key] = zodField;
+        }
+    }
+    const hasFixedProps = Object.keys(fixedShape).length > 0;
+    // ROOT GETTER - always returns full state
+    tools.push({
+        name: `get_${name}`,
+        description: `Get the current ${description} (full state including collections)`,
+        inputSchema: z.object({ excludeCollections: z.boolean().optional() }),
+        handler: async (input) => {
+            const fullState = get();
+            if (input.excludeCollections) {
+                // Return only fixed-shape props
+                const fixedState = {};
+                for (const key of Object.keys(fixedShape)) {
+                    fixedState[key] = fullState[key];
+                }
+                return fixedState;
+            }
+            return fullState;
+        },
+    });
+    // ROOT SETTER - only if there are fixed props
+    if (hasFixedProps) {
+        const setInputSchema = deriveSetInputSchema(z.object(fixedShape));
+        tools.push({
+            name: `set_${name}`,
+            description: `Update ${description} settings (fixed-shape props only, use collection tools for arrays/records)`,
+            inputSchema: setInputSchema,
+            handler: async (input) => {
+                const current = get();
+                const { deepMerge } = await import('./utils.js');
+                // Merge only the fixed props
+                const fixedUpdate = {};
+                for (const key of Object.keys(fixedShape)) {
+                    if (key in input) {
+                        fixedUpdate[key] = input[key];
+                    }
+                }
+                const merged = deepMerge(current, fixedUpdate);
+                const validated = schema.parse(merged);
+                set(validated);
+                // Return only the fixed props that were updated
+                const result = {};
+                for (const key of Object.keys(fixedShape)) {
+                    result[key] = validated[key];
+                }
+                return { success: true, value: result };
+            },
+        });
+    }
+    // COLLECTION TOOLS - generate for each dynamic field
+    for (const { key, field } of dynamicFields) {
+        const unwrappedField = unwrapSchema(field);
+        const collectionOptions = {
+            name: `${name}_${key}`,
+            description: `${key} in ${description}`,
+            get: () => get()[key],
+            set: (value) => {
+                const current = get();
+                current[key] = value;
+                set(current);
+            },
+            schema: field,
+        };
+        if (unwrappedField instanceof z.ZodArray) {
+            tools.push(...generateArrayTools(collectionOptions, mcpWeb));
+        }
+        else if (unwrappedField instanceof z.ZodRecord) {
+            tools.push(...generateRecordTools(collectionOptions, mcpWeb));
+        }
+    }
+    return tools;
+}