@mcp-web/core 0.1.0

package/dist/addTool.typetest.js

@@ -0,0 +1,248 @@
+/**
+ * Type tests for MCPWeb.addTool() overloads.
+ *
+ * These tests verify compile-time type safety. They don't execute any code,
+ * but TypeScript will report errors if the type constraints are violated.
+ *
+ * Positive tests should compile without errors.
+ * Negative tests are commented out with expected errors explained.
+ */
+import { z } from 'zod';
+// ============================================================================
+// CASE 1: Zod input + Zod output (full type safety)
+// ============================================================================
+// Positive test 1.1: Correct handler signature matching schemas
+mcp.addTool({
+    name: 'double',
+    description: 'Double a number',
+    handler: ({ value }) => ({ result: value * 2 }),
+    inputSchema: z.object({ value: z.number() }),
+    outputSchema: z.object({ result: z.number() }),
+});
+// Positive test 1.2: Async handler with correct types
+mcp.addTool({
+    name: 'asyncDouble',
+    description: 'Double a number asynchronously',
+    handler: async ({ value }) => ({ result: value * 2 }),
+    inputSchema: z.object({ value: z.number() }),
+    outputSchema: z.object({ result: z.number() }),
+});
+// Positive test 1.3: Complex nested schema
+mcp.addTool({
+    name: 'complexTool',
+    description: 'Complex tool with nested objects',
+    handler: ({ user }) => ({
+        greeting: `Hello, ${user.name}!`,
+        metadata: { processed: true },
+    }),
+    inputSchema: z.object({
+        user: z.object({
+            name: z.string(),
+            age: z.number().optional(),
+        }),
+    }),
+    outputSchema: z.object({
+        greeting: z.string(),
+        metadata: z.object({ processed: z.boolean() }),
+    }),
+});
+// ============================================================================
+// CASE 1: Negative tests (these should cause TypeScript errors)
+// ============================================================================
+// Negative test 1.1: Wrong input property name
+mcp.addTool({
+    name: 'wrongInput',
+    description: 'Wrong input',
+    // @ts-expect-error
+    // Incorrect input: Handler expects 'value' but schema has 'number'
+    handler: ({ value }) => ({ result: value * 2 }),
+    inputSchema: z.object({ number: z.number() }),
+    outputSchema: z.object({ result: z.number() }),
+});
+// Negative test 1.2: Wrong output property type
+mcp.addTool({
+    name: 'wrongOutput',
+    description: 'Wrong output',
+    // @ts-expect-error
+    // Incorrect output: Handler returns 'string' but schema has 'number'
+    handler: ({ value }) => ({ result: String(value) }),
+    inputSchema: z.object({ value: z.number() }),
+    outputSchema: z.object({ result: z.number() }),
+});
+// Negative test 1.3: Missing required output property
+mcp.addTool({
+    name: 'missingOutput',
+    description: 'Missing output property',
+    // @ts-expect-error
+    // Incorrect output: Handler returns 'result' but schema has 'result' and 'extra'
+    handler: ({ value }) => ({ result: value * 2 }),
+    inputSchema: z.object({ value: z.number() }),
+    outputSchema: z.object({ result: z.number(), extra: z.string() }),
+});
+// ============================================================================
+// CASE 2: Zod output only (no input - getter tools)
+// ============================================================================
+// Positive test 2.1: Simple getter
+mcp.addTool({
+    name: 'getCount',
+    description: 'Get current count',
+    handler: () => ({ count: 42 }),
+    outputSchema: z.object({ count: z.number() }),
+});
+// Positive test 2.2: Async getter
+mcp.addTool({
+    name: 'asyncGetState',
+    description: 'Get current state asynchronously',
+    handler: async () => ({ status: 'active', timestamp: Date.now() }),
+    outputSchema: z.object({ status: z.string(), timestamp: z.number() }),
+});
+// Positive test 2.3: Array output
+mcp.addTool({
+    name: 'getItems',
+    description: 'Get list of items',
+    handler: () => ['item1', 'item2'],
+    outputSchema: z.array(z.string()),
+});
+// ============================================================================
+// CASE 2: Negative tests
+// ============================================================================
+// Negative test 2.1: Wrong return type
+// @ts-expect-error - No overload matches (wrong property name in output)
+mcp.addTool({
+    name: 'wrongReturn',
+    description: 'Wrong return type',
+    handler: () => ({ value: 42 }),
+    outputSchema: z.object({ count: z.number() }),
+});
+// Negative test 2.2: Handler has parameter but shouldn't
+mcp.addTool({
+    name: 'unexpectedParam',
+    description: 'Unexpected parameter',
+    // @ts-expect-error
+    // Incorrect input: Handler has unexpected parameter
+    handler: (count) => ({ count }),
+    outputSchema: z.object({ count: z.number() }),
+});
+// Negative test 2.3: Wrong array element type
+mcp.addTool({
+    name: 'wrongArrayType',
+    description: 'Wrong array element type',
+    handler: () => [1, 2, 3],
+    // @ts-expect-error
+    // Incorrect output: Handler returns number[] but schema has string[]
+    outputSchema: z.array(z.string()),
+});
+// ============================================================================
+// CASE 3: Zod input only (no output - void return)
+// ============================================================================
+// Positive test 3.1: Setter that returns void
+mcp.addTool({
+    name: 'setCount',
+    description: 'Set count value',
+    handler: ({ count }) => {
+        // Set the count, no return value
+        console.log(count);
+    },
+    inputSchema: z.object({ count: z.number() }),
+});
+// Positive test 3.2: Complex input, void return
+mcp.addTool({
+    name: 'updateUser',
+    description: 'Update user data',
+    handler: ({ name, email }) => {
+        console.log(name, email);
+    },
+    inputSchema: z.object({ name: z.string(), email: z.string() }),
+});
+// Positive test 3.3: Nested input, void return
+mcp.addTool({
+    name: 'saveConfig',
+    description: 'Save configuration',
+    handler: ({ config }) => {
+        console.log(config.theme, config.fontSize);
+    },
+    inputSchema: z.object({
+        config: z.object({
+            theme: z.enum(['light', 'dark']),
+            fontSize: z.number(),
+        }),
+    }),
+});
+// ============================================================================
+// CASE 3: Negative tests
+// ============================================================================
+// Negative test 3.1: Wrong input property
+mcp.addTool({
+    name: 'wrongInputProp',
+    description: 'Wrong input property',
+    // @ts-expect-error
+    // Handler expects 'count' but schema has 'value'
+    handler: ({ count }) => { console.log(count); },
+    inputSchema: z.object({ value: z.number() }),
+});
+// USERR: I think this is a an impossible and wrong test. We cannot enforce the usage of inputs.
+// Negative test 3.2: Missing input parameter
+// mcp.addTool({
+//   name: 'missingParam',
+//   description: 'Missing parameter',
+//   // @ts-expect-error
+//   // Handler must accept input parameter when inputSchema is provided
+//   handler: () => { console.log('no input'); },
+//   inputSchema: z.object({ count: z.number() }),
+// });
+// Negative test 3.3: Wrong input type access
+mcp.addTool({
+    name: 'wrongTypeAccess',
+    description: 'Wrong type access',
+    // @ts-expect-error
+    // Trying to access string method on number
+    handler: ({ count }) => { console.log(count.toUpperCase()); },
+    inputSchema: z.object({ count: z.number() }),
+});
+// ============================================================================
+// CASE 4, 5, 6: JSON Schema (runtime validation only - no compile-time safety)
+// ============================================================================
+// These tests verify that JSON Schema overloads accept the types,
+// but don't provide compile-time type checking. Any type mismatches
+// would only be caught at runtime.
+// Test 4: JSON Schema input + output
+mcp.addTool({
+    name: 'jsonSchemaInputOutput',
+    description: 'JSON Schema input and output',
+    handler: (input) => {
+        // input is unknown, no type safety
+        return { result: input.value * 2 };
+    },
+    inputSchema: { type: 'object', properties: { value: { type: 'number' } } },
+    outputSchema: { type: 'object', properties: { result: { type: 'number' } } },
+});
+// Test 5: JSON Schema output only
+mcp.addTool({
+    name: 'jsonSchemaOutputOnly',
+    description: 'JSON Schema output only',
+    handler: () => {
+        return { count: 42 };
+    },
+    outputSchema: { type: 'object', properties: { count: { type: 'number' } } },
+});
+// Test 6: JSON Schema input only
+mcp.addTool({
+    name: 'jsonSchemaInputOnly',
+    description: 'JSON Schema input only',
+    handler: (input) => {
+        console.log(input);
+    },
+    inputSchema: { type: 'object', properties: { value: { type: 'number' } } },
+});
+// JSON Schema tests - These should pass even with type mismatches
+// because JSON Schema doesn't provide compile-time type safety
+// This compiles fine even though we return a string instead of number
+mcp.addTool({
+    name: 'jsonSchemaMismatch',
+    description: 'JSON Schema with type mismatch',
+    handler: () => {
+        return { count: 'not a number' }; // Would fail at runtime, not compile time
+    },
+    outputSchema: { type: 'object', properties: { count: { type: 'number' } } },
+});
+console.log('Type tests passed!');

package/dist/create-state-tools.d.ts

@@ -0,0 +1,77 @@
+import type { SplitPlan } from '@mcp-web/decompose-zod-schema';
+import type { ToolDefinitionZod } from '@mcp-web/types';
+import { type z } from 'zod';
+/**
+ * Configuration for creating state tools.
+ */
+export interface CreateStateToolsConfig<T> {
+    /** The name of the state (used as prefix for tool names). */
+    name: string;
+    /** Description of what this state represents. */
+    description: string;
+    /** Function to get the current state value. */
+    get: () => T;
+    /** Function to set the state value. */
+    set: (value: T) => void;
+    /** Zod schema for validating state values. */
+    schema: z.ZodType<T>;
+    /** Optional split plan for decomposing the schema into multiple setter tools. */
+    schemaSplit?: SplitPlan;
+    /** When true, generates expanded tools for arrays and records. */
+    expand?: boolean;
+}
+/**
+ * Result type for created state tools without schemaSplit or expand.
+ * Returns a single getter and single setter.
+ */
+export interface CreatedStateToolsBasic<T> {
+    /** Marker to identify this as created state tools. */
+    readonly __brand: 'CreatedStateTools';
+    /** The getter tool definition. */
+    readonly getter: ToolDefinitionZod;
+    /** The setter tool definition(s). Single setter for basic mode. */
+    readonly setters: ToolDefinitionZod;
+    /** All tool definitions as an array. */
+    readonly tools: ToolDefinitionZod[];
+    /** The original config. */
+    readonly config: CreateStateToolsConfig<T>;
+    /** Whether this uses expanded/decomposed tools. */
+    readonly isExpanded: false;
+}
+/**
+ * Result type for created state tools with schemaSplit or expand.
+ * Returns a getter and array of setters.
+ */
+export interface CreatedStateToolsExpanded<T> {
+    /** Marker to identify this as created state tools. */
+    readonly __brand: 'CreatedStateTools';
+    /** The getter tool definition. */
+    readonly getter: ToolDefinitionZod;
+    /** The setter tool definition(s). Array for expanded/decomposed mode. */
+    readonly setters: ToolDefinitionZod[];
+    /** All tool definitions as an array. */
+    readonly tools: ToolDefinitionZod[];
+    /** The original config. */
+    readonly config: CreateStateToolsConfig<T>;
+    /** Whether this uses expanded/decomposed tools. */
+    readonly isExpanded: true;
+}
+/** Union type for created state tools. */
+export type CreatedStateTools<T> = CreatedStateToolsBasic<T> | CreatedStateToolsExpanded<T>;
+export declare function createStateTools<T>(config: CreateStateToolsConfig<T> & {
+    schemaSplit?: undefined;
+    expand?: false;
+}): CreatedStateToolsBasic<T>;
+export declare function createStateTools<T>(config: CreateStateToolsConfig<T> & {
+    schemaSplit: SplitPlan;
+    expand?: boolean;
+}): CreatedStateToolsExpanded<T>;
+export declare function createStateTools<T>(config: CreateStateToolsConfig<T> & {
+    schemaSplit?: SplitPlan;
+    expand: true;
+}): CreatedStateToolsExpanded<T>;
+/**
+ * Type guard to check if a value is CreatedStateTools.
+ */
+export declare function isCreatedStateTools(value: unknown): value is CreatedStateTools<unknown>;
+//# sourceMappingURL=create-state-tools.d.ts.map

package/dist/create-state-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-state-tools.d.ts","sourceRoot":"","sources":["../src/create-state-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAEjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAa,KAAK,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxC;;GAEG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC,CAAC;IACb,uCAAuC;IACvC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACxB,8CAA8C;IAC9C,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACrB,iFAAiF;IACjF,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,kEAAkE;IAClE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,EAAE,CAAC;IACpC,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC;IAC3C,mDAAmD;IACnD,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,iBAAiB,EAAE,CAAC;IACtC,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,EAAE,CAAC;IACpC,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC;IAC3C,mDAAmD;IACnD,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;CAC3B;AAED,0CAA0C;AAC1C,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,sBAAsB,CAAC,CAAC,CAAC,GAAG,yBAAyB,CAAC,CAAC,CAAC,CAAC;AAG5F,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG;IACtE,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,MAAM,CAAC,EAAE,KAAK,CAAC;CAChB,GAAG,sBAAsB,CAAC,CAAC,CAAC,CAAC;AAG9B,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG;IACtE,WAAW,EAAE,SAAS,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,yBAAyB,CAAC,CAAC,CAAC,CAAC;AAGjC,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG;IACtE,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,MAAM,EAAE,IAAI,CAAC;CACd,GAAG,yBAAyB,CAAC,CAAC,CAAC,CAAC;AAsLjC;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAOvF"}

package/dist/create-state-tools.js

@@ -0,0 +1,181 @@
+import { decomposeSchema } from '@mcp-web/decompose-zod-schema';
+import { ZodObject } from 'zod';
+import { generateBasicStateTools } from './tool-generators/index.js';
+import { generateToolsForSchema } from './tool-generators/index.js';
+/**
+ * Creates state tool definitions without registering them.
+ *
+ * This follows the Jotai pattern of creating atoms outside React components.
+ * State tools can be defined at module scope and registered when needed.
+ *
+ * @example Basic state tools (module-level definition)
+ * ```typescript
+ * // tools.ts
+ * import { createStateTools } from '@mcp-web/core';
+ * import { z } from 'zod';
+ * import { store, todosAtom } from './states';
+ *
+ * const TodoSchema = z.object({
+ *   id: z.string(),
+ *   title: z.string(),
+ *   completed: z.boolean(),
+ * });
+ *
+ * export const todoTools = createStateTools({
+ *   name: 'todos',
+ *   description: 'Todo list',
+ *   get: () => store.get(todosAtom),
+ *   set: (value) => store.set(todosAtom, value),
+ *   schema: z.array(TodoSchema),
+ *   expand: true, // Generates get_todos, add_todos, set_todos, delete_todos
+ * });
+ * ```
+ *
+ * @example Registration options
+ * ```typescript
+ * // Option 1: Direct registration
+ * mcpWeb.addStateTools(todoTools);
+ *
+ * // Option 2: React hook (auto cleanup on unmount)
+ * function App() {
+ *   useTools(todoTools);
+ *   return <div>...</div>;
+ * }
+ * ```
+ *
+ * @example With schema decomposition
+ * ```typescript
+ * export const settingsTools = createStateTools({
+ *   name: 'settings',
+ *   description: 'App settings',
+ *   get: () => store.get(settingsAtom),
+ *   set: (value) => store.set(settingsAtom, value),
+ *   schema: SettingsSchema,
+ *   schemaSplit: ['theme', ['sortBy', 'sortOrder']], // Creates separate setter tools
+ * });
+ * ```
+ */
+export function createStateTools(config) {
+    const { name, description, get, set, schema, schemaSplit, expand } = config;
+    const allTools = [];
+    // Determine if we're expanding (schemaSplit or expand flag)
+    const isZodObjectSchema = schema instanceof ZodObject;
+    const shouldDecompose = schemaSplit && isZodObjectSchema;
+    // Step 1: Apply schemaSplit if provided
+    let decomposedSchemas = [];
+    if (shouldDecompose) {
+        decomposedSchemas = decomposeSchema(schema, schemaSplit);
+    }
+    // Step 2: Generate tools based on mode
+    if (expand) {
+        // Expanded mode: generate targeted tools for collections
+        if (decomposedSchemas.length > 0) {
+            // Generate expanded tools for each decomposed part
+            for (const decomposed of decomposedSchemas) {
+                const result = generateToolsForSchema({
+                    name: `${name}_${decomposed.name}`,
+                    description: `${decomposed.name} in ${description}`,
+                    get: () => {
+                        const fullState = get();
+                        const extracted = {};
+                        for (const path of decomposed.targetPaths) {
+                            extracted[path] = fullState[path];
+                        }
+                        return Object.keys(extracted).length === 1
+                            ? extracted[decomposed.targetPaths[0]]
+                            : extracted;
+                    },
+                    set: (value) => {
+                        const current = get();
+                        if (decomposed.targetPaths.length === 1) {
+                            set({ ...current, [decomposed.targetPaths[0]]: value });
+                        }
+                        else {
+                            set({ ...current, ...value });
+                        }
+                    },
+                    schema: decomposed.schema,
+                });
+                allTools.push(...result.tools);
+                // Log warnings if any
+                for (const warning of result.warnings) {
+                    console.warn(warning);
+                }
+            }
+        }
+        else {
+            // Generate expanded tools for full schema
+            const result = generateToolsForSchema({
+                name,
+                description,
+                get: get,
+                set: set,
+                schema: schema,
+            });
+            allTools.push(...result.tools);
+            // Log warnings if any
+            for (const warning of result.warnings) {
+                console.warn(warning);
+            }
+        }
+        // For expanded mode, first tool is getter, rest are setters
+        const getter = allTools[0];
+        const setters = allTools.slice(1);
+        return {
+            __brand: 'CreatedStateTools',
+            getter,
+            setters,
+            tools: allTools,
+            config,
+            isExpanded: true,
+        };
+    }
+    else if (shouldDecompose) {
+        // Decompose mode without expand: use basic state tools with decomposition
+        const basicResult = generateBasicStateTools({
+            name,
+            description,
+            get,
+            set,
+            schema: schema,
+            schemaSplit,
+        });
+        allTools.push(basicResult.getter, ...basicResult.setters);
+        return {
+            __brand: 'CreatedStateTools',
+            getter: basicResult.getter,
+            setters: basicResult.setters,
+            tools: allTools,
+            config,
+            isExpanded: true,
+        };
+    }
+    else {
+        // Basic mode: simple get/set tools
+        const basicResult = generateBasicStateTools({
+            name,
+            description,
+            get,
+            set,
+            schema: schema,
+        });
+        allTools.push(basicResult.getter, ...basicResult.setters);
+        return {
+            __brand: 'CreatedStateTools',
+            getter: basicResult.getter,
+            setters: basicResult.setters[0], // Single setter for basic mode
+            tools: allTools,
+            config,
+            isExpanded: false,
+        };
+    }
+}
+/**
+ * Type guard to check if a value is CreatedStateTools.
+ */
+export function isCreatedStateTools(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__brand' in value &&
+        value.__brand === 'CreatedStateTools');
+}

package/dist/create-tool.d.ts

@@ -0,0 +1,90 @@
+import type { ToolDefinitionZod } from '@mcp-web/types';
+import type { z } from 'zod';
+/**
+ * Configuration for creating a tool with Zod schemas.
+ */
+export interface CreateToolConfig<TInput extends z.ZodObject | undefined = undefined, TOutput extends z.ZodType | undefined = undefined> {
+    /** The name of the tool (must be unique). */
+    name: string;
+    /** Description of what the tool does. */
+    description: string;
+    /** The function that handles the tool execution. */
+    handler: TInput extends z.ZodObject ? (input: z.infer<TInput>) => TOutput extends z.ZodType ? z.infer<TOutput> | Promise<z.infer<TOutput>> : void | Promise<void> : TOutput extends z.ZodType ? () => z.infer<TOutput> | Promise<z.infer<TOutput>> : () => void | Promise<void>;
+    /** Optional Zod schema for validating input. */
+    inputSchema?: TInput;
+    /** Optional Zod schema for validating output. */
+    outputSchema?: TOutput;
+}
+/**
+ * A created tool that can be registered with MCPWeb.
+ *
+ * Created tools are validated at creation time but not yet registered.
+ * Use `mcpWeb.addTool(createdTool)` or `useTools(createdTool)` to register.
+ */
+export interface CreatedTool<TInput extends z.ZodObject | undefined = undefined, TOutput extends z.ZodType | undefined = undefined> {
+    /** Marker to identify this as a created tool. */
+    readonly __brand: 'CreatedTool';
+    /** The tool definition. */
+    readonly definition: ToolDefinitionZod;
+    /** The original config for type inference. */
+    readonly config: CreateToolConfig<TInput, TOutput>;
+}
+/**
+ * Creates a tool definition without registering it.
+ *
+ * Useful for:
+ * - Read-only tools (derived state, computed values)
+ * - Custom action tools that don't map directly to state
+ * - Tools that need to be conditionally registered
+ *
+ * This follows the Jotai pattern of creating atoms outside React components.
+ * Tools can be defined at module scope and registered when needed.
+ *
+ * @example Read-only derived state
+ * ```typescript
+ * // tools.ts
+ * import { createTool } from '@mcp-web/core';
+ * import { z } from 'zod';
+ * import { activeTodosAtom } from './atoms';
+ *
+ * export const activeTodosTool = createTool({
+ *   name: 'get_active_todos',
+ *   description: 'Get all incomplete todos',
+ *   handler: () => store.get(activeTodosAtom),
+ *   outputSchema: z.array(TodoSchema),
+ * });
+ * ```
+ *
+ * @example Custom action
+ * ```typescript
+ * export const createTodoTool = createTool({
+ *   name: 'create_todo',
+ *   description: 'Create a new todo',
+ *   handler: ({ title }) => {
+ *     const todo = { id: crypto.randomUUID(), title, completed: false };
+ *     todos.push(todo);
+ *     return todo;
+ *   },
+ *   inputSchema: z.object({ title: z.string() }),
+ *   outputSchema: TodoSchema,
+ * });
+ * ```
+ *
+ * @example Registration options
+ * ```typescript
+ * // Option 1: Direct registration
+ * mcpWeb.addTool(activeTodosTool);
+ *
+ * // Option 2: React hook (auto cleanup on unmount)
+ * function App() {
+ *   useTools(activeTodosTool);
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+export declare function createTool<TInput extends z.ZodObject | undefined = undefined, TOutput extends z.ZodType | undefined = undefined>(config: CreateToolConfig<TInput, TOutput>): CreatedTool<TInput, TOutput>;
+/**
+ * Type guard to check if a value is a CreatedTool.
+ */
+export declare function isCreatedTool(value: unknown): value is CreatedTool;
+//# sourceMappingURL=create-tool.d.ts.map

package/dist/create-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-tool.d.ts","sourceRoot":"","sources":["../src/create-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAC/B,MAAM,SAAS,CAAC,CAAC,SAAS,GAAG,SAAS,GAAG,SAAS,EAClD,OAAO,SAAS,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,SAAS;IAEjD,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,OAAO,EAAE,MAAM,SAAS,CAAC,CAAC,SAAS,GAC/B,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,OAAO,SAAS,CAAC,CAAC,OAAO,GACnD,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAC5C,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACtB,OAAO,SAAS,CAAC,CAAC,OAAO,GACvB,MAAM,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAClD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAC1B,MAAM,SAAS,CAAC,CAAC,SAAS,GAAG,SAAS,GAAG,SAAS,EAClD,OAAO,SAAS,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,SAAS;IAEjD,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,2BAA2B;IAC3B,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,UAAU,CACxB,MAAM,SAAS,CAAC,CAAC,SAAS,GAAG,SAAS,GAAG,SAAS,EAClD,OAAO,SAAS,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,SAAS,EACjD,MAAM,EAAE,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBzE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAOlE"}

package/dist/create-tool.js

@@ -0,0 +1,82 @@
+import { ToolDefinitionSchema } from '@mcp-web/types';
+/**
+ * Creates a tool definition without registering it.
+ *
+ * Useful for:
+ * - Read-only tools (derived state, computed values)
+ * - Custom action tools that don't map directly to state
+ * - Tools that need to be conditionally registered
+ *
+ * This follows the Jotai pattern of creating atoms outside React components.
+ * Tools can be defined at module scope and registered when needed.
+ *
+ * @example Read-only derived state
+ * ```typescript
+ * // tools.ts
+ * import { createTool } from '@mcp-web/core';
+ * import { z } from 'zod';
+ * import { activeTodosAtom } from './atoms';
+ *
+ * export const activeTodosTool = createTool({
+ *   name: 'get_active_todos',
+ *   description: 'Get all incomplete todos',
+ *   handler: () => store.get(activeTodosAtom),
+ *   outputSchema: z.array(TodoSchema),
+ * });
+ * ```
+ *
+ * @example Custom action
+ * ```typescript
+ * export const createTodoTool = createTool({
+ *   name: 'create_todo',
+ *   description: 'Create a new todo',
+ *   handler: ({ title }) => {
+ *     const todo = { id: crypto.randomUUID(), title, completed: false };
+ *     todos.push(todo);
+ *     return todo;
+ *   },
+ *   inputSchema: z.object({ title: z.string() }),
+ *   outputSchema: TodoSchema,
+ * });
+ * ```
+ *
+ * @example Registration options
+ * ```typescript
+ * // Option 1: Direct registration
+ * mcpWeb.addTool(activeTodosTool);
+ *
+ * // Option 2: React hook (auto cleanup on unmount)
+ * function App() {
+ *   useTools(activeTodosTool);
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+export function createTool(config) {
+    // Validate at creation time
+    const validationResult = ToolDefinitionSchema.safeParse(config);
+    if (!validationResult.success) {
+        throw new Error(`Invalid tool definition: ${validationResult.error.message}`);
+    }
+    const definition = {
+        name: config.name,
+        description: config.description,
+        handler: config.handler,
+        inputSchema: config.inputSchema,
+        outputSchema: config.outputSchema,
+    };
+    return {
+        __brand: 'CreatedTool',
+        definition,
+        config,
+    };
+}
+/**
+ * Type guard to check if a value is a CreatedTool.
+ */
+export function isCreatedTool(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__brand' in value &&
+        value.__brand === 'CreatedTool');
+}