@tanstack/ai 0.37.0 → 0.38.0

package/src/activities/chat/tools/tool-calls.ts

@@ -18,6 +18,7 @@ import type {
   AfterToolCallInfo,
   BeforeToolCallDecision,
 } from '../middleware/types'
+import type { McpResourceReadResult } from '../mcp/types'
 import type {
   ContextFromTool,
   DefinedContext,
@@ -33,6 +34,92 @@ function safeJsonParse(value: string): unknown {
   }
 }
 
+/**
+ * MCP Apps metadata attached to a server tool at discovery (see
+ * `@tanstack/ai-mcp` discovery + `MCPManager.discover()`).
+ *
+ * - `uiResourceUri` / `serverId` are stamped by ai-mcp at tool discovery.
+ * - `readResource` is bound by `MCPManager.discover()` (the one site that has
+ *   both the tool and its originating source) so the resource can be eagerly
+ *   read at the emit site. Under `chat()`-managed MCP lifecycle
+ *   (`connection:'close'`), the MCP source is not disposed until the run
+ *   drains, so `readResource` is still live at this emit point. Note: a caller
+ *   who closes the MCP source early (outside `chat()`'s managed lifecycle)
+ *   degrades fail-soft — `readResource` may reject, the widget is absent, but
+ *   the tool result still flows to the model.
+ *   `@tanstack/ai` never imports `@tanstack/ai-mcp`; this travels structurally
+ *   on the tool.
+ */
+interface McpToolAppMeta {
+  uiResourceUri?: string
+  serverId?: string
+  /** Server-native (unprefixed) MCP tool name — used as the renderer's toolName. */
+  serverToolName?: string
+  readResource?: (uri: string) => Promise<McpResourceReadResult>
+}
+
+function readMcpAppMeta(tool: AnyTool): McpToolAppMeta | undefined {
+  const meta = (tool.metadata as { mcp?: McpToolAppMeta } | undefined)?.mcp
+  return meta
+}
+
+/**
+ * Eagerly read a tool's linked `ui://` resource (MCP Apps) and emit a
+ * `ui-resource` CUSTOM event so the client can render the widget. The model
+ * still receives the normal text tool-result; the widget rides alongside and
+ * never enters model input.
+ *
+ * Fail-soft: any read error logs a warning and emits nothing — it never throws,
+ * so the normal tool-result still flows and a broken widget cannot break the run.
+ */
+async function emitUiResourceIfLinked<TContext>(
+  tool: AnyTool,
+  context: ToolExecutionContext<TContext>,
+): Promise<void> {
+  const mcp = readMcpAppMeta(tool)
+  const uiUri = mcp?.uiResourceUri
+  if (!uiUri || !mcp.readResource) return
+
+  // The try covers ONLY the fallible read — keep `emitCustomEvent` out of it so
+  // an exception from the emit path can't be mislabeled as a read failure.
+  let matched: McpResourceReadResult['contents'][number] | undefined
+  try {
+    const res = await mcp.readResource(uiUri)
+    // Emit ONLY the content whose uri matches the requested `uiUri`. A source
+    // can return unrelated contents; falling back to `contents[0]` would risk
+    // rendering a widget that doesn't correspond to the linked resource. This
+    // is a display widget — a mismatched resource is worse than none, so if no
+    // content matches we fail-soft (warn + return) rather than emit.
+    matched = res.contents.find((c) => c.uri === uiUri)
+  } catch (err) {
+    // fail-soft — the text tool-result already flows; a broken widget must
+    // not break the run.
+    console.warn(`[mcp-apps] failed to read ui resource ${uiUri}:`, err)
+    return
+  }
+  if (!matched) {
+    console.warn(
+      `[mcp-apps] ui resource ${uiUri} returned no content matching that uri; not emitting`,
+    )
+    return
+  }
+  // NOTE: `toolCallId` is intentionally NOT set here — it is stamped onto
+  // every emitted event by the `executeToolCalls` context wrapper, so the
+  // UIResourceEvent.value.toolCallId / UIResourcePart.toolCallId contract is
+  // still satisfied downstream.
+  context.emitCustomEvent('ui-resource', {
+    resource: {
+      uri: matched.uri,
+      mimeType: matched.mimeType ?? 'text/html',
+      text: matched.text,
+      blob: matched.blob,
+    },
+    serverId: mcp.serverId,
+    toolName: mcp.serverToolName ?? tool.name,
+    meta: undefined,
+  })
+}
+
 /**
  * Optional middleware hooks for tool execution.
  * When provided, these callbacks are invoked before/after each tool execution.
@@ -456,7 +543,7 @@ async function applyBeforeToolCallDecision(
  * Execute a server-side tool with event polling, output validation, and middleware hooks.
  * Yields CustomEvent chunks during execution and pushes the result to the results array.
  */
-async function* executeServerTool<TContext = unknown>(
+export async function* executeServerTool<TContext = unknown>(
   toolCall: ToolCall,
   tool: AnyTool,
   toolName: string,
@@ -475,7 +562,14 @@ async function* executeServerTool<TContext = unknown>(
     let result = yield* executeWithEventPolling(executionPromise, pendingEvents)
     const duration = Date.now() - startTime
 
-    // Flush remaining events
+    // MCP Apps: if this tool links a ui:// resource, eagerly read it and queue
+    // a `ui-resource` CUSTOM event. The MCP source stays live until the run
+    // drains (MCPManager's `connection:'close'` policy disposes on completion),
+    // so `readResource` is callable here. Fail-soft: a read error warns and
+    // emits nothing — the text result still flows.
+    await emitUiResourceIfLinked(tool, context)
+
+    // Flush remaining events (including any queued ui-resource event)
     let pendingEvent: CustomEvent | undefined
     while ((pendingEvent = pendingEvents.shift()) !== undefined) {
       yield pendingEvent

package/src/client.ts

@@ -114,6 +114,7 @@ export type {
   ToolCallPart,
   ToolResultPart,
   UIMessage,
+  UIResourcePart,
   VideoPart,
   InferSchemaType,
 } from './types'

package/src/types.ts

@@ -416,6 +416,23 @@ export interface StructuredOutputPart<TData = unknown> {
   errorMessage?: string
 }
 
+export interface UIResourcePart {
+  type: 'ui-resource'
+  /** The ui:// resource object in MCP-native shape — fed straight to the renderer. */
+  resource: { uri: string; mimeType: string; text?: string; blob?: string }
+  /** Pool prefix / config key — routes interactive calls to the right MCP server. */
+  serverId?: string
+  /** Links the widget to the originating tool call — correlates it with the
+   *  sibling ToolCallPart/ToolResultPart in the same message. */
+  toolCallId: string
+  /** Server-native (unprefixed) MCP tool name whose UI this resource renders.
+   *  Required by the renderer (`@mcp-ui/client`'s `AppRenderer` `toolName` prop). */
+  toolName: string
+  /** Reserved for future passthrough of the resource/tool `_meta.ui` (e.g. frame-size hints).
+   *  Currently always `undefined` — nothing populates this field yet. */
+  meta?: Record<string, unknown>
+}
+
 export type MessagePart<TData = unknown> =
   | TextPart
   | ImagePart
@@ -426,6 +443,7 @@ export type MessagePart<TData = unknown> =
   | ToolResultPart
   | ThinkingPart
   | StructuredOutputPart<TData>
+  | UIResourcePart
 
 /**
  * UIMessage - Domain-specific message format optimized for building chat UIs
@@ -1308,6 +1326,19 @@ export interface ToolInputAvailableEvent extends CustomEvent {
   }
 }
 
+/** Emitted when an MCP tool returns a ui:// resource (MCP Apps). Reconciled into
+ *  a UIResourcePart on the assistant UIMessage. Never enters model input. */
+export interface UIResourceEvent extends CustomEvent {
+  name: 'ui-resource'
+  value: {
+    resource: UIResourcePart['resource']
+    serverId?: string
+    toolCallId: string
+    toolName: string
+    meta?: Record<string, unknown>
+  }
+}
+
 /**
  * Public type for streams returned by `chat({ outputSchema, stream: true })`.
  *