@assistant-ui/mcp-docs-server 0.1.24 → 0.1.25

package/.docs/organized/code-examples/waterfall.md

@@ -688,7 +688,9 @@ export function WaterfallTimeline() {
               }
             }}
           >
-            <SpanPrimitive.Children components={{ Span: WaterfallRow }} />
+            <SpanPrimitive.Children>
+              {() => <WaterfallRow />}
+            </SpanPrimitive.Children>
           </div>
         </WaterfallLayoutContext.Provider>
       </div>
@@ -774,7 +776,7 @@ export default nextConfig;
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
     "@tailwindcss/postcss": "^4.2.1",
-    "@types/node": "^25.3.3",
+    "@types/node": "^25.5.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "postcss": "^8.5.8",

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

@@ -0,0 +1,676 @@
+# Example: with-a2a
+
+## 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: "assistant-ui + A2A",
+  description: "A2A protocol integration with assistant-ui",
+};
+
+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 type { ReactNode } from "react";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import { useA2ARuntime } from "@assistant-ui/react-a2a";
+
+export function MyRuntimeProvider({
+  children,
+}: Readonly<{ children: ReactNode }>) {
+  const serverUrl =
+    (process.env["NEXT_PUBLIC_A2A_SERVER_URL"] as string | undefined) ??
+    "http://localhost:9999";
+
+  const runtime = useA2ARuntime({
+    baseUrl: serverUrl,
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+
+```
+
+## app/page.tsx
+
+```tsx
+"use client";
+
+import { useAui, AuiProvider, Suggestions } from "@assistant-ui/react";
+import {
+  useA2ATask,
+  useA2AArtifacts,
+  useA2AAgentCard,
+  type A2ATaskState,
+  type A2APart,
+} from "@assistant-ui/react-a2a";
+import { Thread } from "@/components/assistant-ui/thread";
+
+// === State Badge ===
+
+const STATE_CONFIG: Record<
+  string,
+  { label: string; color: string; bg: string }
+> = {
+  submitted: {
+    label: "Submitted",
+    color: "text-blue-600",
+    bg: "bg-blue-100 dark:bg-blue-900/30",
+  },
+  working: {
+    label: "Working",
+    color: "text-amber-600",
+    bg: "bg-amber-100 dark:bg-amber-900/30",
+  },
+  completed: {
+    label: "Completed",
+    color: "text-green-600",
+    bg: "bg-green-100 dark:bg-green-900/30",
+  },
+  failed: {
+    label: "Failed",
+    color: "text-red-600",
+    bg: "bg-red-100 dark:bg-red-900/30",
+  },
+  canceled: {
+    label: "Canceled",
+    color: "text-gray-600",
+    bg: "bg-gray-100 dark:bg-gray-900/30",
+  },
+  rejected: {
+    label: "Rejected",
+    color: "text-red-600",
+    bg: "bg-red-100 dark:bg-red-900/30",
+  },
+  input_required: {
+    label: "Input Required",
+    color: "text-purple-600",
+    bg: "bg-purple-100 dark:bg-purple-900/30",
+  },
+  auth_required: {
+    label: "Auth Required",
+    color: "text-orange-600",
+    bg: "bg-orange-100 dark:bg-orange-900/30",
+  },
+};
+
+function StateBadge({ state }: { state: A2ATaskState }) {
+  const config = STATE_CONFIG[state] ?? {
+    label: state,
+    color: "text-gray-600",
+    bg: "bg-gray-100",
+  };
+  const isActive = state === "working" || state === "submitted";
+
+  return (
+    <span
+      className={`inline-flex items-center gap-1.5 rounded-full px-2.5 py-0.5 font-medium text-xs ${config.color} ${config.bg}`}
+    >
+      {isActive ? (
+        <span className="relative flex size-1.5">
+          <span className="absolute inline-flex size-full animate-ping rounded-full bg-current opacity-75" />
+          <span className="relative inline-flex size-1.5 rounded-full bg-current" />
+        </span>
+      ) : (
+        <span className="inline-flex size-1.5 rounded-full bg-current" />
+      )}
+      {config.label}
+    </span>
+  );
+}
+
+// === Task Status Bar ===
+
+function TaskStatusBar() {
+  const task = useA2ATask();
+
+  if (!task) return null;
+
+  const { state } = task.status;
+  const isError = state === "failed" || state === "rejected";
+  const errorText = isError ? task.status.message?.parts?.[0]?.text : undefined;
+
+  return (
+    <div className="flex items-center gap-2 border-b px-4 py-2 text-sm">
+      <StateBadge state={state} />
+      <span className="text-muted-foreground">Task {task.id.slice(0, 8)}</span>
+      {errorText && (
+        <span className="ml-auto text-red-600 text-xs">{errorText}</span>
+      )}
+    </div>
+  );
+}
+
+// === Artifact Part Renderer ===
+
+function ArtifactPartView({ part }: { part: A2APart }) {
+  if (part.text !== undefined) {
+    return (
+      <pre className="overflow-x-auto whitespace-pre-wrap rounded border bg-background p-2 font-mono text-xs">
+        {part.text}
+      </pre>
+    );
+  }
+  if (part.data !== undefined) {
+    return (
+      <div className="rounded border bg-background p-2">
+        <div className="mb-1 font-medium text-muted-foreground text-xs">
+          Data
+        </div>
+        <pre className="overflow-x-auto whitespace-pre-wrap font-mono text-xs">
+          {JSON.stringify(part.data, null, 2)}
+        </pre>
+      </div>
+    );
+  }
+  if (part.url !== undefined) {
+    const isImage = part.mediaType?.startsWith("image/");
+    if (isImage) {
+      return (
+        <img
+          src={part.url}
+          alt={part.filename ?? "image"}
+          className="max-h-64 rounded border"
+        />
+      );
+    }
+    return (
+      <a
+        href={part.url}
+        target="_blank"
+        rel="noopener noreferrer"
+        className="inline-flex items-center gap-2 rounded border bg-background p-2 text-sm hover:bg-muted"
+      >
+        <span>📄</span>
+        <span>{part.filename ?? "Download"}</span>
+        {part.mediaType && (
+          <span className="text-muted-foreground text-xs">
+            {part.mediaType}
+          </span>
+        )}
+      </a>
+    );
+  }
+  if (part.raw !== undefined) {
+    const isImage = part.mediaType?.startsWith("image/");
+    if (isImage) {
+      return (
+        <img
+          src={`data:${part.mediaType};base64,${part.raw}`}
+          alt={part.filename ?? "image"}
+          className="max-h-64 rounded border"
+        />
+      );
+    }
+    const dataUri = `data:${part.mediaType ?? "application/octet-stream"};base64,${part.raw}`;
+    return (
+      <a
+        href={dataUri}
+        download={part.filename ?? "download"}
+        className="inline-flex items-center gap-2 rounded border bg-background p-2 text-sm hover:bg-muted"
+      >
+        <span>📎</span>
+        <span>{part.filename ?? "File"}</span>
+        {part.mediaType && (
+          <span className="text-muted-foreground text-xs">
+            {part.mediaType}
+          </span>
+        )}
+      </a>
+    );
+  }
+  return null;
+}
+
+// === Artifact Panel ===
+
+function ArtifactPanel() {
+  const artifacts = useA2AArtifacts();
+
+  if (artifacts.length === 0) return null;
+
+  return (
+    <div className="max-h-80 overflow-y-auto border-t px-4 py-3">
+      <h3 className="mb-2 font-medium text-muted-foreground text-xs">
+        Artifacts ({artifacts.length})
+      </h3>
+      <div className="space-y-2">
+        {artifacts.map((artifact) => (
+          <div
+            key={artifact.artifactId}
+            className="overflow-hidden rounded-md border bg-muted/30"
+          >
+            <div className="flex items-center gap-2 border-b bg-muted/50 px-3 py-1.5">
+              <span className="font-medium text-xs">
+                {artifact.name ?? artifact.artifactId}
+              </span>
+              {artifact.description && (
+                <span className="text-muted-foreground text-xs">
+                  {artifact.description}
+                </span>
+              )}
+            </div>
+            <div className="space-y-2 p-3">
+              {artifact.parts.map((part, i) => (
+                <ArtifactPartView key={i} part={part} />
+              ))}
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// === Agent Card Banner ===
+
+function AgentCardBanner() {
+  const card = useA2AAgentCard();
+
+  if (!card) return null;
+
+  return (
+    <div className="flex items-center gap-3 border-b bg-muted/30 px-4 py-2">
+      <div className="flex-1">
+        <div className="font-medium text-sm">{card.name}</div>
+        <div className="text-muted-foreground text-xs">{card.description}</div>
+      </div>
+      <div className="flex flex-wrap gap-1">
+        {card.skills.map((skill) => (
+          <span
+            key={skill.id}
+            className="rounded-md bg-muted px-2 py-0.5 text-xs"
+            title={skill.description}
+          >
+            {skill.name}
+          </span>
+        ))}
+      </div>
+      <div className="text-muted-foreground text-xs">
+        v{card.version}
+        {card.capabilities.streaming && " · Streaming"}
+      </div>
+    </div>
+  );
+}
+
+// === Thread with Suggestions ===
+
+function ThreadWithSuggestions() {
+  const aui = useAui({
+    suggestions: Suggestions([
+      {
+        title: "Chat",
+        label: "say hello",
+        prompt: "Hello! What can you do?",
+      },
+      {
+        title: "Generate artifacts",
+        label: "code + data + file",
+        prompt: "/artifacts a fibonacci function in Python",
+      },
+      {
+        title: "Multi-step",
+        label: "input-required flow",
+        prompt: "/multistep",
+      },
+      {
+        title: "Failure demo",
+        label: "test error handling",
+        prompt: "/fail",
+      },
+      {
+        title: "Slow task",
+        label: "test cancellation",
+        prompt: "/slow",
+      },
+    ]),
+  });
+  return (
+    <AuiProvider value={aui}>
+      <Thread />
+    </AuiProvider>
+  );
+}
+
+// === Main ===
+
+export default function Home() {
+  return (
+    <main className="flex h-dvh flex-col">
+      <AgentCardBanner />
+      <TaskStatusBar />
+      <div className="min-h-0 flex-1">
+        <ThreadWithSuggestions />
+      </div>
+      <ArtifactPanel />
+    </main>
+  );
+}
+
+```
+
+## 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-a2a",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@assistant-ui/react": "workspace:*",
+    "@assistant-ui/react-a2a": "workspace:*",
+    "@assistant-ui/react-markdown": "workspace:*",
+    "@assistant-ui/ui": "workspace:*",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.577.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.5.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "postcss": "^8.5.8",
+    "tailwindcss": "^4.2.1",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5.9.3"
+  }
+}
+
+```
+
+## README.md
+
+```markdown
+# with-a2a
+
+An example of using [assistant-ui](https://www.assistant-ui.com/) with the [A2A (Agent-to-Agent) protocol](https://github.com/a2aproject/A2A).
+
+## Getting Started
+
+### 1. Start an A2A server
+
+You need an A2A-compatible agent server. For example, using the [assistant-ui-a2a](https://github.com/assistant-ui/assistant-ui-a2a) kitchen sink demo:
+
+```bash
+cd a2a-server
+pip install -e .
+python main.py
+```
+
+This starts an A2A server at `http://localhost:9999` with 5 skills.
+
+### 2. Configure the frontend
+
+```bash
+cp .env.example .env
+# Edit .env if your A2A server is not at localhost:9999
+```
+
+### 3. Run the frontend
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+## Features Demonstrated
+
+| Feature | Skill / Command |
+|---|---|
+| Streaming chat | Default chat |
+| Artifacts (text, data, file) | `/artifacts <topic>` |
+| Multi-step input-required flow | `/multistep` then provide topic |
+| Error/failure handling | `/fail` |
+| Long-running + cancellation | `/slow` |
+| Agent card display | Automatic on load |
+| Task state tracking (8 states) | All commands |
+
+## Architecture
+
+```
+Browser (Next.js) ──A2A v1.0 SSE──▶ A2A Server
+```
+
+No proxy backend needed. `@assistant-ui/react-a2a` handles the full A2A protocol directly:
+- Agent card discovery (`/.well-known/agent-card.json`)
+- Streaming via `POST /message:stream` (SSE)
+- Task lifecycle management
+- Artifact accumulation
+
+```
+
+## 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/*"],
+      "@/lib/utils": ["../../packages/ui/src/lib/utils"],
+      "@assistant-ui/ui/*": ["../../packages/ui/src/*"]
+    }
+  },
+  "include": ["**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
+
+```
+