@assistant-ui/mcp-docs-server 0.2.2 → 0.3.0

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

@@ -1,732 +0,0 @@
-# Example: with-interactables
-
-## app/api/chat/route.ts
-
-```typescript
-import { openai } from "@ai-sdk/openai";
-import { streamText, convertToModelMessages, stepCountIs } from "ai";
-import type { UIMessage } from "ai";
-import {
-  frontendTools,
-  type FrontendTools,
-  unstable_injectInteractableContext,
-} from "@assistant-ui/react-ai-sdk";
-
-export const maxDuration = 30;
-
-export async function POST(req: Request) {
-  const {
-    messages,
-    system,
-    tools: clientTools,
-  }: {
-    messages: UIMessage[];
-    system?: string;
-    tools?: FrontendTools;
-  } = await req.json();
-
-  const modelMessages = await convertToModelMessages(
-    unstable_injectInteractableContext(messages),
-  );
-
-  const result = streamText({
-    model: openai("gpt-5.6-luna"),
-    messages: modelMessages,
-    stopWhen: stepCountIs(10),
-    ...(system ? { system } : {}),
-    ...(clientTools ? { tools: frontendTools(clientTools) } : {}),
-  } as Parameters<typeof streamText>[0]);
-
-  return result.toUIMessageStreamResponse();
-}
-
-```
-
-## app/globals.css
-
-```css
-@import "tailwindcss";
-@import "tw-animate-css";
-
-@source "../../../packages/ui/src";
-
-@custom-variant dark (&:is(.dark *));
-
-@theme inline {
-  --radius-sm: calc(var(--radius) - 4px);
-  --radius-md: calc(var(--radius) - 2px);
-  --radius-lg: var(--radius);
-  --radius-xl: calc(var(--radius) + 4px);
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --color-card: var(--card);
-  --color-card-foreground: var(--card-foreground);
-  --color-popover: var(--popover);
-  --color-popover-foreground: var(--popover-foreground);
-  --color-primary: var(--primary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-secondary: var(--secondary);
-  --color-secondary-foreground: var(--secondary-foreground);
-  --color-muted: var(--muted);
-  --color-muted-foreground: var(--muted-foreground);
-  --color-accent: var(--accent);
-  --color-accent-foreground: var(--accent-foreground);
-  --color-destructive: var(--destructive);
-  --color-border: var(--border);
-  --color-input: var(--input);
-  --color-ring: var(--ring);
-  --color-chart-1: var(--chart-1);
-  --color-chart-2: var(--chart-2);
-  --color-chart-3: var(--chart-3);
-  --color-chart-4: var(--chart-4);
-  --color-chart-5: var(--chart-5);
-  --color-sidebar: var(--sidebar);
-  --color-sidebar-foreground: var(--sidebar-foreground);
-  --color-sidebar-primary: var(--sidebar-primary);
-  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
-  --color-sidebar-accent: var(--sidebar-accent);
-  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
-  --color-sidebar-border: var(--sidebar-border);
-  --color-sidebar-ring: var(--sidebar-ring);
-}
-
-:root {
-  --radius: 0.625rem;
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.141 0.005 285.823);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.141 0.005 285.823);
-  --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.141 0.005 285.823);
-  --primary: oklch(0.21 0.006 285.885);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.967 0.001 286.375);
-  --secondary-foreground: oklch(0.21 0.006 285.885);
-  --muted: oklch(0.967 0.001 286.375);
-  --muted-foreground: oklch(0.552 0.016 285.938);
-  --accent: oklch(0.967 0.001 286.375);
-  --accent-foreground: oklch(0.21 0.006 285.885);
-  --destructive: oklch(0.577 0.245 27.325);
-  --border: oklch(0.92 0.004 286.32);
-  --input: oklch(0.92 0.004 286.32);
-  --ring: oklch(0.705 0.015 286.067);
-  --chart-1: oklch(0.646 0.222 41.116);
-  --chart-2: oklch(0.6 0.118 184.704);
-  --chart-3: oklch(0.398 0.07 227.392);
-  --chart-4: oklch(0.828 0.189 84.429);
-  --chart-5: oklch(0.769 0.188 70.08);
-  --sidebar: oklch(0.985 0 0);
-  --sidebar-foreground: oklch(0.141 0.005 285.823);
-  --sidebar-primary: oklch(0.21 0.006 285.885);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.967 0.001 286.375);
-  --sidebar-accent-foreground: oklch(0.21 0.006 285.885);
-  --sidebar-border: oklch(0.92 0.004 286.32);
-  --sidebar-ring: oklch(0.705 0.015 286.067);
-}
-
-.dark {
-  --background: oklch(0.141 0.005 285.823);
-  --foreground: oklch(0.985 0 0);
-  --card: oklch(0.21 0.006 285.885);
-  --card-foreground: oklch(0.985 0 0);
-  --popover: oklch(0.21 0.006 285.885);
-  --popover-foreground: oklch(0.985 0 0);
-  --primary: oklch(0.92 0.004 286.32);
-  --primary-foreground: oklch(0.21 0.006 285.885);
-  --secondary: oklch(0.274 0.006 286.033);
-  --secondary-foreground: oklch(0.985 0 0);
-  --muted: oklch(0.274 0.006 286.033);
-  --muted-foreground: oklch(0.705 0.015 286.067);
-  --accent: oklch(0.274 0.006 286.033);
-  --accent-foreground: oklch(0.985 0 0);
-  --destructive: oklch(0.704 0.191 22.216);
-  --border: oklch(1 0 0 / 10%);
-  --input: oklch(1 0 0 / 15%);
-  --ring: oklch(0.552 0.016 285.938);
-  --chart-1: oklch(0.488 0.243 264.376);
-  --chart-2: oklch(0.696 0.17 162.48);
-  --chart-3: oklch(0.769 0.188 70.08);
-  --chart-4: oklch(0.627 0.265 303.9);
-  --chart-5: oklch(0.645 0.246 16.439);
-  --sidebar: oklch(0.21 0.006 285.885);
-  --sidebar-foreground: oklch(0.985 0 0);
-  --sidebar-primary: oklch(0.488 0.243 264.376);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.274 0.006 286.033);
-  --sidebar-accent-foreground: oklch(0.985 0 0);
-  --sidebar-border: oklch(1 0 0 / 10%);
-  --sidebar-ring: oklch(0.552 0.016 285.938);
-}
-
-@layer base {
-  * {
-    @apply border-border outline-ring/50;
-  }
-  body {
-    @apply bg-background text-foreground;
-  }
-}
-
-```
-
-## app/layout.tsx
-
-```tsx
-import type { Metadata } from "next";
-import "./globals.css";
-
-export const metadata: Metadata = {
-  title: "assistant-ui Interactables Example",
-  description:
-    "Example using assistant-ui interactable components with a task board",
-};
-
-export default function RootLayout({
-  children,
-}: Readonly<{
-  children: React.ReactNode;
-}>) {
-  return (
-    <html lang="en">
-      <body className="h-dvh">{children}</body>
-    </html>
-  );
-}
-
-```
-
-## app/page.tsx
-
-```tsx
-"use client";
-
-import { useCallback } from "react";
-import { Thread } from "@/components/assistant-ui/thread";
-import {
-  AssistantRuntimeProvider,
-  AuiProvider,
-  AuiConfig,
-  unstable_Interactables,
-  Suggestions,
-  useAui,
-  unstable_useInteractable,
-} from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
-import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
-import {
-  CheckCircle2Icon,
-  CircleIcon,
-  ListTodoIcon,
-  Loader2Icon,
-  StickyNoteIcon,
-  Trash2Icon,
-  PlusIcon,
-} from "lucide-react";
-import {
-  type NoteState,
-  noteInitialState,
-  notesInitialState,
-  notesSchema,
-  taskBoardInitialState,
-  taskBoardSchema,
-} from "./state";
-
-function TaskBoard() {
-  const [state, { setState, isPending }] = unstable_useInteractable(
-    "taskBoard",
-    {
-      description:
-        "A task board showing the user's tasks. Use update_taskBoard with tasks.add/update/remove/clear to manage tasks. New tasks need a title and done=false.",
-      stateSchema: taskBoardSchema,
-      initialState: taskBoardInitialState,
-    },
-  );
-
-  const doneCount = state.tasks.filter((t) => t.done).length;
-
-  return (
-    <>
-      <div className="flex h-full 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, index) => (
-                <li
-                  key={task.id ?? `streaming-${index}`}
-                  className="group hover:bg-muted flex items-center gap-2 rounded-lg px-3 py-2 transition-colors"
-                >
-                  <button
-                    type="button"
-                    onClick={() =>
-                      setState((prev) => ({
-                        tasks: prev.tasks.map((t) =>
-                          t.id === task.id ? { ...t, done: !t.done } : t,
-                        ),
-                      }))
-                    }
-                    className="shrink-0"
-                    aria-label={
-                      task.done ? "Mark task undone" : "Mark task done"
-                    }
-                  >
-                    {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"
-                    aria-label={`Remove task ${task.title}`}
-                  >
-                    <Trash2Icon className="text-muted-foreground hover:text-destructive size-3.5" />
-                  </button>
-                </li>
-              ))}
-            </ul>
-          )}
-        </div>
-      </div>
-    </>
-  );
-}
-
-const COLORS: Record<NoteState["color"], string> = {
-  yellow: "bg-yellow-100 border-yellow-300",
-  blue: "bg-blue-100 border-blue-300",
-  green: "bg-green-100 border-green-300",
-  pink: "bg-pink-100 border-pink-300",
-};
-
-function NoteCard({
-  note,
-  selected,
-  onSelect,
-  onRemove,
-}: {
-  note: NoteState;
-  selected: boolean;
-  onSelect: (id: string) => void;
-  onRemove: (id: string) => void;
-}) {
-  return (
-    <div className="group relative">
-      <button
-        type="button"
-        onClick={() => onSelect(note.id)}
-        className={`flex w-full cursor-pointer flex-col gap-1 rounded-lg border-2 p-3 text-left transition-all ${COLORS[note.color] ?? COLORS.yellow} ${selected ? "ring-primary ring-2 ring-offset-1" : "hover:shadow-sm"}`}
-        aria-pressed={selected}
-      >
-        {selected && (
-          <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 text-sm font-semibold text-zinc-800">
-          {note.title}
-        </span>
-        <span className="line-clamp-3 text-xs text-zinc-600">
-          {note.content || "Empty note"}
-        </span>
-      </button>
-      <button
-        type="button"
-        onClick={() => onRemove(note.id)}
-        className="absolute right-2 bottom-2 rounded p-0.5 opacity-0 transition-opacity group-hover:opacity-100 hover:bg-black/10"
-        aria-label={`Remove note ${note.title}`}
-      >
-        <Trash2Icon className="size-3 text-zinc-500" />
-      </button>
-    </div>
-  );
-}
-
-function NotesPanel() {
-  const [state, { setState }] = unstable_useInteractable("notes", {
-    description:
-      "The sticky-note collection and selected note id. Use update_notes with notes.add/update/remove/clear to manage notes, and set selectedId to change focus. New notes need a title, content, and color.",
-    stateSchema: notesSchema,
-    initialState: notesInitialState,
-  });
-
-  const handleAdd = useCallback(() => {
-    const id = `note-${crypto.randomUUID()}`;
-    setState((prev) => ({
-      notes: [...prev.notes, { id, ...noteInitialState }],
-      selectedId: id,
-    }));
-  }, [setState]);
-
-  const handleSelect = useCallback(
-    (id: string) => {
-      setState((prev) => ({ ...prev, selectedId: id }));
-    },
-    [setState],
-  );
-
-  const handleRemove = useCallback(
-    (id: string) => {
-      setState((prev) => ({
-        notes: prev.notes.filter((note) => note.id !== id),
-        selectedId: prev.selectedId === id ? null : prev.selectedId,
-      }));
-    },
-    [setState],
-  );
-
-  return (
-    <>
-      <div className="flex h-full 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">
-            {state.notes.length}
-          </span>
-          <button
-            type="button"
-            onClick={handleAdd}
-            className="hover:bg-muted rounded p-1 transition-colors"
-            aria-label="Add note"
-          >
-            <PlusIcon className="text-muted-foreground size-3.5" />
-          </button>
-        </div>
-        <div className="flex-1 overflow-y-auto p-3">
-          {state.notes.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">
-              {state.notes.map((note, index) => (
-                <NoteCard
-                  key={note.id ?? `streaming-${index}`}
-                  note={note}
-                  selected={state.selectedId === note.id}
-                  onSelect={handleSelect}
-                  onRemove={handleRemove}
-                />
-              ))}
-            </div>
-          )}
-        </div>
-      </div>
-    </>
-  );
-}
-
-const STORAGE_KEY = "interactables-example";
-
-// Module-level so the adapter identity is stable across renders.
-const persistenceAdapter = {
-  load: () => {
-    try {
-      const saved = localStorage.getItem(STORAGE_KEY);
-      return saved ? JSON.parse(saved) : undefined;
-    } catch {
-      return undefined;
-    }
-  },
-  save: (state: unknown) => {
-    localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
-  },
-};
-
-function InteractablesExample() {
-  const aui = useAui();
-  const config = AuiConfig({
-    unstable_interactables: unstable_Interactables({
-      persistence: persistenceAdapter,
-    }),
-    suggestions: Suggestions([
-      {
-        title: "Add 3 tasks",
-        label: "for a grocery run",
-        prompt: "Add 3 tasks for a grocery run",
-      },
-      {
-        title: "Create 2 notes",
-        label: "and set different colors",
-        prompt:
-          "Create 2 sticky notes: one blue note about meeting prep, and one green note about project ideas",
-      },
-      {
-        title: "Change selected note",
-        label: "to pink color",
-        prompt: "Change the selected note's color to pink",
-      },
-    ]),
-  });
-
-  return (
-    <AuiProvider extends={aui} config={config}>
-      <main className="flex h-full min-h-0">
-        <div className="min-w-0 flex-1">
-          <Thread />
-        </div>
-        <div className="flex w-80 flex-col border-l">
-          <div className="min-h-0 flex-1 overflow-y-auto">
-            <NotesPanel />
-          </div>
-          <div className="min-h-0 flex-1 overflow-y-auto border-t">
-            <TaskBoard />
-          </div>
-        </div>
-      </main>
-    </AuiProvider>
-  );
-}
-
-export default function Home() {
-  const runtime = useChatRuntime({
-    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
-  });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <InteractablesExample />
-    </AssistantRuntimeProvider>
-  );
-}
-
-```
-
-## 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().describe("Stable task id, unique within this board."),
-      title: z.string(),
-      done: z.boolean(),
-    }),
-  ),
-});
-
-export const taskBoardInitialState: TaskBoardState = { tasks: [] };
-
-export const noteColorSchema = z.enum(["yellow", "blue", "green", "pink"]);
-
-export const noteSchema = z.object({
-  id: z.string().describe("Stable note id, unique within this collection."),
-  title: z.string(),
-  content: z.string(),
-  color: noteColorSchema,
-});
-
-export type NoteState = z.infer<typeof noteSchema>;
-
-export const noteInitialState: Omit<NoteState, "id"> = {
-  title: "New Note",
-  content: "",
-  color: "yellow",
-};
-
-export const notesSchema = z.object({
-  notes: z.array(noteSchema),
-  selectedId: z.string().nullable(),
-});
-
-export type NotesState = z.infer<typeof notesSchema>;
-
-export const notesInitialState: NotesState = {
-  notes: [],
-  selectedId: null,
-};
-
-```
-
-## components.json
-
-```json
-{
-  "$schema": "https://ui.shadcn.com/schema.json",
-  "style": "new-york",
-  "rsc": true,
-  "tsx": true,
-  "tailwind": {
-    "config": "",
-    "css": "app/globals.css",
-    "baseColor": "zinc",
-    "cssVariables": true,
-    "prefix": ""
-  },
-  "aliases": {
-    "components": "@/components",
-    "utils": "@/lib/utils",
-    "ui": "@/components/ui",
-    "lib": "@/lib",
-    "hooks": "@/hooks"
-  },
-  "iconLibrary": "lucide",
-  "registries": {
-    "@assistant-ui": "https://r.assistant-ui.com/{name}.json"
-  }
-}
-
-```
-
-## next.config.ts
-
-```typescript
-import type { NextConfig } from "next";
-
-const nextConfig: NextConfig = {/* config options here */};
-
-export default nextConfig;
-
-```
-
-## package.json
-
-```json
-{
-  "name": "with-interactables",
-  "version": "0.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start"
-  },
-  "dependencies": {
-    "@ai-sdk/openai": "^4.0.40",
-    "@assistant-ui/react": "workspace:*",
-    "@assistant-ui/react-ai-sdk": "workspace:*",
-    "@assistant-ui/ui": "workspace:*",
-    "ai": "^7.0.62",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "lucide-react": "^1.31.0",
-    "next": "^16.3.0",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "tailwind-merge": "^3.6.0",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@assistant-ui/x-buildutils": "workspace:*",
-    "@tailwindcss/postcss": "^4.3.3",
-    "@types/node": "^26.2.0",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.4",
-    "postcss": "^8.5.26",
-    "tailwindcss": "^4.3.3",
-    "tw-animate-css": "^1.4.0",
-    "typescript": "^7.0.2"
-  }
-}
-
-```
-
-## README.md
-
-```markdown
-# with-interactables
-
-Demonstrates **interactable components** — persistent UI components whose state can be read and updated by both the user and the AI assistant.
-
-## Features Demonstrated
-
-### Task Board
-- `unstable_useInteractable("taskBoard", config)` — registers a single interactable
-- Auto-generated `update_taskBoard` tool with partial scalar updates and array operations
-- Collection edits go through `tasks.add`, `tasks.update`, `tasks.remove`, and `tasks.clear` on the generated update tool
-
-### Sticky Notes
-- `unstable_useInteractable("notes", config)` — registers the sticky-note collection and `selectedId` as one state object
-- Auto-generated `update_notes` manages both note collection edits and selected-note focus
-- **Selection**: click a note to set `selectedId`; the AI can change focus by updating the same normal state field
-- **Partial updates**: AI can change just one note field with `notes.update: [{ id, color: "pink" }]`
-
-## Getting Started
-
-```bash
-# Install dependencies (from monorepo root)
-pnpm install
-
-# Set your OpenAI API key
-cp .env.example .env.local
-# Edit .env.local and add your OPENAI_API_KEY
-
-# Run the development server
-pnpm --filter with-interactables dev
-```
-
-Open [http://localhost:3000](http://localhost:3000) to see the example.
-
-## Key Concepts
-
-- **`unstable_Interactables({ persistence })`** — scope resource registered via `useAui`, with a `load`/`save` adapter
-- **`unstable_useInteractable(name, config)`** — returns `[state, { id, setState, isPending, error, flush }]`
-- **Partial updates** — auto-generated tools use partial schemas; AI only sends changed fields
-- **Array operations** — array fields support generated `add`, `update`, `remove`, `clear`, and `set` operations on the same `update_{name}` tool
-- **Selection as state** — focused UI state lives in the interactable's normal schema (`selectedId`), not in a separate manage tool
-- **`sendAutomaticallyWhen`** — auto-sends follow-up messages when tool calls complete
-
-```
-
-## tsconfig.json
-
-```json
-{
-  "extends": "@assistant-ui/x-buildutils/ts/next",
-  "compilerOptions": {
-    "paths": {
-      "@/*": ["./*"],
-      "@/components/assistant-ui/*": [
-        "../../packages/ui/src/components/assistant-ui/*"
-      ],
-      "@/components/ui/*": [
-        "../../packages/ui/src/components/ui/base/*",
-        "../../packages/ui/src/components/ui/radix/*"
-      ],
-      "@/components/ui/radix/*": [
-        "../../packages/ui/src/components/ui/radix/*"
-      ],
-      "@/lib/utils": ["../../packages/ui/src/lib/utils"],
-      "@assistant-ui/ui/*": ["../../packages/ui/src/*"]
-    }
-  },
-  "include": ["**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
-  "exclude": ["node_modules"]
-}
-
-```
-