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

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

@@ -1,674 +0,0 @@
-# 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,
-  AuiConfig,
-  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";
-
-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 text-xs font-medium ${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>
-  );
-}
-
-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-xs text-red-600">{errorText}</span>
-      )}
-    </div>
-  );
-}
-
-function ArtifactPartView({ part }: { part: A2APart }) {
-  if (part.text !== undefined) {
-    return (
-      <pre className="bg-background overflow-x-auto rounded border p-2 font-mono text-xs whitespace-pre-wrap">
-        {part.text}
-      </pre>
-    );
-  }
-  if (part.data !== undefined) {
-    return (
-      <div className="bg-background rounded border p-2">
-        <div className="text-muted-foreground mb-1 text-xs font-medium">
-          Data
-        </div>
-        <pre className="overflow-x-auto font-mono text-xs whitespace-pre-wrap">
-          {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="bg-background hover:bg-muted inline-flex items-center gap-2 rounded border p-2 text-sm"
-      >
-        <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="bg-background hover:bg-muted inline-flex items-center gap-2 rounded border p-2 text-sm"
-      >
-        <span>📎</span>
-        <span>{part.filename ?? "File"}</span>
-        {part.mediaType && (
-          <span className="text-muted-foreground text-xs">
-            {part.mediaType}
-          </span>
-        )}
-      </a>
-    );
-  }
-  return null;
-}
-
-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="text-muted-foreground mb-2 text-xs font-medium">
-        Artifacts ({artifacts.length})
-      </h3>
-      <div className="space-y-2">
-        {artifacts.map((artifact) => (
-          <div
-            key={artifact.artifactId}
-            className="bg-muted/30 overflow-hidden rounded-md border"
-          >
-            <div className="bg-muted/50 flex items-center gap-2 border-b px-3 py-1.5">
-              <span className="text-xs font-medium">
-                {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>
-  );
-}
-
-function AgentCardBanner() {
-  const card = useA2AAgentCard();
-
-  if (!card) return null;
-
-  return (
-    <div className="bg-muted/30 flex items-center gap-3 border-b px-4 py-2">
-      <div className="flex-1">
-        <div className="text-sm font-medium">{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="bg-muted rounded-md 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>
-  );
-}
-
-function ThreadWithSuggestions() {
-  const aui = useAui();
-  const config = AuiConfig({
-    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 extends={aui} config={config}>
-      <Thread />
-    </AuiProvider>
-  );
-}
-
-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 { 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-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": "^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
-# 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/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"]
-}
-
-```
-