@assistant-ui/mcp-docs-server 0.1.23 → 0.1.25

package/.docs/raw/docs/(docs)/guides/quoting.mdx

@@ -1,113 +1,35 @@
 ---
 title: Quote Selected Text
-description: Let users select and quote text from messages, similar to Claude's quoting experience.
+description: Let users select and quote text from messages. Full guide including backend handling and programmatic API.
 ---
 
-Allow users to select text in assistant messages and reply with a quote reference — just like Claude, ChatGPT, and other modern AI interfaces.
+import { QuoteComposerSample } from "@/components/docs/samples/quote-composer";
 
-## How It Works
-
-1. User selects text in a message
-2. A floating toolbar appears near the selection with a **Quote** button
-3. User clicks it — a quote preview appears in the composer
-4. User types their reply and sends
-5. The sent message displays the quoted text above the user's reply
+<QuoteComposerSample />
 
-Quote data is stored in `metadata.custom.quote` and is **not** injected into message content. Your backend decides how to present the quoted context to the LLM.
+## Get Started
 
-## Quick Start
+The **[Quote](/docs/ui/quote)** registry component gives you everything you need out of the box, including a floating selection toolbar, composer quote preview, and inline quote display.
 
-### 1. Add the Floating Selection Toolbar
+<InstallCommand shadcn={["quote"]} />
 
-Place `SelectionToolbarPrimitive` inside your `ThreadPrimitive.Root`. It renders a floating toolbar near the user's text selection — only when text is selected within a message.
+It ships three composable pieces:
 
-```tsx {1,13-20}
-import { SelectionToolbarPrimitive, ThreadPrimitive } from "@assistant-ui/react";
-import { QuoteIcon } from "lucide-react";
+- **QuoteBlock** renders quoted text inline in user messages
+- **SelectionToolbar** is a floating toolbar that appears on text selection
+- **ComposerQuotePreview** shows the pending quote inside the composer
 
-const Thread = () => {
-  return (
-    <ThreadPrimitive.Root>
-      <ThreadPrimitive.Viewport>
-        <ThreadPrimitive.Messages components={{ ... }} />
-        ...
-      </ThreadPrimitive.Viewport>
-
-      {/* Floating toolbar — appears on text selection */}
-      <SelectionToolbarPrimitive.Root className="flex items-center gap-1 rounded-lg border bg-popover px-1 py-1 shadow-md">
-        <SelectionToolbarPrimitive.Quote className="flex items-center gap-1.5 rounded-md px-2.5 py-1 text-sm hover:bg-accent">
-          <QuoteIcon className="size-3.5" />
-          Quote
-        </SelectionToolbarPrimitive.Quote>
-      </SelectionToolbarPrimitive.Root>
-    </ThreadPrimitive.Root>
-  );
-};
-```
+See the [Quote component page](/docs/ui/quote) for full setup steps and API reference.
 
-The `Root` component:
-- Listens for `mouseup` and `keyup` events to detect text selections
-- Validates the selection is within a single message (cross-message selections are ignored)
-- Renders a portal positioned above the selection
-- Prevents `mousedown` from clearing the selection when clicking the toolbar
-- Hides automatically on scroll or when the selection is cleared
-
-### 2. Show Quote Preview in Composer
-
-Add `ComposerPrimitive.Quote` inside the composer to show what's being quoted:
-
-```tsx {1,8-13}
-import { ComposerPrimitive } from "@assistant-ui/react";
-
-const Composer = () => {
-  return (
-    <ComposerPrimitive.Root>
-      {/* Quote preview — only renders when a quote is set */}
-      <ComposerPrimitive.Quote className="flex items-start gap-2 border-l-4 border-primary/40 bg-muted/50 px-3 py-2 text-sm">
-        <ComposerPrimitive.QuoteText className="line-clamp-2 flex-1 italic text-muted-foreground" />
-        <ComposerPrimitive.QuoteDismiss>
-          ×
-        </ComposerPrimitive.QuoteDismiss>
-      </ComposerPrimitive.Quote>
-
-      <ComposerPrimitive.Input placeholder="Send a message..." />
-      <ComposerPrimitive.Send />
-    </ComposerPrimitive.Root>
-  );
-};
-```
-
-### 3. Display Quotes in Sent Messages
-
-Use `useMessageQuote()` to render quoted text in user messages:
-
-```tsx {1,4-5,11}
-import { MessagePrimitive, useMessageQuote } from "@assistant-ui/react";
-
-const QuoteBlock = () => {
-  const quote = useMessageQuote();
-  if (!quote) return null;
+---
 
-  return (
-    <div className="mb-1 border-l-4 border-primary/40 pl-3 text-xs italic text-muted-foreground">
-      {quote.text}
-    </div>
-  );
-};
+## How It Works
 
-const UserMessage = () => {
-  return (
-    <MessagePrimitive.Root>
-      <QuoteBlock />
-      <MessagePrimitive.Parts />
-    </MessagePrimitive.Root>
-  );
-};
-```
+When a user selects text in an assistant message, a floating toolbar appears with a Quote button. Clicking it calls `composer.setQuote()` to store the selection on the composer. The [Quote component](/docs/ui/quote) does this out of the box.
 
-## Backend Handling
+When the message is sent, the composer runtime automatically writes the quote to `message.metadata.custom.quote` and clears it from the composer.
 
-The quote is stored in message metadata — **not** in message content. This gives your backend full control over how to present quoted context to the LLM.
+On the backend, the route handler extracts the quote from metadata and surfaces it to the LLM. We export a helper called `injectQuoteContext` that handles this automatically for AI-SDK. Without this step, the quote appears in the UI but is not sent to the model as context. See [Backend Handling](#backend-handling) for more info and alternatives.
 
 ### Data Shape
 
@@ -120,57 +42,15 @@ type QuoteInfo = {
 // Stored at: message.metadata.custom.quote
 ```
 
-### Example: Prepend as Markdown Blockquote
-
-A simple approach is to prepend the quoted text as a `>` blockquote before converting to model messages:
-
-```typescript title="app/api/chat/route.ts" {1,9}
-import { convertToModelMessages, streamText } from "ai";
-import type { UIMessage } from "ai";
-
-export async function POST(req: Request) {
-  const { messages } = await req.json();
-
-  const result = streamText({
-    model: myModel,
-    messages: await convertToModelMessages(injectQuoteContext(messages)),
-  });
-
-  return result.toUIMessageStreamResponse();
-}
+## Backend Handling
 
-function injectQuoteContext(messages: UIMessage[]): UIMessage[] {
-  return messages.map((msg) => {
-    const quote = (msg.metadata as Record<string, unknown>)?.custom;
-    if (
-      !quote ||
-      typeof quote !== "object" ||
-      !("quote" in (quote as Record<string, unknown>))
-    )
-      return msg;
-
-    const q = (quote as Record<string, unknown>).quote;
-    if (
-      !q ||
-      typeof q !== "object" ||
-      !("text" in (q as Record<string, unknown>))
-    )
-      return msg;
-
-    const text = (q as { text: unknown }).text;
-    if (typeof text !== "string") return msg;
+Quote data travels in message metadata, not content, so the LLM will not see it unless your backend extracts and surfaces it. The simplest path is [`injectQuoteContext`](/docs/ui/quote#forward-quote-context-to-the-llm), which prepends quoted text as a markdown blockquote before the message parts.
 
-    return {
-      ...msg,
-      parts: [{ type: "text" as const, text: `> ${text}\n\n` }, ...msg.parts],
-    };
-  });
-}
-```
+For provider-specific handling, work with the quote metadata directly.
 
-### Example: Claude-Style Citation Source
+### Claude SDK Citations
 
-For Claude's API, you can pass the quoted text as a citation source. This enables Claude to produce citations that reference the quoted text:
+Pass the quoted text as a citation source so Claude produces citations that reference it:
 
 ```typescript title="app/api/chat/route.ts"
 import Anthropic from "@anthropic-ai/sdk";
@@ -180,7 +60,6 @@ const client = new Anthropic();
 export async function POST(req: Request) {
   const { messages } = await req.json();
 
-  // Transform messages: extract quotes into Claude source blocks
   const claudeMessages = messages.map((msg) => {
     const quote = msg.metadata?.custom?.quote;
     if (!quote?.text) {
@@ -205,7 +84,7 @@ export async function POST(req: Request) {
   });
 
   const response = await client.messages.create({
-    model: "claude-sonnet-4-5-20250929",
+    model: "claude-sonnet-4-6",
     max_tokens: 1024,
     messages: claudeMessages,
   });
@@ -214,9 +93,9 @@ export async function POST(req: Request) {
 }
 ```
 
-### Example: OpenAI-Style System Context
+### OpenAI Message Context
 
-For OpenAI's API, inject the quote as additional context in the user message:
+Inject the quote as additional context in the user message:
 
 ```typescript title="app/api/chat/route.ts"
 function injectQuoteForOpenAI(messages) {
@@ -232,9 +111,28 @@ function injectQuoteForOpenAI(messages) {
 }
 ```
 
+## Reading Quote Data
+
+Use `useMessageQuote` to access quote data in custom components:
+
+```tsx
+import { useMessageQuote } from "@assistant-ui/react";
+
+function CustomQuoteDisplay() {
+  const quote = useMessageQuote();
+  if (!quote) return null;
+
+  return (
+    <blockquote className="border-l-2 pl-3 text-sm text-muted-foreground">
+      {quote.text}
+    </blockquote>
+  );
+}
+```
+
 ## Programmatic API
 
-You can set or clear quotes programmatically via the composer runtime:
+Set or clear quotes via the composer runtime:
 
 ```tsx
 import { useAui } from "@assistant-ui/react";
@@ -243,14 +141,14 @@ function MyComponent() {
   const aui = useAui();
 
   const quoteText = () => {
-    aui.thread().composer.setQuote({
+    aui.thread().composer().setQuote({
       text: "The text to quote",
       messageId: "msg-123",
     });
   };
 
   const clearQuote = () => {
-    aui.thread().composer.setQuote(undefined);
+    aui.thread().composer().setQuote(undefined);
   };
 
   return (
@@ -262,66 +160,17 @@ function MyComponent() {
 }
 ```
 
-## API Reference
-
-### SelectionToolbarPrimitive.Root
-
-A floating container that appears when text is selected within a message. Renders as a portal positioned above the selection.
-
-- Listens for `mouseup` / `keyup` to detect selection
-- Validates selection is within a single message
-- Hides on scroll or when selection is cleared
-- Prevents `mousedown` from clearing the selection
-- Provides selection context to child components
-
-### SelectionToolbarPrimitive.Quote
-
-A button inside the floating toolbar that captures the selection as a quote.
-
-- Reads selection info from the toolbar context (not `window.getSelection()`)
-- Stores `{ text, messageId }` in the thread composer
-- Clears the text selection after quoting
-
-### ComposerPrimitive.Quote
-
-A container that only renders when a quote is set.
-
-### ComposerPrimitive.QuoteText
-
-Renders the quoted text. Defaults to `<span>`.
-
-### ComposerPrimitive.QuoteDismiss
-
-A button that clears the quote by calling `setQuote(undefined)`. Supports `asChild`.
-
-### useMessageQuote()
-
-```tsx
-const quote: QuoteInfo | undefined = useMessageQuote();
-```
-
-Returns the quote attached to the current message, or `undefined`.
-
-### ComposerRuntime.setQuote()
-
-```tsx
-setQuote(quote: QuoteInfo | undefined): void
-```
-
-Set or clear the quote on the composer. The quote is automatically cleared when the message is sent.
-
 ## Design Notes
 
-- **Single quote** — `setQuote` replaces, not appends. Only one quote at a time.
-- **Snapshot text** — The selected text is captured at quote time, not linked to the source message.
-- **Cross-message selection** — Rejected. The toolbar only appears when the selection is within a single message.
-- **Streaming messages** — The floating toolbar works during streaming since it reads from the captured selection, not message status.
-- **`isEmpty` unchanged** — A quote alone doesn't make the composer non-empty. The user must type a reply.
-- **Scroll hides toolbar** — The floating toolbar hides when any scroll event occurs, since the position would become stale.
+- **Single quote:** `setQuote` replaces the current quote instead of appending. Only one quote can be active at a time.
+- **Snapshot text:** The selected text is captured when the quote is created and is not linked to the source message afterward.
+- **Cross-message selection:** The toolbar only appears when the selection stays within a single message.
+- **Streaming messages:** The toolbar still works while a message is streaming because it relies on the captured selection rather than message status.
+- **`isEmpty` unchanged:** A quote by itself does not make the composer non-empty. The user still needs to type a reply.
+- **Scroll hides toolbar:** The toolbar hides on scroll because its position would otherwise become stale.
 
 ## Related
 
-- [Message Editing](/docs/guides/editing) — Edit user messages
-- [Thread Component](/docs/ui/thread) — Main chat container
-- [ComposerPrimitive](/docs/reference/primitives/Composer) — Composer primitive reference
-- [ActionBarPrimitive](/docs/reference/primitives/ActionBar) — Action bar primitive reference
+- [Quote component](/docs/ui/quote): Installation, component setup, and API reference
+- [Message Editing](/docs/guides/editing): Edit user messages
+- [Thread](/docs/ui/thread): Main chat container

package/.docs/raw/docs/(docs)/guides/speech.mdx

@@ -21,10 +21,7 @@ Passing a `SpeechSynthesisAdapter` to the runtime will enable text-to-speech sup
 
 ## UI
 
-By default, a `Read aloud` button will be shown in the assistant message action bar.
-
-This is implemented using `AssistantActionBar.SpeechControl` which is a wrapper around `AssistantActionBar.Speak` and `AssistantActionBar.StopSpeaking`.
-The underlying primitives are `ActionBarPrimitive.Speak` and `ActionBarPrimitive.StopSpeaking`.
+The default action bar does not include a speech button. You need to add `ActionBarPrimitive.Speak` and `ActionBarPrimitive.StopSpeaking` to your assistant message action bar manually. See the example above for a complete implementation.
 
 ## Example
 

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

@@ -102,11 +102,9 @@ const ThreadWelcome = () => {
 
       {/* Display suggestions */}
       <div className="grid grid-cols-2 gap-2">
-        <ThreadPrimitive.Suggestions
-          components={{
-            Suggestion: SuggestionItem,
-          }}
-        />
+        <ThreadPrimitive.Suggestions>
+          {() => <SuggestionItem />}
+        </ThreadPrimitive.Suggestions>
       </div>
     </div>
   );
@@ -135,11 +133,9 @@ const SuggestionItem = () => {
 Renders all suggestions from the suggestions scope.
 
 ```tsx
-<ThreadPrimitive.Suggestions
-  components={{
-    Suggestion: CustomSuggestionComponent,
-  }}
-/>
+<ThreadPrimitive.Suggestions>
+  {() => <CustomSuggestionComponent />}
+</ThreadPrimitive.Suggestions>
 ```
 
 ### SuggestionPrimitive.Title
@@ -276,11 +272,9 @@ const aui = useAui({
 2. Display suggestions using the primitives:
 
 ```tsx
-<ThreadPrimitive.Suggestions
-  components={{
-    Suggestion: SuggestionItem,
-  }}
-/>
+<ThreadPrimitive.Suggestions>
+  {() => <SuggestionItem />}
+</ThreadPrimitive.Suggestions>
 ```
 
 The new API provides:

package/.docs/raw/docs/(docs)/guides/tool-ui.mdx

@@ -200,7 +200,7 @@ export async function POST(req: Request) {
 
   const result = streamText({
     model: openai("gpt-4o"),
-    messages: convertToModelMessages(messages),
+    messages: await convertToModelMessages(messages),
     tools: {
       getWeather: tool({
         description: "Get current weather for a location",
@@ -275,7 +275,7 @@ export const WebSearchToolUI = makeAssistantToolUI<
 Use hooks for dynamic tool UI registration:
 
 <Callout type="tip">
-When you assign your `makeAssistantToolUI({...})` call to a constant starting with `use…`, you can call it directly as a hook inside your component. This pattern lets you access local props or state when rendering the tool UI.
+Use the `useAssistantToolUI` hook directly in your component for dynamic tool UI registration. This allows access to local component state and props when rendering the tool UI.
 </Callout>
 
 ```tsx
@@ -384,6 +384,9 @@ Build complex workflows with human-in-the-loop patterns for multi-step user inte
 ```tsx
 const DeleteProjectTool = makeAssistantTool({
   toolName: "deleteProject",
+  parameters: z.object({
+    projectId: z.string(),
+  }),
   execute: async ({ projectId }, { human }) => {
     const response = await human({ action, details });
     if (!response.approved) throw new Error("Project deletion cancelled");
@@ -502,6 +505,12 @@ render: ({ status, args }) => {
 
 ### Field-Level Validation
 
+<Callout type="warn">
+  `useToolArgsFieldStatus` is not currently exported from `@assistant-ui/react`.
+  The hook exists internally but is not part of the public API. This section is
+  included for reference and may become available in a future release.
+</Callout>
+
 Use `useToolArgsFieldStatus` to show validation states:
 
 ```tsx
@@ -510,8 +519,8 @@ import { useToolArgsFieldStatus } from "@assistant-ui/react";
 const FormToolUI = makeAssistantToolUI({
   toolName: "submitForm",
   render: ({ args }) => {
-    const emailStatus = useToolArgsFieldStatus("email");
-    const phoneStatus = useToolArgsFieldStatus("phone");
+    const emailStatus = useToolArgsFieldStatus(["email"]);
+    const phoneStatus = useToolArgsFieldStatus(["phone"]);
 
     return (
       <form className="space-y-4">
@@ -611,7 +620,7 @@ Provide a custom UI for tools without specific UIs:
 Generative UI components have access to execution context through props:
 
 ```tsx
-type ToolUIRenderProps<TArgs, TResult> = {
+type ToolCallMessagePartProps<TArgs, TResult> = {
   // Tool arguments
   args: TArgs;
   argsText: string; // JSON stringified args
@@ -628,7 +637,7 @@ type ToolUIRenderProps<TArgs, TResult> = {
   toolCallId: string;
 
   // Interactive callbacks
-  addResult: (result: TResult) => void;
+  addResult: (result: TResult | ToolResponse<TResult>) => void;
   resume: (payload: unknown) => void;
 
   // Interrupt state
@@ -671,7 +680,7 @@ const ConfirmationToolUI = makeAssistantToolUI<
 });
 ```
 
-Learn more about tool human input in the [Tools Guide](/docs/guides/tools#tool-human-input).
+Learn more about tool human input in the [Tools Guide](/docs/guides/tools#human-in-the-loop).
 
 ## Best Practices
 
@@ -742,6 +751,7 @@ useAssistantToolUI({
 ## Related Guides
 
 - [Tools Guide](/docs/guides/tools) - Learn how to create and use tools with AI models
+- [Multi-Agent](/docs/guides/multi-agent) - Render sub-agent conversations inside tool call UIs
 - [Tool Fallback](/docs/ui/tool-fallback) - Default UI for tools without custom components
 - [API Reference](/docs/api-reference/primitives/message-part) - Detailed type definitions and component APIs
 - [Message Primitive](/docs/api-reference/primitives/message) - Complete Message component documentation

package/.docs/raw/docs/(docs)/guides/tools.mdx

@@ -92,12 +92,27 @@ function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
 Each tool in the toolkit is a `ToolDefinition` object with these properties:
 
 ```tsx
-type ToolDefinition = {
-  description: string;
-  parameters: z.ZodType; // Zod schema for parameters
-  execute: (args, context) => Promise<any>;
-  render?: (props) => React.ReactNode; // Optional UI component
-};
+type ToolDefinition =
+  | {
+      // Frontend tool: executes in the browser
+      type?: "frontend";
+      description?: string;
+      parameters: StandardSchemaV1 | JSONSchema7; // e.g. a Zod schema
+      execute: (args, context) => Promise<any>;
+      render?: (props) => React.ReactNode;
+    }
+  | {
+      // Human tool: pauses for user input (render is required)
+      type: "human";
+      description?: string;
+      parameters: StandardSchemaV1 | JSONSchema7;
+      render: (props) => React.ReactNode;
+    }
+  | {
+      // Backend tool: execution happens server-side (no execute/parameters needed)
+      type: "backend";
+      render?: (props) => React.ReactNode;
+    };
 ```
 
 ### Organizing Large Toolkits
@@ -385,7 +400,7 @@ export async function POST(req: Request) {
 
   const result = streamText({
     model: openai("gpt-4o"),
-    messages: convertToModelMessages(messages),
+    messages: await convertToModelMessages(messages),
     tools: {
       queryDatabase: {
         description: "Query the application database",
@@ -447,7 +462,7 @@ export async function POST(req: Request) {
 
   const result = streamText({
     model: openai("gpt-4o"),
-    messages: convertToModelMessages(messages),
+    messages: await convertToModelMessages(messages),
     tools: {
       ...frontendTools(tools), // Client-defined tools
       // Additional server-side tools
@@ -487,7 +502,7 @@ export async function POST(req: Request) {
     const result = streamText({
       model: openai("gpt-4o"),
       tools,
-      messages: convertToModelMessages(messages),
+      messages: await convertToModelMessages(messages),
     });
 
     return result.toUIMessageStreamResponse();

package/.docs/raw/docs/(docs)/index.mdx

@@ -1,9 +1,9 @@
 ---
 title: Introduction
-description: Beautiful, enterprise-grade AI chat interfaces for React applications.
+description: Beautiful, enterprise-grade AI chat interfaces for React, React Native, and terminal applications.
 ---
 
-import { Sparkles, PanelsTopLeft, Database, Terminal, Bot } from "lucide-react";
+import { PanelsTopLeft, Database, Terminal } from "lucide-react";
 
 assistant-ui helps you create beautiful, enterprise-grade AI chat interfaces in minutes. Whether you're building a ChatGPT clone, a customer support chatbot, an AI assistant, or a complex multi-agent application, assistant-ui provides the frontend primitive components and state management layers to focus on what makes your application unique.
 
@@ -79,6 +79,6 @@ npx assistant-ui@latest create -t mcp
   <Card
     title="Examples"
     description="Explore full implementations and demos"
-    href="https://github.com/assistant-ui/assistant-ui/tree/main/examples"
+    href="/examples"
   />
 </Cards>