@mcp-web/core 0.1.0

package/dist/tool-generators/schema-analysis.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+import { isKeyField, unwrapSchema } from './schema-helpers.js';
+/**
+ * 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: [],
+    };
+    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;
+    }
+    if (unwrapped instanceof z.ZodTuple) {
+        result.type = 'fixed';
+        result.subtype = 'tuple';
+        return result;
+    }
+    if (unwrapped instanceof z.ZodArray) {
+        result.type = 'dynamic';
+        result.subtype = 'array';
+        return result;
+    }
+    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 findIdField(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;
+}

package/dist/tool-generators/schema-helpers.d.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+/**
+ * Marks a field as the unique identifier for array elements.
+ *
+ * When an array schema has a field marked with `id()`, the generated tools
+ * use ID-based operations (e.g., `set_todos_by_id`) instead of index-based.
+ * Only one field per schema can be marked with `id()`.
+ *
+ * @param schema - The Zod schema to mark as the key field
+ * @returns The same schema with key field metadata attached
+ *
+ * @example
+ * ```typescript
+ * const TodoSchema = z.object({
+ *   id: id(z.string()),
+ *   title: z.string(),
+ *   completed: z.boolean(),
+ * });
+ *
+ * // Generates: get_todos, set_todos_by_id, delete_todos_by_id
+ * mcp.addStateTools({ name: 'todos', schema: z.array(TodoSchema), expand: true });
+ * ```
+ */
+export declare function id<T extends z.ZodTypeAny>(schema: T): T;
+/**
+ * Marks a field as system-generated and excludes it from input schemas.
+ *
+ * System fields are auto-populated and never provided by the AI. They are
+ * excluded from add/set input schemas but included in output/getter schemas.
+ * Fields marked with `system()` MUST have a `.default()` value.
+ *
+ * Common uses: auto-generated IDs, timestamps, version numbers.
+ *
+ * @param schema - The Zod schema to mark as system-generated (must have default)
+ * @returns The same schema with system field metadata attached
+ * @throws {Error} At tool generation time if schema lacks a default value
+ *
+ * @example
+ * ```typescript
+ * const TodoSchema = z.object({
+ *   id: id(system(z.string().default(() => crypto.randomUUID()))),
+ *   createdAt: system(z.number().default(() => Date.now())),
+ *   title: z.string(),  // User provides this
+ * });
+ * ```
+ */
+export declare function system<T extends z.ZodTypeAny>(schema: T): T;
+/**
+ * Checks if a field is marked with id().
+ */
+export declare function isKeyField(field: z.ZodTypeAny): boolean;
+/**
+ * Checks if a field is marked with system().
+ */
+export declare function isSystemField(field: z.ZodTypeAny): boolean;
+/**
+ * Checks if a schema has a default value.
+ */
+export declare function hasDefault(schema: z.ZodTypeAny): boolean;
+/**
+ * Unwraps a schema from ZodDefault, ZodOptional, ZodNullable wrappers.
+ * Returns the innermost schema.
+ */
+export declare function unwrapSchema(schema: z.ZodTypeAny): z.ZodTypeAny;
+/**
+ * Unwraps ZodDefault to get the inner schema.
+ */
+export declare function unwrapDefault(schema: z.ZodTypeAny): z.ZodTypeAny;
+/**
+ * Derives an input schema for add operations.
+ * - system() fields are excluded
+ * - default() fields become optional
+ * - other fields remain required
+ */
+export declare function deriveAddInputSchema(schema: z.ZodObject<z.ZodRawShape>): z.ZodObject<z.ZodRawShape>;
+/**
+ * Derives an input schema for set operations (partial updates).
+ * - system() fields are excluded
+ * - all other fields become optional
+ */
+export declare function deriveSetInputSchema(schema: z.ZodObject<z.ZodRawShape>): z.ZodObject<z.ZodRawShape>;
+/**
+ * Validates that all system() fields have default values.
+ * Throws an error if a system field lacks a default.
+ */
+export declare function validateSystemFields(schema: z.ZodObject<z.ZodRawShape>): void;
+//# sourceMappingURL=schema-helpers.d.ts.map

package/dist/tool-generators/schema-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-helpers.d.ts","sourceRoot":"","sources":["../../src/tool-generators/schema-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAGvD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAG3D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,UAAU,GAAG,OAAO,CAEvD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,UAAU,GAAG,OAAO,CAE1D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,OAAO,CASxD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAa/D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAMhE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAiBnG;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAanG;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,IAAI,CAa7E"}

package/dist/tool-generators/schema-helpers.js

@@ -0,0 +1,157 @@
+import { z } from 'zod';
+/**
+ * Marks a field as the unique identifier for array elements.
+ *
+ * When an array schema has a field marked with `id()`, the generated tools
+ * use ID-based operations (e.g., `set_todos_by_id`) instead of index-based.
+ * Only one field per schema can be marked with `id()`.
+ *
+ * @param schema - The Zod schema to mark as the key field
+ * @returns The same schema with key field metadata attached
+ *
+ * @example
+ * ```typescript
+ * const TodoSchema = z.object({
+ *   id: id(z.string()),
+ *   title: z.string(),
+ *   completed: z.boolean(),
+ * });
+ *
+ * // Generates: get_todos, set_todos_by_id, delete_todos_by_id
+ * mcp.addStateTools({ name: 'todos', schema: z.array(TodoSchema), expand: true });
+ * ```
+ */
+export function id(schema) {
+    schema.def.__mcpWebKey = true;
+    return schema;
+}
+/**
+ * Marks a field as system-generated and excludes it from input schemas.
+ *
+ * System fields are auto-populated and never provided by the AI. They are
+ * excluded from add/set input schemas but included in output/getter schemas.
+ * Fields marked with `system()` MUST have a `.default()` value.
+ *
+ * Common uses: auto-generated IDs, timestamps, version numbers.
+ *
+ * @param schema - The Zod schema to mark as system-generated (must have default)
+ * @returns The same schema with system field metadata attached
+ * @throws {Error} At tool generation time if schema lacks a default value
+ *
+ * @example
+ * ```typescript
+ * const TodoSchema = z.object({
+ *   id: id(system(z.string().default(() => crypto.randomUUID()))),
+ *   createdAt: system(z.number().default(() => Date.now())),
+ *   title: z.string(),  // User provides this
+ * });
+ * ```
+ */
+export function system(schema) {
+    schema.def.__mcpWebSystem = true;
+    return schema;
+}
+/**
+ * Checks if a field is marked with id().
+ */
+export function isKeyField(field) {
+    return field.def.__mcpWebKey === true;
+}
+/**
+ * Checks if a field is marked with system().
+ */
+export function isSystemField(field) {
+    return field.def.__mcpWebSystem === true;
+}
+/**
+ * Checks if a schema has a default value.
+ */
+export function hasDefault(schema) {
+    // Check for ZodDefault wrapper
+    if (schema instanceof z.ZodDefault) {
+        return true;
+    }
+    // Check _def for default value
+    const def = schema.def;
+    return def.defaultValue !== undefined || typeof def.defaultValue === 'function';
+}
+/**
+ * Unwraps a schema from ZodDefault, ZodOptional, ZodNullable wrappers.
+ * Returns the innermost schema.
+ */
+export function unwrapSchema(schema) {
+    let current = schema;
+    while (current instanceof z.ZodDefault ||
+        current instanceof z.ZodOptional ||
+        current instanceof z.ZodNullable) {
+        const def = current.def;
+        current = def.innerType || current;
+    }
+    return current;
+}
+/**
+ * Unwraps ZodDefault to get the inner schema.
+ */
+export function unwrapDefault(schema) {
+    if (schema instanceof z.ZodDefault) {
+        const def = schema.def;
+        return def.innerType;
+    }
+    return schema;
+}
+/**
+ * Derives an input schema for add operations.
+ * - system() fields are excluded
+ * - default() fields become optional
+ * - other fields remain required
+ */
+export function deriveAddInputSchema(schema) {
+    const inputShape = {};
+    for (const [key, field] of Object.entries(schema.shape)) {
+        const zodField = field;
+        // Skip system fields entirely
+        if (isSystemField(zodField))
+            continue;
+        // Fields with default() become optional in add
+        if (hasDefault(zodField)) {
+            inputShape[key] = unwrapDefault(zodField).optional();
+        }
+        else {
+            inputShape[key] = zodField;
+        }
+    }
+    return z.object(inputShape);
+}
+/**
+ * Derives an input schema for set operations (partial updates).
+ * - system() fields are excluded
+ * - all other fields become optional
+ */
+export function deriveSetInputSchema(schema) {
+    const inputShape = {};
+    for (const [key, field] of Object.entries(schema.shape)) {
+        const zodField = field;
+        // Skip system fields entirely
+        if (isSystemField(zodField))
+            continue;
+        // All fields optional for partial updates
+        inputShape[key] = unwrapDefault(zodField).optional();
+    }
+    return z.object(inputShape);
+}
+/**
+ * Validates that all system() fields have default values.
+ * Throws an error if a system field lacks a default.
+ */
+export function validateSystemFields(schema) {
+    for (const [key, field] of Object.entries(schema.shape)) {
+        const zodField = field;
+        if (isSystemField(zodField) && !hasDefault(zodField)) {
+            throw new Error(`Error: Field '${key}' is marked as system() but has no default value.\n\n` +
+                `System fields are excluded from input schemas, so a default is required.\n` +
+                `The handler uses this default to fill in the value when creating new items.\n\n` +
+                `Fix: Add a default value or generator:\n` +
+                `  ${key}: system(z.number().default(() => Date.now()))`);
+        }
+    }
+}

package/dist/tool-generators/tool-generator.d.ts

@@ -0,0 +1,11 @@
+import type { GeneratedTools, ToolGenerationOptions } from './types.js';
+/**
+ * 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
+ *
+ * Returns tool definitions without registering them - the caller is responsible for registration.
+ */
+export declare function generateToolsForSchema(options: ToolGenerationOptions): GeneratedTools;
+//# sourceMappingURL=tool-generator.d.ts.map

package/dist/tool-generators/tool-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-generator.d.ts","sourceRoot":"","sources":["../../src/tool-generators/tool-generator.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAA+B,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAOrG;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAsDhB"}