@assistant-ui/mcp-docs-server 0.1.18 → 0.1.19

package/.docs/raw/docs/(docs)/guides/dictation.mdx

@@ -0,0 +1,370 @@
+---
+title: Speech-to-Text (Dictation)
+---
+
+import { DictationSample } from "@/components/docs/samples/dictation";
+
+assistant-ui supports speech-to-text (dictation) via the `DictationAdapter` interface. This allows users to input messages using their voice.
+
+<DictationSample />
+
+## DictationAdapter
+
+Currently, the following dictation adapters are supported:
+
+- `WebSpeechDictationAdapter`: Uses the browser's `Web Speech API` (SpeechRecognition)
+
+The `WebSpeechDictationAdapter` is supported in Chrome, Edge, and Safari. Check [browser compatibility](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition#browser_compatibility) for details.
+
+## Configuration
+
+```tsx
+import { WebSpeechDictationAdapter } from "@assistant-ui/react";
+
+const runtime = useChatRuntime({
+  api: "/api/chat",
+  adapters: {
+    dictation: new WebSpeechDictationAdapter({
+      // Optional configuration
+      language: "en-US",         // Language for recognition (default: browser language)
+      continuous: true,          // Keep recording after user stops (default: true)
+      interimResults: true,      // Return interim results (default: true)
+    }),
+  },
+});
+```
+
+## UI
+
+The dictation feature uses `ComposerPrimitive.Dictate` and `ComposerPrimitive.StopDictation` components.
+
+```tsx
+import { ComposerPrimitive } from "@assistant-ui/react";
+import { MicIcon, SquareIcon } from "lucide-react";
+
+const ComposerWithDictation = () => (
+  <ComposerPrimitive.Root>
+    <ComposerPrimitive.Input />
+
+    {/* Show Dictate button when not dictating */}
+    <ComposerPrimitive.If dictation={false}>
+      <ComposerPrimitive.Dictate>
+        <MicIcon />
+      </ComposerPrimitive.Dictate>
+    </ComposerPrimitive.If>
+
+    {/* Show Stop button when dictating */}
+    <ComposerPrimitive.If dictation>
+      <ComposerPrimitive.StopDictation>
+        <SquareIcon className="animate-pulse" />
+      </ComposerPrimitive.StopDictation>
+    </ComposerPrimitive.If>
+
+    <ComposerPrimitive.Send />
+  </ComposerPrimitive.Root>
+);
+```
+
+## Browser Compatibility Check
+
+You can check if the browser supports dictation:
+
+```tsx
+import { WebSpeechDictationAdapter } from "@assistant-ui/react";
+
+if (WebSpeechDictationAdapter.isSupported()) {
+  // Dictation is available
+}
+```
+
+## Disabling Input During Dictation
+
+Some dictation services (like ElevenLabs Scribe) return cumulative transcripts that conflict with simultaneous typing. You can disable the text input during dictation:
+
+```tsx
+import type { DictationAdapter } from "@assistant-ui/react";
+
+class MyAdapter implements DictationAdapter {
+  // Set to true to disable typing while dictating
+  disableInputDuringDictation = true;
+
+  listen() { /* ... */ }
+}
+```
+
+<Callout type="info">
+  When a message is sent during an active dictation session, the session is automatically stopped.
+</Callout>
+
+## Custom Adapters
+
+You can create custom adapters to integrate with any dictation service by implementing the `DictationAdapter` interface.
+
+### DictationAdapter Interface
+
+```tsx
+import type { DictationAdapter } from "@assistant-ui/react";
+
+class MyCustomDictationAdapter implements DictationAdapter {
+  // Optional: disable text input while dictating (default: false)
+  disableInputDuringDictation?: boolean;
+
+  listen(): DictationAdapter.Session {
+    // Return a session object that manages the dictation
+    return {
+      status: { type: "starting" },
+
+      stop: async () => {
+        // Stop recognition and finalize results
+      },
+
+      cancel: () => {
+        // Cancel recognition without finalizing
+      },
+
+      onSpeechStart: (callback) => {
+        // Called when speech is detected
+        return () => {}; // Return unsubscribe function
+      },
+
+      onSpeechEnd: (callback) => {
+        // Called when recognition ends with final result
+        return () => {};
+      },
+
+      onSpeech: (callback) => {
+        // Called with transcription results
+        // callback({ transcript: "text", isFinal: true })
+        //
+        // isFinal: true  → Append to composer input (default)
+        // isFinal: false → Show as preview only
+        return () => {};
+      },
+    };
+  }
+}
+```
+
+### Interim vs Final Results
+
+The `onSpeech` callback receives results with an optional `isFinal` flag:
+
+```tsx
+onSpeech: (callback) => {
+  // callback({ transcript: "text", isFinal: true })
+  // - isFinal: true  → Text is committed to the input
+  // - isFinal: false → Text is shown as preview in the input
+  return () => {};
+},
+```
+
+**Both interim and final results are displayed directly in the input field**, just like native dictation on iOS/Android. Interim results replace each other until a final result commits the text. This provides seamless real-time feedback while the user speaks.
+
+### Example: ElevenLabs Scribe v2 Realtime
+
+[ElevenLabs Scribe](https://elevenlabs.io/docs/capabilities/speech-to-text) provides ultra-low latency (~150ms) real-time transcription via WebSocket.
+
+#### Install Dependencies
+
+```bash
+npm install @elevenlabs/client
+```
+
+#### Backend API Route
+
+Create an API route to generate single-use tokens:
+
+```ts title="app/api/scribe-token/route.ts"
+export async function POST() {
+  const response = await fetch(
+    "https://api.elevenlabs.io/v1/single-use-token/realtime_scribe",
+    {
+      method: "POST",
+      headers: {
+        "xi-api-key": process.env.ELEVENLABS_API_KEY!,
+      },
+    }
+  );
+
+  const data = await response.json();
+  return Response.json({ token: data.token });
+}
+```
+
+#### Frontend Adapter
+
+```tsx title="lib/elevenlabs-scribe-adapter.ts"
+import type { DictationAdapter } from "@assistant-ui/react";
+import { Scribe, RealtimeEvents } from "@elevenlabs/client";
+
+export class ElevenLabsScribeAdapter implements DictationAdapter {
+  private tokenEndpoint: string;
+  private languageCode: string;
+
+  // ElevenLabs returns cumulative transcripts, so we disable typing during dictation
+  public disableInputDuringDictation: boolean;
+
+  constructor(options: {
+    tokenEndpoint: string;
+    languageCode?: string;
+    disableInputDuringDictation?: boolean;
+  }) {
+    this.tokenEndpoint = options.tokenEndpoint;
+    this.languageCode = options.languageCode ?? "en";
+    this.disableInputDuringDictation = options.disableInputDuringDictation ?? true;
+  }
+
+  listen(): DictationAdapter.Session {
+    const callbacks = {
+      start: new Set<() => void>(),
+      end: new Set<(r: DictationAdapter.Result) => void>(),
+      speech: new Set<(r: DictationAdapter.Result) => void>(),
+    };
+
+    let connection: ReturnType<typeof Scribe.connect> | null = null;
+    let fullTranscript = "";
+
+    const session: DictationAdapter.Session = {
+      status: { type: "starting" },
+
+      stop: async () => {
+        if (connection) {
+          connection.commit();
+          await new Promise((r) => setTimeout(r, 500));
+          connection.close();
+        }
+        if (fullTranscript) {
+          for (const cb of callbacks.end) cb({ transcript: fullTranscript });
+        }
+      },
+
+      cancel: () => {
+        connection?.close();
+      },
+
+      onSpeechStart: (cb) => {
+        callbacks.start.add(cb);
+        return () => callbacks.start.delete(cb);
+      },
+
+      onSpeechEnd: (cb) => {
+        callbacks.end.add(cb);
+        return () => callbacks.end.delete(cb);
+      },
+
+      onSpeech: (cb) => {
+        callbacks.speech.add(cb);
+        return () => callbacks.speech.delete(cb);
+      },
+    };
+
+    this.connect(session, callbacks, {
+      setConnection: (c) => { connection = c; },
+      getFullTranscript: () => fullTranscript,
+      setFullTranscript: (t) => { fullTranscript = t; },
+    });
+
+    return session;
+  }
+
+  private async connect(
+    session: DictationAdapter.Session,
+    callbacks: {
+      start: Set<() => void>;
+      end: Set<(r: DictationAdapter.Result) => void>;
+      speech: Set<(r: DictationAdapter.Result) => void>;
+    },
+    refs: {
+      setConnection: (c: ReturnType<typeof Scribe.connect>) => void;
+      getFullTranscript: () => string;
+      setFullTranscript: (t: string) => void;
+    }
+  ) {
+    try {
+      // 1. Get token from backend
+      const tokenRes = await fetch(this.tokenEndpoint, { method: "POST" });
+      const { token } = await tokenRes.json();
+
+      // 2. Connect to Scribe with microphone
+      const connection = Scribe.connect({
+        token,
+        modelId: "scribe_v2_realtime",
+        languageCode: this.languageCode,
+        microphone: {
+          echoCancellation: true,
+          noiseSuppression: true,
+        },
+      });
+      refs.setConnection(connection);
+
+      // 3. Handle events
+      connection.on(RealtimeEvents.SESSION_STARTED, () => {
+        (session as { status: DictationAdapter.Status }).status = {
+          type: "running",
+        };
+        for (const cb of callbacks.start) cb();
+      });
+
+      // Partial transcripts → preview (isFinal: false)
+      connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, (data) => {
+        if (data.text) {
+          for (const cb of callbacks.speech)
+            cb({ transcript: data.text, isFinal: false });
+        }
+      });
+
+      // Committed transcripts → append to input (isFinal: true)
+      connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => {
+        if (data.text?.trim()) {
+          refs.setFullTranscript(refs.getFullTranscript() + data.text + " ");
+          for (const cb of callbacks.speech)
+            cb({ transcript: data.text, isFinal: true });
+        }
+      });
+
+      connection.on(RealtimeEvents.ERROR, (error) => {
+        console.error("Scribe error:", error);
+        (session as { status: DictationAdapter.Status }).status = {
+          type: "ended",
+          reason: "error",
+        };
+      });
+
+    } catch (error) {
+      console.error("ElevenLabs Scribe connection failed:", error);
+      (session as { status: DictationAdapter.Status }).status = {
+        type: "ended",
+        reason: "error",
+      };
+    }
+  }
+}
+```
+
+#### Usage
+
+```tsx
+const runtime = useChatRuntime({
+  api: "/api/chat",
+  adapters: {
+    dictation: new ElevenLabsScribeAdapter({
+      tokenEndpoint: "/api/scribe-token",
+      languageCode: "en", // Optional: supports 90+ languages
+      disableInputDuringDictation: true, // Default: true (recommended for ElevenLabs)
+    }),
+  },
+});
+```
+
+#### Real-time Preview
+
+The transcription is displayed directly in the input field as the user speaks — just like native dictation. No additional UI components are needed for basic use cases.
+
+<Callout type="info">
+  For advanced customization, `composer.dictation?.transcript` contains the current interim transcript, and `ComposerPrimitive.DictationTranscript` can display it separately if desired.
+</Callout>
+
+<Callout type="info">
+  For more details, see the [ElevenLabs Scribe documentation](https://elevenlabs.io/docs/capabilities/speech-to-text).
+</Callout>
+

package/.docs/raw/docs/{guides/Editing.mdx → (docs)/guides/editing.mdx}

@@ -1,5 +1,6 @@
 ---
 title: Message Editing
+description: Allow users to edit their messages with custom editor interfaces.
 ---
 
 Give the user the ability to edit their message.

package/.docs/raw/docs/{guides/Latex.mdx → (docs)/guides/latex.mdx}

@@ -1,9 +1,8 @@
 ---
 title: LaTeX
+description: Render mathematical expressions in chat messages using KaTeX.
 ---
 
-import { Steps, Step } from "fumadocs-ui/components/steps";
-import { Callout } from "fumadocs-ui/components/callout";
 
 Render LaTeX mathematical expressions in chat messages using KaTeX.
 

package/.docs/raw/docs/{guides/Speech.mdx → (docs)/guides/speech.mdx}

@@ -1,33 +1,32 @@
 ---
-title: Speech
+title: Text-to-Speech (Speech Synthesis)
+description: Read messages aloud with Web Speech API or custom TTS.
 ---
 
-import { SpeechSample } from "@/components/samples/speech-sample";
-
-## Text-to-Speech
+import { SpeechSample } from "@/components/docs/samples/speech";
 
 assistant-ui supports text-to-speech via the `SpeechSynthesisAdapter` interface.
 
 <SpeechSample />
 
-### SpeechSynthesisAdapter
+## SpeechSynthesisAdapter
 
 Currently, the following speech synthesis adapters are supported:
 
-- `WebSpeechSynthesisAdapter`: Uses the browser's `Web Speech API` API
+- `WebSpeechSynthesisAdapter`: Uses the browser's `Web Speech API`
 
 Support for other speech synthesis adapters is planned for the future.
 
-Passing a `SpeechSynthesisAdapter` to the `EdgeRuntime` will enable text-to-speech support.
+Passing a `SpeechSynthesisAdapter` to the runtime will enable text-to-speech support.
 
-### UI
+## UI
 
 By default, a `Read aloud` button will be shown in the assistant message action bar.
 
 This is implemented using `AssistantActionBar.SpeechControl` which is a wrapper around `AssistantActionBar.Speak` and `AssistantActionBar.StopSpeaking`.
 The underlying primitives are `ActionBarPrimitive.Speak` and `ActionBarPrimitive.StopSpeaking`.
 
-### Example
+## Example
 
 The following example uses the `WebSpeechSynthesisAdapter`.
 
@@ -40,4 +39,4 @@ const runtime = useChatRuntime({
     speech: new WebSpeechSynthesisAdapter(),
   },
 });
-```
+```

package/.docs/raw/docs/{guides/ToolUI.mdx → (docs)/guides/tool-ui.mdx}

@@ -1,10 +1,9 @@
 ---
 title: Generative UI
+description: Render tool calls as interactive UI instead of plain text.
 ---
 
-import { ToolUISample } from "@/components/samples/tool-ui-sample";
-import { Steps, Step } from "fumadocs-ui/components/steps";
-import { Callout } from "fumadocs-ui/components/callout";
+import { ToolUISample } from "@/components/docs/samples/tool-ui";
 
 Create custom UI components for AI tool calls, providing visual feedback and interactive experiences when tools are executed.
 
@@ -81,7 +80,7 @@ const WeatherToolUI = makeAssistantToolUI<
   `frontendTools` utility
 </Callout>
 
-Learn more about creating tools in the [Tools Guide](/docs/guides/Tools).
+Learn more about creating tools in the [Tools Guide](/docs/guides/tools).
 
 ### 2. UI-Only for Existing Tools (`makeAssistantToolUI`)
 
@@ -193,7 +192,7 @@ function App() {
 When using the Vercel AI SDK, define the corresponding tool in your API route:
 
 ```tsx title="/app/api/chat/route.ts"
-import { streamText, tool } from "ai";
+import { streamText, tool, zodSchema } from "ai";
 import { z } from "zod";
 
 export async function POST(req: Request) {
@@ -205,10 +204,12 @@ export async function POST(req: Request) {
     tools: {
       getWeather: tool({
         description: "Get current weather for a location",
-        inputSchema: z.object({
-          location: z.string(),
-          unit: z.enum(["celsius", "fahrenheit"]),
-        }),
+        inputSchema: zodSchema(
+          z.object({
+            location: z.string(),
+            unit: z.enum(["celsius", "fahrenheit"]),
+          }),
+        ),
         execute: async ({ location, unit }) => {
           const weather = await fetchWeatherAPI(location);
           return {
@@ -670,7 +671,7 @@ const ConfirmationToolUI = makeAssistantToolUI<
 });
 ```
 
-Learn more about tool human input in the [Tools Guide](/docs/guides/Tools#tool-human-input).
+Learn more about tool human input in the [Tools Guide](/docs/guides/tools#tool-human-input).
 
 ## Best Practices
 
@@ -740,7 +741,7 @@ useAssistantToolUI({
 
 ## Related Guides
 
-- [Tools Guide](/docs/guides/Tools) - Learn how to create and use tools with AI models
-- [Tool Fallback](/docs/ui/ToolFallback) - Default UI for tools without custom components
-- [API Reference](/docs/api-reference/primitives/MessagePart) - Detailed type definitions and component APIs
-- [Message Primitive](/docs/api-reference/primitives/Message) - Complete Message component documentation
+- [Tools Guide](/docs/guides/tools) - Learn how to create and use tools with AI models
+- [Tool Fallback](/docs/ui/tool-fallback) - Default UI for tools without custom components
+- [API Reference](/docs/api-reference/primitives/message-part) - Detailed type definitions and component APIs
+- [Message Primitive](/docs/api-reference/primitives/message) - Complete Message component documentation

package/.docs/raw/docs/{guides/Tools.mdx → (docs)/guides/tools.mdx}

@@ -1,5 +1,6 @@
 ---
 title: Tools
+description: Give your assistant actions like API calls, database queries, and more.
 ---
 
 Tools enable LLMs to take actions and interact with external systems. assistant-ui provides a comprehensive toolkit for creating, managing, and visualizing tool interactions in real-time.
@@ -14,11 +15,11 @@ Tools in assistant-ui are functions that the LLM can call to perform specific ta
 - Controlling UI elements
 - Executing workflows
 
-When tools are executed, you can display custom generative UI components that provide rich, interactive visualizations of the tool's execution and results. Learn more in the [Generative UI guide](/docs/guides/ToolUI).
+When tools are executed, you can display custom generative UI components that provide rich, interactive visualizations of the tool's execution and results. Learn more in the [Generative UI guide](/docs/guides/tool-ui).
 
 <Callout type="tip">
   If you haven't provided a custom UI for a tool, assistant-ui offers a
-  [`ToolFallback`](/docs/ui/ToolFallback) component that you can add to your
+  [`ToolFallback`](/docs/ui/tool-fallback) component that you can add to your
   codebase to render a default UI for tool executions. You can customize this by
   creating your own Tool UI component for the tool's name.
 </Callout>
@@ -250,10 +251,12 @@ export async function POST(req: Request) {
     tools: {
       queryDatabase: {
         description: "Query the application database",
-        inputSchema: z.object({
-          query: z.string(),
-          table: z.string(),
-        }),
+        inputSchema: zodSchema(
+          z.object({
+            query: z.string(),
+            table: z.string(),
+          }),
+        ),
         execute: async ({ query, table }) => {
           // Server-side database access
           const results = await db.query(query, { table });
@@ -304,7 +307,7 @@ export async function POST(req: Request) {
       // Additional server-side tools
       queryDatabase: {
         description: "Query the application database",
-        inputSchema: z.object({ query: z.string() }),
+        inputSchema: zodSchema(z.object({ query: z.string() })),
         execute: async ({ query }) => {
           return await db.query(query);
         },

package/.docs/raw/docs/{getting-started.mdx → (docs)/index.mdx}

@@ -1,16 +1,15 @@
 ---
 title: Getting Started
+description: Get assistant-ui running in 5 minutes with npm and your first chat component.
 ---
 
-import { Step, Steps } from "fumadocs-ui/components/steps";
-import { Tab, Tabs } from "fumadocs-ui/components/tabs";
-import { Callout } from "fumadocs-ui/components/callout";
-import { Card, Cards } from "fumadocs-ui/components/card";
-import { InstallCommand } from "@/components/docs/install-command";
+import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
 
-## Start with a new project
+## Quick Start
 
-![animated gif showing the steps to create a new project](../../../../.github/assets/assistant-ui-starter.gif)
+The fastest way to get started with assistant-ui.
+
+![animated gif showing the steps to create a new project](../../../../../.github/assets/assistant-ui-starter.gif)
 
 <Steps>
   <Step>
@@ -20,11 +19,13 @@ import { InstallCommand } from "@/components/docs/install-command";
 **Create a new project:**
 
 ```sh
-# Create a new project with the default template
 npx assistant-ui@latest create
+```
+
+Or choose a template:
 
-# Or choose one of the following templates:
-# Assistant Cloud for baked in persistence and thread management
+```sh
+# Assistant Cloud - with persistence and thread management
 npx assistant-ui@latest create -t cloud
 
 # LangGraph
@@ -34,10 +35,9 @@ npx assistant-ui@latest create -t langgraph
 npx assistant-ui@latest create -t mcp
 ```
 
-**Add assistant-ui to an existing React project:**
+**Add to an existing project:**
 
 ```sh
-# Add assistant-ui to an existing React project
 npx assistant-ui@latest init
 ```
 
@@ -46,13 +46,10 @@ npx assistant-ui@latest init
 
 ### Add API key
 
-Add a new `.env` file to your project with your OpenAI API key:
+Create a `.env` file with your API key:
 
 ```
 OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
-
-# chat history -- sign up for free on https://cloud.assistant-ui.com
-# NEXT_PUBLIC_ASSISTANT_BASE_URL="https://..."
 ```
 
   </Step>
@@ -67,11 +64,9 @@ npm run dev
   </Step>
 </Steps>
 
-## Manual installation
+## Add to Existing Project
 
-<Callout>
-  We recommend `npx assistant-ui init` to setup existing projects.
-</Callout>
+If you prefer not to use the CLI, you can install components manually.
 
 <Steps>
   <Step>
@@ -404,7 +399,7 @@ const MyApp = () => {
 ```
 
 ```tsx title="/app/page.tsx" tab="AssistantModal"
-// run `npx shadcn@latest add @assistant-ui/assistant-modal`
+// run `npx shadcn@latest add https://r.assistant-ui.com/assistant-modal.json`
 
 import { AssistantRuntimeProvider } from "@assistant-ui/react";
 import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
@@ -441,7 +436,7 @@ const MyApp = () => {
   <Card
     title="Generative UI"
     description="Create rich UI components for tool executions"
-    href="/docs/guides/ToolUI"
+    href="/docs/guides/tool-ui"
   />
   <Card
     title="Add Persistence"

package/.docs/raw/docs/{mcp-docs-server.mdx → (docs)/mcp-docs-server.mdx}

@@ -1,9 +1,8 @@
 ---
 title: "MCP Docs Server"
-description: "Learn how to use the assistant-ui MCP documentation server in your IDE to access documentation and examples directly."
+description: Access assistant-ui docs and examples directly in your IDE via MCP.
 ---
 
-import { Tabs, Tab } from "fumadocs-ui/components/tabs";
 
 `@assistant-ui/mcp-docs-server` provides direct access to assistant-ui's documentation and examples in Cursor, Windsurf, VSCode, Zed, Claude Code, or any other IDE or tool that supports MCP.
 

package/.docs/raw/docs/{api-reference/context-providers/AssistantRuntimeProvider.mdx → (reference)/api-reference/context-providers/assistant-runtime-provider.mdx}

@@ -1,8 +1,9 @@
 ---
 title: <AssistantRuntimeProvider />
+description: Root provider that connects your runtime to assistant-ui components.
 ---
 
-import { ParametersTable } from "@/components/docs";
+import { ParametersTable } from "@/components/docs/tables/ParametersTable";
 import { AssistantRuntimeProvider } from "@/generated/typeDocs";
 
 The `AssistantRuntimeProvider` provides data and APIs used by assistant-ui components.

package/.docs/raw/docs/{api-reference/context-providers/TextMessagePartProvider.mdx → (reference)/api-reference/context-providers/text-message-part-provider.mdx}

@@ -1,8 +1,9 @@
 ---
 title: <TextMessagePartProvider />
+description: Context provider for reusing text components outside of message content.
 ---
 
-import { ParametersTable } from "@/components/docs";
+import { ParametersTable } from "@/components/docs/tables/ParametersTable";
 import { AssistantRuntimeProvider } from "@/generated/typeDocs";
 
 The `TextMessagePartProvider` provides data and APIs for `TextMessagePart` components.