@assistant-ui/mcp-docs-server 0.1.22 → 0.1.23

package/.docs/raw/docs/(reference)/api-reference/primitives/message-part.mdx

@@ -11,7 +11,7 @@ import {
 } from "@/generated/typeDocs";
 
 Each message can have any number of message parts.
-Message parts are usually one of text, reasoning, audio or tool-call.
+Message parts are usually one of text, reasoning, audio, tool-call, or data.
 
 ## Message part Types
 
@@ -31,6 +31,12 @@ Audio content that can be played back.
 
 Interactive elements that represent tool operations.
 
+### Data
+
+Custom data events that can be rendered as UI at their position in the message stream. Each data part has a `name` and a `data` payload.
+
+You can use either the explicit format `{ type: "data", name: "workflow", data: {...} }` or the shorthand `data-*` prefixed format `{ type: "data-workflow", data: {...} }`. The prefixed format is automatically converted to a `DataMessagePart` (stripping the `data-` prefix as the `name`). Unknown message part types that don't match any built-in type are silently skipped with a console warning.
+
 ## Anatomy
 
 ```tsx
@@ -46,7 +52,7 @@ const TextMessagePart = () => {
 ### Plain Text
 
 ```tsx
-import { MessagePartPrimitive } from "@assistant/react";
+import { MessagePartPrimitive } from "@assistant-ui/react";
 
 <MessagePartPrimitive.Text />;
 ```
@@ -70,7 +76,7 @@ Coming soon.
 Renders children only if the message part is in progress.
 
 ```tsx
-import { MessagePartPrimitive } from "@assistant/react";
+import { MessagePartPrimitive } from "@assistant-ui/react";
 
 <MessagePartPrimitive.InProgress>
   <LoadingIndicator />
@@ -101,6 +107,68 @@ const MyWeatherToolUI = makeAssistantToolUI({
 });
 ```
 
+### Data UI
+
+You can map data events to UI components, similar to tool UIs. There are two approaches:
+
+#### Inline configuration
+
+Pass a `data` config to `MessagePrimitive.Parts`:
+
+```tsx
+<MessagePrimitive.Parts
+  components={{
+    data: {
+      by_name: {
+        my_chart: ({ name, data }) => <ChartComponent data={data} />,
+      },
+      Fallback: ({ name, data }) => (
+        <pre>{JSON.stringify(data, null, 2)}</pre>
+      ),
+    },
+  }}
+/>
+```
+
+#### Global registration
+
+Use `makeAssistantDataUI` or `useAssistantDataUI` to register data UIs globally. Global registrations take priority over inline configuration.
+
+```tsx
+import { makeAssistantDataUI } from "@assistant-ui/react";
+
+const MyChartUI = makeAssistantDataUI({
+  name: "my_chart",
+  render: ({ name, data }) => <ChartComponent data={data} />,
+});
+
+// Place inside AssistantRuntimeProvider
+function App() {
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+      <MyChartUI />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+The hook variant allows access to component state:
+
+```tsx
+import { useAssistantDataUI } from "@assistant-ui/react";
+
+function MyComponent() {
+  useAssistantDataUI({
+    name: "my_chart",
+    render: ({ name, data }) => <ChartComponent data={data} />,
+  });
+  return null;
+}
+```
+
+Each data component receives the full data part as props: `{ type: "data", name: string, data: T, status: MessagePartStatus }`.
+
 ## Context Provider
 
 Message part context is provided by `MessagePrimitive.Parts` or `TextMessagePartProvider`
@@ -108,7 +176,7 @@ Message part context is provided by `MessagePrimitive.Parts` or `TextMessagePart
 ### MessagePrimitive.Parts
 
 ```tsx
-import { MessagePrimitive } from "@assistant/react";
+import { MessagePrimitive } from "@assistant-ui/react";
 
 <MessagePrimitive.Parts
   components={{
@@ -121,6 +189,12 @@ import { MessagePrimitive } from "@assistant/react";
       },
       Fallback: MyFallbackToolUI,
     },
+    data: {
+      by_name: {
+        my_chart: MyChartComponent,
+      },
+      Fallback: GenericDataComponent,
+    },
   }}
 />;
 ```

package/.docs/raw/docs/(reference)/api-reference/primitives/message.mdx

@@ -259,6 +259,38 @@ Renders a single attachment at the specified index within the message.
   ]}
 />
 
+### useMessageQuote()
+
+A hook that returns the quote info attached to the current message, if any. Reads from `message.metadata.custom.quote`.
+
+```tsx
+import { useMessageQuote } from "@assistant-ui/react";
+
+const QuoteBlock = () => {
+  const quote = useMessageQuote();
+  if (!quote) return null;
+
+  return (
+    <div className="mb-2 flex items-start gap-1.5 text-sm italic text-muted-foreground">
+      {quote.text}
+    </div>
+  );
+};
+```
+
+**Returns:** `QuoteInfo | undefined`
+
+```typescript
+type QuoteInfo = {
+  readonly text: string;       // the quoted plain text
+  readonly messageId: string;  // the source message ID
+};
+```
+
+<Callout type="info">
+See the [Quoting guide](/docs/guides/quoting) for a complete walkthrough.
+</Callout>
+
 ### Error
 
 Renders children only if the message has an error status.

package/.docs/raw/docs/(reference)/api-reference/primitives/selection-toolbar.mdx

@@ -0,0 +1,61 @@
+---
+title: SelectionToolbarPrimitive
+description: A floating toolbar that appears when text is selected within a message.
+---
+
+A floating toolbar that appears near the user's text selection within a message. Used to provide contextual actions like quoting selected text.
+
+## Anatomy
+
+```tsx
+import { SelectionToolbarPrimitive } from "@assistant-ui/react";
+
+const FloatingSelectionToolbar = () => (
+  <SelectionToolbarPrimitive.Root>
+    <SelectionToolbarPrimitive.Quote>Quote</SelectionToolbarPrimitive.Quote>
+  </SelectionToolbarPrimitive.Root>
+);
+```
+
+Place this component inside `ThreadPrimitive.Root`:
+
+```tsx
+<ThreadPrimitive.Root>
+  <ThreadPrimitive.Viewport>...</ThreadPrimitive.Viewport>
+  <FloatingSelectionToolbar />
+</ThreadPrimitive.Root>
+```
+
+## API Reference
+
+### Root
+
+A floating container that renders as a portal positioned above the text selection. Only renders when there is a valid text selection within a single message.
+
+This primitive renders a `<div>` element.
+
+**Behavior:**
+
+- Listens for `mouseup` and `keyup` events to detect completed selections
+- Validates the selection is within a single message using `data-message-id` attributes
+- Renders a portal with `position: fixed`, centered above the selection
+- Prevents `mousedown` from clearing the text selection when clicking the toolbar
+- Hides automatically on scroll or when the selection is cleared
+- Cross-message selections are ignored
+
+### Quote
+
+A button that captures the currently selected text and sets it as a quote in the thread composer.
+
+This primitive renders a `<button>` element.
+
+**Behavior:**
+
+- Reads selection info from the Root context (not `window.getSelection()`)
+- Calls `composer.setQuote({ text, messageId })` on the thread composer
+- Clears the text selection after quoting
+- Disabled when no selection info is available
+
+<Callout type="info">
+See the [Quoting guide](/docs/guides/quoting) for a complete walkthrough including composer preview, sent message display, and backend handling.
+</Callout>

package/.docs/raw/docs/(reference)/api-reference/primitives/thread.mdx

@@ -14,7 +14,7 @@ import { ThreadPrimitive } from "@assistant-ui/react";
 const Thread = () => (
   <ThreadPrimitive.Root>
     <ThreadPrimitive.Viewport>
-      <ThreadPrimitive.Empty>...</ThreadPrimitive.Empty>
+      <AuiIf condition={(s) => s.thread.isEmpty}>...</AuiIf>
       <ThreadPrimitive.Messages components={...} />
     </ThreadPrimitive.Viewport>
     <Composer />

package/.docs/raw/docs/(reference)/legacy/styled/assistant-modal.mdx

@@ -24,7 +24,7 @@ A chat bubble shown in the bottom right corner of the screen. Useful for support
 
 Add the following to your `tailwind.config.ts`:
 
-<Tabs items={["Tailwind", "Tailwind + shadcn-ui", "Not using Tailwind"]}>
+<Tabs items={["Tailwind", "Tailwind + shadcn-ui"]}>
 
 ```ts title="/tailwind.config.ts" tab="Tailwind"
 {
@@ -49,11 +49,6 @@ Add the following to your `tailwind.config.ts`:
 }
 ```
 
-```ts title="/app/layout.tsx" tab="Not using Tailwind"
-import "@assistant-ui/react-ui/styles/index.css";
-import "@assistant-ui/react-ui/styles/modal.css";
-```
-
 </Tabs>
 
   </Step>

package/.docs/raw/docs/(reference)/legacy/styled/decomposition.mdx

@@ -181,10 +181,10 @@ import { AuiIf } from "@assistant-ui/react";
 const MyComposerAction: FC = () => {
   return (
     <>
-      <AuiIf condition={({ thread }) => !thread.isRunning}>
+      <AuiIf condition={(s) => !s.thread.isRunning}>
         <Composer.Send />
       </AuiIf>
-      <AuiIf condition={({ thread }) => thread.isRunning}>
+      <AuiIf condition={(s) => s.thread.isRunning}>
         <Composer.Cancel />
       </AuiIf>
     </>

package/.docs/raw/docs/(reference)/legacy/styled/markdown.mdx

@@ -20,7 +20,7 @@ Allow the assistant to display rich text using markdown.
 
 ### Setup styles
 
-<Tabs items={["Tailwind", "Tailwind + shadcn-ui", "Not using Tailwind"]}>
+<Tabs items={["Tailwind", "Tailwind + shadcn-ui"]}>
 
 ```ts {3} title="/tailwind.config.ts" tab="Tailwind"
 {
@@ -40,11 +40,6 @@ Allow the assistant to display rich text using markdown.
 }
 ```
 
-```ts title="/app/layout.tsx" tab="Not using Tailwind"
-import "@assistant-ui/react-ui/styles/index.css";
-import "@assistant-ui/react-ui/styles/markdown.css";
-```
-
 </Tabs>
 
 </Step>

package/.docs/raw/docs/(reference)/legacy/styled/thread.mdx

@@ -24,7 +24,7 @@ The raw message list and message composer UI. Useful for full screen chat use ca
 
 Add the following to your `tailwind.config.ts`:
 
-<Tabs items={["Tailwind", "Tailwind + shadcn-ui", "Not using Tailwind"]}>
+<Tabs items={["Tailwind", "Tailwind + shadcn-ui"]}>
 
 ```ts title="/tailwind.config.ts" tab="Tailwind"
 {
@@ -49,10 +49,6 @@ Add the following to your `tailwind.config.ts`:
 }
 ```
 
-```ts title="/app/layout.tsx" tab="Not using Tailwind"
-import "@assistant-ui/react-ui/styles/index.css";
-```
-
 </Tabs>
 
   </Step>

package/.docs/raw/docs/(reference)/migrations/v0-12.mdx

@@ -63,7 +63,7 @@ import { useAui, useAuiState, useAuiEvent } from "@assistant-ui/react";
 
 function MyComponent() {
   const aui = useAui();
-  const isRunning = useAuiState(({ thread }) => thread.isRunning);
+  const isRunning = useAuiState((s) => s.thread.isRunning);
 
   useAuiEvent("thread.started", () => {
     console.log("Thread started");
@@ -116,30 +116,30 @@ The following hooks have been removed:
 
 **Removed Hooks:**
 
-- `useMessageUtils` → Use `useAuiState(({ message }) => message.isHovering)` / `useAuiState(({ message }) => message.isCopied)`
+- `useMessageUtils` → Use `useAuiState((s) => s.message.isHovering)` / `useAuiState((s) => s.message.isCopied)`
 - `useMessageUtilsStore` → Use `useAui()` with `aui.message().setIsHovering()` / `aui.message().setIsCopied()`
-- `useToolUIs` → Use `useAuiState(({ tools }) => tools)` and `useAui()` with `aui.tools()`
+- `useToolUIs` → Use `useAuiState((s) => s.tools)` and `useAui()` with `aui.tools()`
 - `useToolUIsStore` → Use `useAui()` with `aui.tools()`
 
 **Deprecated Hooks:**
 
 - `useAssistantRuntime` → Use `useAui()`
-- `useThread` → Use `useAuiState(({ thread }) => thread)`
+- `useThread` → Use `useAuiState((s) => s.thread)`
 - `useThreadRuntime` → Use `useAui()` with `aui.thread()`
-- `useMessage` → Use `useAuiState(({ message }) => message)`
+- `useMessage` → Use `useAuiState((s) => s.message)`
 - `useMessageRuntime` → Use `useAui()` with `aui.message()`
-- `useComposer` → Use `useAuiState(({ composer }) => composer)`
+- `useComposer` → Use `useAuiState((s) => s.composer)`
 - `useComposerRuntime` → Use `useAui()` with `aui.composer()`
-- `useEditComposer` → Use `useAuiState(({ message }) => message.composer)`
-- `useThreadListItem` → Use `useAuiState(({ threadListItem }) => threadListItem)`
+- `useEditComposer` → Use `useAuiState((s) => s.message.composer)`
+- `useThreadListItem` → Use `useAuiState((s) => s.threadListItem)`
 - `useThreadListItemRuntime` → Use `useAui()` with `aui.threadListItem()`
-- `useMessagePart` → Use `useAuiState(({ part }) => part)`
+- `useMessagePart` → Use `useAuiState((s) => s.part)`
 - `useMessagePartRuntime` → Use `useAui()` with `aui.part()`
-- `useAttachment` → Use `useAuiState(({ attachment }) => attachment)`
+- `useAttachment` → Use `useAuiState((s) => s.attachment)`
 - `useAttachmentRuntime` → Use `useAui()` with `aui.attachment()`
-- `useThreadModelContext` / `useThreadModelConfig` → Use `useAuiState(({ thread }) => thread.modelContext)`
-- `useThreadComposer` → Use `useAuiState(({ thread }) => thread.composer)`
-- `useThreadList` → Use `useAuiState(({ threads }) => threads)`
+- `useThreadModelContext` / `useThreadModelConfig` → Use `useAuiState((s) => s.thread.modelContext)`
+- `useThreadComposer` → Use `useAuiState((s) => s.thread.composer)`
+- `useThreadList` → Use `useAuiState((s) => s.threads)`
 
 #### Migration Examples
 
@@ -190,10 +190,10 @@ import { useAuiState, useAui } from "@assistant-ui/react";
 
 function MyComponent() {
   // Reading state - all through single hook
-  const messages = useAuiState(({ thread }) => thread.messages);
-  const isRunning = useAuiState(({ thread }) => thread.isRunning);
-  const composerText = useAuiState(({ composer }) => composer.text);
-  const messageRole = useAuiState(({ message }) => message.role);
+  const messages = useAuiState((s) => s.thread.messages);
+  const isRunning = useAuiState((s) => s.thread.isRunning);
+  const composerText = useAuiState((s) => s.composer.text);
+  const messageRole = useAuiState((s) => s.message.role);
 
   // Using client for actions
   const aui = useAui();

package/.docs/raw/docs/cloud/ai-sdk-assistant-ui.mdx

@@ -0,0 +1,205 @@
+---
+title: AI SDK + assistant-ui
+description: Integrate cloud persistence using assistant-ui runtime and pre-built components.
+---
+
+
+## Overview
+
+This guide shows how to integrate Assistant Cloud with the [AI SDK](https://sdk.vercel.ai/) using assistant-ui's runtime system and pre-built UI components.
+
+## What You Get
+
+This integration provides:
+
+- **`<Thread />`** — A complete chat interface with messages, composer, and status indicators
+- **`<ThreadList />`** — A sidebar showing all conversations with auto-generated titles, plus new/delete/manage actions
+- **Automatic Persistence** — Messages save as they stream. Threads are created automatically on first message.
+- **Runtime Integration** — The assistant-ui runtime handles all cloud synchronization behind the scenes.
+
+## How It Works
+
+The `useChatRuntime` hook from `@assistant-ui/react-ai-sdk` wraps AI SDK's `useChat` and adds cloud persistence via the `cloud` parameter. The runtime automatically:
+
+1. Creates a cloud thread on the first user message
+2. Persists messages as they complete streaming
+3. Generates a conversation title after the assistant's first response
+4. Loads historical messages when switching threads via `<ThreadList />`
+
+You provide the AI SDK endpoint (`api: "/api/chat"`) and the cloud configuration—everything else is handled.
+
+## Prerequisites
+
+<Callout type="info">
+  You need an assistant-cloud account to follow this guide. [Sign up here](https://cloud.assistant-ui.com/) to get started.
+</Callout>
+
+## Setup Guide
+
+<Steps>
+
+<Step>
+
+### Create a Cloud Project
+
+Create a new project in the [assistant-cloud dashboard](https://cloud.assistant-ui.com/) and from the settings page, copy:
+
+- **Frontend API URL**: `https://proj-[ID].assistant-api.com`
+- **Assistant Cloud API Key**: `sk_aui_proj_*`
+
+</Step>
+
+<Step>
+
+### Configure Environment Variables
+
+Add the following environment variables to your project:
+
+```bash title=".env.local"
+# Frontend API URL from your cloud project settings
+NEXT_PUBLIC_ASSISTANT_BASE_URL=https://proj-[YOUR-ID].assistant-api.com
+
+# API key for server-side operations
+ASSISTANT_API_KEY=your-api-key-here
+```
+
+</Step>
+
+<Step>
+
+### Install Dependencies
+
+Install the required packages:
+
+<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-ai-sdk"]} />
+
+</Step>
+
+<Step>
+
+### Set Up the Cloud Runtime
+
+Create a client-side AssistantCloud instance and integrate it with your AI SDK runtime:
+
+```tsx title="app/chat/page.tsx"
+"use client";
+
+import { AssistantCloud, AssistantRuntimeProvider } from "@assistant-ui/react";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { ThreadList } from "@/components/assistant-ui/thread-list";
+import { Thread } from "@/components/assistant-ui/thread";
+
+export default function ChatPage() {
+  const cloud = new AssistantCloud({
+    baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
+    anonymous: true, // Creates browser-session based user ID
+  });
+
+  const runtime = useChatRuntime({
+    cloud,
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <div className="grid h-dvh grid-cols-[200px_1fr] gap-x-2 px-4 py-4">
+        <ThreadList />
+        <Thread />
+      </div>
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Step>
+
+</Steps>
+
+## Telemetry
+
+The `useChatRuntime` hook captures full run telemetry including timing data. This integrates with the assistant-ui runtime to provide:
+
+**Automatically captured:**
+- `status` — `"completed"`, `"incomplete"`, or `"error"`
+- `duration_ms` — Total run duration (measured client-side)
+- `steps` — Per-step breakdowns with timing, usage, and tool calls
+- `tool_calls` — Tool invocations with name, arguments, results, and source
+- `total_steps` — Number of reasoning/tool steps
+- `output_text` — Full response text (truncated at 50K characters)
+
+**Requires route configuration:**
+- `model_id` — The model used
+- `input_tokens` / `output_tokens` — Token usage statistics
+
+To capture model and usage data, add the `messageMetadata` callback to your AI SDK route:
+
+```tsx title="app/api/chat/route.ts"
+import { streamText } from "ai";
+
+export async function POST(req: Request) {
+  const result = streamText({
+    model: openai("gpt-5-mini"),
+    messages,
+  });
+
+  return result.toUIMessageStreamResponse({
+    messageMetadata: ({ part }) => {
+      if (part.type === "finish-step") {
+        return {
+          modelId: part.response.modelId,
+          usage: part.usage,
+        };
+      }
+      return undefined;
+    },
+  });
+}
+```
+
+Without this configuration, model and token data will be omitted from telemetry reports.
+
+### Customizing Reports
+
+Use the `beforeReport` hook to add custom metadata or filter reports:
+
+```tsx
+const cloud = new AssistantCloud({
+  baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
+  telemetry: {
+    beforeReport: (report) => ({
+      ...report,
+      metadata: { userTier: "pro", region: "us-east" },
+    }),
+  },
+});
+```
+
+Return `null` from `beforeReport` to skip reporting a specific run. To disable telemetry entirely, pass `telemetry: false`.
+
+## Authentication
+
+The example above uses anonymous mode (browser session-based user ID) via the env var. For production apps with user accounts, pass an explicit cloud instance:
+
+```tsx
+import { useAuth } from "@clerk/nextjs";
+import { AssistantCloud } from "@assistant-ui/react";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+
+function Chat() {
+  const { getToken } = useAuth();
+
+  const cloud = useMemo(() => new AssistantCloud({
+    baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
+    authToken: async () => getToken({ template: "assistant-ui" }),
+  }), [getToken]);
+
+  const runtime = useChatRuntime({ cloud });
+  // ...
+}
+```
+
+See the [Cloud Authorization](/docs/cloud/authorization) guide for other auth providers.
+
+
+## Complete Example
+
+Check out the [with-cloud example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-cloud) on GitHub for a fully working implementation.