@assistant-ui/mcp-docs-server 0.2.3 → 0.3.1

package/.docs/raw/docs/guides/suggestions.mdx

@@ -1,384 +0,0 @@
----
-title: Suggested Prompts
-description: Display suggested starter prompts in your AI chat to onboard users faster. Configurable suggestion components for React, built into assistant-ui.
-platforms: ["react"]
----
-
-Suggestions are pre-defined prompts that help users discover what your assistant can do. They appear in the welcome screen and provide a quick way to start conversations.
-
-## Overview
-
-The Suggestions API allows you to configure a list of suggested prompts that are displayed when the thread is empty. Users can click on a suggestion to either populate the composer or immediately send the message.
-
-## Quick Start
-
-Configure suggestions using the `Suggestions()` API in your runtime provider:
-
-```tsx
-import { AuiConfig, Tools, Suggestions } from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/ai-sdk";
-
-function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
-  const runtime = useChatRuntime();
-
-  const config = AuiConfig({
-    tools: Tools({ toolkit: myToolkit }),
-    suggestions: Suggestions([
-      "What can you help me with?",
-      "Tell me a joke",
-      "Explain quantum computing",
-    ]),
-  });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime} config={config}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-## Suggestion Format
-
-Suggestions can be provided as either strings or objects with title, label, and prompt:
-
-### Simple Strings
-
-```tsx
-AuiConfig({
-  suggestions: Suggestions([
-    "What's the weather today?",
-    "Help me write an email",
-    "Explain React hooks",
-  ]),
-});
-```
-
-### Objects with Title and Description
-
-For more detailed suggestions with separate display text and prompts:
-
-```tsx
-AuiConfig({
-  suggestions: Suggestions([
-    {
-      title: "Weather",
-      label: "in San Francisco",
-      prompt: "What's the weather in San Francisco?",
-    },
-    {
-      title: "React Hooks",
-      label: "useState and useEffect",
-      prompt: "Explain React hooks like useState and useEffect",
-    },
-    {
-      title: "Travel Tips",
-      label: "for Tokyo",
-      prompt: "Give me travel tips for visiting Tokyo",
-    },
-  ]),
-});
-```
-
-## Displaying Suggestions
-
-The default Thread component from the shadcn registry already includes suggestion rendering. The suggestions are displayed in the welcome screen when the thread is empty.
-
-### Customizing Suggestion Display
-
-If you want to customize how suggestions are displayed, you can modify your Thread component. The idiomatic pattern is to wrap the suggestions in `AuiIf` so they only appear when the thread is empty:
-
-```tsx
-import {
-  ThreadPrimitive,
-  SuggestionPrimitive,
-  AuiIf,
-} from "@assistant-ui/react";
-
-const ThreadWelcome = () => {
-  return (
-    <AuiIf condition={(s) => s.thread.isEmpty}>
-      <div className="flex flex-col items-center justify-center">
-        <h1>Welcome!</h1>
-        <p>How can I help you today?</p>
-
-        <div className="grid grid-cols-2 gap-2">
-          <ThreadPrimitive.Suggestions>
-            {() => <SuggestionItem />}
-          </ThreadPrimitive.Suggestions>
-        </div>
-      </div>
-    </AuiIf>
-  );
-};
-
-const SuggestionItem = () => {
-  return (
-    <SuggestionPrimitive.Trigger send asChild>
-      <button className="rounded-lg border p-3 hover:bg-muted">
-        <div className="font-medium">
-          <SuggestionPrimitive.Title />
-        </div>
-        <div className="text-muted-foreground text-sm">
-          <SuggestionPrimitive.Description />
-        </div>
-      </button>
-    </SuggestionPrimitive.Trigger>
-  );
-};
-```
-
-### Dismissal
-
-Suggestions dismiss automatically once the user sends a message because `thread.isEmpty` becomes false. No extra state management is needed. If you want to dismiss suggestions without sending (for example, after a user clicks away), manage a local boolean and combine it with the `AuiIf` condition or a plain conditional render.
-
-## Suggestion Primitives
-
-The primitives available for rendering suggestions are `ThreadPrimitive.Suggestions`, `ThreadPrimitive.SuggestionByIndex`, `SuggestionPrimitive.Title`, `SuggestionPrimitive.Description`, and `SuggestionPrimitive.Trigger`. `ThreadPrimitive.SuggestionByIndex` is useful when you need layout control over a specific suggestion slot rather than iterating all of them. For the full prop reference and usage patterns, see the [Suggestion primitive docs](/docs/primitives/suggestion).
-
-## Runtime driven suggestions
-
-The static `Suggestions(...)` API covers welcome screens. For follow up prompts that depend on the conversation, a tool result, or your backend, push suggestions through the runtime itself. They land on `thread.suggestions`, and when no static `Suggestions(...)` configuration is set, the `suggestions` scope derives from them, so `ThreadPrimitive.Suggestions` renders them as well. Runtime suggestions use the `ThreadSuggestion` shape: a required `prompt` plus optional `title` and `label`. When `title` is omitted it falls back to the prompt, and an omitted `label` renders as empty, so a prompt-only runtime suggestion looks exactly like a plain string suggestion.
-
-### Local runtime: `SuggestionAdapter`
-
-Pass a `suggestion` adapter to `useLocalRuntime`. Its `generate` function runs after every assistant turn and may return a promise or an async generator for streaming updates.
-
-```tsx
-import { useLocalRuntime, type SuggestionAdapter } from "@assistant-ui/react";
-
-const suggestionAdapter: SuggestionAdapter = {
-  async generate({ messages }) {
-    const response = await fetch("/api/follow-ups", {
-      method: "POST",
-      body: JSON.stringify({ messages }),
-    });
-    const data: { prompt: string }[] = await response.json();
-    return data;
-  },
-};
-
-const runtime = useLocalRuntime(myChatModel, {
-  adapters: { suggestion: suggestionAdapter },
-});
-```
-
-For LLM-powered follow ups, use `createSuggestionAdapter`. It builds a deterministic transcript prompt from recent messages and calls your `complete` function. Forward the optional `signal` so in-flight generation can be cancelled when a new run starts.
-
-```tsx
-import { createSuggestionAdapter, useLocalRuntime } from "@assistant-ui/react";
-
-const suggestionAdapter = createSuggestionAdapter({
-  async complete({ prompt, signal }) {
-    const response = await fetch("/api/suggestions", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ prompt }),
-      signal,
-    });
-    const data: string[] = await response.json();
-    return data;
-  },
-  count: 3,
-});
-
-const runtime = useLocalRuntime(myChatModel, {
-  adapters: { suggestion: suggestionAdapter },
-});
-```
-
-### External store runtime
-
-`useExternalStoreRuntime` exposes a `suggestions` field, so you can drive follow ups straight from your application state.
-
-```tsx
-const [suggestions, setSuggestions] = useState<ThreadSuggestion[]>([]);
-
-const runtime = useExternalStoreRuntime({
-  messages,
-  onNew,
-  suggestions,
-});
-
-// Push a follow up after a tool result, a stream chunk, or any app event.
-setSuggestions([{ prompt: "Summarize this case" }]);
-```
-
-### AI SDK runtime
-
-`useChatRuntime` and `useAISDKRuntime` accept the same `suggestions` field and forward it to the underlying external store.
-
-```tsx
-const [suggestions, setSuggestions] = useState<ThreadSuggestion[]>([]);
-
-const runtime = useChatRuntime({ suggestions });
-```
-
-They also accept the same `suggestion` adapter as the local runtime under `adapters`, so one adapter works across both runtimes. When set, the adapter owns `thread.suggestions` after each run settles, and any static `suggestions` option is ignored. Pair it with `createSuggestionAdapter` for built-in prompt construction:
-
-```tsx
-import { createSuggestionAdapter } from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/ai-sdk";
-
-const runtime = useChatRuntime({
-  adapters: {
-    suggestion: createSuggestionAdapter({
-      async complete({ prompt, signal }) {
-        const response = await fetch("/api/suggestions", {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ prompt }),
-          signal,
-        });
-        return response.json();
-      },
-    }),
-  },
-});
-```
-
-Example route that returns suggestion strings with the AI SDK:
-
-```ts
-// app/api/suggestions/route.ts
-import { generateObject } from "ai";
-import { z } from "zod";
-
-export async function POST(req: Request) {
-  const { prompt } = await req.json();
-
-  const { object } = await generateObject({
-    model: yourModel,
-    schema: z.object({
-      suggestions: z.array(z.string()).min(1).max(5),
-    }),
-    prompt,
-  });
-
-  return Response.json(object.suggestions);
-}
-```
-
-The local runtime clears its suggestions when a new run starts. External store runtimes keep whatever state you push, so you control the lifetime. With `adapters.suggestion` on the AI SDK runtime, suggestions clear on run start and regenerate after settle, matching the local runtime.
-
-### Rendering runtime suggestions
-
-Runtime suggestions land on `thread.suggestions`, and `ThreadPrimitive.Suggestions` picks them up unless a static `Suggestions(...)` configuration overrides the scope. The shadcn registry ships `ThreadFollowupSuggestions` for the common single line pill layout. For a custom layout, read the array yourself:
-
-```tsx
-import { useAuiState, ThreadPrimitive, AuiIf } from "@assistant-ui/react";
-
-function FollowUps() {
-  const suggestions = useAuiState((s) => s.thread.suggestions);
-  return (
-    <AuiIf condition={(s) => !s.thread.isEmpty && !s.thread.isRunning}>
-      <div className="flex gap-2">
-        {suggestions.map((s, i) => (
-          <ThreadPrimitive.Suggestion
-            key={i}
-            prompt={s.prompt}
-            method="replace"
-            autoSend
-          >
-            {s.title ?? s.prompt}
-            {s.label && (
-              <span className="text-muted-foreground ms-1">{s.label}</span>
-            )}
-          </ThreadPrimitive.Suggestion>
-        ))}
-      </div>
-    </AuiIf>
-  );
-}
-```
-
-## Reacting to application state
-
-You can dynamically change the static suggestion list based on your application state:
-
-```tsx
-import { useMemo } from "react";
-
-function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
-  const runtime = useChatRuntime();
-  const user = useUser(); // Your user hook
-
-  const suggestions = useMemo(() => {
-    if (user.isPremium) {
-      return [
-        "Analyze my business data",
-        "Generate a detailed report",
-        "Create a custom workflow",
-      ];
-    }
-    return [
-      "What can you do?",
-      "Tell me a joke",
-      "Help me get started",
-    ];
-  }, [user.isPremium]);
-
-  const config = AuiConfig({
-    tools: Tools({ toolkit: myToolkit }),
-    suggestions: Suggestions(suggestions),
-  });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime} config={config}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-## Best Practices
-
-1. **Keep suggestions concise**: Use clear, actionable prompts that users can understand at a glance
-2. **Show capabilities**: Use suggestions to highlight your assistant's key features
-3. **Provide variety**: Offer suggestions across different use cases
-4. **Use the object format for complex suggestions**: When you need separate title/description, use the object format
-5. **Limit the number**: 3-6 suggestions work best to avoid overwhelming users
-6. **Make them actionable**: Each suggestion should lead to a meaningful interaction
-
-## Switching from `ThreadPrimitive.Suggestion`
-
-If your codebase uses the inline `ThreadPrimitive.Suggestion` component (which renders one suggestion at a time with hardcoded `prompt` / `send` props), you can move to the runtime-driven `Suggestions()` API for centralized configuration. The inline component is still supported, but the runtime-driven approach scales better when suggestions need to update dynamically.
-
-### Inline form
-
-```tsx
-<ThreadPrimitive.Suggestion
-  prompt="What's the weather?"
-  send
-/>
-```
-
-### Runtime-driven form
-
-1. Configure suggestions in your runtime provider's `config`:
-
-```tsx
-AuiConfig({
-  suggestions: Suggestions(["What's the weather?"]),
-});
-```
-
-2. Display suggestions using the primitives:
-
-```tsx
-<ThreadPrimitive.Suggestions>
-  {() => <SuggestionItem />}
-</ThreadPrimitive.Suggestions>
-```
-
-The new API provides:
-- **Centralized configuration**: Define suggestions once in your runtime provider
-- **Better separation of concerns**: Configuration separate from presentation
-- **Type safety**: Full TypeScript support
-- **Consistency**: Follows the same pattern as the Tools API
-
-## Related
-
-- [Thread Component](/docs/ui/thread) - Main chat interface
-- [Tools Guide](/docs/tools/defining-tools) - Configure assistant actions
-- [Context API](/docs/guides/context-api) - Access assistant state

package/.docs/raw/docs/guides/virtualization.mdx

@@ -1,133 +0,0 @@
----
-title: Thread Virtualization
-description: Render very long threads with @tanstack/react-virtual, with ThreadPrimitive.Unstable_MessageById and ThreadPrimitive.MessageByIndex.
-platforms: ["react"]
----
-
-Virtualization mounts only the messages near the viewport and represents the rest as empty space, so a thread with thousands of messages scrolls like one with twenty. assistant-ui does not ship a virtualized thread component; this guide shows the supported composition, extracted from a production consumer and available as a runnable example: [`examples/with-virtualized-thread`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-virtualized-thread).
-
-## Do you need this?
-
-Probably not. The default kit already renders message bodies with `content-visibility: auto` and `contain-intrinsic-size`, which skips paint work for off-screen messages, and `ThreadPrimitive.Viewport` handles auto-scroll. That covers typical threads. Reach for virtualization when React mount and update cost itself becomes the bottleneck: threads with hundreds to thousands of messages, or very heavy per-message content, where typing latency degrades because every message stays mounted.
-
-## Rendering Messages By Id
-
-For virtualized rows, use message ids as the row identity. `unstable_useThreadMessageIds` returns the thread's ids with stable array identity across content-only updates, and `ThreadPrimitive.Unstable_MessageById` renders one message with the same `components` surface as `MessageByIndex`. Unknown ids render `null`, which is useful when a virtual row unmounts after a message was removed.
-
-```tsx
-const MESSAGE_COMPONENTS = { UserMessage, AssistantMessage };
-
-const messageIds = unstable_useThreadMessageIds();
-
-return messageIds.map((messageId) => (
-  <ThreadPrimitive.Unstable_MessageById
-    key={messageId}
-    messageId={messageId}
-    components={MESSAGE_COMPONENTS}
-  />
-));
-```
-
-<Callout type="warn">
-  `unstable_useThreadMessageIds` and `ThreadPrimitive.Unstable_MessageById` are
-  experimental and may change in any release.
-</Callout>
-
-## Rendering Messages By Index
-
-`ThreadPrimitive.MessageByIndex` is still supported and is the smaller API when
-you already have a stable index from a fixed-order list. It renders a single
-message at that index and memoizes on the index plus the per-field `components`
-identity:
-
-```tsx
-const MESSAGE_COMPONENTS = { UserMessage, AssistantMessage };
-
-<ThreadPrimitive.MessageByIndex index={index} components={MESSAGE_COMPONENTS} />;
-```
-
-For virtualizers, prefer the id-based API above when you can. Index rows are more
-fragile when messages are inserted, removed, reordered, or when a virtual row
-briefly outlives the item it was created for.
-
-## Grouping into turns
-
-The example virtualizes per user turn (a user message plus the responses that follow it), which gives the virtualizer stable, meaningfully sized items. Keep the id and role together in a stable row shape so the turn array only rebuilds when message membership or roles change:
-
-```tsx
-type MessageRow = {
-  id: string;
-  role: "user" | "assistant" | "system";
-};
-
-const useThreadMessageRows = (): readonly MessageRow[] => {
-  const prevRowsRef = useRef<readonly MessageRow[]>([]);
-
-  return useAuiState((s) => {
-    const messages = s.thread.messages;
-    const prev = prevRowsRef.current;
-    if (
-      prev.length === messages.length &&
-      prev.every((row, index) => {
-        const message = messages[index]!;
-        return row.id === message.id && row.role === message.role;
-      })
-    ) {
-      return prev;
-    }
-
-    const next = messages.map(({ id, role }) => ({ id, role }));
-    prevRowsRef.current = next;
-    return next;
-  });
-};
-
-const messageRows = useThreadMessageRows();
-const turns = useMemo(
-  () => buildTurns(messageRows),
-  [messageRows],
-);
-```
-
-Then each virtual turn renders the ids it owns:
-
-```tsx
-{turn.messageIds.map((messageId) => (
-  <ThreadPrimitive.Unstable_MessageById
-    key={messageId}
-    messageId={messageId}
-    components={MESSAGE_COMPONENTS}
-  />
-))}
-```
-
-## Padding spacers, not absolute positioning
-
-Render the virtual items in normal document flow inside a spacer div whose `paddingTop`/`paddingBottom` represent the unmounted regions. Items remain regular flow children, so message CSS (including `position: sticky` patterns and the kit styling) keeps working, and `virtualizer.measureElement` records real heights as items mount:
-
-```tsx
-const items = virtualizer.getVirtualItems();
-const paddingTop = items[0]?.start ?? 0;
-const paddingBottom = Math.max(
-  0,
-  virtualizer.getTotalSize() - (items.at(-1)?.end ?? 0),
-);
-```
-
-## Owning the scroll element
-
-The composition owns its scroll container instead of using `ThreadPrimitive.Viewport`: the built-in auto-scroll assumes every message is mounted, and its resize-driven re-pin can fight the virtualizer's measurement adjustments. Three pieces replace it:
-
-1. **Auto-follow.** A ResizeObserver on the content wrapper re-pins the scroller to the bottom while a sticky flag is armed. The flag disarms when the user scrolls up (detected as `scrollTop` decreasing while `scrollHeight` and `clientHeight` are stable, the same heuristic the built-in viewport uses, plus wheel-up and touchmove) and re-arms when the user returns to the bottom.
-2. **Measurement guard.** While pinned at the bottom, the virtualizer's own scroll adjustments on item re-measurement are suppressed via a custom `scrollToFn`; without this the two scroll writers fight and the view rubber-bands during streaming.
-3. **Run-start jump.** A `useLayoutEffect` observes `s.thread.isRunning` flipping to true and jumps to the bottom before paint, so a just-sent message never flashes below the fold. The `thread.runStart` event is deprecated; deriving the transition from state is the supported path.
-
-The production consumer this is extracted from disables streaming auto-follow entirely as a product choice; the example keeps following because it matches `ThreadPrimitive.Viewport`'s default behavior. Both are valid, and the disarm guard makes either safe.
-
-## Try it
-
-```sh
-npx assistant-ui@latest create my-app
-```
-
-Then copy `app/VirtualizedThread.tsx`, `app/MyRuntimeProvider.tsx`, and `app/seed-messages.ts` from [the example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-virtualized-thread), or clone the repo and run `pnpm --filter with-virtualized-thread dev`.