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

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

@@ -1,642 +0,0 @@
-# Example: with-livekit
-
-## app/api/chat/route.ts
-
-```typescript
-import { openai } from "@ai-sdk/openai";
-import {
-  streamText,
-  type UIMessage,
-  convertToModelMessages,
-  stepCountIs,
-} 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),
-    stopWhen: stepCountIs(10),
-  });
-
-  return result.toUIMessageStreamResponse();
-}
-
-```
-
-## app/api/livekit-token/route.ts
-
-```typescript
-import { AccessToken } from "livekit-server-sdk";
-import { NextResponse } from "next/server";
-
-export async function POST() {
-  const apiKey = process.env.LIVEKIT_API_KEY;
-  const apiSecret = process.env.LIVEKIT_API_SECRET;
-  const roomName = process.env.LIVEKIT_ROOM_NAME ?? "assistant-room";
-
-  if (!apiKey || !apiSecret) {
-    return NextResponse.json(
-      { error: "LIVEKIT_API_KEY and LIVEKIT_API_SECRET must be set" },
-      { status: 500 },
-    );
-  }
-
-  const participantIdentity = `user-${Date.now()}`;
-
-  const at = new AccessToken(apiKey, apiSecret, {
-    identity: participantIdentity,
-  });
-  at.addGrant({
-    roomJoin: true,
-    room: roomName,
-    canPublish: true,
-    canSubscribe: true,
-  });
-
-  const token = await at.toJwt();
-
-  return NextResponse.json({ token });
-}
-
-```
-
-## 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);
-}
-
-:root {
-  --radius: 0.625rem;
-  --background: oklch(1 0 0);
-  --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);
-  --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);
-}
-
-@layer base {
-  * {
-    @apply border-border outline-ring/50;
-  }
-  body {
-    @apply bg-background text-foreground;
-  }
-}
-
-```
-
-## app/layout.tsx
-
-```tsx
-import type { Metadata } from "next";
-import "./globals.css";
-
-export const metadata: Metadata = {
-  title: "LiveKit Voice Example",
-  description:
-    "Example using @assistant-ui/react with LiveKit for realtime voice",
-};
-
-export default function RootLayout({
-  children,
-}: Readonly<{
-  children: React.ReactNode;
-}>) {
-  return (
-    <html lang="en">
-      <body className="h-dvh">{children}</body>
-    </html>
-  );
-}
-
-```
-
-## app/page.tsx
-
-```tsx
-"use client";
-
-import { AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
-import { LiveKitVoiceAdapter } from "@/lib/livekit-voice-adapter";
-import { VoiceThread } from "./voice-thread";
-
-export default function Home() {
-  const runtime = useChatRuntime({
-    adapters: {
-      voice: new LiveKitVoiceAdapter({
-        url: process.env.NEXT_PUBLIC_LIVEKIT_URL ?? "ws://localhost:7880",
-        token: async () => {
-          const res = await fetch("/api/livekit-token", { method: "POST" });
-          const { token } = await res.json();
-          return token;
-        },
-      }),
-    },
-  });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <VoiceThread />
-    </AssistantRuntimeProvider>
-  );
-}
-
-```
-
-## app/voice-thread.tsx
-
-```tsx
-"use client";
-
-import { MarkdownText } from "@/components/assistant-ui/markdown-text";
-import {
-  VoiceOrb,
-  VoiceConnectButton,
-  VoiceMuteButton,
-  VoiceDisconnectButton,
-  deriveVoiceOrbState,
-} from "@/components/assistant-ui/voice";
-import { TooltipIconButton } from "@/components/assistant-ui/tooltip-icon-button";
-import {
-  AuiIf,
-  MessagePrimitive,
-  ThreadPrimitive,
-  useAuiState,
-  useVoiceState,
-  useVoiceVolume,
-} from "@assistant-ui/react";
-import { ArrowDownIcon } from "lucide-react";
-import type { FC } from "react";
-
-export const VoiceThread: FC = () => {
-  return (
-    <ThreadPrimitive.Root
-      className="aui-root aui-thread-root bg-background flex h-full flex-col"
-      style={{ ["--thread-max-width" as string]: "44rem" }}
-    >
-      <ThreadPrimitive.Viewport className="aui-thread-viewport relative flex flex-1 flex-col overflow-y-scroll scroll-smooth px-4 pt-4">
-        <AuiIf condition={(s) => s.thread.isEmpty}>
-          <VoiceWelcome />
-        </AuiIf>
-
-        <ThreadPrimitive.Messages>
-          {() => <ThreadMessage />}
-        </ThreadPrimitive.Messages>
-
-        <ThreadPrimitive.ViewportFooter className="bg-background sticky bottom-0 mx-auto mt-auto flex w-full max-w-(--thread-max-width) flex-col items-center pt-4 pb-6">
-          <ThreadScrollToBottom />
-          <VoiceControlCenter />
-        </ThreadPrimitive.ViewportFooter>
-      </ThreadPrimitive.Viewport>
-    </ThreadPrimitive.Root>
-  );
-};
-
-const VoiceWelcome: FC = () => {
-  return (
-    <div className="aui-thread-welcome-root mx-auto my-auto flex w-full max-w-(--thread-max-width) grow flex-col items-center justify-center gap-2">
-      <p className="fade-in slide-in-from-bottom-1 animate-in fill-mode-both text-2xl font-semibold duration-200">
-        Voice Conversation
-      </p>
-      <p className="fade-in slide-in-from-bottom-1 animate-in fill-mode-both text-muted-foreground delay-75 duration-200">
-        Tap connect to start speaking
-      </p>
-    </div>
-  );
-};
-
-const ThreadScrollToBottom: FC = () => {
-  return (
-    <ThreadPrimitive.ScrollToBottom asChild>
-      <TooltipIconButton
-        tooltip="Scroll to bottom"
-        variant="outline"
-        className="dark:border-border dark:bg-background dark:hover:bg-accent absolute -top-12 z-10 self-center rounded-full p-4 disabled:invisible"
-      >
-        <ArrowDownIcon />
-      </TooltipIconButton>
-    </ThreadPrimitive.ScrollToBottom>
-  );
-};
-
-const VoiceControlCenter: FC = () => {
-  return (
-    <div className="aui-voice-control-center flex flex-col items-center gap-4">
-      <VoiceOrb variant="blue" className="size-20" />
-      <VoiceWaveform />
-
-      <div className="flex items-center gap-3">
-        <AuiIf
-          condition={(s) =>
-            s.thread.voice == null || s.thread.voice.status.type === "ended"
-          }
-        >
-          <VoiceConnectButton />
-        </AuiIf>
-
-        <AuiIf condition={(s) => s.thread.voice?.status.type === "starting"}>
-          <span className="text-muted-foreground text-sm">Connecting...</span>
-        </AuiIf>
-
-        <AuiIf condition={(s) => s.thread.voice?.status.type === "running"}>
-          <VoiceMuteButton />
-          <VoiceDisconnectButton />
-        </AuiIf>
-      </div>
-    </div>
-  );
-};
-
-const BAR_WEIGHTS = [0.4, 0.65, 0.85, 1.0, 0.9, 0.75, 0.5];
-
-const VoiceWaveform: FC = () => {
-  const voiceState = useVoiceState();
-  const state = deriveVoiceOrbState(voiceState);
-  const volume = useVoiceVolume();
-  const isActive = state === "listening" || state === "speaking";
-
-  return (
-    <div className="aui-voice-waveform flex h-8 items-center justify-center gap-[3px]">
-      {BAR_WEIGHTS.map((weight, i) => {
-        const scale = isActive ? 0.1 + volume * 0.9 * weight : 0.1;
-        return (
-          <span
-            key={i}
-            className="aui-voice-waveform-bar bg-foreground/50 h-full w-[3px] origin-center rounded-full transition-transform duration-100"
-            style={{ transform: `scaleY(${scale})` }}
-          />
-        );
-      })}
-    </div>
-  );
-};
-
-const ThreadMessage: FC = () => {
-  const role = useAuiState((s) => s.message.role);
-  if (role === "user") return <UserMessage />;
-  return <AssistantMessage />;
-};
-
-const AssistantMessage: FC = () => {
-  return (
-    <MessagePrimitive.Root
-      className="aui-assistant-message-root fade-in slide-in-from-bottom-1 animate-in relative mx-auto w-full max-w-(--thread-max-width) py-3 duration-150"
-      data-role="assistant"
-    >
-      <div className="aui-assistant-message-content text-foreground px-2 leading-relaxed wrap-break-word">
-        <MessagePrimitive.Parts>
-          {({ part }) => {
-            if (part.type === "text") return <MarkdownText />;
-            return null;
-          }}
-        </MessagePrimitive.Parts>
-      </div>
-    </MessagePrimitive.Root>
-  );
-};
-
-const UserMessage: FC = () => {
-  return (
-    <MessagePrimitive.Root
-      className="aui-user-message-root fade-in slide-in-from-bottom-1 animate-in mx-auto flex w-full max-w-(--thread-max-width) justify-end px-2 py-3 duration-150"
-      data-role="user"
-    >
-      <div className="aui-user-message-content bg-muted text-foreground rounded-2xl px-4 py-2.5 wrap-break-word">
-        <MessagePrimitive.Parts />
-      </div>
-    </MessagePrimitive.Root>
-  );
-};
-
-```
-
-## 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"
-  }
-}
-
-```
-
-## lib/livekit-voice-adapter.ts
-
-```typescript
-import type { RealtimeVoiceAdapter } from "@assistant-ui/react";
-import { createVoiceSession } from "@assistant-ui/react";
-import {
-  Room,
-  RoomEvent,
-  Track,
-  type RemoteTrack,
-  type RoomOptions,
-} from "livekit-client";
-
-export type LiveKitVoiceAdapterOptions = {
-  url: string;
-  token: string | (() => Promise<string>);
-  roomOptions?: RoomOptions;
-};
-
-export class LiveKitVoiceAdapter implements RealtimeVoiceAdapter {
-  private _url: string;
-  private _token: string | (() => Promise<string>);
-  private _roomOptions: RoomOptions | undefined;
-
-  constructor(options: LiveKitVoiceAdapterOptions) {
-    this._url = options.url;
-    this._token = options.token;
-    this._roomOptions = options.roomOptions;
-  }
-
-  connect(options: {
-    abortSignal?: AbortSignal;
-  }): RealtimeVoiceAdapter.Session {
-    const room = new Room(this._roomOptions);
-
-    return createVoiceSession(options, async (session) => {
-      let volumeInterval: ReturnType<typeof setInterval> | null = null;
-      const attachedAudioElements = new Set<HTMLMediaElement>();
-
-      const attachRemoteAudio = (track: RemoteTrack) => {
-        if (track.kind !== Track.Kind.Audio) return;
-        const element = track.attach();
-        element.style.display = "none";
-        document.body.appendChild(element);
-        attachedAudioElements.add(element);
-      };
-
-      const detachRemoteAudio = (track: RemoteTrack) => {
-        if (track.kind !== Track.Kind.Audio) return;
-        for (const element of track.detach()) {
-          element.remove();
-          attachedAudioElements.delete(element);
-        }
-      };
-
-      const cleanupAudioElements = () => {
-        for (const element of attachedAudioElements) element.remove();
-        attachedAudioElements.clear();
-      };
-
-      room.on(RoomEvent.TrackSubscribed, attachRemoteAudio);
-      room.on(RoomEvent.TrackUnsubscribed, detachRemoteAudio);
-
-      room.on(RoomEvent.Connected, () => {
-        session.setStatus({ type: "running" });
-        if (volumeInterval) clearInterval(volumeInterval);
-        volumeInterval = setInterval(() => {
-          if (session.isDisposed()) return;
-          const localLevel = room.localParticipant.audioLevel ?? 0;
-          let remoteLevel = 0;
-          for (const p of room.remoteParticipants.values()) {
-            remoteLevel = Math.max(remoteLevel, p.audioLevel ?? 0);
-          }
-          session.emitVolume(Math.max(localLevel, remoteLevel));
-        }, 100);
-      });
-
-      room.on(RoomEvent.Disconnected, () => {
-        if (volumeInterval) clearInterval(volumeInterval);
-        session.end("finished");
-      });
-      room.on(RoomEvent.MediaDevicesError, (error) => {
-        if (volumeInterval) clearInterval(volumeInterval);
-        session.end("error", error);
-      });
-
-      room.on(RoomEvent.ActiveSpeakersChanged, (speakers) => {
-        if (session.isDisposed()) return;
-        const remoteIsSpeaking = speakers.some(
-          (s) => s !== room.localParticipant,
-        );
-        session.emitMode(remoteIsSpeaking ? "speaking" : "listening");
-      });
-
-      room.on(
-        RoomEvent.TranscriptionReceived,
-        (segments, participant, _publication) => {
-          if (session.isDisposed()) return;
-          const role =
-            participant === room.localParticipant ? "user" : "assistant";
-          for (const segment of segments) {
-            session.emitTranscript({
-              role,
-              text: segment.text,
-              isFinal: segment.final,
-            });
-          }
-        },
-      );
-
-      const token =
-        typeof this._token === "function" ? await this._token() : this._token;
-      if (session.isDisposed()) {
-        cleanupAudioElements();
-        return { disconnect: () => {}, mute: () => {}, unmute: () => {} };
-      }
-
-      await room.connect(this._url, token);
-      if (session.isDisposed()) {
-        cleanupAudioElements();
-        return { disconnect: () => {}, mute: () => {}, unmute: () => {} };
-      }
-
-      await room.localParticipant.setMicrophoneEnabled(true);
-
-      return {
-        disconnect: () => {
-          if (volumeInterval) clearInterval(volumeInterval);
-          cleanupAudioElements();
-          room.disconnect();
-        },
-        mute: () => {
-          room.localParticipant.setMicrophoneEnabled(false).catch(() => {});
-        },
-        unmute: () => {
-          room.localParticipant.setMicrophoneEnabled(true).catch(() => {});
-        },
-      };
-    });
-  }
-}
-
-```
-
-## next.config.js
-
-```javascript
-import { withAui } from "@assistant-ui/next";
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  transpilePackages: ["@assistant-ui/react", "@assistant-ui/react-ai-sdk"],
-};
-
-export default withAui(nextConfig);
-
-```
-
-## package.json
-
-```json
-{
-  "name": "with-livekit",
-  "private": true,
-  "version": "0.0.0",
-  "type": "module",
-  "dependencies": {
-    "@ai-sdk/openai": "^4.0.40",
-    "@ai-sdk/react": "^4.0.65",
-    "@assistant-ui/react": "workspace:^",
-    "@assistant-ui/react-ai-sdk": "workspace:*",
-    "@assistant-ui/react-markdown": "workspace:^",
-    "@assistant-ui/ui": "workspace:*",
-    "@tailwindcss/postcss": "^4.3.3",
-    "ai": "^7.0.62",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "livekit-client": "^2.21.0",
-    "livekit-server-sdk": "^2.17.0",
-    "lucide-react": "^1.31.0",
-    "motion": "^13.1.0",
-    "next": "^16.3.0",
-    "postcss": "^8.5.26",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "tailwind-merge": "^3.6.0",
-    "tailwindcss": "^4.3.3",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@assistant-ui/next": "workspace:*",
-    "@assistant-ui/x-buildutils": "workspace:*",
-    "@types/node": "^26.2.0",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.4",
-    "tw-animate-css": "^1.4.0",
-    "typescript": "^7.0.2"
-  },
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start"
-  }
-}
-
-```
-
-## tsconfig.json
-
-```json
-{
-  "extends": "@assistant-ui/x-buildutils/ts/base",
-  "compilerOptions": {
-    "target": "ES6",
-    "module": "ESNext",
-    "incremental": true,
-    "plugins": [
-      {
-        "name": "next"
-      }
-    ],
-    "allowJs": true,
-    "strictNullChecks": true,
-    "jsx": "preserve",
-    "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/*"],
-      "@assistant-ui/store/client": ["../../packages/store/src/client"],
-      "@assistant-ui/*": ["../../packages/*/src"],
-      "@assistant-ui/core/*": ["../../packages/core/src/*"],
-      "@assistant-ui/react/*": ["../../packages/react/src/*"],
-      "@assistant-ui/tap/*": ["../../packages/tap/src/*"],
-      "assistant-stream": ["../../packages/assistant-stream/src"],
-      "assistant-stream/*": ["../../packages/assistant-stream/src/*"]
-    }
-  },
-  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
-  "exclude": ["node_modules"]
-}
-
-```
-