@assistant-ui/mcp-docs-server 0.1.12 → 0.1.14

package/.docs/raw/docs/api-reference/integrations/vercel-ai-sdk.mdx

@@ -5,19 +5,29 @@ title: "@assistant-ui/react-ai-sdk"
 Vercel AI SDK integration for assistant-ui.
 
 import { ParametersTable } from "@/components/docs";
+import { Callout } from "fumadocs-ui/components/callout";
+
+<Callout type="info">
+  This package provides integration with AI SDK v5. For AI SDK v4, see the [AI
+  SDK v4 (Legacy)](/docs/runtimes/ai-sdk/v4-legacy) documentation.
+</Callout>
 
 ## API Reference
 
-### `useVercelUseChatRuntime`
+### `useChatRuntime`
 
-Convert Vercel AI SDK chat helpers into a `AssistantRuntime`.
+Creates a runtime directly with AI SDK v5's `useChat` hook integration. This is the recommended approach for most use cases.
 
 ```tsx
-import { useVercelUseChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
 
 const MyRuntimeProvider = ({ children }: { children: React.ReactNode }) => {
-  const chat = useChat();
-  const runtime = useVercelUseChatRuntime(chat);
+  const runtime = useChatRuntime({
+    transport: new AssistantChatTransport({
+      api: "/api/chat",
+    }),
+  });
 
   return (
     <AssistantRuntimeProvider runtime={runtime}>
@@ -27,26 +37,86 @@ const MyRuntimeProvider = ({ children }: { children: React.ReactNode }) => {
 };
 ```
 
+To customize the API endpoint, simply change the `api` parameter:
+
+```tsx
+const runtime = useChatRuntime({
+  transport: new AssistantChatTransport({
+    api: "/my-custom-api/chat",
+  }),
+});
+```
+
 <ParametersTable
   parameters={[
     {
-      name: "chat",
-      type: "ReturnType<typeof useChat>",
-      description: "The UseChatHelpers from @ai-sdk/react.",
+      name: "options",
+      type: "UseChatRuntimeOptions",
+      description: "Configuration options for the chat runtime.",
+      children: [
+        {
+          type: "UseChatRuntimeOptions",
+          parameters: [
+            {
+              name: "api",
+              type: "string",
+              description: "The API endpoint URL. Defaults to '/api/chat'.",
+            },
+            {
+              name: "transport",
+              type: "ChatTransport",
+              description:
+                "Custom transport implementation. Defaults to AssistantChatTransport which forwards system messages and tools.",
+            },
+            {
+              name: "cloud",
+              type: "AssistantCloud",
+              description:
+                "Optional AssistantCloud instance for chat persistence.",
+            },
+            {
+              name: "initialMessages",
+              type: "UIMessage[]",
+              description: "Initial messages to populate the chat.",
+            },
+            {
+              name: "onFinish",
+              type: "(message: UIMessage) => void",
+              description: "Callback when a message completes streaming.",
+            },
+            {
+              name: "onError",
+              type: "(error: Error) => void",
+              description: "Callback for handling errors.",
+            },
+          ],
+        },
+      ],
     },
   ]}
 />
 
-### `useVercelUseAssistantRuntime`
+<Callout type="info">
+  By default, `useChatRuntime` uses `AssistantChatTransport` which automatically
+  forwards system messages and frontend tools to your backend API. This enables
+  your backend to receive the full context from the assistant-ui.
+</Callout>
+
+### `useAISDKRuntime`
 
-Convert Vercel AI SDK assistant helpers into a `AssistantRuntime`.
+For advanced use cases where you need direct access to the `useChat` hook from AI SDK.
 
 ```tsx
-import { useVercelUseAssistantRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChat } from "@ai-sdk/react";
+import { useAISDKRuntime } from "@assistant-ui/react-ai-sdk";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
 
 const MyRuntimeProvider = ({ children }: { children: React.ReactNode }) => {
-  const assistant = useAssistant();
-  const runtime = useVercelUseAssistantRuntime(assistant);
+  const chat = useChat({
+    api: "/api/chat",
+  });
+
+  const runtime = useAISDKRuntime(chat);
 
   return (
     <AssistantRuntimeProvider runtime={runtime}>
@@ -59,83 +129,76 @@ const MyRuntimeProvider = ({ children }: { children: React.ReactNode }) => {
 <ParametersTable
   parameters={[
     {
-      name: "assistant",
-      type: "ReturnType<typeof useAssistant>",
-      description: "The UseAssistantHelpers from @ai-sdk/react.",
+      name: "chat",
+      type: "ReturnType<typeof useChat>",
+      description: "The chat helpers from @ai-sdk/react's useChat hook.",
+    },
+    {
+      name: "options",
+      type: "AISDKRuntimeOptions",
+      description: "Optional configuration options.",
+      children: [
+        {
+          type: "AISDKRuntimeOptions",
+          parameters: [
+            {
+              name: "cloud",
+              type: "AssistantCloud",
+              description:
+                "Optional AssistantCloud instance for chat persistence.",
+            },
+            {
+              name: "adapters",
+              type: "RuntimeAdapters",
+              description:
+                "Optional runtime adapters for attachments, feedback, speech, etc.",
+            },
+          ],
+        },
+      ],
     },
   ]}
 />
 
-### `useVercelRSCRuntime`
+### `AssistantChatTransport`
 
-Convert Vercel RSC runtime into a `AssistantRuntime`.
+A transport that extends the default AI SDK transport to automatically forward system messages and frontend tools to your backend.
 
 ```tsx
-import { useVercelRSCRuntime } from "@assistant-ui/react-ai-sdk";
-
-const MyRuntimeProvider = ({ children }: { children: React.ReactNode }) => {
-  const [messages, setMessages] = useUIState<typeof AI>();
-
-  const onNew = async (m: AppendMessage) => {
-    if (m.content[0]?.type !== "text")
-      throw new Error("Only text messages are supported");
-
-    const input = m.content[0].text;
-    setMessages((currentConversation) => [
-      ...currentConversation,
-      { id: nanoid(), role: "user", display: input },
-    ]);
-
-    const message = await continueConversation(input);
-
-    setMessages((currentConversation) => [...currentConversation, message]);
-  };
-
-  const runtime = useVercelRSCRuntime({ messages, onNew });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-};
+import { AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+
+const runtime = useChatRuntime({
+  transport: new AssistantChatTransport({
+    api: "/my-custom-api/chat",
+  }),
+});
 ```
 
 <ParametersTable
   parameters={[
     {
-      name: "adapter",
-      type: "VercelRSCAdapter<TMessage>",
-      description: "The Vercel RSC adapter to use.",
+      name: "options",
+      type: "HttpChatTransportInitOptions",
+      description: "Transport configuration options.",
       children: [
         {
-          type: "VercelRSCAdapter<TMessage>",
+          type: "HttpChatTransportInitOptions",
           parameters: [
             {
-              name: "messages",
-              type: "readonly ThreadMessage[]",
-              description: "The messages in the thread.",
+              name: "api",
+              type: "string",
+              description: "The API endpoint URL.",
             },
             {
-              name: "onNew",
-              type: "(message: AppendMessage) => Promise<void>",
-              description: "A function to append a message to the thread.",
+              name: "headers",
+              type: "Record<string, string> | Headers",
+              description: "Optional headers to include in requests.",
             },
             {
-              name: "onEdit",
-              type: "(message: AppendMessage) => Promise<void>",
-              description: "A function to edit a message.",
-            },
-            {
-              name: "onReload",
-              type: "(parentId: string | null) => Promise<void>",
-              description: "A function to reload a message.",
-            },
-            {
-              name: "convertMessage",
-              type: "(message: TMessage) => VercelRSCMessage",
-              description:
-                "A function to convert messages to the VercelRSCMessage format. Only required if your message objects are not already compatible with Vercel RSC.",
+              name: "credentials",
+              type: "RequestCredentials",
+              description: "Optional credentials mode for fetch requests.",
             },
           ],
         },
@@ -143,3 +206,49 @@ const MyRuntimeProvider = ({ children }: { children: React.ReactNode }) => {
     },
   ]}
 />
+
+### `frontendTools`
+
+Helper function to convert frontend tool definitions to AI SDK format for use in your backend.
+
+```tsx
+import { frontendTools } from "@assistant-ui/react-ai-sdk";
+import { streamText, convertToModelMessages } from "ai";
+import { openai } from "@ai-sdk/openai";
+
+export async function POST(req: Request) {
+  const { messages, system, tools } = await req.json();
+
+  const result = streamText({
+    model: openai("gpt-4o"),
+    system,
+    messages: convertToModelMessages(messages),
+    tools: {
+      // Wrap frontend tools with the helper
+      ...frontendTools(tools),
+      // Your backend tools
+      myBackendTool: tool({
+        // ...
+      }),
+    },
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+<ParametersTable
+  parameters={[
+    {
+      name: "tools",
+      type: "Record<string, unknown>",
+      description:
+        "Frontend tools object forwarded from AssistantChatTransport.",
+    },
+  ]}
+/>
+
+<Callout type="info">
+  The `frontendTools` helper converts frontend tool definitions to the AI SDK
+  format and ensures they are properly handled by the streaming response.
+</Callout>

package/.docs/raw/docs/cloud/authorization.mdx

@@ -70,7 +70,7 @@ export const POST = async (req: Request) => {
  
   if (!userId) throw new Error("User not authenticated");
  
-  const workspaceId = orgId ? `${orgId}:${userId}` : userId;
+  const workspaceId = orgId ? `${orgId}_${userId}` : userId;
   const assistantCloud = new AssistantCloud({
     apiKey: process.env["ASSISTANT_API_KEY"]!,
     userId,
@@ -91,7 +91,7 @@ const cloud = new AssistantCloud({
   baseUrl: process.env["NEXT_PUBLIC_ASSISTANT_BASE_URL"]!,
   authToken: () =>
     fetch("/api/assistant-ui-token", { method: "POST" }).then((r) =>
-      r.json().then((data) => data.token)
+      r.text(),
     ),
 });
 

package/.docs/raw/docs/copilots/model-context.mdx

@@ -33,7 +33,6 @@ import {
   makeAssistantVisible,
   makeAssistantTool,
   tool,
-  useAssistantRuntime,
 } from "@assistant-ui/react";
 import { z } from "zod";
 
@@ -75,12 +74,12 @@ function Form() {
 The context provider system allows components to contribute to the model context. Here's a typical usage pattern:
 
 ```tsx
-import { useAssistantRuntime, tool } from "@assistant-ui/react";
+import { useAssistantApi, tool } from "@assistant-ui/react";
 import { useEffect } from "react";
 import { z } from "zod";
 
 function MyComponent() {
-  const assistantRuntime = useAssistantRuntime();
+  const api = useAssistantApi();
 
   // Define tool using the tool() helper
   const myTool = tool({
@@ -95,13 +94,13 @@ function MyComponent() {
 
   useEffect(() => {
     // Register context provider
-    return assistantRuntime.registerModelContextProvider({
+    return api.modelContext().register({
       getModelContext: () => ({
         system: "You are a helpful search assistant...",
         tools: { myTool },
       }),
     });
-  }, [assistantRuntime]); // Re-register if runtime changes
+  }, [api]); // Re-register if api changes
 
   return <div>{/* component content */}</div>;
 }

package/.docs/raw/docs/copilots/motivation.mdx

@@ -143,14 +143,14 @@ function SmartTransactionHistory() {
 Finally, let's add dynamic context based on the user's transaction patterns:
 
 ```tsx
-import { useAssistantRuntime } from "@assistant-ui/react";
+import { useAssistantApi } from "@assistant-ui/react";
 import { useEffect } from "react";
 
 function SmartTransactionHistory({ userProfile }) {
-  const assistantRuntime = useAssistantRuntime();
+  const api = useAssistantApi();
 
   useEffect(() => {
-    return assistantRuntime.registerModelContextProvider({
+    return api.modelContext().register({
       getModelContext: () => ({
         system: `
           User spending patterns:
@@ -160,7 +160,7 @@ function SmartTransactionHistory({ userProfile }) {
         `,
       }),
     });
-  }, [assistantRuntime, userProfile]);
+  }, [api, userProfile]);
 
   // Previous components...
 }

package/.docs/raw/docs/getting-started.mdx

@@ -1453,13 +1453,15 @@ If you aren't using Next.js, you can also deploy this endpoint to Cloudflare Wor
 
 ```tsx title="/app/page.tsx" tab="Thread"
 import { AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
 import { ThreadList } from "@/components/assistant-ui/thread-list";
 import { Thread } from "@/components/assistant-ui/thread";
 
 const MyApp = () => {
   const runtime = useChatRuntime({
-    api: "/api/chat",
+    transport: new AssistantChatTransport({
+      api: "/api/chat",
+    }),
   });
 
   return (
@@ -1477,12 +1479,14 @@ const MyApp = () => {
 // run `npx shadcn@latest add "https://r.assistant-ui.com/assistant-modal"`
 
 import { AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
 import { AssistantModal } from "@/components/assistant-ui/assistant-modal";
 
 const MyApp = () => {
   const runtime = useChatRuntime({
-    api: "/api/chat",
+    transport: new AssistantChatTransport({
+      api: "/api/chat",
+    }),
   });
 
   return (

package/.docs/raw/docs/guides/Attachments.mdx

@@ -508,14 +508,14 @@ class ValidatedImageAdapter implements AttachmentAdapter {
 Enable multi-file selection with custom limits:
 
 ```tsx
-const composer = useComposer();
+const api = useAssistantApi();
 
 const handleMultipleFiles = async (files: FileList) => {
   const maxFiles = 5;
   const filesToAdd = Array.from(files).slice(0, maxFiles);
 
   for (const file of filesToAdd) {
-    await composer.addAttachment({ file });
+    await api.composer().addAttachment({ file });
   }
 };
 ```

package/.docs/raw/docs/guides/Tools.mdx

@@ -165,15 +165,15 @@ function App() {
 
 ### 4. Advanced: Direct Context Registration
 
-Use `registerModelContextProvider` when you need to configure more than just tools:
+Use `api.modelContext().register()` when you need to configure more than just tools:
 
 ```tsx
-import { tool, useAssistantRuntime } from "@assistant-ui/react";
+import { tool, useAssistantApi } from "@assistant-ui/react";
 import { useEffect, useState } from "react";
 import { z } from "zod";
 
 function MyComponent() {
-  const runtime = useAssistantRuntime();
+  const api = useAssistantApi();
   const [isCreativeMode, setIsCreativeMode] = useState(false);
 
   useEffect(() => {
@@ -188,7 +188,7 @@ function MyComponent() {
     });
 
     // Register tools with model configuration
-    return runtime.registerModelContextProvider({
+    return api.modelContext().register({
       getModelContext: () => ({
         tools: { calculate: calculateTool },
         callSettings: {
@@ -198,7 +198,7 @@ function MyComponent() {
         priority: 10, // Higher priority overrides other providers
       }),
     });
-  }, [runtime, isCreativeMode]);
+  }, [api, isCreativeMode]);
 
   return <div>{/* Your component */}</div>;
 }

package/.docs/raw/docs/guides/context-api.mdx

@@ -35,7 +35,7 @@ assistant-ui organizes state into **scopes** - logical boundaries that provide a
         └── ✏️  Composer (composer) - New message input
             └── 📎 Attachment (attachment) - Files being added
 
-🔧 ToolUIs (toolUIs) - Custom UI components for tool calls
+🔧 Tools (tools) - Custom UI components for tool calls
 ```
 
 **How scopes work:**
@@ -212,9 +212,9 @@ api.threadListItem().unarchive();
 api.threadListItem().delete();
 api.threads().getState();
 
-// ToolUIs actions
-api.toolUIs().setToolUI(toolName, render);
-api.toolUIs().getState();
+// Tools actions
+api.tools().setToolUI(toolName, render);
+api.tools().getState();
 ```
 
 ### useAssistantEvent
@@ -272,7 +272,7 @@ Each scope provides access to specific state and actions:
 - **Part** (`part`): Content part within a message (text, tool calls, etc.)
 - **Composer** (`composer`): Text input for sending or editing messages
 - **Attachment** (`attachment`): File or media attached to a message or composer
-- **ToolUIs** (`toolUIs`): Tool UI components
+- **Tools** (`tools`): Tool UI components
 
 ### Scope Resolution
 

package/.docs/raw/docs/migrations/v0-12.mdx

@@ -20,8 +20,8 @@ The following hooks have been removed:
 
 - `useMessageUtils` → Use `useAssistantState(({ message }) => message.isHovering)` / `useAssistantState(({ message }) => message.isCopied)`
 - `useMessageUtilsStore` → Use `useAssistantApi()` with `api.message().setIsHovering()` / `api.message().setIsCopied()`
-- `useToolUIs` → Use `useAssistantState(({ toolUIs }) => toolUIs)` and `useAssistantApi()` with `api.toolUIs()`
-- `useToolUIsStore` → Use `useAssistantApi()` with `api.toolUIs()`
+- `useToolUIs` → Use `useAssistantState(({ tools }) => tools)` and `useAssistantApi()` with `api.tools()`
+- `useToolUIsStore` → Use `useAssistantApi()` with `api.tools()`
 
 **Deprecated Hooks:**
 

package/.docs/raw/docs/runtimes/ai-sdk/use-chat.mdx

@@ -94,10 +94,14 @@ export async function POST(req: Request) {
 
 import { Thread } from "@/components/assistant-ui/thread";
 import { AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
 
 export default function Home() {
-  const runtime = useChatRuntime();
+  const runtime = useChatRuntime({
+    transport: new AssistantChatTransport({
+      api: "/api/chat",
+    }),
+  });
 
   return (
     <AssistantRuntimeProvider runtime={runtime}>

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

@@ -109,6 +109,15 @@ When the hook mounts it calls `list()` on your adapter, hydrates existing thread
       async delete(remoteId) {
         await fetch(`/api/threads/${remoteId}`, { method: "DELETE" });
       },
+      async fetch(remoteId) {
+        const response = await fetch(`/api/threads/${remoteId}`);
+        const thread = await response.json();
+        return {
+          status: thread.is_archived ? "archived" : "regular",
+          remoteId: thread.id,
+          title: thread.title,
+        };
+      },
       async generateTitle(remoteId, messages) {
         return createAssistantStream(async (controller) => {
           const response = await fetch(`/api/threads/${remoteId}/title`, {

package/.docs/raw/docs/runtimes/custom/local.mdx

@@ -538,7 +538,12 @@ export function MyRuntimeProvider({ children }) {
 ```
 
 <Callout type="info" title="Returning a title from generateTitle">
-  The `generateTitle` method must return an <code>AssistantStream</code> containing the title text. The easiest, type-safe way is to use <code>createAssistantStream</code> and call <code>controller.appendText(newTitle)</code> followed by <code>controller.close()</code>. Returning a raw <code>ReadableStream</code> won't update the thread list UI.
+  The `generateTitle` method must return an <code>AssistantStream</code>{" "}
+  containing the title text. The easiest, type-safe way is to use{" "}
+  <code>createAssistantStream</code> and call{" "}
+  <code>controller.appendText(newTitle)</code> followed by{" "}
+  <code>controller.close()</code>. Returning a raw <code>ReadableStream</code>{" "}
+  won't update the thread list UI.
 </Callout>
 
 #### Understanding the Architecture
@@ -854,9 +859,9 @@ function MyCustomRuntimeProvider({ children }) {
 </Callout>
 
 <Callout type="warning">
-  **`useThreadRuntime` vs `useLocalThreadRuntime`:** 
-  - `useThreadRuntime` - Access the current thread's runtime from within components 
-  - `useLocalThreadRuntime` - Create a new single-thread runtime instance
+  **`useThreadRuntime` vs `useLocalThreadRuntime`:** - `useThreadRuntime` -
+  Access the current thread's runtime from within components -
+  `useLocalThreadRuntime` - Create a new single-thread runtime instance
 </Callout>
 
 ## Integration Examples
@@ -999,6 +1004,74 @@ async run({ messages }) {  // ❌ Wrong for streaming
 ```
 </Callout>
 
+### Tool UI Flickers or Disappears During Streaming
+
+A common issue when implementing a streaming `ChatModelAdapter` is seeing a tool's UI appear for a moment and then disappear. This is caused by failing to accumulate the `tool_calls` correctly across multiple stream chunks. State must be stored **outside** the streaming loop to persist.
+
+**❌ Incorrect: Forgetting Previous Tool Calls**
+
+This implementation incorrectly re-creates the `content` array for every chunk. If a later chunk contains only text, tool calls from previous chunks are lost, causing the UI to disappear.
+
+```tsx
+// This implementation incorrectly re-creates the `content` array for every chunk.
+// If a later chunk contains only text, tool calls from previous chunks are lost.
+async *run({ messages, abortSignal, context }) {
+  const stream = await backendApi({ messages, abortSignal, context });
+  let text = "";
+
+  for await (const chunk of stream) {
+    // ❌ DON'T: This overwrites toolCalls with only the current chunk's data
+    const toolCalls = chunk.tool_calls || [];
+    const content = [{ type: "text", text }];
+    for (const toolCall of toolCalls) {
+      content.push({
+        type: "tool-call",
+        toolName: toolCall.name,
+        toolCallId: toolCall.id,
+        args: toolCall.args,
+      });
+    }
+    yield { content }; // This yield might not contain the tool call anymore
+  }
+}
+```
+
+**✅ Correct: Accumulating State**
+
+This implementation uses a `Map` outside the loop to remember all tool calls.
+
+```tsx
+// This implementation uses a Map outside the loop to remember all tool calls.
+async *run({ messages, abortSignal, context }) {
+  const stream = await backendApi({ messages, abortSignal, context });
+  let text = "";
+  // ✅ DO: Declare state outside the loop
+  const toolCallsMap = new Map();
+
+  for await (const chunk of stream) {
+    text += chunk.content || "";
+
+    // ✅ DO: Add/update tool calls in the persistent map
+    for (const toolCall of chunk.tool_calls || []) {
+      toolCallsMap.set(toolCall.toolCallId, {
+        type: "tool-call",
+        toolName: toolCall.name,
+        toolCallId: toolCall.toolCallId,
+        args: toolCall.args,
+      });
+    }
+
+    // ✅ DO: Build content from accumulated state
+    const content = [
+      ...(text ? [{ type: "text", text }] : []),
+      ...Array.from(toolCallsMap.values()),
+    ];
+
+    yield { content }; // Yield the complete, correct state every time
+  }
+}
+```
+
 ### Debug Tips
 
 1. **Log adapter calls** to trace execution: