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

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

@@ -1,681 +0,0 @@
-# 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-5.6-luna"),
-    messages: await convertToModelMessages(messages),
-  });
-
-  return result.toUIMessageStreamResponse({
-    messageMetadata: ({ part }) => {
-      if (part.type === "finish") {
-        return {
-          usage: part.totalUsage,
-        };
-      }
-      if (part.type === "finish-step") {
-        return {
-          modelId: part.response.modelId,
-        };
-      }
-      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="bg-background flex items-end gap-2 rounded-2xl border px-3 py-2 shadow-sm">
-        <textarea
-          value={value}
-          onChange={(e) => onChange(e.target.value)}
-          onKeyDown={handleKeyDown}
-          placeholder="Send a message..."
-          className="placeholder:text-muted-foreground max-h-32 min-h-8 flex-1 resize-none bg-transparent py-1 text-sm leading-normal outline-none"
-          rows={1}
-          autoFocus
-        />
-        {isRunning ? (
-          <button
-            type="button"
-            onClick={onCancel}
-            className="bg-destructive text-destructive-foreground hover:bg-destructive/90 flex size-8 shrink-0 items-center justify-center rounded-full transition-colors"
-            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%] rounded-2xl px-4 py-2.5 text-sm break-words whitespace-pre-wrap",
-          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="text-lg font-semibold">How can I help you today?</h2>
-      <p className="text-muted-foreground mt-1 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="bg-muted-foreground/60 size-1.5 animate-bounce rounded-full [animation-delay:-0.3s]" />
-      <span className="bg-muted-foreground/60 size-1.5 animate-bounce rounded-full [animation-delay:-0.15s]" />
-      <span className="bg-muted-foreground/60 size-1.5 animate-bounce rounded-full" />
-    </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="bg-sidebar flex h-full w-64 shrink-0 flex-col border-r">
-      <div className="p-3">
-        <button
-          type="button"
-          onClick={() => onSelect(null)}
-          className="border-sidebar-border bg-sidebar text-sidebar-foreground hover:bg-sidebar-accent flex w-full items-center justify-center gap-2 rounded-lg border px-4 py-2 text-sm font-medium transition-colors"
-        >
-          <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="text-muted-foreground flex items-center justify-center py-8 text-sm">
-            Loading...
-          </div>
-        ) : threads.length === 0 ? (
-          <div className="text-muted-foreground flex flex-col items-center justify-center gap-2 py-8 text-center text-sm">
-            <MessageSquare className="size-6 opacity-40" />
-            <p>No conversations yet</p>
-          </div>
-        ) : (
-          <div className="space-y-0.5">
-            {threads.map((thread) => (
-              <button
-                type="button"
-                key={thread.id}
-                onClick={() => onSelect(thread.id)}
-                className={cn(
-                  "group flex w-full cursor-pointer items-center gap-2 rounded-lg px-3 py-2 text-left 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
-                  type="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="text-muted-foreground hover:text-destructive size-3.5" />
-                </button>
-              </button>
-            ))}
-          </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
-import { withAui } from "@assistant-ui/next";
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  transpilePackages: ["assistant-cloud"],
-};
-
-export default withAui(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": "^4.0.46",
-    "@assistant-ui/cloud-ai-sdk": "workspace:*",
-    "ai": "^7.0.77",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "lucide-react": "^1.33.0",
-    "next": "^16.3.2",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "tailwind-merge": "^3.6.0"
-  },
-  "devDependencies": {
-    "@assistant-ui/next": "workspace:*",
-    "@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.5",
-    "postcss": "^8.5.26",
-    "tailwindcss": "^4.3.3",
-    "tw-animate-css": "^1.4.0",
-    "typescript": "^7.0.2"
-  }
-}
-
-```
-
-## 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](https://github.com/assistant-ui/assistant-ui/tree/main/examples/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"]
-}
-
-```
-