@assistant-ui/mcp-docs-server 0.1.7 → 0.1.8

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

@@ -414,6 +414,8 @@ import {
   type RemoteThreadListAdapter,
   type ThreadHistoryAdapter,
 } from "@assistant-ui/react";
+import { createAssistantStream } from "assistant-stream";
+import { useMemo } from "react";
 
 // Implement your custom adapter with proper message persistence
 const myDatabaseAdapter: RemoteThreadListAdapter = {
@@ -453,9 +455,16 @@ const myDatabaseAdapter: RemoteThreadListAdapter = {
 
   async generateTitle(remoteId, messages) {
     // Generate title from messages using your AI
-    const title = await generateTitle(messages);
-    await db.threads.update(remoteId, { title });
-    return new ReadableStream(); // Return empty stream
+    const newTitle = await generateTitle(messages);
+
+    // Persist the title in your DB
+    await db.threads.update(remoteId, { title: newTitle });
+
+    // IMPORTANT: Return an AssistantStream so the UI updates
+    return createAssistantStream((controller) => {
+      controller.appendText(newTitle);
+      controller.close();
+    });
   },
 };
 
@@ -528,6 +537,10 @@ 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.
+</Callout>
+
 #### Understanding the Architecture
 
 <Callout type="info">

package/.docs/raw/docs/runtimes/data-stream.mdx

@@ -0,0 +1,287 @@
+---
+title: Data Stream Protocol
+---
+
+import { Step, Steps } from "fumadocs-ui/components/steps";
+import { Callout } from "fumadocs-ui/components/callout";
+
+The `@assistant-ui/react-data-stream` package provides integration with data stream protocol endpoints, enabling streaming AI responses with tool support and state management.
+
+## Overview
+
+The data stream protocol is a standardized format for streaming AI responses that supports:
+
+- **Streaming text responses** with real-time updates
+- **Tool calling** with structured parameters and results
+- **State management** for conversation context
+- **Error handling** and cancellation support
+- **Attachment support** for multimodal interactions
+
+## Installation
+
+```bash npm2yarn
+npm install @assistant-ui/react-data-stream
+```
+
+## Basic Usage
+
+<Steps>
+
+<Step>
+
+### Set up the Runtime
+
+Use `useDataStreamRuntime` to connect to your data stream endpoint:
+
+```tsx title="app/page.tsx"
+"use client";
+import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import { Thread } from "@/components/assistant-ui/thread";
+
+export default function ChatPage() {
+  const runtime = useDataStreamRuntime({
+    api: "/api/chat",
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Step>
+
+<Step>
+
+### Create Backend Endpoint
+
+Your backend endpoint should accept POST requests and return data stream responses:
+
+```typescript title="app/api/chat/route.ts"
+import { DataStreamResponse } from "assistant-stream";
+
+export async function POST(request: Request) {
+  const { messages, tools, system } = await request.json();
+
+  // Process the request with your AI provider
+  const stream = await processWithAI({
+    messages,
+    tools,
+    system,
+  });
+
+  return new DataStreamResponse(stream);
+}
+```
+
+</Step>
+
+</Steps>
+
+## Advanced Configuration
+
+### Custom Headers and Authentication
+
+```tsx
+const runtime = useDataStreamRuntime({
+  api: "/api/chat",
+  headers: {
+    "Authorization": "Bearer " + token,
+    "X-Custom-Header": "value",
+  },
+  credentials: "include",
+});
+```
+
+### Dynamic Headers
+
+```tsx
+const runtime = useDataStreamRuntime({
+  api: "/api/chat",
+  headers: async () => {
+    const token = await getAuthToken();
+    return {
+      "Authorization": "Bearer " + token,
+    };
+  },
+});
+```
+
+### Event Callbacks
+
+```tsx
+const runtime = useDataStreamRuntime({
+  api: "/api/chat",
+  onResponse: (response) => {
+    console.log("Response received:", response.status);
+  },
+  onFinish: (message) => {
+    console.log("Message completed:", message);
+  },
+  onError: (error) => {
+    console.error("Error occurred:", error);
+  },
+  onCancel: () => {
+    console.log("Request cancelled");
+  },
+});
+```
+
+## Tool Integration
+
+### Frontend Tools
+
+Use the `frontendTools` helper to serialize client-side tools:
+
+```tsx
+import { frontendTools } from "@assistant-ui/react-data-stream";
+import { makeAssistantTool } from "@assistant-ui/react";
+
+const weatherTool = makeAssistantTool({
+  toolName: "get_weather",
+  description: "Get current weather",
+  parameters: z.object({
+    location: z.string(),
+  }),
+  execute: async ({ location }) => {
+    const weather = await fetchWeather(location);
+    return `Weather in ${location}: ${weather}`;
+  },
+});
+
+const runtime = useDataStreamRuntime({
+  api: "/api/chat",
+  body: {
+    tools: frontendTools({
+      get_weather: weatherTool,
+    }),
+  },
+});
+```
+
+### Backend Tool Processing
+
+Your backend should handle tool calls and return results:
+
+```typescript title="Backend tool handling"
+// Tools are automatically forwarded to your endpoint
+const { tools } = await request.json();
+
+// Process tools with your AI provider
+const response = await ai.generateText({
+  messages,
+  tools,
+  // Tool results are streamed back automatically
+});
+```
+
+## Assistant Cloud Integration
+
+For Assistant Cloud deployments, use `useCloudRuntime`:
+
+```tsx
+import { useCloudRuntime } from "@assistant-ui/react-data-stream";
+
+const runtime = useCloudRuntime({
+  cloud: assistantCloud,
+  assistantId: "my-assistant-id",
+});
+```
+
+<Callout type="info">
+The `useCloudRuntime` hook is currently under active development and not yet ready for production use.
+</Callout>
+
+## Message Conversion
+
+The package includes utilities for converting between message formats:
+
+```tsx
+import { toLanguageModelMessages } from "@assistant-ui/react-data-stream";
+
+// Convert assistant-ui messages to language model format
+const languageModelMessages = toLanguageModelMessages(messages, {
+  unstable_includeId: true, // Include message IDs
+});
+```
+
+## Error Handling
+
+The runtime automatically handles common error scenarios:
+
+- **Network errors**: Automatically retried with exponential backoff
+- **Stream interruptions**: Gracefully handled with partial content preservation
+- **Tool execution errors**: Displayed in the UI with error states
+- **Cancellation**: Clean abort signal handling
+
+## Best Practices
+
+### Performance Optimization
+
+```tsx
+// Use React.memo for expensive components
+const OptimizedThread = React.memo(Thread);
+
+// Memoize runtime configuration
+const runtimeConfig = useMemo(() => ({
+  api: "/api/chat",
+  headers: { "Authorization": `Bearer ${token}` },
+}), [token]);
+
+const runtime = useDataStreamRuntime(runtimeConfig);
+```
+
+### Error Boundaries
+
+```tsx
+import { ErrorBoundary } from "react-error-boundary";
+
+function ChatErrorFallback({ error, resetErrorBoundary }) {
+  return (
+    <div role="alert">
+      <h2>Something went wrong:</h2>
+      <pre>{error.message}</pre>
+      <button onClick={resetErrorBoundary}>Try again</button>
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <ErrorBoundary FallbackComponent={ChatErrorFallback}>
+      <AssistantRuntimeProvider runtime={runtime}>
+        <Thread />
+      </AssistantRuntimeProvider>
+    </ErrorBoundary>
+  );
+}
+```
+
+### State Persistence
+
+```tsx
+const runtime = useDataStreamRuntime({
+  api: "/api/chat",
+  body: {
+    // Include conversation state
+    state: conversationState,
+  },
+  onFinish: (message) => {
+    // Save state after each message
+    saveConversationState(message.metadata.unstable_state);
+  },
+});
+```
+
+## Examples
+
+- **[Basic Data Stream Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-data-stream)** - Simple streaming chat
+- **[Tool Integration Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-data-stream-tools)** - Frontend and backend tools
+- **[Authentication Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-data-stream-auth)** - Secure endpoints
+
+## API Reference
+
+For detailed API documentation, see the [`@assistant-ui/react-data-stream` API Reference](/docs/api-reference/integrations/react-data-stream).

package/.docs/raw/docs/runtimes/pick-a-runtime.mdx

@@ -48,6 +48,11 @@ For popular frameworks, we provide ready-to-use integrations built on top of our
     description="For useChat and useAssistant hooks - streaming with all major providers"
     href="/docs/runtimes/ai-sdk/use-chat"
   />
+  <Card
+    title="Data Stream Protocol"
+    description="For custom backends using the data stream protocol standard"
+    href="/docs/runtimes/data-stream"
+  />
   <Card
     title="LangGraph"
     description="For complex agent workflows with LangChain's graph framework"

package/.docs/raw/docs/ui/ThreadList.mdx

@@ -3,6 +3,8 @@ title: ThreadList
 ---
 
 import { Steps, Step } from "fumadocs-ui/components/steps";
+import { Callout } from "fumadocs-ui/components/callout";
+import { Tabs, Tab } from "fumadocs-ui/components/tabs";
 import { ThreadListSample } from "../../../components/samples/threadlist-sample";
 
 ## Overview
@@ -11,37 +13,73 @@ The ThreadList component lets the user switch between threads.
 
 <ThreadListSample />
 
+<Callout>
+This demo uses **ThreadListSidebar**, which includes `thread-list` as a dependency and provides a complete sidebar layout. For custom implementations, you can use `thread-list` directly.
+</Callout>
+
 ## Getting Started
 
 <Steps>
   <Step>
 
-### Add `thread-list`
+### Add the component
 
 ```sh
+# Complete thread-list sidebar layout
+npx shadcn@latest add "https://r.assistant-ui.com/threadlist-sidebar"
+
+# Just the thread-list for custom layouts
 npx shadcn@latest add "https://r.assistant-ui.com/thread-list"
 ```
 
-This adds a `/components/assistant-ui/thread-list.tsx` file to your project, which you can adjust as needed.
-
   </Step>
   <Step>
 
 ### Use in your application
 
-```tsx title="/app/page.tsx" {1,5-6}
-import { Thread } from "@/components/assistant-ui/thread";
-import { ThreadList } from "@/components/assistant-ui/thread-list";
-
-export default function Home() {
-  return (
-    <div className="grid h-full grid-cols-[200px_1fr]">
-      <ThreadList />
-      <Thread />
-    </div>
-  );
-}
-```
+<Tabs items={["With Sidebar", "Without Sidebar"]}>
+  <Tab value="With Sidebar">
+    ```tsx title="/app/assistant.tsx"
+    import { Thread } from "@/components/assistant-ui/thread";
+    import { ThreadListSidebar } from "@/components/assistant-ui/threadlist-sidebar";
+    import { 
+      SidebarProvider, 
+      SidebarInset,
+      SidebarTrigger 
+    } from "@/components/ui/sidebar";
+
+    export default function Assistant() {
+      return (
+        <SidebarProvider>
+          <div className="flex h-dvh w-full">
+            <ThreadListSidebar />
+            <SidebarInset>
+              {/* Add sidebar trigger, location can be customized */}
+              <SidebarTrigger className="absolute top-4 left-4" />
+              <Thread />
+            </SidebarInset>
+          </div>
+        </SidebarProvider>
+      );
+    }
+    ```
+  </Tab>
+  <Tab value="Without Sidebar">
+    ```tsx title="/app/assistant.tsx"
+    import { Thread } from "@/components/assistant-ui/thread";
+    import { ThreadList } from "@/components/assistant-ui/thread-list";
+
+    export default function Assistant() {
+      return (
+        <div className="grid h-full grid-cols-[200px_1fr]">
+          <ThreadList />
+          <Thread />
+        </div>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
 
   </Step>
 </Steps>

package/dist/{chunk-L4K23SWI.js → chunk-NVNFQ5ZO.js}

@@ -109,6 +109,9 @@ function sanitizePath(userPath) {
   if (!userPath || typeof userPath !== "string") {
     throw new Error("Invalid path: Path must be a non-empty string");
   }
+  if (userPath.includes("../") || userPath.includes("..\\")) {
+    throw new Error("Invalid path: Directory traversal attempt detected");
+  }
   const normalized = normalize(userPath);
   if (path.isAbsolute(normalized)) {
     throw new Error("Invalid path: Absolute paths are not allowed");
@@ -138,7 +141,7 @@ function sanitizePath(userPath) {
       throw new Error("Invalid path: Hidden files are not allowed");
     }
   }
-  return relativePath;
+  return relativePath.replace(/\\/g, "/");
 }
 
 // src/tools/docs.ts

package/dist/index.js

@@ -1 +1 @@
-export { runServer, server } from './chunk-L4K23SWI.js';
+export { runServer, server } from './chunk-NVNFQ5ZO.js';

package/dist/prepare-docs/prepare.js

@@ -153,7 +153,7 @@ _Note: Additional files truncated due to size limits_
 `;
             break;
           }
-          markdown += `## ${file.path}
+          markdown += `## ${file.path.replace(/\\/g, "/")}
 
 `;
           markdown += `\`\`\`${getFileType(file.path)}

package/dist/stdio.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { runServer } from './chunk-L4K23SWI.js';
+import { runServer } from './chunk-NVNFQ5ZO.js';
 
 // src/stdio.ts
 void runServer().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/mcp-docs-server",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "MCP server for assistant-ui documentation and examples",
   "type": "module",
   "main": "dist/index.js",
@@ -30,7 +30,7 @@
     "access": "public"
   },
   "scripts": {
-    "clean": "rm -rf dist .docs",
+    "clean": "tsx scripts/clean.mts",
     "prepare-docs": "cross-env PREPARE=true node ./dist/prepare-docs/prepare.js",
     "build:cli": "tsup src/stdio.ts src/prepare-docs/prepare.ts src/index.ts --format esm --treeshake=smallest --splitting",
     "build": "pnpm clean && pnpm build:cli && pnpm prepare-docs",

package/.docs/raw/docs/concepts/architecture.mdx

@@ -1,19 +0,0 @@
----
-title: Architecture
----
-
-import Image from "next/image";
-import architecture from "@/assets/docs/architecture.png";
-
-### Architecture
-
-`assistant-ui` consists of two parts, **_Runtime_** and **_UI Components_**.
-
-<Image
-  src={architecture}
-  alt="Architecture diagram, UI components connected to the runtime layer and the runtime layer connected to LLM and tools"
-  height={300}
-  className="mx-auto my-2 dark:hue-rotate-180 dark:invert"
-/>
-
-The Runtime and UI Components each require independent setup and both must be set up.

package/.docs/raw/docs/concepts/runtime-layer.mdx

@@ -1,163 +0,0 @@
----
-title: Runtime Layer
----
-
-assistant-ui components are full stack components. This means that they include both the UI presentation, but also logic to communicate with an external system. This logic is handled by the runtime layer and APIs.
-
-You interact with the runtime layer in two ways:
-
-- defining a runtime for your app
-- using the runtime APIs to interact with the runtime
-
-## Defining a runtime
-
-assistant-ui ships with two low-level runtimes:
-
-- `useLocalRuntime`
-- `useExternalStoreRuntime`
-
-Both of these runtimes let you implement your own runtime. The conceptual difference between the two is that `useLocalRuntime` takes ownership of the data layer, while `useExternalStoreRuntime` does not.
-
-If you have a stateful API to integrate, use `useExternalStoreRuntime`, if you have a stateless API to integrate, use `useLocalRuntime`.
-
-### Higher level runtimes
-
-For many services and APIs, assistant-ui provides deeper integrations. These are built with the two low-level runtimes mentioned above.
-
-- `useChatRuntime`: Connect to Vercel AI SDK backends
-- `useVercelUseChatRuntime`: Integrate with Vercel AI SDK's `useChat` hook
-- `useVercelUseAssistantRuntime`: Integrate with Vercel AI SDK's `useAssistant` hook (OpenAI Assistants API)
-- `useVercelRSCRuntime`: Integrate with Vercel AI SDK React Server Components
-- `useLangGraphRuntime`: Connect to LangGraph Cloud
-- ...
-
-### Runtime Providers
-
-The following components accept a `runtime` prop:
-
-- `AssistantRuntimeProvider`
-- `Thread`
-
-These components put the Runtime in the React Context, so that all child components can access the runtime.
-
-### Runtime Adapters
-
-Most runtimes accept additional adapters to configure extra integrations:
-
-- ChatModelAdapter: Configures the backend API
-- AttachmentAdapter: Configures the file/media attachment API
-- SpeechSynthesisAdapter: Configures the speech API
-- FeedbackAdapter: Configures the feedback API
-- SuggestionAdapter: Configures dynamic suggestion generation based on conversation context
-
-## Using the runtime APIs
-
-The same API used by the assistant-ui components is also available to you. This allows you to build your own UI components and integrate them with the runtime layer.
-
-### Runtime Hierarchy
-
-The runtime API is nested as such:
-
-import { File, Folder, Files } from "fumadocs-ui/components/files";
-
-<Files>
-  <Folder name="AssistantRuntime" defaultOpen>
-    <Folder name="ThreadListRuntime" defaultOpen>
-      <Folder name="ThreadRuntime" defaultOpen>
-        <Folder name="MessageRuntime" defaultOpen>
-          <Folder
-            name="MessagePartRuntime (Text / Reasoning / Image / Audio / Tool-Call / UI)"
-            defaultOpen
-          ></Folder>
-          <Folder name="MessageAttachmentRuntime" defaultOpen></Folder>
-          <Folder name="EditComposerRuntime" defaultOpen>
-            <Folder name="EditComposerAttachmentRuntime" defaultOpen></Folder>
-          </Folder>
-        </Folder>
-        <Folder name="ThreadComposerRuntime" defaultOpen>
-          <Folder name="ThreadComposerAttachmentRuntime" defaultOpen></Folder>
-        </Folder>
-      </Folder>
-    </Folder>
-  </Folder>
-</Files>
-
-The AssistantRuntime (which encompasses everything), is sometimes simply called `Runtime`.
-
-### Runtime Context Provider Components
-
-The following components provide the runtime APIs:
-
-```tsx
-// provides AssistantRuntime, ThreadListRuntime, ThreadRuntime, ComposerRuntime (ThreadComposer)
-<AssistantRuntimeProvider runtime={runtime} />
-
-// renders every message, provides MessageRuntime, ComposerRuntime (EditComposer)
-<ThreadPrimitive.Messages components={{ Message, ... }} />
-
-// renders every message part, provides MessagePartRuntime
-<MessagePrimitive.Parts components={{ Text, Reasoning, Image, Audio, UI, tools }} />
-
-// renders every attachment, provides AttachmentRuntime (Thread or EditComposer)
-<ComposerPrimitive.Attachments components={{ Attachment, ... }} />
-
-// renders every attachment, provides AtatchmentRuntime (Message)
-<MessagePrimitive.Attachments components={{ Attachment, ... }} />
-
-// provides a custom TextMessagePartRuntime
-<TextMessagePartProvider text="Hello!" />
-```
-
-### Accessing runtime APIs
-
-You can access the runtime APIs with react hooks:
-
-```tsx
-const runtime = useAssistantRuntime();
-const threadRuntime = useThreadRuntime();
-const messageRuntime = useMessageRuntime();
-const MessagePartRuntime = useMessagePartRuntime();
-
-// thread manager has no separate hook (1:1 relationship with assistant runtime)
-const ThreadListRuntime = useAssistantRuntime().threads;
-
-// composer runtime is multi-use
-const composerRuntime = useComposerRuntime(); // refers to edit composer if available, otherwise thread composer
-
-// thread manager has no separate hook (1:1 relationship with assistant runtime)
-const threadComposer = useThreadRuntime().composer;
-
-// thread manager has no separate hook (1:1 relationship with assistant runtime)
-const editComposerRuntime = useMessageRuntime().composer;
-
-// attachment runtime is multi-use
-const attachmentRuntime = useAttachmentRuntime(); // refers to the closest attachment runtime
-const threadComposerAttachmentRuntime = useThreadComposerAttachmentRuntime();
-const editComposerAttachmentRuntime = useEditComposerAttachmentRuntime();
-const messageAttachmentRuntime = useMessageAttachmentRuntime();
-```
-
-### Accessing runtime state
-
-Most runtimes also expose a state through two methods `getState` and `subscribe`. The following helper hooks subscribe to the state, so that your component is updated when the state changes:
-
-```tsx
-useThreadList(); // get thread manager state
-useThread(); // get thread state
-useMessage(); // get message state
-useMessagePart(); // get message part state
-useComposer(); // get composer state
-useThreadComposer(); // get thread composer state
-useEditComposer(); // get edit composer state
-useAttachment(); // get attachment state
-useThreadComposerAttachment(); // get thread composer attachment state
-useEditComposerAttachment(); // get edit composer attachment state
-useMessageAttachment(); // get message attachment state
-```
-
-You might not want to subscribe to evey update. In that case, pass a callback selector to the hook:
-
-```tsx
-// only subscribe to role changes
-const role = useMessage((state) => message.role);
-```

package/.docs/raw/docs/concepts/why.mdx

@@ -1,9 +0,0 @@
----
-title: Why assistant-ui?
----
-
-assistant-ui is a collection of powerful, modular primitives to build AI chat interfaces.
-
-The modular approach means that you can incrementally adopt assistant-ui (e.g. use the backend connectors and bring your own components, or use the frontend compoents and bring your own backend).
-You can also partially opt out of assistant-ui whenever you hit any limitation in the library.
-