@mcp-web/core 0.1.0

package/dist/expanded-schema-tools/types.d.ts

@@ -0,0 +1,26 @@
+import type { ToolDefinition } from '@mcp-web/types';
+import type { z } from 'zod';
+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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/expanded-schema-tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/expanded-schema-tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,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"}

package/dist/expanded-schema-tools/types.js

@@ -0,0 +1 @@
+export {};

package/dist/expanded-schema-tools/utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Deep merge two objects recursively.
+ * Used for partial updates to state objects.
+ *
+ * @param target - The target object to merge into
+ * @param source - The source object to merge from
+ * @returns The merged result
+ *
+ * Key behaviors:
+ * - `undefined` in source → keep target value (no change)
+ * - `null` in source → set to null (explicit clear)
+ * - Nested objects → recursively merged
+ * - Arrays → replaced entirely (not merged)
+ */
+export declare function deepMerge(target: unknown, source: unknown): unknown;
+//# sourceMappingURL=utils.d.ts.map

package/dist/expanded-schema-tools/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/expanded-schema-tools/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAenE"}

package/dist/expanded-schema-tools/utils.js

@@ -0,0 +1,35 @@
+/**
+ * Deep merge two objects recursively.
+ * Used for partial updates to state objects.
+ *
+ * @param target - The target object to merge into
+ * @param source - The source object to merge from
+ * @returns The merged result
+ *
+ * Key behaviors:
+ * - `undefined` in source → keep target value (no change)
+ * - `null` in source → set to null (explicit clear)
+ * - Nested objects → recursively merged
+ * - Arrays → replaced entirely (not merged)
+ */
+export function deepMerge(target, source) {
+    // Base cases
+    if (source === null)
+        return source; // Explicit null clears the value
+    if (source === undefined)
+        return target; // Undefined means "no change"
+    if (typeof source !== 'object')
+        return source;
+    if (Array.isArray(source))
+        return source; // Arrays are replaced, not merged
+    if (typeof target !== 'object' || target === null)
+        return source;
+    if (Array.isArray(target))
+        return source;
+    // Object merge: recursively merge properties
+    const result = { ...target };
+    for (const [key, value] of Object.entries(source)) {
+        result[key] = deepMerge(result[key], value);
+    }
+    return result;
+}

package/dist/expanded-schema-tools/utils.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=utils.test.d.ts.map

package/dist/expanded-schema-tools/utils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.test.d.ts","sourceRoot":"","sources":["../../src/expanded-schema-tools/utils.test.ts"],"names":[],"mappings":""}

package/dist/expanded-schema-tools/utils.test.js

@@ -0,0 +1,169 @@
+import { expect, test } from 'bun:test';
+import { deepMerge } from './utils.js';
+// ============================================================================
+// Basic Merge Cases
+// ============================================================================
+test('deepMerge - merges two simple objects', () => {
+    const target = { a: 1, b: 2 };
+    const source = { c: 3 };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 1, b: 2, c: 3 });
+});
+test('deepMerge - merges with nested objects recursively', () => {
+    const target = {
+        user: { name: 'Alice', age: 30 },
+        settings: { theme: 'dark' },
+    };
+    const source = {
+        user: { age: 31, email: 'alice@example.com' },
+        settings: { notifications: true },
+    };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({
+        user: { name: 'Alice', age: 31, email: 'alice@example.com' },
+        settings: { theme: 'dark', notifications: true },
+    });
+});
+test('deepMerge - merges with overlapping keys', () => {
+    const target = { a: 1, b: 2, c: 3 };
+    const source = { b: 20, c: 30 };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 1, b: 20, c: 30 });
+});
+// ============================================================================
+// Null/Undefined Handling
+// ============================================================================
+test('deepMerge - null in source sets value to null (explicit clear)', () => {
+    const target = { a: 1, b: 2 };
+    const source = { b: null };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 1, b: null });
+});
+test('deepMerge - undefined in source keeps target value (no change)', () => {
+    const target = { a: 1, b: 2 };
+    const source = { b: undefined };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 1, b: 2 });
+});
+test('deepMerge - null target, non-null source replaces with source', () => {
+    const target = null;
+    const source = { a: 1 };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 1 });
+});
+test('deepMerge - nested null clears nested value', () => {
+    const target = {
+        user: { name: 'Alice', email: 'alice@example.com' },
+    };
+    const source = {
+        user: { email: null },
+    };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({
+        user: { name: 'Alice', email: null },
+    });
+});
+// ============================================================================
+// Array Behavior
+// ============================================================================
+test('deepMerge - arrays are replaced entirely (not merged)', () => {
+    const target = { tags: ['a', 'b', 'c'] };
+    const source = { tags: ['x', 'y'] };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ tags: ['x', 'y'] });
+});
+test('deepMerge - nested arrays within objects are replaced', () => {
+    const target = {
+        user: { name: 'Alice', tags: ['a', 'b'] },
+    };
+    const source = {
+        user: { tags: ['x'] },
+    };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({
+        user: { name: 'Alice', tags: ['x'] },
+    });
+});
+test('deepMerge - array at root replaces target', () => {
+    const target = [1, 2, 3];
+    const source = [4, 5];
+    const result = deepMerge(target, source);
+    expect(result).toEqual([4, 5]);
+});
+// ============================================================================
+// Edge Cases
+// ============================================================================
+test('deepMerge - empty objects', () => {
+    const target = {};
+    const source = {};
+    const result = deepMerge(target, source);
+    expect(result).toEqual({});
+});
+test('deepMerge - empty source returns target', () => {
+    const target = { a: 1, b: 2 };
+    const source = {};
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 1, b: 2 });
+});
+test('deepMerge - primitives in source replace target', () => {
+    const target = { a: { nested: true } };
+    const source = { a: 'string' };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 'string' });
+});
+test('deepMerge - deep nesting (3+ levels)', () => {
+    const target = {
+        level1: {
+            level2: {
+                level3: {
+                    value: 'original',
+                    keep: true,
+                },
+            },
+        },
+    };
+    const source = {
+        level1: {
+            level2: {
+                level3: {
+                    value: 'updated',
+                },
+            },
+        },
+    };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({
+        level1: {
+            level2: {
+                level3: {
+                    value: 'updated',
+                    keep: true,
+                },
+            },
+        },
+    });
+});
+test('deepMerge - undefined source returns target', () => {
+    const target = { a: 1 };
+    const source = undefined;
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 1 });
+});
+test('deepMerge - primitive target and object source', () => {
+    const target = 'string';
+    const source = { a: 1 };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 1 });
+});
+test('deepMerge - number source replaces any target', () => {
+    const target = { nested: { value: true } };
+    const source = 42;
+    const result = deepMerge(target, source);
+    expect(result).toBe(42);
+});
+test('deepMerge - boolean source replaces any target', () => {
+    const target = { a: 1 };
+    const source = false;
+    const result = deepMerge(target, source);
+    expect(result).toBe(false);
+});

package/dist/group-state.d.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+/**
+ * A tuple representing a single piece of state: [getter, setter, schema]
+ * Follows the familiar [value, setter] pattern from React/Jotai hooks.
+ */
+export type StateTriple<T> = [get: () => T, set: (value: T) => void, schema: z.ZodType<T>];
+/**
+ * Configuration object mapping state names to their getter/setter/schema triples.
+ * Uses `any` instead of `unknown` to avoid contravariance issues with the setter function.
+ */
+export type StateTriples = Record<string, StateTriple<any>>;
+/**
+ * Infer the value type from a StateTriple.
+ */
+type InferTripleType<T> = T extends StateTriple<infer U> ? U : never;
+/**
+ * The result of groupState: combined schema, getter, and setter.
+ */
+export type GroupedState<T extends StateTriples> = {
+    schema: z.ZodObject<{
+        [K in keyof T]: z.ZodOptional<T[K] extends StateTriple<infer U> ? z.ZodType<U> : never>;
+    }>;
+    get: () => {
+        [K in keyof T]: InferTripleType<T[K]>;
+    };
+    set: (value: Partial<{
+        [K in keyof T]: InferTripleType<T[K]>;
+    }>) => void;
+};
+/**
+ * Groups multiple atomic state variables into a single schema/getter/setter
+ * that can be spread into `addStateTools`.
+ *
+ * This reduces tool explosion when using declarative reactive state (like Jotai atoms)
+ * by exposing semantically related state through one tool set.
+ *
+ * @param atoms - Object mapping state names to [getter, setter, schema] triples
+ * @returns Object with combined { schema, get, set } for use with addStateTools
+ *
+ * @example
+ * ```typescript
+ * import { groupState } from '@mcp-web/core';
+ *
+ * const settingsGroup = groupState({
+ *   sortBy: [getSortBy, setSortBy, SortBySchema],
+ *   sortOrder: [getSortOrder, setSortOrder, SortOrderSchema],
+ *   showCompleted: [getShowCompleted, setShowCompleted, ShowCompletedSchema],
+ *   theme: [getTheme, setTheme, ThemeSchema],
+ * });
+ *
+ * mcpWeb.addStateTools({
+ *   name: 'settings',
+ *   description: 'Display and app settings',
+ *   ...settingsGroup,
+ * });
+ * ```
+ */
+export declare function groupState<T extends StateTriples>(atoms: T): GroupedState<T>;
+export {};
+//# sourceMappingURL=group-state.d.ts.map

package/dist/group-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-state.d.ts","sourceRoot":"","sources":["../src/group-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAE3F;;;GAGG;AAEH,MAAM,MAAO,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;AAE7D;;GAEG;AACH,KAAK,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAErE;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,YAAY,IAAI;IACjD,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC;SACjB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;KACxF,CAAC,CAAC;IACH,GAAG,EAAE,MAAM;SAAG,CAAC,IAAI,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KAAE,CAAC;IACrD,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC;SAAG,CAAC,IAAI,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KAAE,CAAC,KAAK,IAAI,CAAC;CAC1E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,YAAY,EAAE,KAAK,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CA2B5E"}

package/dist/group-state.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+/**
+ * Groups multiple atomic state variables into a single schema/getter/setter
+ * that can be spread into `addStateTools`.
+ *
+ * This reduces tool explosion when using declarative reactive state (like Jotai atoms)
+ * by exposing semantically related state through one tool set.
+ *
+ * @param atoms - Object mapping state names to [getter, setter, schema] triples
+ * @returns Object with combined { schema, get, set } for use with addStateTools
+ *
+ * @example
+ * ```typescript
+ * import { groupState } from '@mcp-web/core';
+ *
+ * const settingsGroup = groupState({
+ *   sortBy: [getSortBy, setSortBy, SortBySchema],
+ *   sortOrder: [getSortOrder, setSortOrder, SortOrderSchema],
+ *   showCompleted: [getShowCompleted, setShowCompleted, ShowCompletedSchema],
+ *   theme: [getTheme, setTheme, ThemeSchema],
+ * });
+ *
+ * mcpWeb.addStateTools({
+ *   name: 'settings',
+ *   description: 'Display and app settings',
+ *   ...settingsGroup,
+ * });
+ * ```
+ */
+export function groupState(atoms) {
+    // Build combined schema with all fields optional (for partial updates)
+    const schemaShape = {};
+    for (const [key, [, , schema]] of Object.entries(atoms)) {
+        schemaShape[key] = schema.optional();
+    }
+    const schema = z.object(schemaShape);
+    // Build combined getter
+    const get = () => {
+        const result = {};
+        for (const [key, [getter]] of Object.entries(atoms)) {
+            result[key] = getter();
+        }
+        return result;
+    };
+    // Build combined setter (only sets defined values)
+    const set = (value) => {
+        for (const [key, [, setter]] of Object.entries(atoms)) {
+            if (value[key] !== undefined) {
+                setter(value[key]);
+            }
+        }
+    };
+    return { schema, get, set };
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { QueryResponse } from './query.js';
+export { id, system } from './tool-generators/index.js';
+export { groupState } from './group-state.js';
+export type { StateTriple, StateTriples, GroupedState } from './group-state.js';
+export type { ContextItem, EphemeralContext, QueryRequest, QueryResponseResult, QueryResponseResultAccepted, QueryResponseResultComplete, QueryResponseResultFailure, QueryResponseResultProgress, } from './types.js';
+export * from './utils.js';
+export { MCPWeb } from './web.js';
+export { createTool, isCreatedTool } from './create-tool.js';
+export type { CreateToolConfig, CreatedTool } from './create-tool.js';
+export { createStateTools, isCreatedStateTools } from './create-state-tools.js';
+export type { CreateStateToolsConfig, CreatedStateTools, CreatedStateToolsBasic, CreatedStateToolsExpanded, } from './create-state-tools.js';
+export { isCreatedApp } from '@mcp-web/types';
+export type { AppDefinition, CreatedApp, ToolRegistrationError } from '@mcp-web/types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChF,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,YAAY,CAAC;AACpB,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAGlC,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC7D,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAChF,YAAY,EACV,sBAAsB,EACtB,iBAAiB,EACjB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+// Export query-related types
+export { QueryResponse } from './query.js';
+// Export schema helper functions for expanded tools
+export { id, system } from './tool-generators/index.js';
+// Export state grouping helper
+export { groupState } from './group-state.js';
+export * from './utils.js';
+export { MCPWeb } from './web.js';
+// Export tool creation functions (Jotai-style pattern)
+export { createTool, isCreatedTool } from './create-tool.js';
+export { createStateTools, isCreatedStateTools } from './create-state-tools.js';
+// Re-export app-related types from @mcp-web/types for convenience
+export { isCreatedApp } from '@mcp-web/types';

package/dist/query.d.ts

@@ -0,0 +1,104 @@
+import type { QueryResponseResult, QueryResponseResultComplete, QueryResponseResultFailure } from './types';
+/**
+ * Represents an in-flight query to an AI agent.
+ *
+ * QueryResponse provides multiple ways to interact with query results:
+ * - `stream` for fine-grained event handling
+ * - `result` for simple await-the-final-result usage
+ * - `cancel()` to abort the query
+ *
+ * @example Streaming events
+ * ```typescript
+ * const query = mcp.query({ prompt: 'Analyze the data' });
+ *
+ * for await (const event of query.stream) {
+ *   if (event.type === 'query_progress') {
+ *     console.log('Progress:', event.message);
+ *   } else if (event.type === 'query_complete') {
+ *     console.log('Done:', event.message);
+ *   }
+ * }
+ * ```
+ *
+ * @example Simple result awaiting
+ * ```typescript
+ * const query = mcp.query({ prompt: 'Analyze the data' });
+ * const result = await query.result;
+ *
+ * if (result.type === 'query_complete') {
+ *   console.log('Success:', result.message);
+ * }
+ * ```
+ */
+export declare class QueryResponse {
+    #private;
+    /**
+     * Creates a new QueryResponse instance.
+     * @internal This is typically created by MCPWeb.query(), not directly.
+     */
+    constructor(uuid: string, stream: AsyncIterableIterator<QueryResponseResult>, cancelFn?: () => void);
+    /**
+     * Unique identifier for this query.
+     * Can be used to track or reference the query externally.
+     */
+    get uuid(): string;
+    /**
+     * Async iterator of query events (progress, completion, failure, cancel).
+     *
+     * Use this for fine-grained control over query lifecycle, such as
+     * displaying progress updates to users.
+     *
+     * @example
+     * ```typescript
+     * for await (const event of query.stream) {
+     *   switch (event.type) {
+     *     case 'query_progress':
+     *       updateProgress(event.message);
+     *       break;
+     *     case 'query_complete':
+     *       showResult(event);
+     *       break;
+     *   }
+     * }
+     * ```
+     */
+    get stream(): AsyncIterableIterator<QueryResponseResult>;
+    /**
+     * Promise that resolves to the final query result.
+     *
+     * This is a convenience property for when you only care about the final
+     * outcome and don't need to track progress events.
+     *
+     * @returns Promise resolving to complete or failure event
+     * @throws {Error} If query ends without completion or failure
+     *
+     * @example
+     * ```typescript
+     * const result = await query.result;
+     * if (result.type === 'query_complete') {
+     *   console.log('Success:', result.toolCalls);
+     * } else {
+     *   console.error('Failed:', result.error);
+     * }
+     * ```
+     */
+    get result(): Promise<QueryResponseResultComplete | QueryResponseResultFailure>;
+    /**
+     * Cancels the in-flight query.
+     *
+     * Triggers cancellation via AbortController or directly through the bridge,
+     * depending on how the query was created.
+     *
+     * @throws {Error} If cancel function is not available
+     *
+     * @example
+     * ```typescript
+     * const query = mcp.query({ prompt: 'Long task' });
+     *
+     * // Cancel after 5 seconds
+     * setTimeout(() => query.cancel(), 5000);
+     * ```
+     */
+    cancel(): void;
+}
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAE5G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,aAAa;;IAKxB;;;OAGG;gBACS,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,CAAC,mBAAmB,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,IAAI;IAMnG;;;OAGG;IACH,IAAI,IAAI,WAEP;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAI,MAAM,IAAI,qBAAqB,CAAC,mBAAmB,CAAC,CAEvD;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,MAAM,IAAI,OAAO,CAAC,2BAA2B,GAAG,0BAA0B,CAAC,CAS9E;IAED;;;;;;;;;;;;;;;OAeG;IACH,MAAM,IAAI,IAAI;CAOf"}

package/dist/query.js

@@ -0,0 +1,128 @@
+/**
+ * Represents an in-flight query to an AI agent.
+ *
+ * QueryResponse provides multiple ways to interact with query results:
+ * - `stream` for fine-grained event handling
+ * - `result` for simple await-the-final-result usage
+ * - `cancel()` to abort the query
+ *
+ * @example Streaming events
+ * ```typescript
+ * const query = mcp.query({ prompt: 'Analyze the data' });
+ *
+ * for await (const event of query.stream) {
+ *   if (event.type === 'query_progress') {
+ *     console.log('Progress:', event.message);
+ *   } else if (event.type === 'query_complete') {
+ *     console.log('Done:', event.message);
+ *   }
+ * }
+ * ```
+ *
+ * @example Simple result awaiting
+ * ```typescript
+ * const query = mcp.query({ prompt: 'Analyze the data' });
+ * const result = await query.result;
+ *
+ * if (result.type === 'query_complete') {
+ *   console.log('Success:', result.message);
+ * }
+ * ```
+ */
+export class QueryResponse {
+    #streamIterator;
+    #uuid;
+    #cancelFn;
+    /**
+     * Creates a new QueryResponse instance.
+     * @internal This is typically created by MCPWeb.query(), not directly.
+     */
+    constructor(uuid, stream, cancelFn) {
+        this.#uuid = uuid;
+        this.#streamIterator = stream;
+        this.#cancelFn = cancelFn;
+    }
+    /**
+     * Unique identifier for this query.
+     * Can be used to track or reference the query externally.
+     */
+    get uuid() {
+        return this.#uuid;
+    }
+    /**
+     * Async iterator of query events (progress, completion, failure, cancel).
+     *
+     * Use this for fine-grained control over query lifecycle, such as
+     * displaying progress updates to users.
+     *
+     * @example
+     * ```typescript
+     * for await (const event of query.stream) {
+     *   switch (event.type) {
+     *     case 'query_progress':
+     *       updateProgress(event.message);
+     *       break;
+     *     case 'query_complete':
+     *       showResult(event);
+     *       break;
+     *   }
+     * }
+     * ```
+     */
+    get stream() {
+        return this.#streamIterator;
+    }
+    /**
+     * Promise that resolves to the final query result.
+     *
+     * This is a convenience property for when you only care about the final
+     * outcome and don't need to track progress events.
+     *
+     * @returns Promise resolving to complete or failure event
+     * @throws {Error} If query ends without completion or failure
+     *
+     * @example
+     * ```typescript
+     * const result = await query.result;
+     * if (result.type === 'query_complete') {
+     *   console.log('Success:', result.toolCalls);
+     * } else {
+     *   console.error('Failed:', result.error);
+     * }
+     * ```
+     */
+    get result() {
+        return (async () => {
+            for await (const event of this.#streamIterator) {
+                if (event.type === 'query_complete' || event.type === 'query_failure') {
+                    return event;
+                }
+            }
+            throw new Error('Query ended without completion or failure event');
+        })();
+    }
+    /**
+     * Cancels the in-flight query.
+     *
+     * Triggers cancellation via AbortController or directly through the bridge,
+     * depending on how the query was created.
+     *
+     * @throws {Error} If cancel function is not available
+     *
+     * @example
+     * ```typescript
+     * const query = mcp.query({ prompt: 'Long task' });
+     *
+     * // Cancel after 5 seconds
+     * setTimeout(() => query.cancel(), 5000);
+     * ```
+     */
+    cancel() {
+        if (this.#cancelFn) {
+            this.#cancelFn();
+        }
+        else {
+            throw new Error('Cancel function not available for this query');
+        }
+    }
+}