@assistant-ui/mcp-docs-server 0.1.32 → 0.1.34

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

@@ -1,6 +1,6 @@
 ---
 title: Adapters
-description: Title generation and storage adapters for React Ink.
+description: Attachment, title generation, and storage adapters for React Ink.
 ---
 
 Adapters customize runtime behavior. They can be passed as options to `useLocalRuntime` or `useRemoteThreadListRuntime`.
@@ -17,6 +17,28 @@ const adapter = createFileStorageAdapter({
 });
 ```
 
+## 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`.

package/.docs/raw/docs/ink/hooks.mdx

@@ -60,6 +60,51 @@ useAuiEvent("thread.runStart", (payload) => {
 });
 ```
 
+### useNotification
+
+Ring the terminal bell and emit an OSC desktop notification when the assistant finishes a run, stops with an error, or pauses for human approval.
+
+```tsx
+import { useNotification } from "@assistant-ui/react-ink";
+
+useNotification();
+```
+
+Defaults:
+
+- `task-complete`: bell + OSC 9
+- `task-incomplete`: bell
+- `needs-input` (assistant message in `requires-action` with `reason: "interrupt"`): bell
+
+Pass `false` to suppress one trigger, or a `NotificationHandler` to override it:
+
+```tsx
+useNotification({
+  onTaskComplete: { osc: "osc99" },
+  onTaskIncomplete: false,
+  onNeedsInput: {
+    custom: (event) => myLogger.log(event),
+  },
+});
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `enabled` | `boolean` | Master switch. Defaults to `true`. |
+| `onTaskComplete` | `NotificationHandler<"task-complete"> \| false` | Fired when the latest assistant message status flips to `complete` after a run was observed. |
+| `onTaskIncomplete` | `NotificationHandler<"task-incomplete"> \| false` | Fired when the latest assistant message status flips to `incomplete` after a run was observed. |
+| `onNeedsInput` | `NotificationHandler<"needs-input"> \| false` | Fired when the latest assistant message enters `requires-action` with `reason: "interrupt"`. Tool-call pauses are skipped. |
+
+`NotificationHandler<T>` fields (all optional, any combination):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `bell` | `boolean` | Ring the terminal bell (`\x07`). |
+| `osc` | `boolean \| "osc9" \| "osc99" \| "osc777"` | Send an OSC notification. `true` is equivalent to `"osc9"`. |
+| `custom` | `(event: Extract<NotificationEvent, { type: T }>) => void` | User callback invoked with the event payload narrowed to this handler's type. |
+
+Notifications are deduplicated per `thread:message:status:reason` tuple, so passing an inline config object does not produce duplicate fires. `ringBell` and `sendOSCNotification(title, body?, variant?)` are also exported for imperative use. OSC support depends on the terminal emulator.
+
 ## Runtime Hooks
 
 ### useLocalRuntime
@@ -108,52 +153,47 @@ const runtime = useRemoteThreadListRuntime({
 
 ## Model Context Hooks
 
-### useAssistantTool
+### Tools
 
-Register a tool with an optional UI renderer. The tool definition is forwarded to the model, and when the model calls it, the `execute` function runs and the `render` component displays the result.
+Author tools with `defineToolkit`, the same API as on the web ([Defining Tools](/docs/tools/defining-tools)). The tool definition is forwarded to the model; when the model calls it, the `execute` function runs and the `render` component displays the result.
 
-```tsx
-import { useAssistantTool } from "@assistant-ui/react-ink";
-import { Text } from "ink";
+<Callout type="info">
+  An Ink app runs in a single Node process, so there is no client/server
+  boundary to split and no build step. `defineToolkit` from
+  `@assistant-ui/react-ink` runs at runtime: import it as a value, with no
+  `"use generative"` directive and no `"use client"` inside `execute`.
+</Callout>
 
-useAssistantTool({
-  toolName: "get_weather",
-  description: "Get the current weather for a city",
-  parameters: {
-    type: "object",
-    properties: {
-      city: { type: "string" },
+```tsx title="weather-toolkit.tsx"
+import { defineToolkit } from "@assistant-ui/react-ink";
+import { Text } from "ink";
+import { z } from "zod";
+
+export default defineToolkit({
+  get_weather: {
+    description: "Get the current weather for a city",
+    parameters: z.object({ city: z.string() }),
+    execute: async ({ city }) => {
+      const res = await fetch(`https://api.weather.example/${city}`);
+      return res.json();
     },
-    required: ["city"],
+    render: ({ args, result }) => (
+      <Text>
+        {args.city}: {result?.temperature}°F
+      </Text>
+    ),
   },
-  execute: async ({ city }) => {
-    const res = await fetch(`https://api.weather.example/${city}`);
-    return res.json();
-  },
-  render: ({ args, result }) => (
-    <Text>{args.city}: {result?.temperature}°F</Text>
-  ),
 });
 ```
 
-### useAssistantToolUI
-
-Register only a UI renderer for a tool (without tool definition or execute function).
-
-```tsx
-import { useAssistantToolUI } from "@assistant-ui/react-ink";
-import { Text } from "ink";
+```tsx title="ToolProvider.tsx"
+import { AuiProvider, Tools, useAui } from "@assistant-ui/react-ink";
+import toolkit from "./weather-toolkit";
 
-useAssistantToolUI({
-  toolName: "get_weather",
-  render: ({ args, result, status }) => (
-    <Text>
-      {status?.type === "running"
-        ? `Loading weather for ${args.city}...`
-        : `${args.city}: ${result?.temperature}°F`}
-    </Text>
-  ),
-});
+function ToolProvider({ children }: { children: React.ReactNode }) {
+  const aui = useAui({ tools: Tools({ toolkit }) });
+  return <AuiProvider value={aui}>{children}</AuiProvider>;
+}
 ```
 
 ### useAssistantInstructions
@@ -181,48 +221,9 @@ useAssistantDataUI({
   ),
 });
 ```
-### makeAssistantTool
-
-Create a component that registers a tool when mounted.
-
-```tsx
-import { makeAssistantTool } from "@assistant-ui/react-ink";
-import { Text } from "ink";
-
-const WeatherTool = makeAssistantTool({
-  toolName: "get_weather",
-  description: "Get weather",
-  parameters: { type: "object", properties: { city: { type: "string" } }, required: ["city"] },
-  execute: async ({ city }) => ({ temperature: 72 }),
-  render: ({ args, result }) => <Text>{args.city}: {result?.temperature}°F</Text>,
-});
-
-// Mount inside AssistantRuntimeProvider to register
-<WeatherTool />
-```
-
-### makeAssistantToolUI
+### Dynamic Tool Renderers
 
-Create a component that registers only a tool UI renderer (no tool definition or execute) when mounted.
-
-```tsx
-import { makeAssistantToolUI } from "@assistant-ui/react-ink";
-import { Text } from "ink";
-
-const WeatherToolUI = makeAssistantToolUI({
-  toolName: "get_weather",
-  render: ({ args, result, status }) => (
-    <Text>
-      {status?.type === "running"
-        ? `Loading weather for ${args.city}...`
-        : `${args.city}: ${result?.temperature}°F`}
-    </Text>
-  ),
-});
-
-// Mount inside AssistantRuntimeProvider to register
-<WeatherToolUI />
-```
+Use a toolkit with `useInlineRender` when the renderer closes over changing props.
 
 ### makeAssistantDataUI
 
@@ -247,16 +248,31 @@ const WeatherCardUI = makeAssistantDataUI({
 
 Wrap a render function component so that it always uses the latest version without re-creating a stable reference. Useful when passing a render prop inline and the function closes over changing state.
 
-```tsx
-import { useInlineRender } from "@assistant-ui/react-ink";
-
-const render = useInlineRender(({ args, result }) => (
-  <Text>{args.city}: {result?.temperature}°F</Text>
-));
+```tsx title="weather-toolkit.tsx"
+import { defineToolkit, useInlineRender } from "@assistant-ui/react-ink";
+import { Text } from "ink";
+import { useMemo } from "react";
 
-useAssistantToolUI({ toolName: "get_weather", render });
+export function useWeatherToolkit() {
+  const render = useInlineRender(({ args, result }) => (
+    <Text>{args.city}: {result?.temperature}°F</Text>
+  ));
+
+  return useMemo(
+    () =>
+      defineToolkit({
+        get_weather: {
+          type: "backend",
+          render,
+        },
+      }),
+    [render],
+  );
+}
 ```
 
+Import the toolkit hook, pass its result to `useAui({ tools: Tools({ toolkit }) })`, and provide the returned `aui` with `AuiProvider`, as shown in the [Tools](#tools) section above.
+
 ## Runtime Providers
 
 ### AssistantRuntimeProvider

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

@@ -9,7 +9,7 @@ If you already have an assistant-ui web app, most of your code transfers directl
 
 - **Runtime setup** — `useLocalRuntime`, `ChatModelAdapter`, and all runtime options work identically.
 - **AI SDK integration** — `@assistant-ui/react-ai-sdk` works with React Ink. Your runtime setup transfers directly.
-- **Tool definitions** — `useAssistantTool`, `makeAssistantTool`, and tool UI renderers use the same API.
+- **Tool definitions** — `Tools({ toolkit })` and toolkit renderers use the same API.
 - **State hooks** — `useAuiState`, `useAui`, and selector patterns are the same.
 - **Backend code** — Your API routes, streaming endpoints, and server-side logic need zero changes.
 

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

@@ -475,7 +475,7 @@ Container `Box` for a single message.
 
 ### Parts
 
-Renders message content parts via a `components` prop. Tool call and data parts automatically render registered tool UIs (via `useAssistantTool` / `useAssistantDataUI`), falling back to components provided here. Default terminal-safe renderers are provided for text, reasoning, source, image, file, and data parts.
+Renders message content parts via a `components` prop. Tool call and data parts automatically render registered toolkit renderers and data UIs (via `useAssistantDataUI`), falling back to components provided here. Default terminal-safe renderers are provided for text, reasoning, source, image, file, and data parts.
 
 ```tsx
 <MessagePrimitive.Parts>
@@ -509,7 +509,7 @@ Override part rendering with app-owned components when you need richer terminal
   Deprecated. Use `MessagePrimitive.Parts` instead. See the [v0.11 migration guide](/docs/migrations/v0-11) for details.
 </Callout>
 
-Renders message content parts using render props. Tool call and data parts automatically render registered tool UIs (via `useAssistantTool` / `useAssistantDataUI`), falling back to render props if provided.
+Renders message content parts using render props. Tool call and data parts automatically render registered toolkit renderers and data UIs (via `useAssistantDataUI`), falling back to render props if provided.
 
 ```tsx
 <MessagePrimitive.Content

package/.docs/raw/docs/integrations/frameworks/ai-sdk.mdx

@@ -52,7 +52,7 @@ Three versions of `ai` are supported. New projects should pick **v6**; v5 and v4
 AI SDK is the default choice for new projects on Next.js, Remix, or any framework with a Node-compatible API route. Pick it when:
 
 - You want a single direct path from the chat UI to your model with the smallest possible code surface.
-- You will compose with a framework like [Mastra](/docs/integrations/frameworks/mastra/overview), an [observability tool](/docs/integrations/observability/helicone), an [LLM gateway](/docs/integrations/gateways), or [tools through MCP](/docs/integrations/tools/mcp), all of which assume an AI SDK route.
+- You will compose with a framework like [Mastra](/docs/integrations/frameworks/mastra/overview), an [observability tool](/docs/integrations/observability/helicone), an [LLM gateway](/docs/integrations/gateways), or [tools through MCP](/docs/tools/mcp), all of which assume an AI SDK route.
 - You want first-party `frontendTools`, attachments, multi-step tool calls, token-usage metadata, and persisted history via `withFormat`.
 
 If you need streaming agent state (subgraph events, generative UI messages), look at [LangGraph](/docs/runtimes/langgraph) instead. If you have a different protocol-shaped backend (A2A, AG-UI, OpenCode), see [pick a runtime](/docs/runtimes/pick-a-runtime).

package/.docs/raw/docs/integrations/index.mdx

@@ -60,14 +60,14 @@ Framework integrations that pair with assistant-ui at the API-route layer.
 
 ## Tools
 
-Pluggable tool catalogs and protocols.
+Tool catalogs and protocols have their own [Tools](/docs/tools) section.
 
 <Cards>
   <Card
     icon={<McpIcon width={20} height={20} />}
     title="Model Context Protocol (MCP)"
     description="Connect any MCP server as a tool catalog through the AI SDK MCP client."
-    href="/docs/integrations/tools/mcp"
+    href="/docs/tools/mcp"
   />
 </Cards>
 

package/.docs/raw/docs/integrations/persistence/custom-adapter.mdx

@@ -65,7 +65,22 @@ export const messages = pgTable(
 );
 ```
 
-The four message columns (`id`, `parent_id`, `format`, `content`) are the contract `withFormat` writes against. `format` lets multiple runtimes coexist on one row (e.g., `"aisdk-v6"` from `useChatRuntime`, a different value from another runtime).
+The four message columns (`id`, `parent_id`, `format`, `content`) are the contract `withFormat` writes against. `format` records which adapter encoded the row so multiple runtimes can coexist on one table; `useChatRuntime` sets it from `fmt.format`.
+
+<Callout type="warn">
+  `content` is not arbitrary JSON. It must be the payload the active format adapter produced via `fmt.encode(item)`, and it is read back through `fmt.decode`; the route handlers below are a pass-through that never inspects it. For `useChatRuntime` (AI SDK v6) a valid stored row looks like:
+
+  ```json
+  {
+    "id": "msg_abc",
+    "parent_id": null,
+    "format": "ai-sdk/v6",
+    "content": { "role": "user", "parts": [{ "type": "text", "text": "hello" }] }
+  }
+  ```
+
+  A row that satisfies the column types but carries a different shape (e.g. `{ "foo": "bar" }`) is accepted on write, then fails history reload. Seed test data through the adapter, not by hand-crafting `content`.
+</Callout>
 
 ## Setup
 
@@ -678,7 +693,7 @@ Send a message in a fresh thread. Check the database:
 
 - The `threads` table has a new row with the current `userId`.
 - The `messages` table has at least two rows (user + assistant) for that thread.
-- `format` is `"aisdk-v6"` (or whatever AI SDK's current format string is).
+- `format` matches what `fmt.format` wrote (`"ai-sdk/v6"` for AI SDK v6) and `content` is the encoded `UIMessage` (a `role` plus `parts`), not a placeholder blob.
 - Reload the page; the thread list and the messages survive.
 
 </Step>

package/.docs/raw/docs/migrations/toolkit-tools.mdx

@@ -0,0 +1,232 @@
+---
+title: Migrating Tools to Toolkits
+description: Move makeAssistantTool, useAssistantTool, makeAssistantToolUI, and useAssistantToolUI registrations to the toolkit API.
+---
+
+The component and hook based tool APIs are deprecated:
+
+- `makeAssistantTool`
+- `useAssistantTool`
+- `makeAssistantToolUI`
+- `useAssistantToolUI`
+
+Use a toolkit registered with `Tools({ toolkit })` instead. Toolkits keep the model contract, browser execution, and tool-call rendering in one named map, which avoids duplicate registrations and makes the client/backend split explicit.
+
+## Before
+
+```tsx
+import { AssistantRuntimeProvider, makeAssistantTool } from "@assistant-ui/react";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { z } from "zod";
+
+const WeatherTool = makeAssistantTool({
+  toolName: "get_weather",
+  description: "Get the current weather for a city.",
+  parameters: z.object({
+    city: z.string(),
+  }),
+  execute: async ({ city }) => fetchWeather(city),
+  render: ({ args, result }) => (
+    <WeatherCard city={args.city} weather={result} />
+  ),
+});
+
+export function App() {
+  const runtime = useChatRuntime({ api: "/api/chat" });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <WeatherTool />
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+## After
+
+```tsx title="app/toolkit.tsx"
+"use generative";
+
+import { defineToolkit } from "@assistant-ui/react";
+import { z } from "zod";
+
+export default defineToolkit({
+  get_weather: {
+    description: "Get the current weather for a city.",
+    parameters: z.object({
+      city: z.string(),
+    }),
+    execute: async ({ city }) => {
+      "use client";
+      return fetchWeather(city);
+    },
+    render: ({ args, result }) => (
+      <WeatherCard city={args.city} weather={result} />
+    ),
+  },
+});
+```
+
+```tsx title="app/MyRuntimeProvider.tsx"
+"use client";
+
+import {
+  AssistantRuntimeProvider,
+  Tools,
+  useAui,
+} from "@assistant-ui/react";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import toolkit from "./toolkit";
+
+export function App() {
+  const runtime = useChatRuntime({ api: "/api/chat" });
+  const aui = useAui({
+    tools: Tools({ toolkit }),
+  });
+
+  return (
+    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+## Mechanical Steps
+
+1. Create a `Toolkit` object.
+2. Move each `toolName` into the toolkit key.
+3. Move `description`, `parameters`, `execute`, `providerOptions`, `render`, `renderText`, and `display` onto the toolkit entry.
+4. Register the toolkit once with `useAui({ tools: Tools({ toolkit }) })`.
+5. Remove `<Tool />`, `<ToolUI />`, `useAssistantTool(...)`, and `useAssistantToolUI(...)` registrations.
+
+## UI-Only Tool Renderers
+
+If you used `makeAssistantToolUI` or `useAssistantToolUI` for a backend, MCP, or
+LangGraph tool, the tool executes elsewhere. Prefer a `"use generative"` toolkit
+with `execute: externalTool()` so the compiler omits the server entry, while the
+client keeps your renderer as `type: "backend"`:
+
+```tsx
+// app/toolkit.tsx
+"use generative";
+
+import { defineToolkit, externalTool } from "@assistant-ui/react";
+
+export default defineToolkit({
+  web_search: {
+    execute: externalTool(),
+    render: ({ args, result }) => (
+      <SearchResults query={args.query} results={result?.results ?? []} />
+    ),
+  },
+});
+```
+
+Register it like any toolkit: `useAui({ tools: Tools({ toolkit }) })`.
+Render-only entries upload no schema and run no browser code — they only attach
+UI for matching tool-call message parts. For MCP server catalogs, spread
+`defineMcpToolkit({ ... })` in the same generative toolkit.
+
+For a one-off renderer that should only affect a particular message surface, use `MessagePrimitive.Parts` inline tool render overrides instead of a global registration.
+
+## Dynamic Tools
+
+If a tool needs component state or props, keep the toolkit contract in a `"use generative"` file and use `stubTool()` for the executor. The component that owns the state supplies the real executor with `useAuiToolOverrides(...)`:
+
+<Callout type="warn">
+  `useAuiToolOverrides` is experimental and its API may change.
+</Callout>
+
+```tsx title="task-board-toolkit.tsx"
+"use generative";
+
+import { defineToolkit, stubTool } from "@assistant-ui/react";
+import { z } from "zod";
+
+export type Task = { id: string; title: string };
+
+export default defineToolkit({
+  add_task: {
+    description: "Add a task to the board.",
+    parameters: z.object({ title: z.string() }),
+    execute: stubTool(),
+    renderText: {
+      running: "Adding task",
+      complete: "Task added",
+    },
+  },
+});
+```
+
+```tsx title="TaskBoard.tsx"
+import { AuiProvider, Tools, useAui, useAuiToolOverrides } from "@assistant-ui/react";
+import { useState, type Dispatch, type SetStateAction } from "react";
+import type { Task } from "./task-board-toolkit";
+import toolkit from "./task-board-toolkit";
+
+function TaskBoard() {
+  const [tasks, setTasks] = useState<Task[]>([]);
+
+  const aui = useAui({
+    tools: Tools({ toolkit }),
+  });
+
+  return (
+    <AuiProvider value={aui}>
+      <TaskBoardToolOverrides setTasks={setTasks} />
+      <TaskList tasks={tasks} />
+    </AuiProvider>
+  );
+}
+
+function TaskBoardToolOverrides({
+  setTasks,
+}: {
+  setTasks: Dispatch<SetStateAction<Task[]>>;
+}) {
+  useAuiToolOverrides({
+    add_task: {
+      execute: async ({ title }) => {
+        setTasks((prev) => [
+          ...prev,
+          { id: crypto.randomUUID(), title },
+        ]);
+        return { ok: true };
+      },
+    },
+  });
+  return null;
+}
+```
+
+This keeps the model-facing contract in the toolkit file while the component owns the stateful executor.
+
+## Generative Toolkits
+
+For tools authored in a `"use generative"` file, export a toolkit with `defineToolkit(...)`. The compiler splits backend, frontend, and human tools for you. This is the default shape to use for docs and copy-paste examples:
+
+```tsx
+"use generative";
+
+import { defineToolkit } from "@assistant-ui/react";
+import { z } from "zod";
+
+export default defineToolkit({
+  create_chart: {
+    description: "Create a chart for the user.",
+    parameters: z.object({
+      title: z.string(),
+      values: z.array(z.number()),
+    }),
+    execute: async ({ title, values }) => {
+      "use client";
+      return renderChart(title, values);
+    },
+    render: ChartTool,
+  },
+});
+```
+
+Frontend and human tools produced by the generative compiler already have their schema defaults on the backend, so the client no longer re-uploads those schemas.

package/.docs/raw/docs/primitives/chain-of-thought.mdx

@@ -22,19 +22,16 @@ For new grouped reasoning/tool-call UI, use `MessagePrimitive.GroupedParts`. `Ch
   </Tab>
   <Tab>
 ```tsx
-import { MessagePrimitive } from "@assistant-ui/react";
+import { MessagePrimitive, groupPartByType } from "@assistant-ui/react";
 
 function AssistantMessage() {
   return (
     <MessagePrimitive.Root>
       <MessagePrimitive.GroupedParts
-        groupBy={(part) => {
-          if (part.type === "reasoning")
-            return ["group-chainOfThought", "group-reasoning"];
-          if (part.type === "tool-call")
-            return ["group-chainOfThought", "group-tool"];
-          return null;
-        }}
+        groupBy={groupPartByType({
+          reasoning: ["group-chainOfThought", "group-reasoning"],
+          "tool-call": ["group-chainOfThought", "group-tool"],
+        })}
       >
         {({ part, children }) => {
           switch (part.type) {
@@ -67,17 +64,14 @@ function AssistantMessage() {
 Group reasoning and tool-call parts directly in your assistant message:
 
 ```tsx
-import { MessagePrimitive } from "@assistant-ui/react";
+import { MessagePrimitive, groupPartByType } from "@assistant-ui/react";
 
 <MessagePrimitive.Root>
   <MessagePrimitive.GroupedParts
-    groupBy={(part) => {
-      if (part.type === "reasoning")
-        return ["group-chainOfThought", "group-reasoning"];
-      if (part.type === "tool-call")
-        return ["group-chainOfThought", "group-tool"];
-      return null;
-    }}
+    groupBy={groupPartByType({
+      reasoning: ["group-chainOfThought", "group-reasoning"],
+      "tool-call": ["group-chainOfThought", "group-tool"],
+    })}
   >
     {({ part, children }) => {
       switch (part.type) {