@mcp-web/core 0.1.0

package/dist/schema-helpers.d.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+/**
+ * Marks a field as the unique identifier for array elements.
+ * Enables ID-based tools instead of index-based.
+ * Only one field per schema can be marked with id().
+ *
+ * @example
+ * ```typescript
+ * const TodoSchema = z.object({
+ *   id: id(z.string()),
+ *   value: z.string()
+ * });
+ * ```
+ */
+export declare function id<T extends z.ZodTypeAny>(schema: T): T;
+/**
+ * Marks a field as system-generated.
+ * Field is excluded from input schemas (add/set).
+ * MUST have a default() — error thrown otherwise.
+ *
+ * @example
+ * ```typescript
+ * const TodoSchema = z.object({
+ *   id: id(system(z.string().default(() => crypto.randomUUID()))),
+ *   created_at: system(z.number().default(() => Date.now()))
+ * });
+ * ```
+ */
+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/schema-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-helpers.d.ts","sourceRoot":"","sources":["../src/schema-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,wBAAgB,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAGvD;AAED;;;;;;;;;;;;GAYG;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/schema-helpers.js

@@ -0,0 +1,139 @@
+import { z } from 'zod';
+/**
+ * Marks a field as the unique identifier for array elements.
+ * Enables ID-based tools instead of index-based.
+ * Only one field per schema can be marked with id().
+ *
+ * @example
+ * ```typescript
+ * const TodoSchema = z.object({
+ *   id: id(z.string()),
+ *   value: z.string()
+ * });
+ * ```
+ */
+export function id(schema) {
+    schema._def.__mcpWebKey = true;
+    return schema;
+}
+/**
+ * Marks a field as system-generated.
+ * Field is excluded from input schemas (add/set).
+ * MUST have a default() — error thrown otherwise.
+ *
+ * @example
+ * ```typescript
+ * const TodoSchema = z.object({
+ *   id: id(system(z.string().default(() => crypto.randomUUID()))),
+ *   created_at: system(z.number().default(() => Date.now()))
+ * });
+ * ```
+ */
+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/schemas.d.ts

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+export declare const EphemeralContextSchema: z.ZodObject<{
+    name: z.ZodString;
+    value: z.ZodUnknown;
+    description: z.ZodOptional<z.ZodString>;
+    schema: z.ZodOptional<z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>>;
+}, z.core.$strip>;
+export declare const ContextItemSchema: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    handler: z.ZodCustom<(...args: any[]) => any | Promise<any>, (...args: any[]) => any | Promise<any>>;
+    inputSchema: z.ZodOptional<z.ZodCustom<z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>, z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>>>;
+    outputSchema: z.ZodOptional<z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    handler: z.ZodCustom<(...args: any[]) => any | Promise<any>, (...args: any[]) => any | Promise<any>>;
+    inputSchema: z.ZodOptional<z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>>;
+    outputSchema: z.ZodOptional<z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>>;
+}, z.core.$strip>]>, z.ZodObject<{
+    name: z.ZodString;
+    value: z.ZodUnknown;
+    description: z.ZodOptional<z.ZodString>;
+    schema: z.ZodOptional<z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>>;
+}, z.core.$strip>]>;
+export declare const QueryRequestSchema: z.ZodObject<{
+    prompt: z.ZodString;
+    context: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        handler: z.ZodCustom<(...args: any[]) => any | Promise<any>, (...args: any[]) => any | Promise<any>>;
+        inputSchema: z.ZodOptional<z.ZodCustom<z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>, z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>>>;
+        outputSchema: z.ZodOptional<z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        handler: z.ZodCustom<(...args: any[]) => any | Promise<any>, (...args: any[]) => any | Promise<any>>;
+        inputSchema: z.ZodOptional<z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>>;
+        outputSchema: z.ZodOptional<z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>>;
+    }, z.core.$strip>]>, z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodUnknown;
+        description: z.ZodOptional<z.ZodString>;
+        schema: z.ZodOptional<z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>>;
+    }, z.core.$strip>]>>>;
+    responseTool: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        handler: z.ZodCustom<(...args: any[]) => any | Promise<any>, (...args: any[]) => any | Promise<any>>;
+        inputSchema: z.ZodOptional<z.ZodCustom<z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>, z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>>>;
+        outputSchema: z.ZodOptional<z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        handler: z.ZodCustom<(...args: any[]) => any | Promise<any>, (...args: any[]) => any | Promise<any>>;
+        inputSchema: z.ZodOptional<z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>>;
+        outputSchema: z.ZodOptional<z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>>;
+    }, z.core.$strip>]>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        handler: z.ZodCustom<(...args: any[]) => any | Promise<any>, (...args: any[]) => any | Promise<any>>;
+        inputSchema: z.ZodOptional<z.ZodCustom<z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>, z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>>>;
+        outputSchema: z.ZodOptional<z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        handler: z.ZodCustom<(...args: any[]) => any | Promise<any>, (...args: any[]) => any | Promise<any>>;
+        inputSchema: z.ZodOptional<z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>>;
+        outputSchema: z.ZodOptional<z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>>;
+    }, z.core.$strip>]>>>;
+    restrictTools: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+/**
+ * Client-side query response result schemas.
+ *
+ * These schemas represent individual query lifecycle events as consumed by the web library from the bridge.
+ * They differ slightly from the wire-format schemas in @mcp-web/types/query because:
+ * - Wire format (types package): Optimized for WebSocket transmission between bridge and frontend
+ * - Client format (web package): Optimized for consumption by the MCPWeb class
+ *
+ * The main difference is that `QueryResponseResultCompleteSchema` includes the full toolCalls array,
+ * while the wire format `QueryCompleteBridgeMessageSchema` is the same but sent over WebSocket.
+ */
+export declare const QueryResponseResultAcceptedSchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"query_accepted">>;
+    uuid: z.ZodString;
+}, z.core.$strip>;
+export declare const QueryResponseResultProgressSchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"query_progress">>;
+    uuid: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+export declare const QueryResponseResultCompleteSchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"query_complete">>;
+    uuid: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+    toolCalls: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        arguments: z.ZodUnknown;
+        result: z.ZodUnknown;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const QueryResponseResultFailureSchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"query_failure">>;
+    uuid: z.ZodString;
+    error: z.ZodString;
+}, z.core.$strip>;
+export declare const QueryResponseResultCancelSchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"query_cancel">>;
+    uuid: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const QueryResponseResultSchema: z.ZodUnion<readonly [z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"query_accepted">>;
+    uuid: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"query_progress">>;
+    uuid: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"query_complete">>;
+    uuid: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+    toolCalls: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        arguments: z.ZodUnknown;
+        result: z.ZodUnknown;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"query_failure">>;
+    uuid: z.ZodString;
+    error: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"query_cancel">>;
+    uuid: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>]>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,sBAAsB;;;;;iBAKjC,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;0BAqChB,GAAG,qCAGS,GAAG;;;;;;0BAiB2B,GACvD,qCAAqC,GAAG;;;;;;;;mBA1D+C,CAAC;AAEzF,eAAO,MAAM,kBAAkB;;;;;8BAmCjB,GAAG,qCAGS,GAAG;;;;;;8BAiB2B,GACvD,qCAAqC,GAAG;;;;;;;;;;;;8BArB3B,GAAG,qCAGS,GAAG;;;;;;8BAiB2B,GACvD,qCAAqC,GAAG;;;;;;;8BArB3B,GAAG,qCAGS,GAAG;;;;;;8BAiB2B,GACvD,qCAAqC,GAAG;;;;;;iBA3CvC,CAAC;AAEH;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,iCAAiC;;;iBAG5C,CAAC;AAEH,eAAO,MAAM,iCAAiC;;;;iBAI5C,CAAC;AAEH,eAAO,MAAM,iCAAiC;;;;;;;;;iBAS5C,CAAC;AAEH,eAAO,MAAM,gCAAgC;;;;iBAI3C,CAAC;AAEH,eAAO,MAAM,+BAA+B;;;;iBAI1C,CAAC;AAEH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;mBAMpC,CAAC"}

package/dist/schemas.js

@@ -0,0 +1,70 @@
+import { ToolDefinitionSchema } from '@mcp-web/types';
+import { z } from 'zod';
+export const EphemeralContextSchema = z.object({
+    name: z.string(),
+    value: z.unknown(),
+    description: z.string().optional(),
+    schema: z.custom().optional()
+});
+export const ContextItemSchema = z.union([ToolDefinitionSchema, EphemeralContextSchema]);
+export const QueryRequestSchema = z.object({
+    /** Query prompt */
+    prompt: z.string(),
+    /** Context items to use for the query */
+    context: z.array(ContextItemSchema).optional(),
+    /** Tool to use for completing a query */
+    responseTool: ToolDefinitionSchema.optional(),
+    /** Tools available for this query (optimization - avoids listTools call) */
+    tools: z.array(ToolDefinitionSchema).optional(),
+    /** If true, only tools listed in 'tools' array can be called */
+    restrictTools: z.boolean().optional().default(false),
+    /** Timeout for the query */
+    timeout: z.number().optional().default(30000),
+});
+/**
+ * Client-side query response result schemas.
+ *
+ * These schemas represent individual query lifecycle events as consumed by the web library from the bridge.
+ * They differ slightly from the wire-format schemas in @mcp-web/types/query because:
+ * - Wire format (types package): Optimized for WebSocket transmission between bridge and frontend
+ * - Client format (web package): Optimized for consumption by the MCPWeb class
+ *
+ * The main difference is that `QueryResponseResultCompleteSchema` includes the full toolCalls array,
+ * while the wire format `QueryCompleteBridgeMessageSchema` is the same but sent over WebSocket.
+ */
+export const QueryResponseResultAcceptedSchema = z.object({
+    type: z.literal('query_accepted').default('query_accepted'),
+    uuid: z.string(),
+});
+export const QueryResponseResultProgressSchema = z.object({
+    type: z.literal('query_progress').default('query_progress'),
+    uuid: z.string(),
+    message: z.string(),
+});
+export const QueryResponseResultCompleteSchema = z.object({
+    type: z.literal('query_complete').default('query_complete'),
+    uuid: z.string(),
+    message: z.string().optional(),
+    toolCalls: z.array(z.object({
+        tool: z.string(),
+        arguments: z.unknown(),
+        result: z.unknown()
+    })),
+});
+export const QueryResponseResultFailureSchema = z.object({
+    type: z.literal('query_failure').default('query_failure'),
+    uuid: z.string(),
+    error: z.string(),
+});
+export const QueryResponseResultCancelSchema = z.object({
+    type: z.literal('query_cancel').default('query_cancel'),
+    uuid: z.string(),
+    reason: z.string().optional(),
+});
+export const QueryResponseResultSchema = z.union([
+    QueryResponseResultAcceptedSchema,
+    QueryResponseResultProgressSchema,
+    QueryResponseResultCompleteSchema,
+    QueryResponseResultFailureSchema,
+    QueryResponseResultCancelSchema,
+]);

package/dist/tool-generators/generate-basic-state-tools.d.ts

@@ -0,0 +1,23 @@
+import type { ToolDefinitionZod } from '@mcp-web/types';
+import type { SplitPlan, DecompositionOptions } from '@mcp-web/decompose-zod-schema';
+import { z } from 'zod';
+export interface BasicStateToolOptions<T> {
+    name: string;
+    description: string;
+    get: () => T;
+    set: (value: T) => void;
+    schema: z.ZodType<T> | z.core.JSONSchema.JSONSchema;
+    schemaSplit?: SplitPlan | DecompositionOptions;
+}
+export interface BasicStateToolsResult {
+    getter: ToolDefinitionZod;
+    setters: ToolDefinitionZod[];
+}
+/**
+ * Generates basic getter and setter tools for state management.
+ * Returns tool definitions without registering them - the caller is responsible for registration.
+ *
+ * @returns Object containing getter tool and array of setter tools (1 for simple, N for decomposed)
+ */
+export declare function generateBasicStateTools<T>(options: BasicStateToolOptions<T>): BasicStateToolsResult;
+//# sourceMappingURL=generate-basic-state-tools.d.ts.map

package/dist/tool-generators/generate-basic-state-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-basic-state-tools.d.ts","sourceRoot":"","sources":["../../src/tool-generators/generate-basic-state-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAoB,SAAS,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAEvG,OAAO,EAAa,CAAC,EAAE,MAAM,KAAK,CAAC;AAGnC,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,CAAC;IACb,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACxB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;IACpD,WAAW,CAAC,EAAE,SAAS,GAAG,oBAAoB,CAAC;CAChD;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAChC,qBAAqB,CAgGvB"}

package/dist/tool-generators/generate-basic-state-tools.js

@@ -0,0 +1,95 @@
+import { applyPartialUpdate, decomposeSchema } from '@mcp-web/decompose-zod-schema';
+import { ZodObject, z } from 'zod';
+import { isZodSchema, validateInput } from '../utils.js';
+/**
+ * Generates basic getter and setter tools for state management.
+ * Returns tool definitions without registering them - the caller is responsible for registration.
+ *
+ * @returns Object containing getter tool and array of setter tools (1 for simple, N for decomposed)
+ */
+export function generateBasicStateTools(options) {
+    const { name, description, get, set, schema, schemaSplit } = options;
+    // Always create a getter tool
+    const getter = {
+        name: `get_${name}`,
+        description: `Get the current value of ${name}. ${description}`,
+        handler: get,
+        outputSchema: schema,
+    };
+    const setters = [];
+    // Determine if we should decompose the schema
+    const isZodObjectSchema = isZodSchema(schema) && schema instanceof ZodObject;
+    const shouldDecompose = isZodObjectSchema && schemaSplit !== undefined;
+    let decomposedSchemas = [];
+    if (shouldDecompose && schemaSplit) {
+        try {
+            decomposedSchemas = decomposeSchema(schema, schemaSplit);
+        }
+        catch (error) {
+            console.warn(`Failed to decompose schema for ${name}:`, error);
+        }
+    }
+    if (decomposedSchemas.length > 0) {
+        // Add decomposed setter tools
+        for (const decomposed of decomposedSchemas) {
+            const setterTool = {
+                name: `set_${name}_${decomposed.name}`,
+                description: `Set ${decomposed.name} properties of ${name}. ${description}`,
+                handler: (partialValue) => {
+                    try {
+                        const currentValue = get();
+                        const updatedValue = applyPartialUpdate(currentValue, decomposed.targetPaths, partialValue);
+                        const validatedValue = validateInput(updatedValue, schema);
+                        set(validatedValue);
+                        return { success: true };
+                    }
+                    catch (error) {
+                        return {
+                            success: false,
+                            error: error instanceof Error ? error.message : 'Unknown error',
+                        };
+                    }
+                },
+                inputSchema: decomposed.schema,
+                outputSchema: z.object({
+                    success: z.boolean(),
+                    error: z.string().optional(),
+                }),
+            };
+            setters.push(setterTool);
+        }
+    }
+    else {
+        // Add single setter tool
+        // Wrap non-object schemas in a value property (MCP requires object inputs)
+        const inputSchema = isZodObjectSchema
+            ? schema
+            : z.object({ value: schema });
+        const setterTool = {
+            name: `set_${name}`,
+            description: `Set the value of ${name}. ${description}`,
+            handler: (newValue) => {
+                try {
+                    // Unwrap if we wrapped in value property
+                    const actualValue = isZodObjectSchema ? newValue : newValue.value;
+                    const validatedValue = validateInput(actualValue, schema);
+                    set(validatedValue);
+                    return { success: true };
+                }
+                catch (error) {
+                    return {
+                        success: false,
+                        error: error instanceof Error ? error.message : 'Unknown error',
+                    };
+                }
+            },
+            inputSchema,
+            outputSchema: z.object({
+                success: z.boolean(),
+                error: z.string().optional(),
+            }),
+        };
+        setters.push(setterTool);
+    }
+    return { getter, setters };
+}

package/dist/tool-generators/generate-fixed-shape-tools.d.ts

@@ -0,0 +1,8 @@
+import type { ToolDefinitionZod } from '@mcp-web/types';
+import type { SchemaShape, ToolGenerationOptions } from './types.js';
+/**
+ * Generates getter and setter tools for fixed-shape schemas.
+ * Fixed-shape includes: primitives, tuples, and objects with only fixed props.
+ */
+export declare function generateFixedShapeTools(options: ToolGenerationOptions, shape: SchemaShape): ToolDefinitionZod[];
+//# sourceMappingURL=generate-fixed-shape-tools.d.ts.map

package/dist/tool-generators/generate-fixed-shape-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-fixed-shape-tools.d.ts","sourceRoot":"","sources":["../../src/tool-generators/generate-fixed-shape-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGxD,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGrE;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,qBAAqB,EAC9B,KAAK,EAAE,WAAW,GACjB,iBAAiB,EAAE,CAgDrB"}

package/dist/tool-generators/generate-fixed-shape-tools.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { deriveSetInputSchema, unwrapSchema } from './schema-helpers.js';
+import { deepMerge } from './utils.js';
+/**
+ * Generates getter and setter tools for fixed-shape schemas.
+ * Fixed-shape includes: primitives, tuples, and objects with only fixed props.
+ */
+export function generateFixedShapeTools(options, shape) {
+    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 merged = deepMerge(current, input);
+                const validated = schema.parse(merged);
+                set(validated);
+                return { success: true, value: validated };
+            },
+        });
+    }
+    return tools;
+}

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

@@ -0,0 +1,6 @@
+export { id, system } from './schema-helpers.js';
+export { generateToolsForSchema } from './tool-generator.js';
+export { generateBasicStateTools } from './generate-basic-state-tools.js';
+export type { BasicStateToolOptions, BasicStateToolsResult } from './generate-basic-state-tools.js';
+export type { GeneratedTools, KeyFieldResult, SchemaShape, ToolGenerationOptions } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tool-generators/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAEjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,YAAY,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAEpG,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}

package/dist/tool-generators/index.js

@@ -0,0 +1,3 @@
+export { id, system } from './schema-helpers.js';
+export { generateToolsForSchema } from './tool-generator.js';
+export { generateBasicStateTools } from './generate-basic-state-tools.js';

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

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import type { KeyFieldResult, SchemaShape } from './types.js';
+/**
+ * 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 findIdField(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=schema-analysis.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema-analysis.d.ts","sourceRoot":"","sources":["../../src/tool-generators/schema-analysis.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,WAAW,CA+EpE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,cAAc,CAuB9E;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,IAAI,SAAS,GAAG,MAAM,EAAE,CA0CpF"}