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

package/.docs/raw/docs/guides/voice.mdx

@@ -1,310 +0,0 @@
----
-title: Realtime Voice Chat
-description: Build bidirectional voice conversations with AI in React. Realtime audio streaming, interruption handling, and visual state, integrated via assistant-ui.
-platforms: ["react"]
----
-
-import { VoiceSample } from "@/components/pages/docs/samples/voice";
-
-assistant-ui supports realtime bidirectional voice through the `RealtimeVoiceAdapter` interface. Users speak into their microphone, the agent answers with audio, and transcripts appear in the thread while the session runs.
-
-<VoiceSample />
-
-## Three voice modes
-
-assistant-ui ships three related but distinct voice capabilities. Choose the mode that matches the product surface:
-
-| Mode | Guide | Adapter | Direction |
-|------|-------|---------|-----------|
-| **Realtime duplex** | this page | `RealtimeVoiceAdapter` | Audio ↔ audio, live session |
-| **Push-to-talk dictation** | [Dictation](/docs/guides/dictation) | `DictationAdapter` | Audio → text into the composer |
-| **Read-aloud** | [Speech](/docs/guides/speech) | `SpeechSynthesisAdapter` | Text → audio for one message |
-
-Realtime voice is the only mode that owns both directions at once. Dictation fills the composer; speech reads a finished message aloud.
-
-## RealtimeVoiceAdapter
-
-Implement `RealtimeVoiceAdapter` to connect any voice provider. The contract lives in `@assistant-ui/core` and is re-exported from `@assistant-ui/react`:
-
-```tsx
-import type { RealtimeVoiceAdapter } from "@assistant-ui/react";
-
-type RealtimeVoiceAdapter = {
-  connect: (options: {
-    abortSignal?: AbortSignal;
-  }) => RealtimeVoiceAdapter.Session;
-};
-```
-
-A session exposes connection state, mute controls, and event subscriptions:
-
-```tsx
-namespace RealtimeVoiceAdapter {
-  type Status =
-    | { type: "starting" | "running" }
-    | {
-        type: "ended";
-        reason: "finished" | "cancelled" | "error";
-        error?: unknown;
-      };
-
-  type Mode = "listening" | "speaking";
-
-  type TranscriptItem = {
-    role: "user" | "assistant";
-    text: string;
-    isFinal?: boolean;
-  };
-
-  type Session = {
-    status: Status;
-    isMuted: boolean;
-
-    disconnect: () => void;
-    mute: () => void;
-    unmute: () => void;
-
-    onStatusChange: (callback: (status: Status) => void) => Unsubscribe;
-    onTranscript: (
-      callback: (transcript: TranscriptItem) => void,
-    ) => Unsubscribe;
-    onModeChange: (callback: (mode: Mode) => void) => Unsubscribe;
-    onVolumeChange: (callback: (volume: number) => void) => Unsubscribe;
-  };
-}
-```
-
-Session status moves `starting` → `running` → `ended`. The `ended` status includes a reason: `"finished"`, `"cancelled"`, or `"error"` (with an optional `error` field).
-
-Transcripts from `onTranscript` are appended to the message thread automatically:
-
-- User transcripts (`role: "user"`, `isFinal: true`) become user messages.
-- Assistant transcripts (`role: "assistant"`) stream into an assistant message. The message stays in a running status until `isFinal: true`.
-
-`onModeChange` reports `"listening"` (user's turn) or `"speaking"` (agent's turn). `onVolumeChange` reports a real-time level from `0` to `1` for visual feedback such as the voice orb.
-
-## createVoiceSession
-
-`createVoiceSession` removes the manual callback-set boilerplate when you implement an adapter. Pass it the connect options and an async `setup` function that receives `VoiceSessionHelpers` and returns `VoiceSessionControls`:
-
-```tsx
-import {
-  createVoiceSession,
-  type RealtimeVoiceAdapter,
-  type VoiceSessionControls,
-  type VoiceSessionHelpers,
-} from "@assistant-ui/react";
-
-export class MyVoiceAdapter implements RealtimeVoiceAdapter {
-  connect(options: {
-    abortSignal?: AbortSignal;
-  }): RealtimeVoiceAdapter.Session {
-    return createVoiceSession(options, async (helpers: VoiceSessionHelpers) => {
-      const client = await MyVoiceClient.connect();
-
-      client.on("open", () => helpers.setStatus({ type: "running" }));
-      client.on("close", () => helpers.end("finished"));
-      client.on("error", (err: unknown) => helpers.end("error", err));
-      client.on("transcript", (item) => helpers.emitTranscript(item));
-      client.on("mode", (mode) => helpers.emitMode(mode));
-      client.on("volume", (v: number) => helpers.emitVolume(v));
-
-      const controls: VoiceSessionControls = {
-        disconnect: () => client.close(),
-        mute: () => client.setMuted(true),
-        unmute: () => client.setMuted(false),
-      };
-      return controls;
-    });
-  }
-}
-```
-
-`VoiceSessionHelpers` provides:
-
-| Helper | Role |
-|--------|------|
-| `setStatus(status)` | Update session status (for example to `{ type: "running" }`) |
-| `end(reason, error?)` | End the session and clean up subscribers |
-| `emitTranscript(item)` | Push a transcript into the thread |
-| `emitMode(mode)` | Report `"listening"` or `"speaking"` |
-| `emitVolume(volume)` | Report a level from `0` to `1` |
-| `isDisposed()` | Skip events after teardown |
-
-`createVoiceSession` wires status tracking, mute state, abort-signal disconnect, and all `on*` subscriptions for you.
-
-## Configuration
-
-Pass a `RealtimeVoiceAdapter` implementation on the runtime:
-
-```tsx
-const runtime = useChatRuntime({
-  adapters: {
-    voice: new MyVoiceAdapter({ /* provider options */ }),
-  },
-});
-```
-
-When a voice adapter is provided, `capabilities.voice` is set to `true` automatically.
-
-## React hooks
-
-These hooks are exported from `@assistant-ui/react` and read the active voice session on the current thread.
-
-### useVoiceState
-
-Returns the current `VoiceSessionState`, or `undefined` when no session is active:
-
-```tsx
-import { useVoiceState } from "@assistant-ui/react";
-
-const voiceState = useVoiceState();
-// voiceState?.status.type: "starting" | "running" | "ended"
-// voiceState?.isMuted: boolean
-// voiceState?.mode: "listening" | "speaking"
-```
-
-`VoiceSessionState` is:
-
-```tsx
-type VoiceSessionState = {
-  readonly status: RealtimeVoiceAdapter.Status;
-  readonly isMuted: boolean;
-  readonly mode: RealtimeVoiceAdapter.Mode;
-};
-```
-
-### useVoiceVolume
-
-Subscribes to real-time audio level independently of session state:
-
-```tsx
-import { useVoiceVolume } from "@assistant-ui/react";
-
-const volume = useVoiceVolume(); // number from 0 to 1
-```
-
-### useVoiceControls
-
-Returns methods that drive the session:
-
-```tsx
-import { useVoiceControls } from "@assistant-ui/react";
-
-const { connect, disconnect, mute, unmute } = useVoiceControls();
-```
-
-### Headless control bar
-
-Build your own controls from the hooks when you need a custom layout:
-
-```tsx
-import { useVoiceState, useVoiceControls } from "@assistant-ui/react";
-import { PhoneIcon, PhoneOffIcon, MicIcon, MicOffIcon } from "lucide-react";
-
-function VoiceControls() {
-  const voiceState = useVoiceState();
-  const { connect, disconnect, mute, unmute } = useVoiceControls();
-
-  const isRunning = voiceState?.status.type === "running";
-  const isStarting = voiceState?.status.type === "starting";
-  const isMuted = voiceState?.isMuted ?? false;
-
-  if (!isRunning && !isStarting) {
-    return (
-      <button onClick={() => connect()}>
-        <PhoneIcon /> Connect
-      </button>
-    );
-  }
-
-  return (
-    <>
-      <button onClick={() => (isMuted ? unmute() : mute())} disabled={!isRunning}>
-        {isMuted ? <MicOffIcon /> : <MicIcon />}
-        {isMuted ? "Unmute" : "Mute"}
-      </button>
-      <button onClick={() => disconnect()}>
-        <PhoneOffIcon /> Disconnect
-      </button>
-    </>
-  );
-}
-```
-
-## Voice UI component
-
-The fastest path is the styled `voice` registry component. It ships a `VoiceControl` bar, mute and disconnect buttons, status indicator, and animated `VoiceOrb` built on the hooks above.
-
-### Install
-
-<InstallCommand shadcn={["voice"]} />
-
-This adds `/components/assistant-ui/voice.tsx` to your project. Adjust styling as needed.
-
-### Use with a runtime
-
-```tsx title="app/page.tsx"
-import { Thread } from "@/components/assistant-ui/thread";
-import { VoiceControl } from "@/components/assistant-ui/voice";
-import { AuiIf } from "@assistant-ui/react";
-
-export default function Chat() {
-  return (
-    <div className="flex h-full flex-col">
-      <AuiIf condition={(s) => s.thread.capabilities.voice}>
-        <VoiceControl />
-      </AuiIf>
-      <div className="min-h-0 flex-1">
-        <Thread />
-      </div>
-    </div>
-  );
-}
-```
-
-See the [Voice UI page](/docs/ui/voice) for anatomy, variants, and state samples.
-
-## Example: LiveKit
-
-[LiveKit](https://livekit.io/) provides realtime voice over WebRTC rooms with transcription support. The browser adapter joins a room; a separate agent worker (STT, LLM, TTS) joins the same room. Without an agent in the room, the client connects but has nothing to talk to.
-
-The [`with-livekit`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-livekit) example shows the full wiring:
-
-1. **Adapter** (`examples/with-livekit/lib/livekit-voice-adapter.ts`): `LiveKitVoiceAdapter` implements `RealtimeVoiceAdapter`. `connect` calls `createVoiceSession`, connects a LiveKit `Room`, enables the local microphone, attaches remote audio tracks, and maps room events to helpers (`setStatus`, `end`, `emitMode`, `emitVolume`, `emitTranscript`).
-2. **Token route** (`examples/with-livekit/app/api/livekit-token/route.ts`): mints a short-lived room token server-side so secrets stay off the client.
-3. **Agent worker** (`examples/with-livekit/agent/`): a Python LiveKit Agents process that joins the room and runs the voice pipeline.
-
-Minimal runtime wiring:
-
-```tsx
-import { LiveKitVoiceAdapter } from "@/lib/livekit-voice-adapter";
-
-const runtime = useChatRuntime({
-  adapters: {
-    voice: new LiveKitVoiceAdapter({
-      url: process.env.NEXT_PUBLIC_LIVEKIT_URL!,
-      token: async () => {
-        const res = await fetch("/api/livekit-token", { method: "POST" });
-        const { token } = await res.json();
-        return token;
-      },
-    }),
-  },
-});
-```
-
-Clone the example for the adapter source, token endpoint, and agent worker rather than re-implementing the full LiveKit event map from scratch.
-
-You can also scaffold it with the CLI:
-
-```bash
-npx assistant-ui create my-app -e with-livekit
-```
-
-## Related guides
-
-- [Dictation](/docs/guides/dictation): push-to-talk speech-to-text into the composer (`DictationAdapter`, `ComposerPrimitive.Dictate`).
-- [Speech](/docs/guides/speech): read-aloud for assistant messages (`SpeechSynthesisAdapter`, `ActionBarPrimitive.Speak`).
-- [Voice UI](/docs/ui/voice): registry component reference for `VoiceControl` and `VoiceOrb`.
-- [Voice API reference](/docs/api-reference/voice): generated types for sessions, speech, and dictation.

package/.docs/raw/docs/ink/adapters.mdx

@@ -1,99 +0,0 @@
----
-title: Adapters
-description: Attachment, title generation, and storage adapters for React Ink.
----
-
-Adapters customize runtime behavior. They can be passed as options to `useLocalRuntime` or `useRemoteThreadListRuntime`.
-
-## createFileStorageAdapter
-
-A `RemoteThreadListAdapter` that persists threads and messages to a local directory. See [Custom Backend → Option 2](/docs/ink/custom-backend#option-2-local-file-persistence) for usage.
-
-```ts
-import { createFileStorageAdapter } from "@assistant-ui/react-ink";
-
-const adapter = createFileStorageAdapter({
-  dir: "/path/to/threads",
-});
-```
-
-## Attachment adapters
-
-`SimpleTextAttachmentAdapter` and `SimpleImageAttachmentAdapter` work the same in the terminal as on web and React Native. Text contents are sent to the model wrapped in `<attachment name=...>` tags, and images are sent as base64 data URLs.
-
-```ts
-import {
-  CompositeAttachmentAdapter,
-  SimpleImageAttachmentAdapter,
-  SimpleTextAttachmentAdapter,
-  useLocalRuntime,
-} from "@assistant-ui/react-ink";
-
-const runtime = useLocalRuntime(chatModelAdapter, {
-  adapters: {
-    attachments: new CompositeAttachmentAdapter([
-      new SimpleTextAttachmentAdapter(),
-      new SimpleImageAttachmentAdapter(),
-    ]),
-  },
-});
-```
-
-## TitleGenerationAdapter
-
-Produces a thread title from a thread's messages. Pass one as the `titleGenerator` option to `createFileStorageAdapter`, or call it from a custom `RemoteThreadListAdapter`.
-
-```ts
-type TitleGenerationAdapter = {
-  generateTitle(messages: readonly ThreadMessage[]): Promise<string>;
-};
-```
-
-`createSimpleTitleAdapter` is the built-in implementation; it derives the title from the first user message, truncated to 50 characters.
-
-```ts
-import {
-  createFileStorageAdapter,
-  createSimpleTitleAdapter,
-} from "@assistant-ui/react-ink";
-
-const adapter = createFileStorageAdapter({
-  dir: "/path/to/threads",
-  titleGenerator: createSimpleTitleAdapter(),
-});
-```
-
-## RemoteThreadListAdapter
-
-Title generation is configured via the `generateTitle` method on `RemoteThreadListAdapter`. See the [Custom Backend](/docs/ink/custom-backend) page for a full example.
-
-```tsx
-import type { RemoteThreadListAdapter } from "@assistant-ui/react-ink";
-import { createAssistantStream } from "assistant-stream";
-
-const myAdapter: RemoteThreadListAdapter = {
-  // ... other methods ...
-
-  async generateTitle(remoteId, unstable_messages) {
-    return createAssistantStream(async (controller) => {
-      const res = await fetch(`/api/threads/${remoteId}/title`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ messages: unstable_messages }),
-      });
-      const { title } = await res.json();
-      controller.appendText(title);
-    });
-  },
-};
-```
-
-## Which option to choose?
-
-| | ChatModelAdapter + `useLocalRuntime` | RemoteThreadListAdapter + `useRemoteThreadListRuntime` |
-|---|---|---|
-| **Thread storage** | In-memory | Your backend |
-| **Message storage** | In-memory | In-memory (can add history adapter for server-side) |
-| **Cross-session persistence** | No | Yes |
-| **Setup complexity** | Minimal | Moderate |
-| **Best for** | CLI tools, demos, prototypes | Production apps with persistence |

package/.docs/raw/docs/ink/custom-backend.mdx

@@ -1,254 +0,0 @@
----
-title: Custom Backend
-description: Connect your terminal app to your own backend API.
----
-
-By default, `useLocalRuntime` manages threads and messages in memory. You can connect to your own backend in two ways depending on your needs.
-
-## Option 1: ChatModelAdapter only
-
-The simplest approach — keep thread management local, but send messages to your backend for inference.
-
-```tsx title="adapters/my-chat-adapter.ts"
-import type { ChatModelAdapter } from "@assistant-ui/react-ink";
-
-export const myChatAdapter: ChatModelAdapter = {
-  async *run({ messages, abortSignal }) {
-    const response = await fetch("https://my-api.com/chat", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ messages }),
-      signal: abortSignal,
-    });
-
-    const reader = response.body?.getReader();
-    if (!reader) throw new Error("No response body");
-
-    const decoder = new TextDecoder();
-    let fullText = "";
-
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-
-      const chunk = decoder.decode(value, { stream: true });
-      fullText += chunk;
-      yield { content: [{ type: "text", text: fullText }] };
-    }
-  },
-};
-```
-
-```tsx title="app.tsx"
-import { useLocalRuntime, AssistantRuntimeProvider } from "@assistant-ui/react-ink";
-import { myChatAdapter } from "./adapters/my-chat-adapter.js";
-
-export function App() {
-  const runtime = useLocalRuntime(myChatAdapter);
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {/* your chat UI */}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-This gives you:
-
-- Streaming chat responses from your API
-- In-memory thread list (lost on process exit)
-- Multi-thread support
-
-## Option 2: Local file persistence
-
-When you want threads and messages to survive across sessions without running a backend, use `createFileStorageAdapter`. It writes each thread to a JSON file on disk and plugs into `useRemoteThreadListRuntime`.
-
-```tsx title="app.tsx"
-import { join } from "node:path";
-import { homedir } from "node:os";
-import {
-  useLocalRuntime,
-  useRemoteThreadListRuntime,
-  createFileStorageAdapter,
-  AssistantRuntimeProvider,
-} from "@assistant-ui/react-ink";
-import { myChatAdapter } from "./adapters/my-chat-adapter.js";
-
-const threadListAdapter = createFileStorageAdapter({
-  dir: join(homedir(), ".my-cli", "threads"),
-});
-
-function useAppRuntime() {
-  return useRemoteThreadListRuntime({
-    runtimeHook: () => useLocalRuntime(myChatAdapter),
-    adapter: threadListAdapter,
-  });
-}
-
-export function App() {
-  const runtime = useAppRuntime();
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {/* your chat UI */}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-Writes are atomic (temp file + `rename`), so a crash mid-write cannot leave a partial JSON file. The directory is created lazily on first write.
-
-### Options
-
-| Option | Description |
-|---|---|
-| `dir` | Directory where thread files are stored. Created if missing. |
-| `prefix` | Key prefix for stored files. Defaults to `@assistant-ui:`. Useful when two apps share a directory. |
-| `titleGenerator` | Optional [`TitleGenerationAdapter`](/docs/ink/adapters#titlegenerationadapter) that auto-generates thread titles from the first messages. Pass `createSimpleTitleAdapter()` for the built-in implementation. |
-
-### When this fits
-
-Designed for single-process terminal apps where one user has one CLI running at a time. The wrapped read-modify-write on the thread list isn't lock-safe, so two CLI processes pointed at the same directory can lose updates to thread metadata (rename, archive). If that's your scenario, use Option 3 instead.
-
-## Option 3: Full backend thread management
-
-When you want your backend to own thread state (e.g. for persistence across sessions, team sharing, or server-side history), implement a `RemoteThreadListAdapter`.
-
-<Steps>
-  <Step>
-
-### Implement the adapter
-
-```tsx title="adapters/my-thread-list-adapter.ts"
-import type { RemoteThreadListAdapter } from "@assistant-ui/react-ink";
-import { createAssistantStream } from "assistant-stream";
-
-const API_BASE = "https://my-api.com";
-
-export const myThreadListAdapter: RemoteThreadListAdapter = {
-  async list() {
-    const res = await fetch(`${API_BASE}/threads`);
-    const threads = await res.json();
-    return {
-      threads: threads.map((t: any) => ({
-        remoteId: t.id,
-        status: t.archived ? "archived" : "regular",
-        title: t.title,
-      })),
-    };
-  },
-
-  async initialize(localId) {
-    const res = await fetch(`${API_BASE}/threads`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ localId }),
-    });
-    const { id } = await res.json();
-    return { remoteId: id, externalId: undefined };
-  },
-
-  async rename(remoteId, title) {
-    await fetch(`${API_BASE}/threads/${remoteId}`, {
-      method: "PATCH",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ title }),
-    });
-  },
-
-  async archive(remoteId) {
-    await fetch(`${API_BASE}/threads/${remoteId}/archive`, {
-      method: "POST",
-    });
-  },
-
-  async unarchive(remoteId) {
-    await fetch(`${API_BASE}/threads/${remoteId}/unarchive`, {
-      method: "POST",
-    });
-  },
-
-  async delete(remoteId) {
-    await fetch(`${API_BASE}/threads/${remoteId}`, { method: "DELETE" });
-  },
-
-  async fetch(remoteId) {
-    const res = await fetch(`${API_BASE}/threads/${remoteId}`);
-    const t = await res.json();
-    return {
-      remoteId: t.id,
-      status: t.archived ? "archived" : "regular",
-      title: t.title,
-    };
-  },
-
-  async generateTitle(remoteId, unstable_messages) {
-    return createAssistantStream(async (controller) => {
-      const res = await fetch(`${API_BASE}/threads/${remoteId}/title`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ messages: unstable_messages }),
-      });
-      const { title } = await res.json();
-      controller.appendText(title);
-    });
-  },
-};
-```
-
-  </Step>
-  <Step>
-
-### Compose the runtime
-
-```tsx title="app.tsx"
-import {
-  useLocalRuntime,
-  useRemoteThreadListRuntime,
-  AssistantRuntimeProvider,
-} from "@assistant-ui/react-ink";
-import { myChatAdapter } from "./adapters/my-chat-adapter.js";
-import { myThreadListAdapter } from "./adapters/my-thread-list-adapter.js";
-
-function useAppRuntime() {
-  return useRemoteThreadListRuntime({
-    runtimeHook: () => useLocalRuntime(myChatAdapter),
-    adapter: myThreadListAdapter,
-  });
-}
-
-export function App() {
-  const runtime = useAppRuntime();
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {/* your chat UI */}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-  </Step>
-</Steps>
-
-## Adapter methods
-
-| Method | Description |
-|--------|-------------|
-| `list()` | Return all threads on mount |
-| `initialize(localId)` | Create a thread server-side, return `{ remoteId }` |
-| `rename(remoteId, title)` | Persist title changes |
-| `archive(remoteId)` | Mark thread as archived |
-| `unarchive(remoteId)` | Restore archived thread |
-| `delete(remoteId)` | Permanently remove thread |
-| `fetch(remoteId)` | Fetch single thread metadata |
-| `generateTitle(remoteId, unstable_messages)` | Return an `AssistantStream` with the generated title |
-
-## Which option to choose?
-
-| | Option 1: ChatModelAdapter | Option 2: createFileStorageAdapter | Option 3: RemoteThreadListAdapter |
-|---|---|---|---|
-| **Thread storage** | In-memory (process lifetime) | Local disk | Your backend |
-| **Message storage** | In-memory | Local disk | In-memory (can add history adapter for server-side) |
-| **Cross-session persistence** | No | Yes | Yes |
-| **Multi-process safe** | N/A | No | Depends on backend |
-| **Setup complexity** | Minimal | Minimal | Moderate |
-| **Best for** | Demos, prototypes | Local CLI tools | Production apps with sync / team sharing |