@assistant-ui/mcp-docs-server 0.1.30 → 0.1.31

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

@@ -1,6 +1,7 @@
 ---
 title: Tools
 description: Give your assistant actions like API calls, database queries, and more.
+platforms: ["react"]
 ---
 
 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.
@@ -24,9 +25,9 @@ When tools are executed, you can display custom generative UI components that pr
   creating your own Tool UI component for the tool's name.
 </Callout>
 
-## Recommended: Tools() API
+## Tools() API
 
-The `Tools()` API is the recommended way to register tools in assistant-ui. It provides centralized tool registration that prevents duplicate registrations and works seamlessly with all runtimes.
+The `Tools()` API is the recommended starting point for registering tools in assistant-ui. It provides centralized tool registration that prevents duplicate registrations and works seamlessly with all runtimes. For tools whose availability depends on a specific part of your UI being mounted, see the [component-based APIs](#component-based-apis) below; both styles are supported and can be mixed in the same app.
 
 ### Quick Start
 
@@ -207,6 +208,32 @@ execute: async (args, context) => {
 };
 ```
 
+### Cancellation
+
+`context.abortSignal` is an `AbortSignal` that fires when the user stops the run. Pass it to any async I/O so the work stops immediately:
+
+```tsx
+execute: async ({ query }, { abortSignal }) => {
+  const res = await fetch(`/api/search?q=${query}`, { signal: abortSignal });
+  return res.json();
+},
+```
+
+When using LangGraph with `unstable_createLangGraphStream`, the default `onDisconnect` value is already `"cancel"`, which tells the LangGraph server to cancel the run on abort:
+
+```ts
+import { unstable_createLangGraphStream } from "@assistant-ui/react-langgraph";
+
+const stream = unstable_createLangGraphStream({
+  client,
+  assistantId,
+  // onDisconnect defaults to "cancel"; the server cancels the run when the
+  // client disconnects or the user stops the message.
+});
+```
+
+See the [LangGraph quickstart](/docs/runtimes/langgraph/quickstart) for full setup.
+
 ### Human-in-the-Loop
 
 Tools can pause execution to request user input or approval:
@@ -260,15 +287,51 @@ const confirmationToolkit: Toolkit = {
 };
 ```
 
-## Alternative Methods (Legacy)
+### Streaming Tool Args
+
+While a tool is running, its arguments arrive as partial JSON. Use `useToolArgsStatus` inside a tool UI render function to react to each top-level field as it streams in. The hook is exported from `@assistant-ui/react`.
+
+```tsx
+import { useToolArgsStatus } from "@assistant-ui/react";
+
+const SearchToolUI = makeAssistantToolUI<{ query: string; limit: number }, unknown>({
+  toolName: "search",
+  render: ({ args }) => {
+    const { propStatus } = useToolArgsStatus<{ query: string; limit: number }>();
+
+    return (
+      <div>
+        <span className={propStatus.query === "streaming" ? "animate-pulse" : ""}>
+          {args.query ?? "..."}
+        </span>
+        {propStatus.limit === "complete" && <span> (limit: {args.limit})</span>}
+      </div>
+    );
+  },
+});
+```
+
+`propStatus` maps each top-level key in the args object to `"streaming"` while it is still being parsed and to `"complete"` once that field is fully present.
+
+## Component-Based APIs
+
+`makeAssistantTool`, `useAssistantTool`, and `makeAssistantToolUI` are component-and-hook-based APIs that coexist with the [`Tools()`](#tools-api) toolkit pattern. They are fully supported and the natural fit for the [intelligent components](/docs/copilots/motivation) pattern, where each part of your UI registers the tools it owns when it is mounted, for example a product-specific tool that should only be exposed while that product's screen is open.
+
+<Callout type="info">
+  Be careful not to register the same tool from both APIs at once: each API
+  registers under `toolName`, and duplicate registrations will be rejected.
+</Callout>
 
-<Callout type="warning">
-  The following methods are supported for backwards compatibility but are not
-  recommended for new code. They can cause duplicate registration errors and are
-  harder to maintain. Use the `Tools()` API instead.
+<Callout type="warn">
+  Tool **execution** can be registered dynamically (when a component mounts),
+  but tool **UI** should generally be pre-registered. A `render` function that
+  is only registered while a specific component is mounted will not render
+  when chat history is replayed or during server-side rendering. Either
+  declare the tool's `render` in a `Tools()` toolkit, or mount
+  `makeAssistantToolUI` near the root of your tree.
 </Callout>
 
-### Using `makeAssistantTool` (Deprecated)
+### Using `makeAssistantTool`
 
 Register tools with the assistant context. Returns a React component that registers the tool when rendered:
 
@@ -303,9 +366,9 @@ function App() {
 }
 ```
 
-**Why this is deprecated**: Component-based registration can lead to duplicate registrations if components are remounted or if the same tool is defined in multiple places.
+Tradeoff: component-based registration is tied to React lifecycle, so the tool is registered when the component mounts and unregistered when it unmounts. Take care not to remount it accidentally if you also register the same tool elsewhere.
 
-### Using `useAssistantTool` Hook (Deprecated)
+### Using the `useAssistantTool` Hook
 
 Register tools dynamically using React hooks:
 
@@ -329,9 +392,9 @@ function DynamicTools() {
 }
 ```
 
-**Why this is deprecated**: Hook-based registration ties tool definitions to component lifecycle, making them harder to test and potentially causing duplicate registrations.
+Tradeoff: like `makeAssistantTool`, the registration follows the component lifecycle. Useful for dynamic tools that depend on component state or props.
 
-### Using `makeAssistantToolUI` (Deprecated)
+### Using `makeAssistantToolUI`
 
 Create UI-only components for tools defined elsewhere:
 
@@ -365,7 +428,7 @@ function App() {
 }
 ```
 
-**Why this is deprecated**: Component-based UI registration can cause issues with tool UI not appearing or appearing multiple times.
+Tradeoff: like the other component-based APIs, the UI is registered while the component is mounted. Useful when the tool UI needs access to surrounding component state or context.
 
 ## Tool Paradigms
 
@@ -391,37 +454,32 @@ const frontendToolkit: Toolkit = {
 
 ### Backend Tools
 
-Tools executed server-side:
+Tools executed server-side live in your API route. A minimal example with the AI SDK:
+
+```ts title="@/app/api/chat/route.ts"
+import { openai } from "@ai-sdk/openai";
+import { streamText, convertToModelMessages, tool, zodSchema } from "ai";
+import { z } from "zod";
 
-```tsx
-// Backend route (AI SDK)
 export async function POST(req: Request) {
   const { messages } = await req.json();
-
   const result = streamText({
     model: openai("gpt-4o"),
     messages: await convertToModelMessages(messages),
     tools: {
-      queryDatabase: {
+      queryDatabase: tool({
         description: "Query the application database",
-        inputSchema: zodSchema(
-          z.object({
-            query: z.string(),
-            table: z.string(),
-          }),
-        ),
-        execute: async ({ query, table }) => {
-          const results = await db.query(query, { table });
-          return results;
-        },
-      },
+        inputSchema: zodSchema(z.object({ query: z.string(), table: z.string() })),
+        execute: async ({ query, table }) => db.query(query, { table }),
+      }),
     },
   });
-
   return result.toUIMessageStreamResponse();
 }
 ```
 
+For the full AI SDK v6 backend setup including multi-step tool calls, frontend tools, history persistence with `withFormat`, and more, see the [AI SDK v6 guide](/docs/runtimes/ai-sdk/v6).
+
 ### Client-Defined Tools with frontendTools
 
 The Vercel AI SDK adapter implements automatic serialization of client-defined tools. Tools registered via the `Tools()` API are automatically included in API requests:
@@ -512,9 +570,47 @@ export async function POST(req: Request) {
 }
 ```
 
+## LangGraph subgraph events
+
+When a LangGraph graph contains sub-agents (nested subgraphs), events from those subgraphs arrive with a `metadata.namespace` field identifying the originating subgraph. Pass event handlers to `useLangGraphRuntime` (or `useLangGraphMessages`) to react to them:
+
+```ts
+const runtime = useLangGraphRuntime({
+  stream,
+  eventHandlers: {
+    onSubgraphValues: (namespace, values) => {
+      console.log("subgraph", namespace, "state:", values);
+    },
+    onSubgraphUpdates: (namespace, updates) => {
+      console.log("subgraph", namespace, "updates:", updates);
+    },
+    onSubgraphError: (namespace, error) => {
+      console.error("subgraph", namespace, "error:", error);
+    },
+  },
+});
+```
+
+`namespace` is a pipe-separated string like `"parent|child_agent"`. Messages emitted by a subgraph include `metadata.namespace` so you can attribute tool results to the correct sub-agent.
+
+## `useLangChainState`
+
+When using `@assistant-ui/react-langchain` (`useStreamRuntime`), the `useLangChainState` hook lets you read any key from the current LangChain/LangGraph state on the client without a separate API call:
+
+```tsx
+import { useLangChainState } from "@assistant-ui/react-langchain";
+
+function TodoSidebar() {
+  const todos = useLangChainState<string[]>("todos", []);
+  return <ul>{todos.map((t) => <li key={t}>{t}</li>)}</ul>;
+}
+```
+
+The second argument is an optional default value. The hook re-renders whenever the state key changes during a stream.
+
 ## Best Practices
 
-1. **Use Tools() API**: Always prefer the `Tools()` API over legacy component/hook-based registration
+1. **Pick one registration style per tool**: avoid registering the same tool through both the `Tools()` toolkit and a component-based API; both routes will register, and duplicates are rejected
 2. **Centralize Definitions**: Keep all tools in a toolkit file for easy management
 3. **Clear Descriptions**: Write descriptive tool descriptions that help the LLM understand when to use each tool
 4. **Parameter Validation**: Use Zod schemas to ensure type safety
@@ -524,9 +620,9 @@ export async function POST(req: Request) {
 8. **Performance**: Use abort signals for cancellable operations
 9. **Testing**: Test tools in isolation and with the full assistant flow
 
-## Migration from Legacy APIs
+## Switching from Component-Based to Toolkit
 
-To migrate from legacy APIs to the `Tools()` API:
+If you prefer the toolkit shape, switching is mechanical:
 
 1. **Create a toolkit object** with all your tools
 2. **Move tool definitions** from `makeAssistantTool`/`useAssistantTool` calls into the toolkit
@@ -537,7 +633,7 @@ To migrate from legacy APIs to the `Tools()` API:
 Example migration:
 
 ```tsx
-// Before (Legacy)
+// Component-based API
 const WeatherTool = makeAssistantTool({
   toolName: "getWeather",
   description: "Get weather",
@@ -554,7 +650,7 @@ function App() {
   );
 }
 
-// After (Recommended)
+// Toolkit API
 const toolkit: Toolkit = {
   getWeather: {
     description: "Get weather",

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

@@ -1,6 +1,7 @@
 ---
 title: Realtime Voice
 description: Bidirectional realtime voice conversations with AI agents.
+platforms: ["react"]
 ---
 
 import { VoiceSample } from "@/components/docs/samples/voice";
@@ -63,6 +64,10 @@ const { connect, disconnect, mute, unmute } = useVoiceControls();
 
 ## UI Example
 
+<Callout type="info">
+  For a ready-made control bar with a voice orb and call controls, see the [Voice component](/docs/ui/voice).
+</Callout>
+
 ```tsx
 import { useVoiceState, useVoiceControls } from "@assistant-ui/react";
 import { PhoneIcon, PhoneOffIcon, MicIcon, MicOffIcon } from "lucide-react";
@@ -301,6 +306,40 @@ const runtime = useChatRuntime({
 });
 ```
 
+## Using `createVoiceSession`
+
+`createVoiceSession` is a helper that eliminates the manual `Set<callback>` boilerplate shown in the ElevenLabs example above. Pass it an async `setup` function that receives a `helpers` object and returns `{ disconnect, mute, unmute }`. The helper wires up all callback sets, status tracking, and abort-signal handling for you.
+
+```tsx title="lib/my-voice-adapter.ts"
+import { createVoiceSession, type RealtimeVoiceAdapter } from "@assistant-ui/react";
+
+export class MyVoiceAdapter implements RealtimeVoiceAdapter {
+  connect(options: { abortSignal?: AbortSignal }): RealtimeVoiceAdapter.Session {
+    return createVoiceSession(options, async (helpers) => {
+      // Connect to your provider
+      const client = await MyVoiceClient.connect();
+
+      client.on("open", () => helpers.setStatus({ type: "running" }));
+      client.on("close", () => helpers.end("finished"));
+      client.on("error", (err) => helpers.end("error", err));
+
+      client.on("transcript", (item) => helpers.emitTranscript(item));
+      client.on("mode", (mode) => helpers.emitMode(mode));
+      client.on("volume", (v) => helpers.emitVolume(v));
+
+      // Return controls — createVoiceSession calls these on disconnect/mute/unmute
+      return {
+        disconnect: () => client.close(),
+        mute: () => client.setMuted(true),
+        unmute: () => client.setMuted(false),
+      };
+    });
+  }
+}
+```
+
+The `helpers` object exposes `setStatus`, `end`, `emitTranscript`, `emitMode`, `emitVolume`, and `isDisposed`. When `isDisposed()` is true the session has been torn down and you can skip further event handling.
+
 ## Example: LiveKit
 
 [LiveKit](https://livekit.io/) provides realtime voice via WebRTC rooms with transcription support. Unlike fully-hosted agent services, LiveKit follows a "bring-your-own-agent" model: the browser adapter only joins a room, and you run a separate **agent worker** that joins the same room and handles STT, LLM, and TTS. Without an agent in the room, the client will connect successfully but have nothing to talk to.

package/.docs/raw/docs/ink/index.mdx

@@ -47,9 +47,7 @@ If you prefer to add assistant-ui to an existing Node.js project, follow these s
 
 ### Install dependencies
 
-```sh
-npm install @assistant-ui/react-ink @assistant-ui/react-ink-markdown ink react
-```
+<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/react-ink-markdown", "ink", "react"]} />
 
   </Step>
   <Step>

package/.docs/raw/docs/ink/migration.mdx

@@ -30,9 +30,7 @@ If you already have an assistant-ui web app, most of your code transfers directl
 
 ### Install the React Ink package
 
-```sh
-npm install @assistant-ui/react-ink ink react
-```
+<InstallCommand npm={["@assistant-ui/react-ink", "ink", "react"]} />
 
   </Step>
   <Step>

package/.docs/raw/docs/ink/primitives.mdx

@@ -177,11 +177,12 @@ Container `Box` for the composer area.
 
 ### Input
 
-Ink `TextInput` wired to the composer runtime. Value is managed automatically.
+Terminal line editor wired to the composer runtime. Value is managed automatically and supports cursor-aware editing.
 
 ```tsx
 <ComposerPrimitive.Input
   submitOnEnter
+  multiLine
   placeholder="Type a message..."
   autoFocus
 />
@@ -192,6 +193,41 @@ Ink `TextInput` wired to the composer runtime. Value is managed automatically.
 | `submitOnEnter` | `boolean` | Whether Enter sends the message (default: `false`) |
 | `placeholder` | `string` | Placeholder text when empty |
 | `autoFocus` | `boolean` | Auto-focus on mount |
+| `multiLine` | `boolean` | When true, Enter inserts a newline unless `submitOnEnter` is enabled |
+| `onSubmit` | `(text: string) => void` | Overrides the default send behavior and receives the current composer text |
+
+Supported keyboard bindings:
+
+| Key | Action | Context |
+|-----|--------|---------|
+| `Left` / `Right` | Move cursor by one grapheme | Always |
+| `Backspace` / `Delete` | Remove the grapheme before / after the cursor | Always |
+| `Home` / `End` | Jump to buffer or line boundary | Buffer in single-line, line in multi-line |
+| `Up` / `Down` | Move between lines, preserving column when possible | Multi-line only |
+| `Ctrl+A` / `Ctrl+E` | Move to line start / end | Always |
+| `Ctrl+W` | Kill the word before the cursor | Always |
+| `Ctrl+D` | Delete the grapheme after the cursor | Always |
+| `Ctrl+U` / `Ctrl+K` | Kill from cursor to line start / end; in multi-line, `Ctrl+K` at end-of-line joins the next line | Always |
+| `Ctrl+J` | Insert a newline | Multi-line only; swallowed in single-line so it never submits |
+| `Alt+B` / `Alt+F` | Move by word backward / forward | Terminals that emit meta-key sequences |
+| `Alt+D` | Kill the word after the cursor | Terminals that emit meta-key sequences |
+| `Shift+Enter` | Insert a newline | Multi-line submit mode, terminals that distinguish it |
+
+Word boundaries and grapheme stepping use `Intl.Segmenter`, so emoji, accented letters, skin-tone modifiers, ZWJ sequences, and CJK ideographs each move and delete as a single character.
+
+Some bindings depend on terminal capabilities. iTerm2, Windows Terminal, and most Linux terminals emit `Alt`-letter combinations as `Esc`-prefixed sequences that Ink decodes as meta-key input; macOS Terminal.app requires enabling "Use Option as Meta key" in its preferences before `Alt+B` / `Alt+F` / `Alt+D` work as expected. `Shift+Enter` requires a terminal that supports the CSI-u protocol (iTerm2 3.4+, kitty, foot, and similar) — terminals that conflate it with `Enter` will fall back to the `submitOnEnter` behaviour.
+
+Example with custom submit handling:
+
+```tsx
+<ComposerPrimitive.Input
+  multiLine
+  submitOnEnter
+  onSubmit={(text) => {
+    console.log("submit", text);
+  }}
+/>
+```
 
 ### Send