@assistant-ui/mcp-docs-server 0.1.39 → 0.2.1

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

@@ -4,45 +4,43 @@
 
 ```typescript
 import { openai } from "@ai-sdk/openai";
-import {
-  streamText,
-  convertToModelMessages,
-  tool,
-  stepCountIs,
-  zodSchema,
-} from "ai";
+import { convertToModelMessages, stepCountIs, streamText } from "ai";
 import type { UIMessage } from "ai";
-import { z } from "zod";
+import {
+  AISDKToolkit,
+  unstable_injectInteractableContext,
+  type AISDKToolkitToolsOptions,
+} from "@assistant-ui/react-ai-sdk";
+import toolkit from "../../toolkit";
 
 export const maxDuration = 30;
 
+const aiToolkit = new AISDKToolkit({ toolkit });
+
+type FrontendToolDefs = NonNullable<AISDKToolkitToolsOptions["frontend"]>;
+
 export async function POST(req: Request) {
-  const { messages }: { messages: UIMessage[] } = await req.json();
+  const {
+    messages,
+    tools: clientTools,
+  }: {
+    messages: UIMessage[];
+    tools?: FrontendToolDefs;
+  } = await req.json();
+
+  const tools = await aiToolkit.tools({
+    ...(clientTools && { frontend: clientTools }),
+  });
 
   const result = streamText({
     model: openai("gpt-5.4-nano"),
     system:
-      "You are a helpful assistant that can generate HTML code. When the user asks you to create any visual content, UI, or webpage, use the render_html tool to render it in the browser. Always use the render_html tool for HTML output rather than showing code in a code block.",
-    messages: await convertToModelMessages(messages),
+      "You create functional HTML artifacts. When the user requests a webpage, interface, visualization, or other visual content, call the artifact tool with a short title and a complete HTML document. When an artifact already exists and the user requests a change, call update_artifact with its id and only the fields that changed. Do not put artifact HTML in a code block.",
+    messages: await convertToModelMessages(
+      unstable_injectInteractableContext(messages),
+    ),
     stopWhen: stepCountIs(10),
-    tools: {
-      render_html: tool({
-        description:
-          "Render HTML code in the user's browser. Use this whenever the user asks for HTML, a webpage, a UI component, or any visual content.",
-        inputSchema: zodSchema(
-          z.object({
-            code: z
-              .string()
-              .describe(
-                "The complete HTML code to render, including inline CSS and JavaScript if needed.",
-              ),
-          }),
-        ),
-        execute: async () => {
-          return { success: true };
-        },
-      }),
-    },
+    tools,
   });
 
   return result.toUIMessageStreamResponse();
@@ -50,6 +48,391 @@ export async function POST(req: Request) {
 
 ```
 
+## app/artifact-state.ts
+
+```typescript
+import { z } from "zod";
+
+export const artifactSchema = z.object({
+  title: z.string().describe("A short title for the artifact."),
+  code: z
+    .string()
+    .describe(
+      "A complete HTML document with inline CSS and JavaScript when needed.",
+    ),
+});
+
+export type ArtifactState = z.infer<typeof artifactSchema>;
+
+export const emptyArtifact: ArtifactState = {
+  title: "Untitled artifact",
+  code: "",
+};
+
+export const artifactDescription =
+  "Create an interactive HTML artifact when the user asks for a webpage, interface, visualization, or other visual content. Provide a short title and a complete HTML document.";
+
+```
+
+## app/artifact-surface.tsx
+
+```tsx
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import {
+  unstable_useInteractable,
+  unstable_useInteractableVersions,
+  useAuiState,
+  type Unstable_InteractableToolRenderProps,
+} from "@assistant-ui/react";
+import {
+  ArrowLeftIcon,
+  CheckIcon,
+  Code2Icon,
+  EyeIcon,
+  FileCode2Icon,
+  HistoryIcon,
+  Loader2Icon,
+  PanelRightOpenIcon,
+  SparklesIcon,
+  XIcon,
+} from "lucide-react";
+import {
+  artifactDescription,
+  artifactSchema,
+  emptyArtifact,
+  type ArtifactState,
+} from "./artifact-state";
+
+type ArtifactSurfaceTarget = {
+  id: string;
+  name: "artifact";
+  messageId: string;
+};
+
+type ArtifactSurfaceContextValue = {
+  active: ArtifactSurfaceTarget | null;
+  open: (target: ArtifactSurfaceTarget) => void;
+  close: () => void;
+  returnToOrigin: () => void;
+};
+
+const ArtifactSurfaceContext =
+  createContext<ArtifactSurfaceContextValue | null>(null);
+
+export function ArtifactSurfaceProvider({ children }: { children: ReactNode }) {
+  const [active, setActive] = useState<ArtifactSurfaceTarget | null>(null);
+
+  const value = useMemo<ArtifactSurfaceContextValue>(
+    () => ({
+      active,
+      open: setActive,
+      close: () => setActive(null),
+      returnToOrigin: () => {
+        const messageId = active?.messageId;
+        setActive(null);
+        if (!messageId) return;
+        requestAnimationFrame(() => {
+          const message = Array.from(
+            document.querySelectorAll<HTMLElement>("[data-message-id]"),
+          ).find((element) => element.dataset.messageId === messageId);
+          message?.scrollIntoView({ behavior: "smooth", block: "center" });
+        });
+      },
+    }),
+    [active],
+  );
+
+  return (
+    <ArtifactSurfaceContext.Provider value={value}>
+      {children}
+    </ArtifactSurfaceContext.Provider>
+  );
+}
+
+export function useArtifactSurface() {
+  const value = useContext(ArtifactSurfaceContext);
+  if (!value) {
+    throw new Error(
+      "useArtifactSurface must be used within ArtifactSurfaceProvider",
+    );
+  }
+  return value;
+}
+
+export function ArtifactTrigger({
+  state,
+  version,
+  id,
+  streaming,
+}: Unstable_InteractableToolRenderProps<ArtifactState>) {
+  const messageId = useAuiState((s) => s.message.id);
+  const { active, open } = useArtifactSurface();
+  const displayState = version && !version.isLatest ? version.state : state;
+  const title = displayState.title || "Untitled artifact";
+  const lineCount = displayState.code
+    ? displayState.code.split(/\r?\n/).length
+    : 0;
+  const isOpen = active?.id === id;
+
+  return (
+    <div className="bg-card my-3 overflow-hidden rounded-xl border shadow-[0_10px_30px_-22px_rgba(24,24,27,0.5)]">
+      <div className="bg-muted text-muted-foreground flex items-center gap-2 border-b px-3 py-2 font-mono text-[10px] tracking-[0.16em] uppercase">
+        <FileCode2Icon className="size-3.5" />
+        HTML artifact
+        {streaming ? (
+          <span className="ml-auto inline-flex items-center gap-1.5 text-amber-700">
+            <Loader2Icon className="size-3 animate-spin" />
+            Writing
+          </span>
+        ) : (
+          <span className="ml-auto inline-flex items-center gap-1.5 text-emerald-700">
+            <CheckIcon className="size-3" />
+            Ready
+          </span>
+        )}
+      </div>
+      <div className="flex items-center gap-4 p-3">
+        <div className="min-w-0 flex-1">
+          <p className="truncate text-sm font-semibold">{title}</p>
+          <p className="text-muted-foreground mt-0.5 text-xs">
+            {lineCount > 0 ? `${lineCount} lines` : "Preparing document"}
+            {version && !version.isLatest ? " · historical version" : ""}
+          </p>
+        </div>
+        <button
+          type="button"
+          data-testid="artifact-trigger"
+          disabled={streaming}
+          onClick={() =>
+            open({
+              id,
+              name: "artifact",
+              messageId,
+            })
+          }
+          className="bg-primary text-primary-foreground hover:bg-primary/90 inline-flex h-9 shrink-0 items-center gap-2 rounded-lg px-3 text-xs font-medium transition-colors disabled:cursor-wait disabled:opacity-50"
+        >
+          <PanelRightOpenIcon className="size-3.5" />
+          {isOpen ? "In workbench" : "Open workbench"}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+export function ArtifactSurface() {
+  const { active } = useArtifactSurface();
+  if (!active) return null;
+  return <ArtifactWorkbench key={active.id} target={active} />;
+}
+
+function ArtifactWorkbench({ target }: { target: ArtifactSurfaceTarget }) {
+  const [state, { setState }] = unstable_useInteractable("artifact", {
+    id: target.id,
+    description: artifactDescription,
+    stateSchema: artifactSchema,
+    initialState: emptyArtifact,
+  });
+  const versions = unstable_useInteractableVersions<ArtifactState>(
+    target.id,
+    target.name,
+  );
+  const { close, returnToOrigin } = useArtifactSurface();
+  const [view, setView] = useState<"preview" | "code">("preview");
+  const [historyOpen, setHistoryOpen] = useState(false);
+  const historyRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!historyOpen) return;
+    const dismissPointer = (event: PointerEvent) => {
+      if (!historyRef.current?.contains(event.target as Node)) {
+        setHistoryOpen(false);
+      }
+    };
+    const dismissKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") setHistoryOpen(false);
+    };
+    const dismissBlur = () => setHistoryOpen(false);
+    document.addEventListener("pointerdown", dismissPointer);
+    document.addEventListener("keydown", dismissKey);
+    window.addEventListener("blur", dismissBlur);
+    return () => {
+      document.removeEventListener("pointerdown", dismissPointer);
+      document.removeEventListener("keydown", dismissKey);
+      window.removeEventListener("blur", dismissBlur);
+    };
+  }, [historyOpen]);
+
+  return (
+    <aside
+      data-testid="artifact-surface"
+      className="bg-muted fixed inset-0 z-30 flex min-w-0 flex-1 flex-col md:static md:z-0 md:border-l"
+    >
+      <header className="border-border bg-background/90 flex h-14 shrink-0 items-center gap-3 border-b px-3 backdrop-blur md:px-5">
+        <div className="flex min-w-0 items-center gap-2">
+          <span className="grid size-7 shrink-0 place-items-center rounded-lg bg-amber-300 text-zinc-950 shadow-[inset_0_0_0_1px_rgba(24,24,27,0.12)]">
+            <SparklesIcon className="size-3.5" />
+          </span>
+          <div className="min-w-0">
+            <p className="truncate text-sm font-semibold">
+              {state.title || "Untitled artifact"}
+            </p>
+            <p className="text-muted-foreground font-mono text-[9px] tracking-[0.14em] uppercase">
+              Opened from conversation
+            </p>
+          </div>
+        </div>
+
+        <div className="ml-auto flex items-center gap-1.5">
+          <div className="relative" ref={historyRef}>
+            <button
+              type="button"
+              data-testid="artifact-version-select"
+              aria-label="Artifact version history"
+              aria-expanded={historyOpen}
+              onClick={() => setHistoryOpen((open) => !open)}
+              className="border-border bg-card text-foreground hover:bg-muted inline-flex h-8 items-center gap-1.5 rounded-md border px-2.5 text-xs font-medium"
+            >
+              <HistoryIcon className="size-3.5" />
+              {versions.length} {versions.length === 1 ? "version" : "versions"}
+            </button>
+            {historyOpen && (
+              <div className="border-border bg-card absolute top-9 right-0 z-10 flex w-44 flex-col overflow-hidden rounded-md border py-1 shadow-lg">
+                {versions.map((version, index) => (
+                  <button
+                    key={`${version.origin}-${index}`}
+                    type="button"
+                    onClick={() => {
+                      version.restore();
+                      setHistoryOpen(false);
+                    }}
+                    className="text-foreground hover:bg-muted flex items-center justify-between px-3 py-1.5 text-left text-xs"
+                  >
+                    <span>
+                      v{index + 1} ·{" "}
+                      {version.origin === "user-edit" ? "you" : "assistant"}
+                    </span>
+                    {index === versions.length - 1 && (
+                      <span className="text-muted-foreground font-mono text-[9px] uppercase">
+                        latest
+                      </span>
+                    )}
+                  </button>
+                ))}
+              </div>
+            )}
+          </div>
+          <button
+            type="button"
+            data-testid="artifact-return"
+            aria-label="Return to conversation"
+            onClick={returnToOrigin}
+            className="border-border bg-card text-foreground hover:bg-muted inline-flex h-8 items-center gap-1.5 rounded-md border px-2.5 text-xs font-medium"
+          >
+            <ArrowLeftIcon className="size-3.5" />
+            <span className="hidden sm:inline">Conversation</span>
+          </button>
+          <button
+            type="button"
+            data-testid="artifact-close"
+            onClick={close}
+            className="text-muted-foreground hover:bg-muted hover:text-foreground grid size-8 place-items-center rounded-md"
+            aria-label="Close artifact"
+          >
+            <XIcon className="size-4" />
+          </button>
+        </div>
+      </header>
+
+      <div className="flex min-h-0 flex-1 flex-col p-2 md:p-4">
+        <div className="border-border bg-card flex min-h-0 flex-1 flex-col overflow-hidden rounded-xl border shadow-[0_24px_70px_-44px_rgba(24,24,27,0.55)]">
+          <div className="bg-muted/80 flex shrink-0 items-center gap-1 border-b p-1.5">
+            <button
+              type="button"
+              aria-pressed={view === "preview"}
+              onClick={() => setView("preview")}
+              className={`inline-flex h-8 items-center gap-2 rounded-md px-3 text-xs font-medium transition-colors ${
+                view === "preview"
+                  ? "bg-card text-foreground ring-border shadow-sm ring-1"
+                  : "text-muted-foreground hover:text-foreground"
+              }`}
+            >
+              <EyeIcon className="size-3.5" />
+              Preview
+            </button>
+            <button
+              type="button"
+              aria-pressed={view === "code"}
+              onClick={() => setView("code")}
+              className={`inline-flex h-8 items-center gap-2 rounded-md px-3 text-xs font-medium transition-colors ${
+                view === "code"
+                  ? "bg-card text-foreground ring-border shadow-sm ring-1"
+                  : "text-muted-foreground hover:text-foreground"
+              }`}
+            >
+              <Code2Icon className="size-3.5" />
+              Source
+            </button>
+            <span className="text-muted-foreground ml-auto pr-2 font-mono text-[9px] tracking-[0.14em] uppercase">
+              Live document
+            </span>
+          </div>
+
+          {view === "preview" ? (
+            <iframe
+              data-testid="artifact-preview"
+              title={`Preview of ${state.title || "artifact"}`}
+              srcDoc={state.code}
+              sandbox="allow-scripts allow-forms"
+              className="min-h-0 flex-1 bg-white"
+            />
+          ) : (
+            <div className="flex min-h-0 flex-1 flex-col">
+              <input
+                aria-label="Artifact title"
+                value={state.title}
+                onChange={(event) =>
+                  setState((previous) => ({
+                    ...previous,
+                    title: event.target.value,
+                  }))
+                }
+                className="placeholder:text-muted-foreground h-11 shrink-0 border-b px-4 text-sm font-semibold outline-none"
+                placeholder="Artifact title"
+              />
+              <textarea
+                data-testid="artifact-code-editor"
+                aria-label="Artifact HTML source"
+                value={state.code}
+                onChange={(event) =>
+                  setState((previous) => ({
+                    ...previous,
+                    code: event.target.value,
+                  }))
+                }
+                spellCheck={false}
+                className="min-h-0 flex-1 resize-none bg-zinc-950 p-4 font-mono text-[13px] leading-6 text-zinc-100 outline-none selection:bg-amber-300 selection:text-zinc-950"
+              />
+            </div>
+          )}
+        </div>
+      </div>
+    </aside>
+  );
+}
+
+```
+
 ## app/globals.css
 
 ```css
@@ -211,90 +594,46 @@ export default function RootLayout({
 import { Thread } from "@/components/assistant-ui/thread";
 import {
   AssistantRuntimeProvider,
-  Tools,
-  useAui,
-  useAuiState,
   AuiProvider,
+  AuiConfig,
   Suggestions,
+  Tools,
+  unstable_Interactables,
+  useAui,
 } from "@assistant-ui/react";
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
-import type { ToolCallMessagePart } from "@assistant-ui/react";
-import { CodeIcon, EyeIcon } from "lucide-react";
-import { useState } from "react";
+import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
+import {
+  ArtifactSurface,
+  ArtifactSurfaceProvider,
+  useArtifactSurface,
+} from "./artifact-surface";
 import toolkit from "./toolkit";
 
-function ArtifactsView() {
-  const [tab, setTab] = useState<"source" | "preview">("source");
-
-  const lastToolCall = useAuiState((s) => {
-    const messages = s.thread.messages;
-    return messages
-      .flatMap((m) =>
-        m.content.filter(
-          (c): c is ToolCallMessagePart =>
-            c.type === "tool-call" && c.toolName === "render_html",
-        ),
-      )
-      .at(-1);
-  });
-
-  const code = lastToolCall?.args.code as string | undefined;
-  const isComplete = lastToolCall?.result !== undefined;
-
-  if (!code) return null;
+function ArtifactExperience() {
+  const { active } = useArtifactSurface();
 
   return (
-    <div className="flex flex-grow basis-full justify-stretch p-3">
-      <div className="flex h-full w-full flex-col overflow-hidden rounded-lg border">
-        <div className="flex border-b">
-          <button
-            type="button"
-            onClick={() => setTab("source")}
-            className={`inline-flex flex-1 items-center justify-center gap-2 px-4 py-2.5 text-sm font-medium transition-colors ${
-              tab === "source"
-                ? "bg-background text-foreground"
-                : "text-muted-foreground hover:text-foreground"
-            }`}
-          >
-            <CodeIcon className="size-4" />
-            Source Code
-          </button>
-          <button
-            type="button"
-            onClick={() => isComplete && setTab("preview")}
-            disabled={!isComplete}
-            className={`inline-flex flex-1 items-center justify-center gap-2 px-4 py-2.5 text-sm font-medium transition-colors ${
-              !isComplete
-                ? "cursor-not-allowed opacity-50"
-                : tab === "preview"
-                  ? "bg-background text-foreground"
-                  : "text-muted-foreground hover:text-foreground"
-            }`}
-          >
-            <EyeIcon className="size-4" />
-            Preview
-          </button>
-        </div>
-        {tab === "source" || !isComplete ? (
-          <div className="h-full overflow-y-auto px-4 py-2 font-mono text-sm break-words whitespace-pre-line">
-            {code}
-          </div>
-        ) : (
-          <div className="flex h-full flex-grow px-4 py-2">
-            <iframe
-              className="h-full w-full"
-              title="Artifact Preview"
-              srcDoc={code}
-            />
-          </div>
-        )}
-      </div>
-    </div>
+    <main className="bg-background flex h-full min-h-0 overflow-hidden">
+      <section
+        className={
+          active
+            ? "bg-background hidden min-w-0 md:block md:w-[min(44vw,42rem)] md:shrink-0"
+            : "bg-background min-w-0 flex-1"
+        }
+      >
+        <Thread />
+      </section>
+      <ArtifactSurface />
+    </main>
   );
 }
 
-function ThreadWithSuggestions() {
-  const aui = useAui({
+function ArtifactScopes() {
+  const aui = useAui();
+  const config = AuiConfig({
+    tools: Tools({ toolkit }),
+    unstable_interactables: unstable_Interactables(),
     suggestions: Suggestions([
       {
         title: "Build a landing page",
@@ -310,27 +649,24 @@ function ThreadWithSuggestions() {
       },
     ]),
   });
+
   return (
-    <AuiProvider value={aui}>
-      <Thread />
+    <AuiProvider extends={aui} config={config}>
+      <ArtifactSurfaceProvider>
+        <ArtifactExperience />
+      </ArtifactSurfaceProvider>
     </AuiProvider>
   );
 }
 
 export default function Home() {
-  const runtime = useChatRuntime();
-  const aui = useAui({
-    tools: Tools({ toolkit }),
+  const runtime = useChatRuntime({
+    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
   });
 
   return (
-    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
-      <main className="flex h-full justify-stretch">
-        <div className="flex-grow basis-full">
-          <ThreadWithSuggestions />
-        </div>
-        <ArtifactsView />
-      </main>
+    <AssistantRuntimeProvider runtime={runtime}>
+      <ArtifactScopes />
     </AssistantRuntimeProvider>
   );
 }
@@ -342,25 +678,16 @@ export default function Home() {
 ```tsx
 "use generative";
 
-import { defineToolkit, externalTool } from "@assistant-ui/react";
-import { TerminalIcon } from "lucide-react";
-import { z } from "zod";
+import { defineToolkit, unstable_interactableTool } from "@assistant-ui/react";
+import { ArtifactTrigger } from "./artifact-surface";
+import { artifactDescription, artifactSchema } from "./artifact-state";
 
 export default defineToolkit({
-  render_html: {
-    parameters: z.object({
-      code: z.string(),
-    }),
-    execute: externalTool(),
-    render: () => {
-      return (
-        <div className="bg-primary text-primary-foreground my-2 inline-flex items-center gap-2 rounded-full border px-4 py-2">
-          <TerminalIcon className="size-4" />
-          render_html(&#123; code: &quot;...&quot; &#125;)
-        </div>
-      );
-    },
-  },
+  artifact: unstable_interactableTool({
+    description: artifactDescription,
+    stateSchema: artifactSchema,
+    render: (props) => <ArtifactTrigger {...props} />,
+  }),
 });
 
 ```
@@ -426,33 +753,32 @@ export default withAui(nextConfig);
     "start": "next start"
   },
   "dependencies": {
-    "@ai-sdk/openai": "^4.0.14",
+    "@ai-sdk/openai": "^4.0.34",
     "@assistant-ui/react": "workspace:*",
     "@assistant-ui/react-ai-sdk": "workspace:*",
     "@assistant-ui/react-markdown": "workspace:*",
     "@assistant-ui/ui": "workspace:*",
-    "ai": "^7.0.28",
+    "ai": "^7.0.56",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "lucide-react": "^1.24.0",
-    "next": "^16.2.10",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
+    "lucide-react": "^1.29.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/next": "workspace:*",
     "@assistant-ui/x-buildutils": "workspace:*",
-    "@tailwindcss/postcss": "^4.3.2",
-    "@types/node": "^26.1.1",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "postcss": "^8.5.19",
-    "tailwindcss": "^4.3.2",
+    "@tailwindcss/postcss": "^4.3.3",
+    "@types/node": "^26.1.2",
+    "@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": "npm:@typescript/typescript6@^6.0.2",
-    "typescript-7": "npm:typescript@^7.0.2"
+    "typescript": "^7.0.2"
   }
 }