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

package/.docs/organized/code-examples/with-interactables.md

@@ -29,7 +29,7 @@ export async function POST(req: Request) {
 
   // Convert client-defined tools (forwarded from model context) to AI SDK format.
   // These have no `execute` — they are frontend tools executed on the client
-  // via useAssistantTool / useAssistantInteractable.
+  // via Tools({ toolkit }) / useAssistantInteractable.
   const tools = clientTools
     ? Object.fromEntries(
         Object.entries(clientTools).map(([name, def]) => [
@@ -43,7 +43,7 @@ export async function POST(req: Request) {
     : undefined;
 
   const result = streamText({
-    model: openai("gpt-4o"),
+    model: openai("gpt-5.4-nano"),
     messages: await convertToModelMessages(messages),
     stopWhen: stepCountIs(10),
     ...(system ? { system } : {}),
@@ -214,20 +214,28 @@ export default function RootLayout({
 ```tsx
 "use client";
 
-import { useRef, useState, useCallback, useEffect } from "react";
+import {
+  useRef,
+  useState,
+  useCallback,
+  useEffect,
+  type Dispatch,
+  type SetStateAction,
+} from "react";
 import { Thread } from "@/components/assistant-ui/thread";
 import {
   AssistantRuntimeProvider,
+  AuiProvider,
   Interactables,
   Suggestions,
+  Tools,
   useAui,
+  useAuiToolOverrides,
   useAssistantInteractable,
   useInteractableState,
-  useAssistantTool,
 } from "@assistant-ui/react";
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
-import { z } from "zod";
 import {
   CheckCircle2Icon,
   CircleIcon,
@@ -237,23 +245,15 @@ import {
   Trash2Icon,
   PlusIcon,
 } from "lucide-react";
-
-type Task = { id: string; title: string; done: boolean };
-type TaskBoardState = { tasks: Task[] };
-
-const taskBoardSchema = z.object({
-  tasks: z.array(
-    z.object({
-      id: z.string(),
-      title: z.string(),
-      done: z.boolean(),
-    }),
-  ),
-});
-
-const taskBoardInitialState: TaskBoardState = { tasks: [] };
-
-let nextTaskId = 0;
+import {
+  type NoteState,
+  type TaskBoardState,
+  noteInitialState,
+  noteSchema,
+  taskBoardInitialState,
+  taskBoardSchema,
+} from "./state";
+import toolkit from "./toolkits";
 
 function TaskBoard() {
   const id = useAssistantInteractable("taskBoard", {
@@ -267,140 +267,128 @@ function TaskBoard() {
     taskBoardInitialState,
   );
 
-  const setStateRef = useRef(setState);
-  setStateRef.current = setState;
-
-  useAssistantTool({
-    toolName: "manage_tasks",
-    description:
-      'Manage tasks on the task board. Actions: "add" (requires title), "toggle" (requires id), "remove" (requires id), "clear" (no extra fields).',
-    parameters: z.object({
-      action: z.enum(["add", "toggle", "remove", "clear"]),
-      title: z.string().optional(),
-      id: z.string().optional(),
-    }),
-    execute: async (args) => {
-      const set = setStateRef.current;
-      switch (args.action) {
-        case "add": {
-          const id = `task-${++nextTaskId}`;
-          set((prev) => ({
-            tasks: [
-              ...prev.tasks,
-              { id, title: args.title ?? "Untitled", done: false },
-            ],
-          }));
-          return { success: true, id };
-        }
-        case "toggle": {
-          if (!args.id) return { success: false, error: "id is required" };
-          set((prev) => ({
-            tasks: prev.tasks.map((t) =>
-              t.id === args.id ? { ...t, done: !t.done } : t,
-            ),
-          }));
-          return { success: true };
-        }
-        case "remove": {
-          if (!args.id) return { success: false, error: "id is required" };
-          set((prev) => ({
-            tasks: prev.tasks.filter((t) => t.id !== args.id),
-          }));
-          return { success: true };
-        }
-        case "clear": {
-          set({ tasks: [] });
-          return { success: true };
-        }
-        default:
-          return { success: false, error: "Unknown action" };
-      }
-    },
-  });
+  const aui = useAui({ tools: Tools({ toolkit }) });
 
   const doneCount = state.tasks.filter((t) => t.done).length;
 
   return (
-    <div className="flex flex-col">
-      <div className="flex items-center gap-2 border-b px-4 py-3">
-        <ListTodoIcon className="size-4 text-muted-foreground" />
-        <span className="font-semibold text-sm">Task Board</span>
-        {isPending && (
-          <Loader2Icon className="size-3 animate-spin text-muted-foreground" />
-        )}
-        {state.tasks.length > 0 && (
-          <span className="ml-auto rounded-full bg-primary/10 px-2 py-0.5 font-medium text-primary text-xs">
-            {doneCount}/{state.tasks.length}
-          </span>
-        )}
-      </div>
-      <div className="flex-1 overflow-y-auto p-3">
-        {state.tasks.length === 0 ? (
-          <p className="py-6 text-center text-muted-foreground text-xs">
-            No tasks yet. Ask the assistant!
-          </p>
-        ) : (
-          <ul className="space-y-1">
-            {state.tasks.map((task) => (
-              <li
-                key={task.id}
-                className="group flex items-center gap-2 rounded-lg px-3 py-2 transition-colors hover:bg-muted"
-              >
-                <button
-                  type="button"
-                  onClick={() =>
-                    setState((prev) => ({
-                      tasks: prev.tasks.map((t) =>
-                        t.id === task.id ? { ...t, done: !t.done } : t,
-                      ),
-                    }))
-                  }
-                  className="shrink-0"
-                >
-                  {task.done ? (
-                    <CheckCircle2Icon className="size-4 text-primary" />
-                  ) : (
-                    <CircleIcon className="size-4 text-muted-foreground" />
-                  )}
-                </button>
-                <span
-                  className={`flex-1 text-sm ${task.done ? "text-muted-foreground line-through" : ""}`}
-                >
-                  {task.title}
-                </span>
-                <button
-                  type="button"
-                  onClick={() =>
-                    setState((prev) => ({
-                      tasks: prev.tasks.filter((t) => t.id !== task.id),
-                    }))
-                  }
-                  className="shrink-0 opacity-0 transition-opacity group-hover:opacity-100"
+    <AuiProvider value={aui}>
+      <TaskBoardToolOverrides setState={setState} />
+      <div className="flex flex-col">
+        <div className="flex items-center gap-2 border-b px-4 py-3">
+          <ListTodoIcon className="text-muted-foreground size-4" />
+          <span className="text-sm font-semibold">Task Board</span>
+          {isPending && (
+            <Loader2Icon className="text-muted-foreground size-3 animate-spin" />
+          )}
+          {state.tasks.length > 0 && (
+            <span className="bg-primary/10 text-primary ml-auto rounded-full px-2 py-0.5 text-xs font-medium">
+              {doneCount}/{state.tasks.length}
+            </span>
+          )}
+        </div>
+        <div className="flex-1 overflow-y-auto p-3">
+          {state.tasks.length === 0 ? (
+            <p className="text-muted-foreground py-6 text-center text-xs">
+              No tasks yet. Ask the assistant!
+            </p>
+          ) : (
+            <ul className="space-y-1">
+              {state.tasks.map((task) => (
+                <li
+                  key={task.id}
+                  className="group hover:bg-muted flex items-center gap-2 rounded-lg px-3 py-2 transition-colors"
                 >
-                  <Trash2Icon className="size-3.5 text-muted-foreground hover:text-destructive" />
-                </button>
-              </li>
-            ))}
-          </ul>
-        )}
+                  <button
+                    type="button"
+                    onClick={() =>
+                      setState((prev) => ({
+                        tasks: prev.tasks.map((t) =>
+                          t.id === task.id ? { ...t, done: !t.done } : t,
+                        ),
+                      }))
+                    }
+                    className="shrink-0"
+                  >
+                    {task.done ? (
+                      <CheckCircle2Icon className="text-primary size-4" />
+                    ) : (
+                      <CircleIcon className="text-muted-foreground size-4" />
+                    )}
+                  </button>
+                  <span
+                    className={`flex-1 text-sm ${task.done ? "text-muted-foreground line-through" : ""}`}
+                  >
+                    {task.title}
+                  </span>
+                  <button
+                    type="button"
+                    onClick={() =>
+                      setState((prev) => ({
+                        tasks: prev.tasks.filter((t) => t.id !== task.id),
+                      }))
+                    }
+                    className="shrink-0 opacity-0 transition-opacity group-hover:opacity-100"
+                  >
+                    <Trash2Icon className="text-muted-foreground hover:text-destructive size-3.5" />
+                  </button>
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
       </div>
-    </div>
+    </AuiProvider>
   );
 }
 
-type NoteState = { title: string; content: string; color: string };
-
-const noteSchema = z.object({
-  title: z.string(),
-  content: z.string(),
-  color: z.enum(["yellow", "blue", "green", "pink"]),
-});
-
-const noteInitialState: NoteState = {
-  title: "New Note",
-  content: "",
-  color: "yellow",
-};
+function TaskBoardToolOverrides({
+  setState,
+}: {
+  setState: Dispatch<SetStateAction<TaskBoardState>>;
+}) {
+  useAuiToolOverrides({
+    manage_tasks: {
+      execute: async (args) => {
+        switch (args.action) {
+          case "add": {
+            const id = crypto.randomUUID();
+            setState((prev) => ({
+              tasks: [
+                ...prev.tasks,
+                { id, title: args.title ?? "Untitled", done: false },
+              ],
+            }));
+            return { success: true, id };
+          }
+          case "toggle": {
+            if (!args.id) return { success: false, error: "id is required" };
+            setState((prev) => ({
+              tasks: prev.tasks.map((t) =>
+                t.id === args.id ? { ...t, done: !t.done } : t,
+              ),
+            }));
+            return { success: true };
+          }
+          case "remove": {
+            if (!args.id) return { success: false, error: "id is required" };
+            setState((prev) => ({
+              tasks: prev.tasks.filter((t) => t.id !== args.id),
+            }));
+            return { success: true };
+          }
+          case "clear": {
+            setState({ tasks: [] });
+            return { success: true };
+          }
+          default:
+            return { success: false, error: "Unknown action" };
+        }
+      },
+    },
+  });
+  return null;
+}
 
 const COLORS: Record<string, string> = {
   yellow: "bg-yellow-100 border-yellow-300",
@@ -441,20 +429,19 @@ function NoteCard({
   };
 
   return (
-    // biome-ignore lint/a11y/useSemanticElements: styled interactive card
     <div
       role="button"
       tabIndex={0}
       onClick={handleClick}
       onKeyDown={(e) => (e.key === "Enter" || e.key === " ") && handleClick()}
-      className={`group relative flex w-full cursor-pointer flex-col gap-1 rounded-lg border-2 p-3 text-left transition-all ${COLORS[state.color] ?? COLORS.yellow} ${isSelected ? "ring-2 ring-primary ring-offset-1" : "hover:shadow-sm"}`}
+      className={`group relative flex w-full cursor-pointer flex-col gap-1 rounded-lg border-2 p-3 text-left transition-all ${COLORS[state.color] ?? COLORS.yellow} ${isSelected ? "ring-primary ring-2 ring-offset-1" : "hover:shadow-sm"}`}
     >
       {isSelected && (
-        <span className="absolute top-1.5 right-2 rounded bg-primary px-1.5 py-0.5 font-medium text-[10px] text-primary-foreground leading-none">
+        <span className="bg-primary text-primary-foreground absolute top-1.5 right-2 rounded px-1.5 py-0.5 text-[10px] leading-none font-medium">
           SELECTED
         </span>
       )}
-      <span className="pr-16 font-semibold text-sm text-zinc-800">
+      <span className="pr-16 text-sm font-semibold text-zinc-800">
         {state.title}
       </span>
       <span className="line-clamp-3 text-xs text-zinc-600">
@@ -466,7 +453,7 @@ function NoteCard({
           e.stopPropagation();
           onRemove(noteId);
         }}
-        className="absolute right-2 bottom-2 rounded p-0.5 opacity-0 transition-opacity hover:bg-black/10 group-hover:opacity-100"
+        className="absolute right-2 bottom-2 rounded p-0.5 opacity-0 transition-opacity group-hover:opacity-100 hover:bg-black/10"
       >
         <Trash2Icon className="size-3 text-zinc-500" />
       </button>
@@ -500,46 +487,7 @@ function NotesPanel() {
     localStorage.setItem(NOTE_IDS_KEY, JSON.stringify(noteIds));
   }, [noteIds]);
 
-  const noteIdsRef = useRef(noteIds);
-  noteIdsRef.current = noteIds;
-  const setNoteIdsRef = useRef(setNoteIds);
-  setNoteIdsRef.current = setNoteIds;
-  const setSelectedIdRef = useRef(setSelectedId);
-  setSelectedIdRef.current = setSelectedId;
-
-  useAssistantTool({
-    toolName: "manage_notes",
-    description:
-      'Manage sticky notes. Actions: "add" (creates a new note, returns its id), "remove" (requires noteId), "clear" (removes all notes). After adding, use the update_note_{id} tool to set its content.',
-    parameters: z.object({
-      action: z.enum(["add", "remove", "clear"]),
-      noteId: z.string().optional(),
-    }),
-    execute: async (args) => {
-      switch (args.action) {
-        case "add": {
-          const id = `note-${Date.now().toString(36)}`;
-          setNoteIdsRef.current((prev) => [...prev, id]);
-          return { success: true, noteId: id };
-        }
-        case "remove": {
-          if (args.noteId) {
-            setNoteIdsRef.current((prev) =>
-              prev.filter((id) => id !== args.noteId),
-            );
-          }
-          return { success: true };
-        }
-        case "clear": {
-          setNoteIdsRef.current([]);
-          setSelectedIdRef.current(null);
-          return { success: true };
-        }
-        default:
-          return { success: false, error: "Unknown action" };
-      }
-    },
-  });
+  const aui = useAui({ tools: Tools({ toolkit }) });
 
   const handleSelect = useCallback((id: string) => {
     setSelectedId(id);
@@ -551,47 +499,89 @@ function NotesPanel() {
   }, []);
 
   return (
-    <div className="flex flex-col">
-      <div className="flex items-center gap-2 border-b px-4 py-3">
-        <StickyNoteIcon className="size-4 text-muted-foreground" />
-        <span className="font-semibold text-sm">Notes</span>
-        <span className="ml-auto text-muted-foreground text-xs">
-          {noteIds.length}
-        </span>
-        <button
-          type="button"
-          onClick={() => {
-            const id = `note-${Date.now().toString(36)}`;
-            setNoteIds((prev) => [...prev, id]);
-          }}
-          className="rounded p-1 transition-colors hover:bg-muted"
-        >
-          <PlusIcon className="size-3.5 text-muted-foreground" />
-        </button>
-      </div>
-      <div className="flex-1 overflow-y-auto p-3">
-        {noteIds.length === 0 ? (
-          <p className="py-6 text-center text-muted-foreground text-xs">
-            No notes yet. Ask the assistant!
-          </p>
-        ) : (
-          <div className="grid gap-2">
-            {noteIds.map((noteId) => (
-              <NoteCard
-                key={noteId}
-                noteId={noteId}
-                selectedId={selectedId}
-                onSelect={handleSelect}
-                onRemove={handleRemove}
-              />
-            ))}
-          </div>
-        )}
+    <AuiProvider value={aui}>
+      <NotesToolOverrides
+        setNoteIds={setNoteIds}
+        setSelectedId={setSelectedId}
+      />
+      <div className="flex flex-col">
+        <div className="flex items-center gap-2 border-b px-4 py-3">
+          <StickyNoteIcon className="text-muted-foreground size-4" />
+          <span className="text-sm font-semibold">Notes</span>
+          <span className="text-muted-foreground ml-auto text-xs">
+            {noteIds.length}
+          </span>
+          <button
+            type="button"
+            onClick={() => {
+              const id = `note-${crypto.randomUUID()}`;
+              setNoteIds((prev) => [...prev, id]);
+            }}
+            className="hover:bg-muted rounded p-1 transition-colors"
+          >
+            <PlusIcon className="text-muted-foreground size-3.5" />
+          </button>
+        </div>
+        <div className="flex-1 overflow-y-auto p-3">
+          {noteIds.length === 0 ? (
+            <p className="text-muted-foreground py-6 text-center text-xs">
+              No notes yet. Ask the assistant!
+            </p>
+          ) : (
+            <div className="grid gap-2">
+              {noteIds.map((noteId) => (
+                <NoteCard
+                  key={noteId}
+                  noteId={noteId}
+                  selectedId={selectedId}
+                  onSelect={handleSelect}
+                  onRemove={handleRemove}
+                />
+              ))}
+            </div>
+          )}
+        </div>
       </div>
-    </div>
+    </AuiProvider>
   );
 }
 
+function NotesToolOverrides({
+  setNoteIds,
+  setSelectedId,
+}: {
+  setNoteIds: Dispatch<SetStateAction<string[]>>;
+  setSelectedId: Dispatch<SetStateAction<string | null>>;
+}) {
+  useAuiToolOverrides({
+    manage_notes: {
+      execute: async (args) => {
+        switch (args.action) {
+          case "add": {
+            const id = `note-${crypto.randomUUID()}`;
+            setNoteIds((prev) => [...prev, id]);
+            return { success: true, noteId: id };
+          }
+          case "remove": {
+            if (args.noteId) {
+              setNoteIds((prev) => prev.filter((id) => id !== args.noteId));
+            }
+            return { success: true };
+          }
+          case "clear": {
+            setNoteIds([]);
+            setSelectedId(null);
+            return { success: true };
+          }
+          default:
+            return { success: false, error: "Unknown action" };
+        }
+      },
+    },
+  });
+  return null;
+}
+
 const STORAGE_KEY = "interactables-example";
 
 function useInteractablePersistence(aui: ReturnType<typeof useAui>) {
@@ -663,6 +653,92 @@ export default function Home() {
 
 ```
 
+## app/state.ts
+
+```typescript
+import { z } from "zod";
+
+export type Task = { id: string; title: string; done: boolean };
+export type TaskBoardState = { tasks: Task[] };
+
+export const taskBoardSchema = z.object({
+  tasks: z.array(
+    z.object({
+      id: z.string(),
+      title: z.string(),
+      done: z.boolean(),
+    }),
+  ),
+});
+
+export const taskBoardInitialState: TaskBoardState = { tasks: [] };
+
+export const manageTasksParameters = z.object({
+  action: z.enum(["add", "toggle", "remove", "clear"]),
+  title: z.string().optional(),
+  id: z.string().optional(),
+});
+
+export type ManageTasksArgs = z.infer<typeof manageTasksParameters>;
+
+export type NoteState = { title: string; content: string; color: string };
+
+export const noteSchema = z.object({
+  title: z.string(),
+  content: z.string(),
+  color: z.enum(["yellow", "blue", "green", "pink"]),
+});
+
+export const noteInitialState: NoteState = {
+  title: "New Note",
+  content: "",
+  color: "yellow",
+};
+
+export const manageNotesParameters = z.object({
+  action: z.enum(["add", "remove", "clear"]),
+  noteId: z.string().optional(),
+});
+
+export type ManageNotesArgs = z.infer<typeof manageNotesParameters>;
+
+```
+
+## app/toolkits.ts
+
+```typescript
+"use generative";
+
+import { defineToolkit, stubTool } from "@assistant-ui/react";
+import { manageNotesParameters, manageTasksParameters } from "./state";
+
+export default defineToolkit({
+  manage_tasks: {
+    description:
+      'Manage tasks on the task board. Actions: "add" (requires title), "toggle" (requires id), "remove" (requires id), "clear" (no extra fields).',
+    parameters: manageTasksParameters,
+    // The generative compiler strips this stub; TaskBoardToolOverrides provides the real executor.
+    execute: stubTool(),
+    renderText: {
+      running: ({ args }) => `Updating tasks: ${args.action}`,
+      complete: "Tasks updated",
+    },
+  },
+  manage_notes: {
+    description:
+      'Manage sticky notes. Actions: "add" (creates a new note, returns its id), "remove" (requires noteId), "clear" (removes all notes). After adding, use the update_note_{id} tool to set its content.',
+    parameters: manageNotesParameters,
+    // The generative compiler strips this stub; NotesToolOverrides provides the real executor.
+    execute: stubTool(),
+    renderText: {
+      running: ({ args }) => `Updating notes: ${args.action}`,
+      complete: "Notes updated",
+    },
+  },
+});
+
+```
+
 ## components.json
 
 ```json
@@ -696,13 +772,14 @@ export default function Home() {
 ## next.config.ts
 
 ```typescript
+import { withAui } from "@assistant-ui/next";
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
   /* config options here */
 };
 
-export default nextConfig;
+export default withAui(nextConfig);
 
 ```
 
@@ -720,28 +797,29 @@ export default nextConfig;
     "start": "next start"
   },
   "dependencies": {
-    "@ai-sdk/openai": "^3.0.61",
+    "@ai-sdk/openai": "^3.0.67",
     "@assistant-ui/react": "workspace:*",
     "@assistant-ui/react-ai-sdk": "workspace:*",
     "@assistant-ui/ui": "workspace:*",
-    "ai": "^6.0.175",
+    "ai": "^6.0.193",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "lucide-react": "^1.14.0",
-    "next": "^16.2.4",
-    "react": "^19.2.5",
-    "react-dom": "^19.2.5",
-    "tailwind-merge": "^3.5.0",
+    "lucide-react": "^1.17.0",
+    "next": "^16.2.6",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "tailwind-merge": "^3.6.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@assistant-ui/next": "workspace:*",
     "@assistant-ui/x-buildutils": "workspace:*",
-    "@tailwindcss/postcss": "^4.2.4",
-    "@types/node": "^25.6.0",
-    "@types/react": "^19.2.14",
+    "@tailwindcss/postcss": "^4.3.0",
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",
-    "postcss": "^8.5.14",
-    "tailwindcss": "^4.2.4",
+    "postcss": "^8.5.15",
+    "tailwindcss": "^4.3.0",
     "tw-animate-css": "^1.4.0",
     "typescript": "^6.0.3"
   }
@@ -760,7 +838,7 @@ Demonstrates **interactable components** — persistent UI components whose stat
 
 ### Task Board (single instance + custom tool)
 - `useInteractable("taskBoard", config)` — registers a single interactable
-- `useAssistantTool("manage_tasks")` — custom tool for incremental add/toggle/remove/clear
+- `Tools({ toolkit })` — custom tool for incremental add/toggle/remove/clear
 - Auto-generated `update_taskBoard` tool with **partial updates** (AI only sends changed fields)
 
 ### Sticky Notes (multi-instance + selection + partial updates)
@@ -792,7 +870,7 @@ Open [http://localhost:3000](http://localhost:3000) to see the example.
 - **Partial updates** — auto-generated tools use partial schemas; AI only sends changed fields
 - **Multi-instance** — same `name`, different `id`; tools named `update_{name}_{id}`
 - **Selection** — `setSelected(true)` marks a component as focused for the AI
-- **`useAssistantTool`** — custom frontend tools for fine-grained control
+- **`Tools({ toolkit })`** — custom frontend tools for fine-grained control
 - **`sendAutomaticallyWhen`** — auto-sends follow-up messages when tool calls complete
 
 ```