mcp-use 2.0.0-beta.4 → 2.0.0-beta.41

package/dist/react/runtime/model-context-store.d.ts

@@ -1,106 +1,71 @@
 import type { App } from "@modelcontextprotocol/ext-apps";
 import type { ContentBlock } from "@modelcontextprotocol/server";
+/** Model-visible state owned by one mounted view runtime. */
+export type ViewState = Record<string, unknown>;
+/** Reserved field carrying the serialized {@link ModelContext} tree. */
+export declare const UI_CONTEXT_KEY: "_uiContext";
 interface ModelContextNode {
     id: string;
     parentId: string | null;
     content: string;
 }
-/**
- * Complete `ui/update-model-context` params built from the store — the wire
- * shape of the MCP Apps spec's `content` blocks. Each push carries the full
- * current state (the spec's overwrite semantics).
- *
- * @internal
- */
+/** Complete model-visible snapshot sent on every update. */
 export interface ModelContextParams {
-    /**
-     * Content blocks: empty, or a single text block with the serialized
-     * description tree.
-     */
+    structuredContent: ViewState & {
+        [UI_CONTEXT_KEY]: string;
+    };
     content: ContentBlock[];
 }
-/**
- * Narrow runtime surface the flush pump needs to connect and send.
- *
- * @internal
- */
+/** Narrow runtime surface used by the shared state/context flush pump. */
 export interface ModelContextStoreHost {
     /** Connect once, or return the cached in-flight / settled connection promise. */
     connect(): Promise<App>;
 }
-/**
- * Mark that the missing-`updateModelContext` warning has been emitted.
- *
- * @returns `true` if this call should emit the warning (first time only).
- *
- * @internal
- */
+/** Mark that the missing-capability warning has been emitted. */
 export declare function markModelContextUnsupportedWarned(): boolean;
-/**
- * @internal Reset the missing-capability warn-once flag between tests.
- *
- * Prefer {@link _resetModelContextForTesting} from `model-context.tsx` when the
- * active runtime's store must also be cleared; this seam only resets the
- * document-level warn flag (dispose already drops the store).
- */
+/** Reset the missing-capability warn-once flag between tests. */
 export declare function _resetModelContextForTesting(): void;
-/**
- * @internal Reset the missing-capability warn-once flag between tests.
- */
+/** Reset the missing-capability warn-once flag between tests. */
 export declare function _resetModelContextUnsupportedWarnedForTesting(): void;
 /**
- * Per-runtime model-context node tree and async flush pump.
+ * Per-runtime view-state document, model-context tree, and async flush pump.
  *
- * Owned by one {@link McpAppRuntime}: constructed with it, disposed with it.
- * Mutations update desired state and schedule a microtask-batched pump that
- * acknowledges a payload only after a successful `updateModelContext` send.
+ * `useViewState`, `ModelContext`, and the imperative `modelContext` API all
+ * mutate this single owner. Each delivery contains the complete merged
+ * snapshot because `ui/update-model-context` has overwrite semantics.
  *
  * @internal
  */
 export declare class ModelContextStore {
     #private;
-    /**
-     * @param host - Runtime bridge used to `connect` and send updates.
-     */
+    /** Create a store backed by the owning view runtime's host connection. */
     constructor(host: ModelContextStoreHost);
+    /** Stable external-store subscription used by `useViewState`. */
+    readonly subscribeViewState: (listener: () => void) => (() => void);
+    /** Current canonical view state, excluding the reserved UI-context field. */
+    readonly getViewStateSnapshot: () => ViewState | null;
     /**
-     * Register or replace a node and schedule a flush.
-     *
-     * @param node - Node identity, parent link, and text content.
+     * Initialize view state from a hook default when ChatGPT restored no state.
+     * The first hook default wins; later conflicting defaults warn in development.
      */
+    initializeViewState(defaultState: ViewState): void;
+    /** Resolve and apply a `useState`-style update synchronously. */
+    updateViewState(updater: (previous: ViewState | null) => ViewState): void;
+    /** Register or replace a model-context node and schedule a merged flush. */
     setNode(node: ModelContextNode): void;
-    /**
-     * Remove a node by id and schedule a flush.
-     *
-     * @param id - Node id previously passed to {@link setNode}.
-     */
+    /** Remove a model-context node and schedule a merged flush. */
     removeNode(id: string): void;
-    /** Remove every node and schedule a flush (empty clear when previously non-empty). */
+    /** Remove every model-context node. */
     clear(): void;
-    /**
-     * Invalidate the store: ignore late in-flight completions and reject further
-     * mutations. Does not send a final clear — the runtime is going away.
-     */
+    /** Invalidate the store and ignore late in-flight completions. */
     dispose(): void;
-    /**
-     * Serialize the registered tree into an indented markdown-like string.
-     *
-     * @returns Description text, or `""` when nothing is registered.
-     */
+    /** Serialize registered context nodes into an indented markdown list. */
     buildDescriptionString(): string;
-    /**
-     * Build the `ui/update-model-context` params from the current tree.
-     *
-     * @returns Empty `content` when nothing is registered; otherwise one text block.
-     */
+    /** Build the complete merged payload sent through either host transport. */
     buildModelContextParams(): ModelContextParams;
-    /**
-     * @internal Clear nodes and pump state between tests without disposing the
-     * owning runtime (warn-once flag is reset separately).
-     */
+    /** Clear state between tests without disposing the owning runtime. */
     resetForTesting(): void;
-    /** @internal Serialized tree for tests. */
+    /** Internal serialized tree for tests. */
     getDescriptionForTesting(): string;
 }
 export {};
-//# sourceMappingURL=model-context-store.d.ts.map

package/dist/react/runtime/view-config.d.ts

@@ -59,4 +59,3 @@ export interface NormalizedViewConfig {
  * @internal
  */
 export declare function normalizeViewConfig(config?: ViewConfig): NormalizedViewConfig;
-//# sourceMappingURL=view-config.d.ts.map

package/dist/react/runtime/view-runtime-context.d.ts

@@ -43,4 +43,3 @@ export declare function useViewRuntime(): McpAppRuntime;
  * @internal
  */
 export declare function useHostContextSubscription(): McpUiHostContext | undefined;
-//# sourceMappingURL=view-runtime-context.d.ts.map

package/dist/react/runtime/view-runtime.d.ts

@@ -1,6 +1,7 @@
 import { App, type McpUiHostContext, type RegisteredAppTool } from "@modelcontextprotocol/ext-apps";
 import type { CallToolResult, ContentBlock } from "@modelcontextprotocol/server";
 import type { DisplayMode } from "../types/host-types.js";
+import type { FileMetadata } from "../types/file-types.js";
 import { type ToolContextError } from "../types/result-types.js";
 import { ModelContextStore } from "./model-context-store.js";
 import type { NormalizedViewConfig } from "./view-config.js";
@@ -64,6 +65,18 @@ export interface DisplaySnapshot {
      */
     availableDisplayModes: readonly DisplayMode[];
 }
+/**
+ * ChatGPT file-extension channel snapshot.
+ *
+ * This channel deliberately represents only the optional file APIs used by
+ * `useFiles`; the runtime does not mirror other `window.openai` globals.
+ *
+ * @internal
+ */
+export interface FilesSnapshot {
+    /** Whether both upload and temporary-download-url helpers are available. */
+    isSupported: boolean;
+}
 /**
  * Parameters for {@link McpAppRuntime.callServerTool}.
  *
@@ -109,7 +122,7 @@ export type ViewToolCallback = Parameters<App["registerTool"]>[2];
 /**
  * Per-document MCP Apps runtime: owns one guest {@link App}, one cached
  * connection attempt, tool-handler handoff, narrow external-store channels,
- * one {@link ModelContextStore}, and disposal.
+ * one shared view-state/model-context store, and disposal.
  *
  * Created by {@link createMcpAppRuntime} / {@link bootstrapView}. Hooks obtain
  * the instance from {@link ViewRuntimeContext}.
@@ -120,7 +133,7 @@ export interface McpAppRuntime {
     /** Normalized immutable view configuration fixed at construction. */
     readonly config: NormalizedViewConfig;
     /**
-     * Per-runtime model-context node tree and async flush pump.
+     * Per-runtime structured view state, model-context tree, and async flush pump.
      *
      * Constructed with this runtime and disposed with it. React components obtain
      * it via {@link useViewRuntime}; the imperative `modelContext` API delegates
@@ -157,6 +170,10 @@ export interface McpAppRuntime {
      * negotiated `availableDisplayModes` change).
      */
     getDisplaySnapshot(): DisplaySnapshot;
+    /** Subscribe to ChatGPT file-extension availability changes. */
+    subscribeFiles(listener: Listener): () => void;
+    /** Current ChatGPT file-extension snapshot. */
+    getFilesSnapshot(): FilesSnapshot;
     /** Runtime-owned guest {@link App}, or `null` after disposal. */
     getApp(): App | null;
     /** Call a server tool through the host. */
@@ -169,6 +186,12 @@ export interface McpAppRuntime {
     requestDisplayMode(params: RequestDisplayModeParams): Promise<void>;
     /** Notify the host of a size change. */
     sendSizeChanged(params: SizeChangedParams): Promise<void>;
+    /** Upload a file through ChatGPT's optional file extension. */
+    uploadFile(file: File): Promise<FileMetadata>;
+    /** Request a temporary download URL through ChatGPT's file extension. */
+    getFileDownloadUrl(file: FileMetadata): Promise<{
+        downloadUrl: string;
+    }>;
     /**
      * Register a view tool, performing the empty-handler → registry handoff on
      * the first call. Must remain synchronous relative to the handoff.
@@ -254,4 +277,3 @@ export declare function _getAppForTesting(): App | null;
 /** @internal Active runtime instance (Phase 5 runtime tests). */
 export declare function _getRuntimeForTesting(): McpAppRuntime | null;
 export {};
-//# sourceMappingURL=view-runtime.d.ts.map

package/dist/react/types/file-types.d.ts

@@ -0,0 +1,15 @@
+/** Opaque file reference returned by {@link useFiles}. */
+export type FileMetadata = {
+    fileId: string;
+};
+/** Value returned by {@link useFiles}. */
+export interface UseFilesResult {
+    /** Whether the ChatGPT file upload and download extensions are available. */
+    isSupported: boolean;
+    /** Upload a file through ChatGPT. */
+    upload(file: File): Promise<FileMetadata>;
+    /** Request a temporary download URL for an uploaded file. */
+    getDownloadUrl(file: FileMetadata): Promise<{
+        downloadUrl: string;
+    }>;
+}

package/dist/react/types/host-types.d.ts

@@ -22,4 +22,3 @@ export type HostContext = McpUiHostContext;
  * How the host surfaces the view iframe.
  */
 export type DisplayMode = "inline" | "fullscreen" | "pip";
-//# sourceMappingURL=host-types.d.ts.map

package/dist/react/types/register.d.ts

@@ -1,10 +1,10 @@
 import type { ToolRef } from "../../tools.js";
-/** Augmented by the project's `register.d.ts`; empty by default. */
+/** Augmented by the project's `mcp-env.d.ts`; empty by default. */
 export interface Register {
 }
 type RegisteredToolsModule = Register extends {
     tools: infer M;
-} ? M : Record<never, never>;
+} ? M : undefined;
 type ToolsFromModule<M> = {
     [K in keyof M as M[K] extends ToolRef<infer N, any, any> ? N : never]: M[K] extends ToolRef<any, infer I, infer O> ? {
         input: I;
@@ -14,8 +14,16 @@ type ToolsFromModule<M> = {
 /**
  * Map of registered tool names to their inferred input/output types, derived
  * from exported {@link ToolRef} values in the augmented {@link Register} module.
+ *
+ * Projects without an `mcp-env.d.ts` registration retain a loose string map so
+ * existing non-scaffolded applications keep compiling. Once the module is
+ * registered, only exported tool refs are accepted by typed React hooks; an
+ * empty registered module therefore exposes no tool names.
  */
-export type RegisteredTools = ToolsFromModule<RegisteredToolsModule>;
+export type RegisteredTools = RegisteredToolsModule extends undefined ? Record<string, {
+    input: Record<string, unknown>;
+    output: unknown;
+}> : ToolsFromModule<RegisteredToolsModule>;
 /**
  * Recursive partial for streamed JSON: every field optional at every depth.
  *
@@ -26,4 +34,3 @@ export type DeepPartial<T> = T extends (infer E)[] ? DeepPartial<E>[] : T extend
     [K in keyof T]?: DeepPartial<T[K]>;
 } : T;
 export {};
-//# sourceMappingURL=register.d.ts.map

package/dist/react/types/result-types.d.ts

@@ -62,4 +62,3 @@ export type CallToolSuccess<Result> = CallToolResult & {
 } & ([Result] extends [never] ? unknown : {
     structuredContent: Result;
 });
-//# sourceMappingURL=result-types.d.ts.map

package/dist/resource-completion.d.ts

@@ -0,0 +1,11 @@
+import type { CompleteResourceTemplateCallback } from "@modelcontextprotocol/server";
+import type { ResourceTemplateCompleter } from "./resources.js";
+/**
+ * Convert public static and callback completions to the SDK callback map.
+ *
+ * @param completions - Public completion providers keyed by template variable.
+ * @returns The callback-only map required by the official SDK.
+ *
+ * @internal
+ */
+export declare function normalizeCompletions(completions: Readonly<Record<string, ResourceTemplateCompleter | undefined>>): Record<string, CompleteResourceTemplateCallback>;

package/dist/resources.d.ts

@@ -1,4 +1,5 @@
-import type { ReadResourceResult } from "@modelcontextprotocol/server";
+import type { Annotations, CallToolResult, CompleteResourceTemplateCallback, MetaObject, ReadResourceResult } from "@modelcontextprotocol/server";
+import type { Env } from "hono";
 import type { RequestContext } from "./context.js";
 /** Declares a static resource at a fixed URI. First argument to {@link MCPServer.resource}. */
 export interface ResourceDefinition {
@@ -15,11 +16,24 @@ export interface ResourceDefinition {
      * own `mimeType` on the wire — set it in the callback's result.
      */
     mimeType?: string;
+    /** Standard MCP hints describing the resource's audience and presentation. */
+    annotations?: Annotations;
+    /**
+     * Extension metadata advertised on this resource's `resources/list`
+     * descriptor. Use vendor-namespaced keys for custom data.
+     *
+     * This value is not copied into `resources/read` content entries; content
+     * metadata must be returned by the callback on each entry's own `_meta`.
+     */
+    _meta?: MetaObject;
 }
 /**
- * Resource read callback. Returns the SDK's raw {@link ReadResourceResult};
+ * Resource read callback. Prefer the SDK's raw {@link ReadResourceResult};
  * each `contents` entry addresses itself with the read `uri`.
  *
+ * Deprecated response helpers that return a {@link CallToolResult} are still
+ * accepted and converted at registration time.
+ *
  * @example
  * ```ts
  * async (uri) => ({
@@ -27,19 +41,64 @@ export interface ResourceDefinition {
  * })
  * ```
  */
-export type ResourceCallback<TUser = never, HasOAuth extends boolean = false> = (uri: URL, ctx: RequestContext<TUser, HasOAuth>) => ReadResourceResult | Promise<ReadResourceResult>;
-/** Declares a parameterized resource matched by URI template. First argument to {@link MCPServer.resourceTemplate}. */
-export interface ResourceTemplateDefinition {
+export type ResourceCallback<TUser = never, HasOAuth extends boolean = false, TEnv extends Env = Env> = (uri: URL, ctx: RequestContext<TUser, HasOAuth, TEnv>) => ReadResourceResult | CallToolResult | Promise<ReadResourceResult | CallToolResult>;
+/**
+ * A resource-template variable completer accepted by
+ * {@link MCPServer.resourceTemplate}.
+ *
+ * Static values are matched case-insensitively against the beginning of the
+ * current value. Callback completions use the official SDK callback shape and
+ * may inspect the other resolved string arguments in its optional context.
+ * The SDK limits wire results to 100 values and derives `total` and `hasMore`
+ * from the returned array.
+ */
+export type ResourceTemplateCompleter = readonly string[] | CompleteResourceTemplateCallback;
+/**
+ * Per-variable completion map inferred from an RFC 6570 URI template.
+ *
+ * Literal templates accept only variables declared by the template. A
+ * widened `string` template accepts arbitrary string keys because its
+ * variables cannot be known at compile time.
+ *
+ * @typeParam TUriTemplate - URI template whose variables become map keys.
+ */
+export type ResourceTemplateCompletions<TUriTemplate extends string> = string extends TUriTemplate ? Partial<Record<string, ResourceTemplateCompleter>> : Partial<Record<ExtractTemplateVariables<TUriTemplate>, ResourceTemplateCompleter>>;
+/**
+ * Declares a parameterized resource matched by URI template.
+ *
+ * @typeParam TUriTemplate - Literal URI template used to infer read variables
+ * and completion keys.
+ */
+export interface ResourceTemplateDefinition<TUriTemplate extends string = string> {
     /** Template display name. */
     name: string;
     /** RFC 6570 URI template with variables, e.g. `"db://users/{id}"`. */
-    uriTemplate: string;
+    uriTemplate: TUriTemplate;
     /** Human-readable title (falls back to `name`). */
     title?: string;
     /** Human-readable description. */
     description?: string;
     /** MIME type of the content. */
     mimeType?: string;
+    /** Standard MCP hints describing resources produced by this template. */
+    annotations?: Annotations;
+    /**
+     * Extension metadata advertised on this template's
+     * `resources/templates/list` descriptor. Use vendor-namespaced keys for
+     * custom data.
+     *
+     * This value is not copied into `resources/read` content entries; content
+     * metadata must be returned by the callback on each entry's own `_meta`.
+     */
+    _meta?: MetaObject;
+    /**
+     * Optional completion providers keyed by URI-template variable.
+     *
+     * Static arrays use case-insensitive prefix matching. Dynamic callbacks may
+     * be synchronous or asynchronous and receive the current value plus the
+     * official completion context containing already-resolved arguments.
+     */
+    complete?: ResourceTemplateCompletions<TUriTemplate>;
 }
 /** Strip a leading RFC 6570 operator (`+`, `#`, `.`, `/`, `;`, `?`, `&`) from a template expression. */
 type StripOperator<E extends string> = E extends `${"+" | "#" | "." | "/" | ";" | "?" | "&"}${infer Rest}` ? Rest : E;
@@ -60,7 +119,11 @@ export type InferTemplateParams<T> = T extends {
 } ? string extends U ? Record<string, TemplateVariableValue> : {
     [K in ExtractTemplateVariables<U>]: TemplateVariableValue;
 } : Record<string, TemplateVariableValue>;
-/** Resource template read callback; receives the matched URI and variables. */
-export type ResourceTemplateCallback<TParams = Record<string, TemplateVariableValue>, TUser = never, HasOAuth extends boolean = false> = (uri: URL, params: TParams, ctx: RequestContext<TUser, HasOAuth>) => ReadResourceResult | Promise<ReadResourceResult>;
+/**
+ * Resource template read callback; receives the matched URI and variables.
+ *
+ * Prefer {@link ReadResourceResult}. Deprecated helper-shaped
+ * {@link CallToolResult} returns are still accepted and converted.
+ */
+export type ResourceTemplateCallback<TParams = Record<string, TemplateVariableValue>, TUser = never, HasOAuth extends boolean = false, TEnv extends Env = Env> = (uri: URL, params: TParams, ctx: RequestContext<TUser, HasOAuth, TEnv>) => ReadResourceResult | CallToolResult | Promise<ReadResourceResult | CallToolResult>;
 export {};
-//# sourceMappingURL=resources.d.ts.map

package/dist/response-conversion.d.ts

@@ -0,0 +1,25 @@
+import type { CallToolResult, GetPromptResult, ReadResourceResult } from "@modelcontextprotocol/server";
+/**
+ * Convert a helper/`CallToolResult` (or pass through a raw resource result) to
+ * {@link ReadResourceResult}.
+ *
+ * Maps official {@link ContentBlock}s: `text` → text contents, `image`/`audio`
+ * `data` → `blob`, embedded `resource` → unwrap, `resource_link` skipped.
+ * Empty `content` with `structuredContent` becomes a JSON text entry.
+ *
+ * @param result - Tool-shaped or resource result from a resource callback.
+ * @param uri - URI of the resource being read (used for synthesized entries).
+ * @returns Official resource read envelope.
+ */
+export declare function toResourceResult(result: CallToolResult | ReadResourceResult, uri: string): ReadResourceResult;
+/**
+ * Convert a helper/`CallToolResult` (or pass through a raw prompt result) to
+ * {@link GetPromptResult}.
+ *
+ * Each tool {@link ContentBlock} becomes a `user` {@link PromptMessage}
+ * (prompt messages already accept the same content-block union).
+ *
+ * @param result - Tool-shaped or prompt result from a prompt callback.
+ * @returns Official prompt get envelope.
+ */
+export declare function toPromptResult(result: CallToolResult | GetPromptResult): GetPromptResult;

package/dist/response-helpers.d.ts

@@ -0,0 +1,223 @@
+import type { CallToolResult } from "@modelcontextprotocol/server";
+/**
+ * Typed {@link CallToolResult} that constrains `structuredContent` to `T`.
+ *
+ * @deprecated Prefer returning a raw {@link CallToolResult} from tool
+ * callbacks. Example: `{ content: [{ type: "text", text: JSON.stringify(data) }], structuredContent: data }`.
+ *
+ * @typeParam T - Structured payload type (typically an object).
+ */
+export interface TypedCallToolResult<T extends Record<string, unknown> = Record<string, unknown>> {
+    [x: string]: unknown;
+    content: CallToolResult["content"];
+    isError?: CallToolResult["isError"];
+    _meta?: CallToolResult["_meta"];
+    structuredContent?: T;
+}
+/**
+ * Content-only tool result (`structuredContent` pinned to `never`).
+ *
+ * @deprecated Prefer returning a raw {@link CallToolResult}:
+ * `{ content: [{ type: "text", text }] }`.
+ */
+export interface ToolContentResult {
+    [x: string]: unknown;
+    content: CallToolResult["content"];
+    isError?: CallToolResult["isError"];
+    _meta?: CallToolResult["_meta"];
+    structuredContent?: never;
+}
+/**
+ * Create a plain-text tool result.
+ *
+ * @deprecated Prefer `{ content: [{ type: "text", text: content }] }`.
+ *
+ * @param content - Text to return.
+ * @returns Tool result with a single text content block.
+ *
+ * @example
+ * ```ts
+ * // Preferred:
+ * return { content: [{ type: "text", text: `Hello, ${name}!` }] };
+ * // Deprecated:
+ * return text(`Hello, ${name}!`);
+ * ```
+ */
+export declare function text(content: string): ToolContentResult;
+/**
+ * Create a Markdown text tool result.
+ *
+ * @deprecated Prefer `{ content: [{ type: "text", text: content }] }`.
+ *
+ * @param content - Markdown text.
+ * @returns Tool result with `text/markdown` MIME metadata.
+ */
+export declare function markdown(content: string): ToolContentResult;
+/**
+ * Create an HTML text tool result.
+ *
+ * @deprecated Prefer `{ content: [{ type: "text", text: content }] }`.
+ *
+ * @param content - HTML text.
+ * @returns Tool result with `text/html` MIME metadata.
+ */
+export declare function html(content: string): ToolContentResult;
+/**
+ * Create an XML text tool result.
+ *
+ * @deprecated Prefer `{ content: [{ type: "text", text: content }] }`.
+ *
+ * @param content - XML text.
+ * @returns Tool result with `text/xml` MIME metadata.
+ */
+export declare function xml(content: string): ToolContentResult;
+/**
+ * Create a CSS text tool result.
+ *
+ * @deprecated Prefer `{ content: [{ type: "text", text: content }] }`.
+ *
+ * @param content - CSS text.
+ * @returns Tool result with `text/css` MIME metadata.
+ */
+export declare function css(content: string): ToolContentResult;
+/**
+ * Create a JavaScript text tool result.
+ *
+ * @deprecated Prefer `{ content: [{ type: "text", text: content }] }`.
+ *
+ * @param content - JavaScript source text.
+ * @returns Tool result with `text/javascript` MIME metadata.
+ */
+export declare function javascript(content: string): ToolContentResult;
+/**
+ * Create an image content tool result.
+ *
+ * @deprecated Prefer
+ * `{ content: [{ type: "image", data, mimeType }] }`.
+ *
+ * @param data - Base64 image data (or data URL payload).
+ * @param mimeType - Image MIME type.
+ * @returns Tool result with an image content block.
+ *
+ * @defaultValue mimeType - `"image/png"`
+ */
+export declare function image(data: string, mimeType?: string): ToolContentResult;
+/**
+ * Create an audio content tool result from base64 data.
+ *
+ * @deprecated Prefer
+ * `{ content: [{ type: "audio", data, mimeType }] }`.
+ *
+ * @param data - Base64-encoded audio.
+ * @param mimeType - Audio MIME type.
+ * @returns Tool result with an audio content block.
+ *
+ * @defaultValue mimeType - `"audio/wav"`
+ */
+export declare function audio(data: string, mimeType?: string): ToolContentResult;
+/**
+ * Create a binary payload carried as base64 text.
+ *
+ * @deprecated Prefer a raw {@link CallToolResult} with an appropriate content
+ * block, or a resource `{ contents: [{ uri, mimeType, blob }] }`.
+ *
+ * @param base64Data - Base64-encoded bytes.
+ * @param mimeType - MIME type of the binary payload.
+ * @returns Tool result with base64 text and binary MIME metadata.
+ */
+export declare function binary(base64Data: string, mimeType: string): ToolContentResult;
+/**
+ * Create an embedded-resource content block for a tool result.
+ *
+ * Supports `resource(uri, mimeType, text?)` or `resource(uri, callToolResult)`.
+ *
+ * @deprecated Prefer
+ * `{ content: [{ type: "resource", resource: { uri, mimeType, text } }] }`.
+ *
+ * @param uri - Resource URI.
+ * @param mimeTypeOrContent - MIME type string, or a helper/`CallToolResult` to extract from.
+ * @param text - Optional text body (3-arg form).
+ * @returns Tool result with an embedded resource content block.
+ */
+export declare function resource(uri: string, mimeTypeOrContent: string | CallToolResult | TypedCallToolResult, text?: string): ToolContentResult;
+/**
+ * Create a failed tool result.
+ *
+ * @deprecated Prefer
+ * `{ isError: true, content: [{ type: "text", text: message }] }`.
+ *
+ * @param message - Error message shown to the model.
+ * @returns Tool result with `isError: true`.
+ */
+export declare function error(message: string): TypedCallToolResult<never>;
+/**
+ * Create a structured JSON object tool result.
+ *
+ * @deprecated Prefer
+ * `{ content: [{ type: "text", text: JSON.stringify(data) }], structuredContent: data }`.
+ *
+ * @typeParam T - Object payload type.
+ * @param data - Object (or array — forwarded to {@link array}) to return.
+ * @returns Tool result with JSON text and `structuredContent`.
+ */
+export declare function object<T extends Record<string, unknown>>(data: T): TypedCallToolResult<T>;
+/**
+ * Create a structured array tool result (2026 any-JSON root — no `{ data }` wrap).
+ *
+ * @deprecated Prefer
+ * `{ content: [{ type: "text", text: JSON.stringify(data) }], structuredContent: data }`
+ * or `{ content: [], structuredContent: data }` (SDK may auto-append JSON text for
+ * non-object roots).
+ *
+ * @typeParam T - Array payload type.
+ * @param data - Array to return as `structuredContent`.
+ * @returns Tool result with JSON text and the array as `structuredContent`.
+ */
+export declare function array<T extends unknown[]>(data: T): CallToolResult;
+/**
+ * Runtime data for a view-bound tool result (legacy widget helper).
+ *
+ * @deprecated Prefer returning a plain {@link CallToolResult} from a tool
+ * registered with `view: { name }`. Put view props in `structuredContent` and
+ * model-facing text in `content`.
+ *
+ * @typeParam TProps - Props object placed in `structuredContent`.
+ */
+export interface WidgetResponseConfig<TProps extends Record<string, unknown> = Record<string, unknown>> {
+    /** View-facing data sent as `structuredContent`. */
+    props?: TProps;
+    /**
+     * Legacy alias for {@link WidgetResponseConfig.props}.
+     *
+     * @deprecated Use `props` instead.
+     */
+    data?: TProps;
+    /** Model-facing helper/`CallToolResult` whose `content` is forwarded. */
+    output?: CallToolResult | TypedCallToolResult;
+    /** Extra result `_meta` for the view. */
+    metadata?: Record<string, unknown>;
+    /** Override text when `output` is omitted or should be replaced. */
+    message?: string;
+}
+/**
+ * Create a view/widget tool result (`props` → `structuredContent`).
+ *
+ * @deprecated Prefer a plain {@link CallToolResult} with `view:` on the tool
+ * definition:
+ * `{ content: [{ type: "text", text }], structuredContent: props }`.
+ *
+ * @typeParam TProps - Props object type.
+ * @param config - Runtime view data.
+ * @returns Tool result with props in `structuredContent`.
+ */
+export declare function widget<TProps extends Record<string, unknown> = Record<string, unknown>>(config: WidgetResponseConfig<TProps>): TypedCallToolResult<TProps>;
+/**
+ * Merge several tool results into one (`content` concatenated; objects shallow-merged).
+ *
+ * @deprecated Prefer building a single raw {@link CallToolResult} with the
+ * desired `content` array.
+ *
+ * @param results - Results to merge.
+ * @returns Combined tool result.
+ */
+export declare function mix(...results: CallToolResult[]): CallToolResult;