@assistant-ui/mcp-docs-server 0.1.30 → 0.1.31

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

@@ -0,0 +1,52 @@
+---
+title: Overview
+description: Vercel AI SDK integration for assistant-ui across major versions.
+---
+
+import { VercelIcon } from "@/components/icons/vercel";
+
+`@assistant-ui/react-ai-sdk` integrates assistant-ui with the [Vercel AI SDK](https://ai-sdk.dev/). It covers `useChat` flows, custom transports, frontend tools, attachments, quote context, multi-step agents, token usage, and cloud persistence.
+
+## Pick a version
+
+| AI SDK | Runtime package | Docs |
+| --- | --- | --- |
+| `ai@^6` + `@ai-sdk/react@^3` | `@assistant-ui/react-ai-sdk` (latest) | [v6 (current)](/docs/runtimes/ai-sdk/v6) |
+| `ai@^5` + `@ai-sdk/react@^2` | `@assistant-ui/react-ai-sdk@0.x` | [v5 (legacy)](/docs/runtimes/ai-sdk/v5-legacy) |
+| `ai@^4` | `@assistant-ui/react-data-stream` | [v4 (legacy)](/docs/runtimes/ai-sdk/v4-legacy) |
+
+New projects should target v6. v5 and v4 are documented for projects that have not migrated yet; both have known compatibility gaps and receive no new features.
+
+## Architecture
+
+`@assistant-ui/react-ai-sdk` is layered on `ExternalStoreRuntime` (see [architecture](/docs/runtimes/concepts/architecture)). Features that ship as runtime adapters work the same way they do everywhere else; see [adapters](/docs/runtimes/concepts/adapters).
+
+## Choosing useChatRuntime vs useAISDKRuntime
+
+Both ship in the same package.
+
+- **`useChatRuntime`** (recommended) wraps the AI SDK's `useChat` hook and adds cloud thread support, the standard adapter slots, and `AssistantChatTransport` (which forwards system messages and frontend tools by default). Use this unless you have a reason not to.
+- **`useAISDKRuntime`** is a lower-level hook that takes an existing `useChat` instance you control directly. Use it when you need to share the chat instance with non-assistant-ui code or wire in a custom transport that does not inherit from `AssistantChatTransport`.
+
+## Next
+
+<Cards>
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="v6 (current)"
+    description="Quickstart, frontend tools, attachments, quotes, history, multi-step, useAISDKRuntime."
+    href="/docs/runtimes/ai-sdk/v6"
+  />
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="v5 (legacy)"
+    description="Reference for projects still on AI SDK v5."
+    href="/docs/runtimes/ai-sdk/v5-legacy"
+  />
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="v4 (legacy)"
+    description="Reference for projects still on AI SDK v4."
+    href="/docs/runtimes/ai-sdk/v4-legacy"
+  />
+</Cards>

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

@@ -1,66 +1,51 @@
 ---
-title: AI SDK v4 (Legacy)
-description: Legacy integration for Vercel AI SDK v4 using data stream runtime.
+title: AI SDK v4 (legacy)
+description: Reference for projects still on AI SDK v4. New projects should use v6.
 ---
 
+import { VercelIcon } from "@/components/icons/vercel";
 
-## Overview
-
-If you're using AI SDK v4 (legacy), you can integrate with assistant-ui using the `@assistant-ui/react-data-stream` package and its `useDataStreamRuntime` hook. This provides a compatible runtime that works with AI SDK v4's streaming responses.
-
-<Callout type="warning">
-  AI SDK v4 is now considered legacy. We recommend upgrading to [AI SDK
-  v6](/docs/runtimes/ai-sdk/v6) for improved features and better
-  TypeScript support. This documentation is provided for projects that haven't
-  migrated yet.
+<Callout type="warn">
+AI SDK v4 is a legacy version. New projects should use [AI SDK v6](/docs/runtimes/ai-sdk/v6). v4 integrations use the older `@assistant-ui/react-data-stream` package, not `@assistant-ui/react-ai-sdk`.
 </Callout>
 
-## Getting Started
+## Why legacy
 
+Vercel ships AI SDK majors roughly yearly; v4 is two majors behind v6. The current `@assistant-ui/react-ai-sdk` package targets v6+ exclusively, so v4 users plug into [`@assistant-ui/react-data-stream`](/docs/runtimes/custom/data-stream) instead — the same data stream protocol that v4's `toDataStreamResponse()` emits.
 
-### Option 1: Using @assistant-ui/react-data-stream (Recommended)
+This page is reference for existing v4 projects. Plan to migrate to v6 when feasible.
+
+## Setup
 
 <Steps>
-  <Step>
-  ### Install the required packages
+<Step>
 
-Install `@assistant-ui/react-data-stream` alongside assistant-ui and AI SDK v4:
+### Install
 
 <InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-data-stream", "ai@^4"]} />
 
-  </Step>
-  <Step>
-
-### Setup your backend route
+</Step>
+<Step>
 
-Create an API route that uses AI SDK v4's streaming capabilities:
+### Backend route
 
-`@/app/api/chat/route.ts`
-
-```tsx
+```ts title="@/app/api/chat/route.ts"
 import { streamText } from "ai";
 import { openai } from "@ai-sdk/openai";
 
 export async function POST(req: Request) {
   const { messages } = await req.json();
-
-  const result = streamText({
-    model: openai("gpt-4"),
-    messages,
-  });
-
+  const result = streamText({ model: openai("gpt-4"), messages });
   return result.toDataStreamResponse();
 }
 ```
 
-  </Step>
-  <Step>
+</Step>
+<Step>
 
-### Use `useDataStreamRuntime` in your component
+### Frontend
 
-`@/app/page.tsx`
-
-```tsx
+```tsx title="@/app/page.tsx"
 "use client";
 
 import { AssistantRuntimeProvider } from "@assistant-ui/react";
@@ -68,10 +53,7 @@ import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";
 import { Thread } from "@/components/assistant-ui/thread";
 
 export default function Home() {
-  const runtime = useDataStreamRuntime({
-    api: "/api/chat",
-  });
-
+  const runtime = useDataStreamRuntime({ api: "/api/chat" });
   return (
     <AssistantRuntimeProvider runtime={runtime}>
       <div className="h-full">
@@ -82,96 +64,54 @@ export default function Home() {
 }
 ```
 
-  </Step>
+</Step>
 </Steps>
 
-### Option 2: Using @assistant-ui/react-ai-sdk v0.1.10 (Legacy)
-
-Alternatively, you can use the older version of the AI SDK integration package, though this version is no longer actively maintained:
-
-<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-ai-sdk@0.1.10", "ai@^4"]} />
-
-<Callout type="warning">
-  Version 0.1.10 of `@assistant-ui/react-ai-sdk` is no longer actively
-  maintained. We recommend using the `@assistant-ui/react-data-stream` approach
-  or upgrading to AI SDK v6 for continued support.
-</Callout>
-
-With this legacy version, you would use the `useVercelUseChatRuntime` hook:
-
-```tsx
-"use client";
-
-import { useChat } from "ai/react";
-import { AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useVercelUseChatRuntime } from "@assistant-ui/react-ai-sdk";
-import { Thread } from "@/components/assistant-ui/thread";
-
-export default function Home() {
-  const chat = useChat({
-    api: "/api/chat",
-  });
-  const runtime = useVercelUseChatRuntime(chat);
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <div className="h-full">
-        <Thread />
-      </div>
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-## API Reference
-
-### `useDataStreamRuntime`
-
-The `useDataStreamRuntime` hook creates a runtime compatible with assistant-ui from AI SDK v4's streaming responses.
-
-```tsx
-import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";
-
-const runtime = useDataStreamRuntime({
-  api: "/api/chat",
-  // Options similar to AI SDK v4's useChat
-  initialMessages: [],
-  onFinish: (message) => {
-    console.log("Message completed:", message);
-  },
-  onError: (error) => {
-    console.error("Chat error:", error);
-  },
-});
-```
-
-#### Options
-
-The `useDataStreamRuntime` hook accepts options similar to AI SDK v4's `useChat` hook:
-
-- **`api`**: The API endpoint for chat requests (required)
-- **`initialMessages`**: Initial messages to populate the chat
-- **`onFinish`**: Callback when a message completes streaming
-- **`onError`**: Callback for handling errors
-- **`headers`**: Additional headers to send with requests
-- **`body`**: Additional body parameters to send with requests
-
-<Callout type="info">
-  The `useDataStreamRuntime` API is designed to be familiar to developers
-  already using AI SDK v4's `useChat` hook, making migration straightforward.
-</Callout>
-
-## Migration to AI SDK v6
-
-When you're ready to upgrade to AI SDK v6:
-
-1. Replace `@assistant-ui/react-data-stream` with `@assistant-ui/react-ai-sdk`
-2. Update your backend to use AI SDK v6's `streamText` API
-3. Switch from `useDataStreamRuntime` to `useChatRuntime`
-4. Take advantage of improved TypeScript support and automatic system/tool forwarding
-
-See our [AI SDK v6 documentation](/docs/runtimes/ai-sdk/v6) for the complete migration guide.
-
-## Example
-
-For a working example with AI SDK v4, you can adapt the patterns from our [AI SDK examples](https://github.com/assistant-ui/assistant-ui/tree/main/examples) using the `@assistant-ui/react-data-stream` package instead of the v6 integration.
+`useDataStreamRuntime` accepts `api`, `initialMessages`, `onFinish`, `onError`, `headers`, `body`, and the standard `LocalRuntimeOptions`. For the full reference, see [Data Stream Protocol](/docs/runtimes/custom/data-stream).
+
+## Differences from v6
+
+| Feature | v4 | v6 |
+| --- | --- | --- |
+| `ai` package | `ai@^4` | `ai@^6` |
+| Runtime package | `@assistant-ui/react-data-stream` | `@assistant-ui/react-ai-sdk` |
+| Runtime hook | `useDataStreamRuntime` | `useChatRuntime` |
+| Response | `toDataStreamResponse()` | `toUIMessageStreamResponse()` |
+| Tool schema | `parameters: z.object({...})` | `inputSchema: zodSchema(z.object({...}))` |
+| Message type | (untyped) | `UIMessage` |
+
+## Migration to v6
+
+When you are ready to upgrade:
+
+1. Swap `@assistant-ui/react-data-stream` for `@assistant-ui/react-ai-sdk`.
+2. Update your backend to AI SDK v6's `streamText` (see [v6 docs](/docs/runtimes/ai-sdk/v6)).
+3. Switch the runtime hook from `useDataStreamRuntime` to `useChatRuntime`.
+
+AI SDK provides codemods at [ai-sdk.dev/docs/migration-guides](https://ai-sdk.dev/docs/migration-guides) that handle the package-side rewrites.
+
+## Alternative: react-ai-sdk@0.1.10
+
+An older release line of `@assistant-ui/react-ai-sdk` (0.1.10) supported AI SDK v4 directly. It is no longer maintained and has no upgrade path; if you are starting a new v4 project, use `@assistant-ui/react-data-stream` instead.
+
+## Related
+
+<Cards>
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="AI SDK v6"
+    description="Current integration; what new projects should target."
+    href="/docs/runtimes/ai-sdk/v6"
+  />
+  <Card
+    title="Data Stream Protocol"
+    description="The runtime v4 integrations are built on."
+    href="/docs/runtimes/custom/data-stream"
+  />
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="AI SDK v5 (legacy)"
+    description="The intermediate legacy version."
+    href="/docs/runtimes/ai-sdk/v5-legacy"
+  />
+</Cards>

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

@@ -1,45 +1,35 @@
 ---
-title: AI SDK v5 (Legacy)
-description: Integrate Vercel AI SDK v5 with useChatRuntime for streaming chat.
+title: AI SDK v5 (legacy)
+description: Reference for projects still on AI SDK v5. New projects should use v6.
 ---
 
-<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>
+import { VercelIcon } from "@/components/icons/vercel";
 
-## Overview
+<Callout type="warn">
+AI SDK v5 is a legacy version. New projects should use [AI SDK v6](/docs/runtimes/ai-sdk/v6). v5 users stay on `@assistant-ui/react-ai-sdk@0.x`; the latest line targets v6+.
+</Callout>
 
-This documentation is preserved for reference. For new projects, use [AI SDK v6](/docs/runtimes/ai-sdk/v6).
+## Why legacy
 
-## Getting Started
+AI SDK v6 introduced major API changes: async `convertToModelMessages`, a new tool schema, and `toUIMessageStreamResponse()`. v5 still works but no longer receives new features in `@assistant-ui/react-ai-sdk`. Pinning to `@0.x` keeps you on the v5-compatible surface.
 
-<Steps>
-  <Step>
-  ### Create a Next.js project
-
-```sh
-npx create-next-app@latest my-app
-cd my-app
-```
+This page is reference for existing v5 projects. Plan to migrate to v6 when feasible.
 
-  </Step>
-  <Step>
+## Setup
 
-### Install AI SDK v5 and `@assistant-ui/react`
+<Steps>
+<Step>
 
-```sh
-npm install @assistant-ui/react @assistant-ui/react-ai-sdk@0.x ai@^5 @ai-sdk/openai@^1 zod
-```
+### Install v5-compatible versions
 
-  </Step>
-  <Step>
+<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-ai-sdk@0.x", "ai@^5", "@ai-sdk/openai@^1", "zod"]} />
 
-### Setup a backend route under `/api/chat`
+</Step>
+<Step>
 
-`@/app/api/chat/route.ts`
+### Backend route
 
-```tsx
+```ts title="@/app/api/chat/route.ts"
 import { openai } from "@ai-sdk/openai";
 import { streamText, tool } from "ai";
 import type { Message } from "ai";
@@ -49,35 +39,27 @@ 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`;
-        },
+        parameters: z.object({ city: z.string() }),
+        execute: async ({ city }) => `The weather in ${city} is sunny`,
       }),
     },
   });
-
   return result.toDataStreamResponse();
 }
 ```
 
-  </Step>
-  <Step>
+</Step>
+<Step>
 
-### Setup the frontend
+### Frontend
 
-`@/app/page.tsx`
-
-```tsx
+```tsx title="@/app/page.tsx"
 "use client";
 
 import { Thread } from "@/components/assistant-ui/thread";
@@ -86,7 +68,6 @@ import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 
 export default function Home() {
   const runtime = useChatRuntime();
-
   return (
     <AssistantRuntimeProvider runtime={runtime}>
       <div className="h-full">
@@ -97,33 +78,58 @@ export default function Home() {
 }
 ```
 
+</Step>
+</Steps>
+
 <Callout type="info">
-  `useChatRuntime` was introduced in `@assistant-ui/react-ai-sdk@0.11.3`. If you're using an older 0.x version, use `useVercelUseChatRuntime` with `useChat` from `ai/react` instead:
+On `@assistant-ui/react-ai-sdk` versions older than 0.11.3, use `useVercelUseChatRuntime` with `useChat` from `ai/react` instead:
 
-  ```tsx
-  import { useChat } from "ai/react";
-  import { useVercelUseChatRuntime } from "@assistant-ui/react-ai-sdk";
+```tsx
+import { useChat } from "ai/react";
+import { useVercelUseChatRuntime } from "@assistant-ui/react-ai-sdk";
 
-  const chat = useChat({ api: "/api/chat" });
-  const runtime = useVercelUseChatRuntime(chat);
-  ```
+const chat = useChat({ api: "/api/chat" });
+const runtime = useVercelUseChatRuntime(chat);
+```
 </Callout>
 
-  </Step>
-</Steps>
-
-## Key Differences from v6
+## Differences from v6
 
 | Feature | v5 | v6 |
-|---------|----|----|
-| **ai package** | `ai@^5` | `ai@^6` |
-| **@assistant-ui/react-ai-sdk** | `@0.x` | `@latest` |
-| **@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()` |
+| --- | --- | --- |
+| `ai` package | `ai@^5` | `ai@^6` |
+| `@assistant-ui/react-ai-sdk` | `@0.x` | `@latest` |
+| `@ai-sdk/openai` | `^1` | `^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.
+When you are ready to upgrade:
+
+1. Update `ai` from `@^5` to `@^6`, and `@assistant-ui/react-ai-sdk` to the latest line.
+2. Add `await` to `convertToModelMessages(...)` calls.
+3. Convert tool schemas: `parameters: z.object({...})` → `inputSchema: zodSchema(z.object({...}))`.
+4. Replace `toDataStreamResponse()` with `toUIMessageStreamResponse()`.
+5. Switch the `Message` type to `UIMessage`.
+
+AI SDK provides codemods at [ai-sdk.dev/docs/migration-guides/migration-guide-6-0](https://ai-sdk.dev/docs/migration-guides/migration-guide-6-0) that handle most of the package-side rewrites.
+
+## Related
+
+<Cards>
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="AI SDK v6"
+    description="Current integration; what new projects should target."
+    href="/docs/runtimes/ai-sdk/v6"
+  />
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="AI SDK v4 (legacy)"
+    description="The earlier legacy version using react-data-stream."
+    href="/docs/runtimes/ai-sdk/v4-legacy"
+  />
+</Cards>