@assistant-ui/mcp-docs-server 0.1.19 → 0.1.21

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

@@ -7,11 +7,108 @@ description: Unified state API replaces individual context hooks.
 
 Version 0.12 introduces a complete rewrite of the state management system with a more consistent API.
 
+## Automatic Migration
+
+We provide a codemod to automatically migrate your code:
+
+```bash
+npx assistant-ui@latest upgrade
+```
+
+This will automatically handle the hook renames and update your imports.
+
 ## Breaking Changes
 
-### 1. Context Hooks Replaced with Unified State API
+### 1. Assistant API Hooks Renamed
+
+The core hooks have been renamed for consistency and clarity:
+
+- `useAssistantApi` → `useAui`
+- `useAssistantState` → `useAuiState`
+- `useAssistantEvent` → `useAuiEvent`
+
+The variable naming convention has also changed from `api` to `aui`.
+
+#### Migration
+
+**Before:**
+
+```tsx
+import {
+  useAssistantApi,
+  useAssistantState,
+  useAssistantEvent,
+} from "@assistant-ui/react";
+
+function MyComponent() {
+  const api = useAssistantApi();
+  const isRunning = useAssistantState(({ thread }) => thread.isRunning);
+
+  useAssistantEvent("thread.started", () => {
+    console.log("Thread started");
+  });
+
+  const handleSend = () => {
+    api.composer().send();
+  };
+
+  return <button onClick={handleSend}>Send</button>;
+}
+```
+
+**After:**
+
+```tsx
+import { useAui, useAuiState, useAuiEvent } from "@assistant-ui/react";
+
+function MyComponent() {
+  const aui = useAui();
+  const isRunning = useAuiState(({ thread }) => thread.isRunning);
+
+  useAuiEvent("thread.started", () => {
+    console.log("Thread started");
+  });
+
+  const handleSend = () => {
+    aui.composer().send();
+  };
+
+  return <button onClick={handleSend}>Send</button>;
+}
+```
+
+**Automatic Migration:**
+
+Run the codemod to automatically update your code:
+
+```bash
+npx assistant-ui@latest upgrade
+```
+
+The codemod will:
+- Rename all hook imports (`useAssistantApi` → `useAui`, etc.)
+- Rename `const api = useAui()` declarations to `const aui = useAui()`
+- Update all references to the `api` variable throughout your codebase
+- Correctly handle scoping (won't rename `api` variables from other sources)
+
+**Backwards Compatibility:**
+
+The old names are still available as deprecated exports until v0.13:
 
-All individual context hooks have been replaced with a single `useAssistantState` hook and `useAssistantApi` for actions.
+```tsx
+// Still works, but deprecated
+import {
+  useAssistantApi,
+  useAssistantState,
+  useAssistantEvent,
+} from "@assistant-ui/react";
+
+const api = useAssistantApi(); // deprecated but functional
+```
+
+### 2. Context Hooks Replaced with Unified State API
+
+All individual context hooks have been replaced with a single `useAuiState` hook and `useAui` for actions.
 
 #### What changed
 
@@ -19,30 +116,30 @@ The following hooks have been removed:
 
 **Removed Hooks:**
 
-- `useMessageUtils` → Use `useAssistantState(({ message }) => message.isHovering)` / `useAssistantState(({ message }) => message.isCopied)`
-- `useMessageUtilsStore` → Use `useAssistantApi()` with `api.message().setIsHovering()` / `api.message().setIsCopied()`
-- `useToolUIs` → Use `useAssistantState(({ tools }) => tools)` and `useAssistantApi()` with `api.tools()`
-- `useToolUIsStore` → Use `useAssistantApi()` with `api.tools()`
+- `useMessageUtils` → Use `useAuiState(({ message }) => message.isHovering)` / `useAuiState(({ message }) => message.isCopied)`
+- `useMessageUtilsStore` → Use `useAui()` with `aui.message().setIsHovering()` / `aui.message().setIsCopied()`
+- `useToolUIs` → Use `useAuiState(({ tools }) => tools)` and `useAui()` with `aui.tools()`
+- `useToolUIsStore` → Use `useAui()` with `aui.tools()`
 
 **Deprecated Hooks:**
 
-- `useAssistantRuntime` → Use `useAssistantApi()`
-- `useThread` → Use `useAssistantState(({ thread }) => thread)`
-- `useThreadRuntime` → Use `useAssistantApi()` with `api.thread()`
-- `useMessage` → Use `useAssistantState(({ message }) => message)`
-- `useMessageRuntime` → Use `useAssistantApi()` with `api.message()`
-- `useComposer` → Use `useAssistantState(({ composer }) => composer)`
-- `useComposerRuntime` → Use `useAssistantApi()` with `api.composer()`
-- `useEditComposer` → Use `useAssistantState(({ message }) => message.composer)`
-- `useThreadListItem` → Use `useAssistantState(({ threadListItem }) => threadListItem)`
-- `useThreadListItemRuntime` → Use `useAssistantApi()` with `api.threadListItem()`
-- `useMessagePart` → Use `useAssistantState(({ part }) => part)`
-- `useMessagePartRuntime` → Use `useAssistantApi()` with `api.part()`
-- `useAttachment` → Use `useAssistantState(({ attachment }) => attachment)`
-- `useAttachmentRuntime` → Use `useAssistantApi()` with `api.attachment()`
-- `useThreadModelContext` / `useThreadModelConfig` → Use `useAssistantState(({ thread }) => thread.modelContext)`
-- `useThreadComposer` → Use `useAssistantState(({ thread }) => thread.composer)`
-- `useThreadList` → Use `useAssistantState(({ threads }) => threads)`
+- `useAssistantRuntime` → Use `useAui()`
+- `useThread` → Use `useAuiState(({ thread }) => thread)`
+- `useThreadRuntime` → Use `useAui()` with `aui.thread()`
+- `useMessage` → Use `useAuiState(({ message }) => message)`
+- `useMessageRuntime` → Use `useAui()` with `aui.message()`
+- `useComposer` → Use `useAuiState(({ composer }) => composer)`
+- `useComposerRuntime` → Use `useAui()` with `aui.composer()`
+- `useEditComposer` → Use `useAuiState(({ message }) => message.composer)`
+- `useThreadListItem` → Use `useAuiState(({ threadListItem }) => threadListItem)`
+- `useThreadListItemRuntime` → Use `useAui()` with `aui.threadListItem()`
+- `useMessagePart` → Use `useAuiState(({ part }) => part)`
+- `useMessagePartRuntime` → Use `useAui()` with `aui.part()`
+- `useAttachment` → Use `useAuiState(({ attachment }) => 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)`
 
 #### Migration Examples
 
@@ -89,34 +186,111 @@ function MyComponent() {
 **After:**
 
 ```tsx
-import { useAssistantState, useAssistantApi } from "@assistant-ui/react";
+import { useAuiState, useAui } from "@assistant-ui/react";
 
 function MyComponent() {
   // Reading state - all through single hook
-  const messages = useAssistantState(({ thread }) => thread.messages);
-  const isRunning = useAssistantState(({ thread }) => thread.isRunning);
-  const composerText = useAssistantState(({ composer }) => composer.text);
-  const messageRole = useAssistantState(({ message }) => message.role);
+  const messages = useAuiState(({ thread }) => thread.messages);
+  const isRunning = useAuiState(({ thread }) => thread.isRunning);
+  const composerText = useAuiState(({ composer }) => composer.text);
+  const messageRole = useAuiState(({ message }) => message.role);
 
-  // Using API for actions
-  const api = useAssistantApi();
+  // Using client for actions
+  const aui = useAui();
 
   const handleSend = () => {
-    api.composer().send();
+    aui.composer().send();
   };
 
   const handleReload = () => {
-    api.message().reload();
+    aui.message().reload();
   };
 
   const handleCancel = () => {
-    api.thread().cancelRun();
+    aui.thread().cancelRun();
   };
 
   return null;
 }
 ```
 
+### 3. Event Names Changed to camelCase
+
+Event names used with `useAuiEvent` have been standardized to use camelCase instead of kebab-case.
+
+#### What changed
+
+The following event names have been updated:
+
+| Old Name (kebab-case)               | New Name (camelCase)               |
+| ----------------------------------- | ---------------------------------- |
+| `thread.run-start`                  | `thread.runStart`                  |
+| `thread.run-end`                    | `thread.runEnd`                    |
+| `thread.model-context-update`       | `thread.modelContextUpdate`        |
+| `composer.attachment-add`           | `composer.attachmentAdd`           |
+| `thread-list-item.switched-to`      | `threadListItem.switchedTo`        |
+| `thread-list-item.switched-away`    | `threadListItem.switchedAway`      |
+
+Events that remain unchanged:
+- `thread.initialize`
+- `composer.send`
+
+#### Migration
+
+**Before:**
+
+```tsx
+import { useAuiEvent } from "@assistant-ui/react";
+
+function MyComponent() {
+  useAuiEvent("thread.run-start", () => {
+    console.log("Thread started running");
+  });
+
+  useAuiEvent("thread.run-end", () => {
+    console.log("Thread finished running");
+  });
+
+  useAuiEvent("composer.attachment-add", () => {
+    console.log("Attachment added");
+  });
+
+  return null;
+}
+```
+
+**After:**
+
+```tsx
+import { useAuiEvent } from "@assistant-ui/react";
+
+function MyComponent() {
+  useAuiEvent("thread.runStart", () => {
+    console.log("Thread started running");
+  });
+
+  useAuiEvent("thread.runEnd", () => {
+    console.log("Thread finished running");
+  });
+
+  useAuiEvent("composer.attachmentAdd", () => {
+    console.log("Attachment added");
+  });
+
+  return null;
+}
+```
+
+**Automatic Migration:**
+
+Run the codemod to automatically update event names:
+
+```bash
+npx assistant-ui@latest upgrade
+```
+
+The codemod will automatically replace all occurrences of the old kebab-case event names with their new camelCase equivalents.
+
 ## Getting Help
 
 If you encounter issues during migration:

package/.docs/raw/docs/(reference)/react-compatibility.mdx

@@ -3,7 +3,6 @@ title: Using old React versions
 description: Compatibility notes for React 18, 17, and 16.
 ---
 
-import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
 
 <Callout type="warning" title="Older React Versions">
   Older React versions are not continuously tested. If you encounter any issues

package/.docs/raw/docs/cloud/persistence/ai-sdk.mdx

@@ -3,7 +3,6 @@ title: Chat History for AI SDK
 description: Integrate cloud persistence and thread management with Vercel AI SDK.
 ---
 
-import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
 
 ## Overview
 

package/.docs/raw/docs/cloud/persistence/langgraph.mdx

@@ -3,7 +3,6 @@ title: Chat History for LangGraph Cloud
 description: Integrate cloud persistence and thread management with LangGraph Cloud.
 ---
 
-import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
 
 ## Overview
 

package/.docs/raw/docs/runtimes/ai-sdk/v4-legacy.mdx

@@ -3,7 +3,6 @@ title: AI SDK v4 (Legacy)
 description: Legacy integration for Vercel AI SDK v4 using data stream runtime.
 ---
 
-import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
 
 ## Overview
 

package/.docs/raw/docs/runtimes/ai-sdk/v5-legacy.mdx

@@ -0,0 +1,118 @@
+---
+title: AI SDK v5 (Legacy)
+description: Integrate Vercel AI SDK v5 with useChatRuntime for streaming chat.
+---
+
+<Callout type="error">
+  AI SDK v5 is no longer supported. The `@assistant-ui/react-ai-sdk` package now requires AI SDK v6+.
+  Please upgrade to [AI SDK v6](/docs/runtimes/ai-sdk/v6).
+</Callout>
+
+## Overview
+
+This documentation is preserved for reference. For new projects, use [AI SDK v6](/docs/runtimes/ai-sdk/v6).
+
+## Getting Started
+
+<Steps>
+  <Step>
+  ### Create a Next.js project
+
+```sh
+npx create-next-app@latest my-app
+cd my-app
+```
+
+  </Step>
+  <Step>
+
+### Install AI SDK v5 and `@assistant-ui/react`
+
+```sh
+npm install @assistant-ui/react @assistant-ui/react-ai-sdk@0.x ai@^5 @ai-sdk/openai@^1 zod
+```
+
+  </Step>
+  <Step>
+
+### Setup a backend route under `/api/chat`
+
+`@/app/api/chat/route.ts`
+
+```tsx
+import { openai } from "@ai-sdk/openai";
+import { streamText, tool } from "ai";
+import type { Message } from "ai";
+import { z } from "zod";
+
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+  const { messages }: { messages: Message[] } = await req.json();
+
+  const result = streamText({
+    model: openai("gpt-4o"),
+    messages,
+    tools: {
+      get_current_weather: tool({
+        description: "Get the current weather",
+        parameters: z.object({
+          city: z.string(),
+        }),
+        execute: async ({ city }) => {
+          return `The weather in ${city} is sunny`;
+        },
+      }),
+    },
+  });
+
+  return result.toDataStreamResponse();
+}
+```
+
+  </Step>
+  <Step>
+
+### Setup the frontend
+
+`@/app/page.tsx`
+
+```tsx
+"use client";
+
+import { Thread } from "@/components/assistant-ui/thread";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+
+export default function Home() {
+  const runtime = useChatRuntime({
+    api: "/api/chat",
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <div className="h-full">
+        <Thread />
+      </div>
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+  </Step>
+</Steps>
+
+## Key Differences from v6
+
+| Feature | v5 | v6 |
+|---------|----|----|
+| **ai package** | `ai@^5` | `ai@^6` |
+| **@ai-sdk/openai** | `@ai-sdk/openai@^1` | `@ai-sdk/openai@^3` |
+| **Message type** | `Message` | `UIMessage` |
+| **convertToModelMessages** | Sync | Async (`await`) |
+| **Tool schema** | `parameters: z.object({...})` | `inputSchema: zodSchema(z.object({...}))` |
+| **Response** | `toDataStreamResponse()` | `toUIMessageStreamResponse()` |
+
+## Migration to v6
+
+See the [AI SDK v6 documentation](/docs/runtimes/ai-sdk/v6) for the latest integration guide.

package/.docs/raw/docs/runtimes/ai-sdk/v6.mdx

@@ -0,0 +1,198 @@
+---
+title: AI SDK v6
+description: Integrate Vercel AI SDK v6 with assistant-ui for streaming chat.
+---
+
+
+## Overview
+
+Integration with the Vercel AI SDK v6 using the `useChatRuntime` hook from `@assistant-ui/react-ai-sdk`.
+
+## Getting Started
+
+<Steps>
+  <Step>
+  ### Create a Next.js project
+
+```sh
+npx create-next-app@latest my-app
+cd my-app
+```
+
+  </Step>
+  <Step>
+
+### Install dependencies
+
+<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-ai-sdk", "ai@^6", "@ai-sdk/react@^3", "@ai-sdk/openai", "zod"]} />
+
+  </Step>
+  <Step>
+
+### Setup a backend route under `/api/chat`
+
+`@/app/api/chat/route.ts`
+
+```tsx
+import { openai } from "@ai-sdk/openai";
+import {
+  streamText,
+  convertToModelMessages,
+  tool,
+  zodSchema,
+} from "ai";
+import type { UIMessage } from "ai";
+import { z } from "zod";
+
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+
+  const result = streamText({
+    model: openai("gpt-4o"),
+    messages: await convertToModelMessages(messages), // Note: async in v6
+    tools: {
+      get_current_weather: tool({
+        description: "Get the current weather",
+        inputSchema: zodSchema(
+          z.object({
+            city: z.string(),
+          }),
+        ),
+        execute: async ({ city }) => {
+          return `The weather in ${city} is sunny`;
+        },
+      }),
+    },
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+  </Step>
+  <Step>
+
+### Setup the frontend
+
+`@/app/page.tsx`
+
+```tsx
+"use client";
+
+import { Thread } from "@/components/assistant-ui/thread";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+
+export default function Home() {
+  const runtime = useChatRuntime();
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <div className="h-full">
+        <Thread />
+      </div>
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+  </Step>
+</Steps>
+
+## Key Changes from v5
+
+| Feature | v5 | v6 |
+|---------|----|----|
+| **ai package** | `ai@^5` | `ai@^6` |
+| **@ai-sdk/react** | `@ai-sdk/react@^2` | `@ai-sdk/react@^3` |
+| **convertToModelMessages** | Sync | Async (`await`) |
+| **Tool schema** | `parameters: z.object({...})` | `inputSchema: zodSchema(z.object({...}))` |
+
+## API Reference
+
+### useChatRuntime
+
+Creates a runtime integrated with AI SDK's `useChat` hook.
+
+```tsx
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+
+const runtime = useChatRuntime({
+  api: "/api/chat", // optional, defaults to "/api/chat"
+});
+```
+
+### Custom API URL
+
+```tsx
+const runtime = useChatRuntime({
+  api: "/my-custom-api/chat",
+});
+```
+
+### Forwarding System Messages and Frontend Tools
+
+Use `AssistantChatTransport` to automatically forward system messages and frontend tools to your backend:
+
+```tsx
+"use client";
+
+import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
+
+const runtime = useChatRuntime({
+  transport: new AssistantChatTransport({
+    api: "/api/chat",
+  }),
+});
+```
+
+Backend route with system/tools forwarding:
+
+```tsx
+import { openai } from "@ai-sdk/openai";
+import { streamText, convertToModelMessages, zodSchema } from "ai";
+import type { UIMessage } from "ai";
+import { frontendTools } from "@assistant-ui/react-ai-sdk";
+
+export async function POST(req: Request) {
+  const {
+    messages,
+    system,
+    tools,
+  }: {
+    messages: UIMessage[];
+    system?: string;
+    tools?: any;
+  } = await req.json();
+
+  const result = streamText({
+    model: openai("gpt-4o"),
+    system,
+    messages: await convertToModelMessages(messages),
+    tools: {
+      ...frontendTools(tools),
+      // your backend tools...
+    },
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+### useAISDKRuntime (Advanced)
+
+For advanced use cases where you need direct access to the `useChat` hook:
+
+```tsx
+import { useChat } from "@ai-sdk/react";
+import { useAISDKRuntime } from "@assistant-ui/react-ai-sdk";
+
+const chat = useChat();
+const runtime = useAISDKRuntime(chat);
+```
+
+## Example
+
+For a complete example, check out the [AI SDK v6 example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-ai-sdk-v6) in our repository.

package/.docs/raw/docs/runtimes/assistant-transport.mdx

@@ -503,7 +503,7 @@ To enable resumability, you need to:
 2. Use the `unstable_resumeRun` API to resume a conversation
 
 ```typescript
-import { useAssistantApi } from "@assistant-ui/react";
+import { useAui } from "@assistant-ui/react";
 
 const runtime = useAssistantTransportRuntime({
   // ... other options
@@ -513,8 +513,8 @@ const runtime = useAssistantTransportRuntime({
 });
 
 // Typically called on thread switch or mount to check if sync server has anything to resume
-const api = useAssistantApi();
-api.thread().unstable_resumeRun({
+const aui = useAui();
+aui.thread().unstable_resumeRun({
   parentId: null, // Ignored (will be removed in a future version)
 });
 ```

package/.docs/raw/docs/runtimes/custom/custom-thread-list.mdx

@@ -3,7 +3,6 @@ title: Custom Thread List
 description: Plug a custom thread database for multi-thread persistence.
 ---
 
-import { ParametersTable } from "@/components/docs/tables/ParametersTable";
 
 ## Overview
 
@@ -222,26 +221,26 @@ When the hook mounts it calls `list()` on your adapter, hydrates existing thread
 When implementing a custom history adapter, you must await thread initialization before saving messages. Failing to do so can cause the first message to be lost due to a race condition.
 </Callout>
 
-If you're building a history adapter that persists messages to your own database, use `api.threadListItem().initialize()` to ensure the thread is fully initialized before saving:
+If you're building a history adapter that persists messages to your own database, use `aui.threadListItem().initialize()` to ensure the thread is fully initialized before saving:
 
 ```tsx
-import { useAssistantApi } from "@assistant-ui/react";
+import { useAui } from "@assistant-ui/react";
 
 // Inside your unstable_Provider component
-const api = useAssistantApi();
+const aui = useAui();
 
 const history = useMemo<ThreadHistoryAdapter>(
   () => ({
     async append(message) {
       // Wait for initialization to complete and get the remoteId
-      const { remoteId } = await api.threadListItem().initialize();
+      const { remoteId } = await aui.threadListItem().initialize();
 
       // Now safe to save the message using the remoteId
       await saveMessageToDatabase(remoteId, message);
     },
     // ...
   }),
-  [api],
+  [aui],
 );
 ```