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

package/.docs/organized/code-examples/with-cloud-standalone.md

@@ -0,0 +1,675 @@
+# Example: with-cloud-standalone
+
+## app/api/chat/route.ts
+
+```typescript
+import { openai } from "@ai-sdk/openai";
+import { streamText, convertToModelMessages } from "ai";
+import type { UIMessage } from "ai";
+
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+
+  const result = streamText({
+    model: openai("gpt-4o-mini"),
+    messages: await convertToModelMessages(messages),
+  });
+
+  return result.toUIMessageStreamResponse({
+    messageMetadata: ({ part }) => {
+      if (part.type === "finish-step") {
+        return {
+          modelId: part.response.modelId,
+          usage: part.usage,
+        };
+      }
+      return undefined;
+    },
+  });
+}
+
+```
+
+## app/globals.css
+
+```css
+@import "tailwindcss";
+@import "tw-animate-css";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+  --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-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);
+  --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);
+  --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 { Geist, Geist_Mono } from "next/font/google";
+import "./globals.css";
+
+const geistSans = Geist({
+  variable: "--font-geist-sans",
+  subsets: ["latin"],
+});
+
+const geistMono = Geist_Mono({
+  variable: "--font-geist-mono",
+  subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+  title: "Cloud AI SDK Example",
+  description: "Example using assistant-cloud with AI SDK v6",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en" className="dark">
+      <body
+        className={`${geistSans.variable} ${geistMono.variable} h-dvh antialiased`}
+      >
+        {children}
+      </body>
+    </html>
+  );
+}
+
+```
+
+## app/page.client.tsx
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { useCloudChat } from "@assistant-ui/cloud-ai-sdk";
+import { Thread } from "@/components/chat/Thread";
+import { Composer } from "@/components/chat/Composer";
+import { ThreadList } from "@/components/chat/ThreadList";
+
+export function ChatPageClient() {
+  // Zero-config mode: auto-initializes anonymous cloud from NEXT_PUBLIC_ASSISTANT_BASE_URL.
+  // For custom configuration, pass options:
+  //   - { cloud: myCloud } for authenticated users
+  //   - { threads: useThreads(...) } for external thread management
+  //   - { onSyncError: (err) => ... } for error handling
+  const { messages, sendMessage, stop, status, threads } = useCloudChat();
+
+  const [input, setInput] = useState("");
+
+  const handleSubmit = () => {
+    if (!input.trim()) return;
+    sendMessage({ text: input });
+    setInput("");
+  };
+
+  const isRunning = status === "streaming" || status === "submitted";
+  const isLoading = status === "submitted";
+
+  const handleDelete = async (id: string) => {
+    if (threads.threadId === id) threads.selectThread(null);
+    await threads.delete(id);
+  };
+
+  return (
+    <div className="flex h-full">
+      <ThreadList
+        threads={threads.threads}
+        selectedId={threads.threadId}
+        onSelect={threads.selectThread}
+        onDelete={handleDelete}
+        isLoading={threads.isLoading}
+      />
+
+      <div className="flex min-w-0 flex-1 flex-col">
+        <Thread messages={messages} isLoading={isLoading}>
+          <Composer
+            value={input}
+            onChange={setInput}
+            onSubmit={handleSubmit}
+            isRunning={isRunning}
+            onCancel={stop}
+          />
+        </Thread>
+      </div>
+    </div>
+  );
+}
+
+```
+
+## app/page.tsx
+
+```tsx
+import { ChatPageClient } from "./page.client";
+
+// Only needed if NEXT_PUBLIC_ASSISTANT_BASE_URL is unset and no cloud instance is passed to useCloudChat({ cloud }).
+export const dynamic = "force-dynamic";
+
+export default function Home() {
+  return <ChatPageClient />;
+}
+
+```
+
+## components/chat/Composer.tsx
+
+```tsx
+"use client";
+
+import type { FormEvent, KeyboardEvent } from "react";
+import { cn } from "@/lib/utils";
+import { ArrowUp, Square } from "lucide-react";
+
+type ComposerProps = {
+  value: string;
+  onChange: (value: string) => void;
+  onSubmit: () => void;
+  isRunning: boolean;
+  onCancel?: () => void;
+};
+
+export function Composer({
+  value,
+  onChange,
+  onSubmit,
+  isRunning,
+  onCancel,
+}: ComposerProps) {
+  const handleSubmit = (e: FormEvent) => {
+    e.preventDefault();
+    if (value.trim() && !isRunning) {
+      onSubmit();
+    }
+  };
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault();
+      if (value.trim() && !isRunning) {
+        onSubmit();
+      }
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className="p-4 pt-2">
+      <div className="flex items-end gap-2 rounded-2xl border bg-background px-3 py-2 shadow-sm">
+        <textarea
+          value={value}
+          onChange={(e) => onChange(e.target.value)}
+          onKeyDown={handleKeyDown}
+          placeholder="Send a message..."
+          className="max-h-32 min-h-8 flex-1 resize-none bg-transparent py-1 text-sm leading-normal outline-none placeholder:text-muted-foreground"
+          rows={1}
+          // biome-ignore lint/a11y/noAutofocus: chat input should autofocus
+          autoFocus
+        />
+        {isRunning ? (
+          <button
+            type="button"
+            onClick={onCancel}
+            className="flex size-8 shrink-0 items-center justify-center rounded-full bg-destructive text-destructive-foreground transition-colors hover:bg-destructive/90"
+            aria-label="Stop generating"
+          >
+            <Square className="size-3 fill-current" />
+          </button>
+        ) : (
+          <button
+            type="submit"
+            disabled={!value.trim()}
+            className={cn(
+              "flex size-8 shrink-0 items-center justify-center rounded-full transition-colors",
+              value.trim()
+                ? "bg-primary text-primary-foreground hover:bg-primary/90"
+                : "bg-muted text-muted-foreground",
+            )}
+            aria-label="Send message"
+          >
+            <ArrowUp className="size-4" />
+          </button>
+        )}
+      </div>
+    </form>
+  );
+}
+
+```
+
+## components/chat/Message.tsx
+
+```tsx
+"use client";
+
+import type { UIMessage } from "ai";
+import { cn } from "@/lib/utils";
+
+type MessageProps = {
+  message: UIMessage;
+};
+
+export function Message({ message }: MessageProps) {
+  const isUser = message.role === "user";
+
+  return (
+    <div className={cn("flex", isUser ? "justify-end" : "justify-start")}>
+      <div
+        className={cn(
+          "max-w-[80%] whitespace-pre-wrap break-words rounded-2xl px-4 py-2.5 text-sm",
+          isUser
+            ? "bg-primary text-primary-foreground"
+            : "bg-muted text-foreground",
+        )}
+      >
+        {message.parts.map((part, i) => {
+          if (part.type === "text") {
+            return <p key={i}>{part.text}</p>;
+          }
+          return null;
+        })}
+      </div>
+    </div>
+  );
+}
+
+```
+
+## components/chat/Thread.tsx
+
+```tsx
+"use client";
+
+import type { UIMessage } from "ai";
+import { Message } from "./Message";
+
+type ThreadProps = {
+  messages: UIMessage[];
+  isLoading: boolean;
+  children?: React.ReactNode;
+};
+
+function ThreadWelcome() {
+  return (
+    <div className="flex flex-1 flex-col items-center justify-center text-center">
+      <h2 className="font-semibold text-lg">How can I help you today?</h2>
+      <p className="mt-1 text-muted-foreground text-sm">
+        Send a message to start a conversation.
+      </p>
+    </div>
+  );
+}
+
+function LoadingIndicator() {
+  return (
+    <div className="flex items-center gap-1.5 py-2">
+      <span className="size-1.5 animate-bounce rounded-full bg-muted-foreground/60 [animation-delay:-0.3s]" />
+      <span className="size-1.5 animate-bounce rounded-full bg-muted-foreground/60 [animation-delay:-0.15s]" />
+      <span className="size-1.5 animate-bounce rounded-full bg-muted-foreground/60" />
+    </div>
+  );
+}
+
+export function Thread({ messages, isLoading, children }: ThreadProps) {
+  return (
+    <div className="flex h-full flex-col">
+      <div className="flex flex-1 flex-col overflow-y-auto px-4 py-6">
+        {messages.length === 0 ? (
+          <ThreadWelcome />
+        ) : (
+          <div className="mx-auto w-full max-w-3xl space-y-4">
+            {messages.map((msg) => (
+              <Message key={msg.id} message={msg} />
+            ))}
+            {isLoading && <LoadingIndicator />}
+          </div>
+        )}
+      </div>
+      <div className="mx-auto w-full max-w-3xl">{children}</div>
+    </div>
+  );
+}
+
+```
+
+## components/chat/ThreadList.tsx
+
+```tsx
+"use client";
+
+import type { CloudThread } from "@assistant-ui/cloud-ai-sdk";
+import { cn } from "@/lib/utils";
+import { Plus, Trash2, MessageSquare } from "lucide-react";
+
+type ThreadListProps = {
+  threads: CloudThread[];
+  selectedId: string | null;
+  onSelect: (id: string | null) => void;
+  onDelete: (id: string) => void;
+  isLoading: boolean;
+};
+
+export function ThreadList({
+  threads,
+  selectedId,
+  onSelect,
+  onDelete,
+  isLoading,
+}: ThreadListProps) {
+  return (
+    <div className="flex h-full w-64 shrink-0 flex-col border-r bg-sidebar">
+      <div className="p-3">
+        <button
+          onClick={() => onSelect(null)}
+          className="flex w-full items-center justify-center gap-2 rounded-lg border border-sidebar-border bg-sidebar px-4 py-2 font-medium text-sidebar-foreground text-sm transition-colors hover:bg-sidebar-accent"
+        >
+          <Plus className="size-4" />
+          New Chat
+        </button>
+      </div>
+
+      <div className="flex-1 overflow-y-auto px-2 pb-2">
+        {isLoading && threads.length === 0 ? (
+          <div className="flex items-center justify-center py-8 text-muted-foreground text-sm">
+            Loading...
+          </div>
+        ) : threads.length === 0 ? (
+          <div className="flex flex-col items-center justify-center gap-2 py-8 text-center text-muted-foreground text-sm">
+            <MessageSquare className="size-6 opacity-40" />
+            <p>No conversations yet</p>
+          </div>
+        ) : (
+          <div className="space-y-0.5">
+            {threads.map((thread) => (
+              <div
+                key={thread.id}
+                onClick={() => onSelect(thread.id)}
+                className={cn(
+                  "group flex cursor-pointer items-center gap-2 rounded-lg px-3 py-2 text-sm transition-colors",
+                  selectedId === thread.id
+                    ? "bg-sidebar-accent text-sidebar-accent-foreground"
+                    : "text-sidebar-foreground hover:bg-sidebar-accent/50",
+                )}
+              >
+                <span className="flex-1 truncate">
+                  {thread.title || "New conversation"}
+                </span>
+                <button
+                  onClick={(e) => {
+                    e.stopPropagation();
+                    onDelete(thread.id);
+                  }}
+                  className="shrink-0 opacity-0 transition-opacity group-hover:opacity-100"
+                  aria-label="Delete thread"
+                >
+                  <Trash2 className="size-3.5 text-muted-foreground hover:text-destructive" />
+                </button>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+```
+
+## lib/utils.ts
+
+```typescript
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+```
+
+## next.config.js
+
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ["assistant-cloud"],
+};
+
+export default nextConfig;
+
+```
+
+## package.json
+
+```json
+{
+  "name": "with-cloud-standalone",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^3.0.33",
+    "@ai-sdk/react": "^3.0.100",
+    "ai": "^6.0.98",
+    "@assistant-ui/cloud-ai-sdk": "workspace:*",
+    "assistant-cloud": "workspace:*",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.575.0",
+    "next": "^16.1.6",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tailwind-merge": "^3.5.0"
+  },
+  "devDependencies": {
+    "@assistant-ui/x-buildutils": "workspace:*",
+    "@tailwindcss/postcss": "^4.2.1",
+    "@types/node": "^25.3.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^4.2.1",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5.9.3"
+  }
+}
+
+```
+
+## README.md
+
+```markdown
+# Cloud Persistence for AI SDK (Standalone)
+
+Lightweight cloud persistence for AI SDK apps without assistant-ui components.
+
+> **Want the full assistant-ui experience?** See [with-cloud](../with-cloud) instead, which uses `useChatRuntime` with `<Thread />` and other primitives.
+
+## Setup
+
+1. Get your project URL from [cloud.assistant-ui.com](https://cloud.assistant-ui.com)
+2. Add to `.env`:
+   ```
+   NEXT_PUBLIC_ASSISTANT_BASE_URL=https://your-project.assistant-api.com
+   OPENAI_API_KEY=sk-...
+   ```
+
+## Usage
+
+### Zero-config (anonymous users)
+
+```tsx
+import { useCloudChat } from "@assistant-ui/cloud-ai-sdk";
+
+function Chat() {
+  // Auto-initializes anonymous cloud from NEXT_PUBLIC_ASSISTANT_BASE_URL
+  const { messages, sendMessage, threads } = useCloudChat();
+  // ...
+}
+```
+
+### With custom cloud instance (authenticated users)
+
+```tsx
+import { AssistantCloud } from "assistant-cloud";
+import { useCloudChat } from "@assistant-ui/cloud-ai-sdk";
+
+function Chat() {
+  const cloud = useMemo(() => new AssistantCloud({
+    baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
+    authToken: async () => getToken(),
+  }), [getToken]);
+
+  const { messages, sendMessage, threads } = useCloudChat({ cloud });
+  // ...
+}
+```
+
+### With external thread management
+
+When you need thread operations in a separate component (e.g., a sidebar) or custom options like `includeArchived`:
+
+```tsx
+// In parent or context
+const myThreads = useThreads({ cloud, includeArchived: true });
+
+// In chat component - uses your thread state
+const { messages, sendMessage } = useCloudChat({ threads: myThreads });
+
+// In sidebar component - same thread state
+<ThreadList threads={myThreads.threads} onSelect={myThreads.selectThread} />
+```
+
+## How it works
+
+Messages persist automatically as they complete. Thread creation is handled automatically when you send the first message — the thread is created, selected, and the list is refreshed. Call `threads.selectThread(id)` to switch threads, `threads.selectThread(null)` for a new chat.
+
+```
+
+## tsconfig.json
+
+```json
+{
+  "extends": "@assistant-ui/x-buildutils/ts/next",
+  "compilerOptions": {
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
+
+```
+