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

package/.docs/organized/code-examples/with-ag-ui.md

@@ -1,552 +0,0 @@
-# Example: with-ag-ui
-
-## 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 { MyRuntimeProvider } from "@/app/MyRuntimeProvider";
-
-import "./globals.css";
-
-export const metadata: Metadata = {
-  title: "Create Next App",
-  description: "Generated by create next app",
-};
-
-export const dynamic = "force-dynamic";
-
-export default function RootLayout({
-  children,
-}: Readonly<{
-  children: React.ReactNode;
-}>) {
-  return (
-    <html lang="en" className="h-dvh">
-      <body className="h-dvh font-sans">
-        <MyRuntimeProvider>{children}</MyRuntimeProvider>
-      </body>
-    </html>
-  );
-}
-
-```
-
-## app/MyRuntimeProvider.tsx
-
-```tsx
-"use client";
-
-import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
-import {
-  AssistantRuntimeProvider,
-  type ThreadMessage,
-} from "@assistant-ui/react";
-import { HttpAgent } from "@ag-ui/client";
-import { useAgUiRuntime } from "@assistant-ui/react-ag-ui";
-
-type StoredThread = {
-  id: string;
-  messages: readonly ThreadMessage[];
-};
-
-/**
- * AG-UI runtime with threadList adapter for multi-thread support.
- */
-export function MyRuntimeProvider({
-  children,
-}: Readonly<{ children: ReactNode }>) {
-  const agentUrl =
-    (process.env.NEXT_PUBLIC_AGUI_AGENT_URL as string | undefined) ??
-    "http://localhost:8000/agent";
-
-  // Simple in-memory thread storage
-  const threadsRef = useRef<Map<string, StoredThread>>(new Map());
-  const [currentThreadId, setCurrentThreadId] = useState<string>(() => {
-    const id = crypto.randomUUID();
-    threadsRef.current.set(id, { id, messages: [] });
-    return id;
-  });
-
-  const agent = useMemo(() => {
-    return new HttpAgent({
-      url: agentUrl,
-      threadId: currentThreadId,
-      headers: {
-        Accept: "text/event-stream",
-      },
-    });
-  }, [agentUrl, currentThreadId]);
-
-  const threadListAdapter = useMemo(
-    () => ({
-      threadId: currentThreadId,
-      onSwitchToNewThread: async () => {
-        const newId = crypto.randomUUID();
-        threadsRef.current.set(newId, { id: newId, messages: [] });
-        setCurrentThreadId(newId);
-        console.debug("[agui] Switched to new thread:", newId);
-      },
-      onSwitchToThread: async (threadId: string) => {
-        const thread = threadsRef.current.get(threadId);
-        if (!thread) {
-          throw new Error(`Thread ${threadId} not found`);
-        }
-        setCurrentThreadId(threadId);
-        console.debug("[agui] Switched to thread:", threadId);
-        return { messages: thread.messages };
-      },
-    }),
-    [currentThreadId],
-  );
-
-  const runtime = useAgUiRuntime({
-    agent,
-    logger: {
-      debug: (...a: any[]) => console.debug("[agui]", ...a),
-      error: (...a: any[]) => console.error("[agui]", ...a),
-    },
-    adapters: {
-      threadList: threadListAdapter,
-    },
-  });
-
-  // Persist messages to threadsRef when they change
-  useEffect(() => {
-    return runtime.thread.subscribe(() => {
-      threadsRef.current.set(currentThreadId, {
-        id: currentThreadId,
-        messages: runtime.thread.getState().messages,
-      });
-    });
-  }, [runtime, currentThreadId]);
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-
-```
-
-## app/page.tsx
-
-```tsx
-"use client";
-
-import {
-  defineToolkit,
-  useAui,
-  AuiProvider,
-  AuiConfig,
-  Suggestions,
-  Tools,
-} from "@assistant-ui/react";
-import { Thread } from "@/components/assistant-ui/thread";
-import { PlusIcon } from "lucide-react";
-
-const toolkit = defineToolkit({
-  browser_alert: {
-    description: "Display a native browser alert dialog to the user.",
-    parameters: {
-      type: "object",
-      properties: {
-        message: {
-          type: "string",
-          description: "Text to display inside the alert dialog.",
-        },
-      },
-      required: ["message"],
-    },
-    execute: async ({ message }) => {
-      alert(message);
-      return { status: "shown" };
-    },
-    render: ({ args, result }) => (
-      <div className="mt-3 w-full max-w-(--thread-max-width) rounded-lg border px-4 py-3 text-sm">
-        <p className="text-muted-foreground font-semibold">browser_alert</p>
-        <p className="mt-1">
-          Requested alert with message:
-          <span className="text-foreground ml-1 font-mono">
-            {JSON.stringify(args.message)}
-          </span>
-        </p>
-        {result?.status === "shown" && (
-          <p className="text-foreground/70 mt-2 text-xs">
-            Alert displayed in this tab.
-          </p>
-        )}
-      </div>
-    ),
-  },
-});
-
-function NewThreadButton() {
-  const aui = useAui();
-
-  return (
-    <button
-      type="button"
-      onClick={() => aui.threads.switchToNewThread()}
-      className="bg-background hover:bg-accent absolute top-4 right-4 z-10 flex items-center gap-2 rounded-lg border px-3 py-2 text-sm font-medium shadow-sm transition-colors"
-    >
-      <PlusIcon className="size-4" />
-      New Thread
-    </button>
-  );
-}
-
-function ThreadWithSuggestions() {
-  const aui = useAui();
-  const config = AuiConfig({
-    suggestions: Suggestions([
-      {
-        title: "Run a web search",
-        label: "for recent AI news",
-        prompt: "Search the web for the latest AI news.",
-      },
-      {
-        title: "Show a browser alert",
-        label: "using the alert tool",
-        prompt: "Show me a browser alert saying hello!",
-      },
-    ]),
-  });
-  return (
-    <AuiProvider extends={aui} config={config}>
-      <Thread />
-    </AuiProvider>
-  );
-}
-
-export default function Home() {
-  const aui = useAui();
-  const config = AuiConfig({
-    tools: Tools({ toolkit }),
-  });
-
-  return (
-    <AuiProvider extends={aui} config={config}>
-      <main className="relative h-dvh">
-        <NewThreadButton />
-        <ThreadWithSuggestions />
-      </main>
-    </AuiProvider>
-  );
-}
-
-```
-
-## 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 { withAui } from "@assistant-ui/next";
-import type { NextConfig } from "next";
-
-const nextConfig: NextConfig = {/* config options here */};
-
-export default withAui(nextConfig);
-
-```
-
-## package.json
-
-```json
-{
-  "name": "with-ag-ui",
-  "version": "0.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start"
-  },
-  "dependencies": {
-    "@ag-ui/client": "^0.0.57",
-    "@assistant-ui/react": "workspace:*",
-    "@assistant-ui/react-ag-ui": "workspace:*",
-    "@assistant-ui/react-markdown": "workspace:*",
-    "@assistant-ui/ui": "workspace:*",
-    "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"
-  },
-  "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.4",
-    "postcss": "^8.5.26",
-    "tailwindcss": "^4.3.3",
-    "tw-animate-css": "^1.4.0",
-    "typescript": "^7.0.2"
-  }
-}
-
-```
-
-## README.md
-
-```markdown
-# AG-UI Protocol Integration
-
-This example demonstrates how to integrate assistant-ui with the AG-UI protocol for connecting to AG-UI compatible agents.
-
-## Quick Start
-
-### Using CLI (Recommended)
-
-```bash
-npx assistant-ui@latest create my-app --example with-ag-ui
-cd my-app
-```
-
-### 1. Start the Backend Agent
-
-```bash
-# Install Python dependencies
-pip install -r server/requirements.txt
-
-# Run the agent (echo mode by default)
-python server/agent.py
-
-# Or with OpenAI integration
-OPENAI_API_KEY=sk-xxx python server/agent.py
-```
-
-The agent will start at `http://localhost:8000/agent`.
-
-### 2. Configure Environment
-
-Create `.env.local`:
-
-```
-NEXT_PUBLIC_AGUI_AGENT_URL=http://localhost:8000/agent
-```
-
-### 3. Run the Frontend
-
-```bash
-pnpm dev
-```
-
-## Features
-
-- AG-UI protocol integration via `@assistant-ui/react-ag-ui`
-- Multi-thread support with "New Thread" button
-- Custom browser alert tool demonstration
-- Client-side tool execution
-- Tool result rendering
-
-## Backend Agent
-
-The included `server/agent.py` provides:
-
-- **Echo mode** (default): Echoes back user messages for testing
-- **OpenAI mode**: Uses GPT-5.6 Luna when `OPENAI_API_KEY` is set
-
-### Endpoints
-
-- `POST /agent` - AG-UI agent endpoint (SSE streaming)
-- `GET /health` - Health check
-
-## Related Documentation
-
-- [assistant-ui Documentation](https://www.assistant-ui.com/docs)
-- [AG-UI Protocol](https://docs.ag-ui.com)
-
-```
-
-## 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"]
-}
-
-```
-