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

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

@@ -1,236 +0,0 @@
----
-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/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();
-
-  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,
-  AuiConfig,
-  Tools,
-} from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/ai-sdk";
-import toolkit from "./toolkit";
-
-export function App() {
-  const runtime = useChatRuntime();
-  const config = AuiConfig({ tools: Tools({ toolkit }) });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime} config={config}>
-      <Thread />
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-`useChatRuntime()` targets `/api/chat` by default. To point at a different endpoint or customize requests, see [Custom transport](/docs/runtimes/ai-sdk/v7#custom-transport).
-
-## 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 `config={config}` on your runtime provider, where `const config = AuiConfig({ 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: `config={config}` where `const config = AuiConfig({ 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 {
-  AuiConfig,
-  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();
-  const config = AuiConfig({ tools: Tools({ toolkit }) });
-
-  return (
-    <AuiProvider extends={aui} config={config}>
-      <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/migrations/v0-11.mdx

@@ -1,172 +0,0 @@
----
-title: Migration to v0.11
-description: ContentPart renamed to MessagePart for better semantic clarity.
----
-
-## ContentPart renamed to MessagePart
-
-All ContentPart-related types, hooks, and components have been renamed to MessagePart for better semantic clarity and consistency.
-
-### What changed
-
-The following types and components have been renamed:
-
-#### Core Types
-
-- `TextContentPart` → `TextMessagePart`
-- `ReasoningContentPart` → `ReasoningMessagePart`
-- `SourceContentPart` → `SourceMessagePart`
-- `ImageContentPart` → `ImageMessagePart`
-- `FileContentPart` → `FileMessagePart`
-- `Unstable_AudioContentPart` → `Unstable_AudioMessagePart`
-- `ToolCallContentPart` → `ToolCallMessagePart`
-- `ContentPartStatus` → `MessagePartStatus`
-- `ToolCallContentPartStatus` → `ToolCallMessagePartStatus`
-
-#### Thread Message Parts
-
-- `ThreadUserContentPart` → `ThreadUserMessagePart`
-- `ThreadAssistantContentPart` → `ThreadAssistantMessagePart`
-
-#### Runtime and State Types
-
-- `ContentPartRuntime` → `MessagePartRuntime`
-- `ContentPartState` → `MessagePartState`
-
-#### Hooks
-
-- `useContentPart` → `useMessagePart`
-- `useContentPartRuntime` → `useMessagePartRuntime`
-- `useContentPartText` → `useMessagePartText`
-- `useContentPartReasoning` → `useMessagePartReasoning`
-- `useContentPartSource` → `useMessagePartSource`
-- `useContentPartFile` → `useMessagePartFile`
-- `useContentPartImage` → `useMessagePartImage`
-- `useTextContentPart` → `useMessagePartText`
-
-#### Component Types
-
-- `EmptyContentPartComponent` → `EmptyMessagePartComponent`
-- `TextContentPartComponent` → `TextMessagePartComponent`
-- `ReasoningContentPartComponent` → `ReasoningMessagePartComponent`
-- `SourceContentPartComponent` → `SourceMessagePartComponent`
-- `ImageContentPartComponent` → `ImageMessagePartComponent`
-- `FileContentPartComponent` → `FileMessagePartComponent`
-- `Unstable_AudioContentPartComponent` → `Unstable_AudioMessagePartComponent`
-- `ToolCallContentPartComponent` → `ToolCallMessagePartComponent`
-
-#### Props Types
-
-- `EmptyContentPartProps` → `EmptyMessagePartProps`
-- `TextContentPartProps` → `TextMessagePartProps`
-- `ReasoningContentPartProps` → `ReasoningMessagePartProps`
-- `SourceContentPartProps` → `SourceMessagePartProps`
-- `ImageContentPartProps` → `ImageMessagePartProps`
-- `FileContentPartProps` → `FileMessagePartProps`
-- `Unstable_AudioContentPartProps` → `Unstable_AudioMessagePartProps`
-- `ToolCallContentPartProps` → `ToolCallMessagePartProps`
-
-#### Providers and Context
-
-- `TextContentPartProvider` → `TextMessagePartProvider`
-- `TextContentPartProviderProps` → `TextMessagePartProviderProps`
-- `ContentPartRuntimeProvider` → `MessagePartRuntimeProvider`
-- `ContentPartContext` → `MessagePartContext`
-- `ContentPartContextValue` → `MessagePartContextValue`
-
-#### Primitives
-
-- `ContentPartPrimitive` → `MessagePartPrimitive`
-- `ContentPartPrimitiveText` → `MessagePartPrimitiveText`
-- `ContentPartPrimitiveImage` → `MessagePartPrimitiveImage`
-- `ContentPartPrimitiveInProgress` → `MessagePartPrimitiveInProgress`
-
-### MessagePrimitive.Content renamed to MessagePrimitive.Parts
-
-The `MessagePrimitive.Content` component has been renamed to `MessagePrimitive.Parts` to better reflect its purpose of rendering message parts.
-
-```diff
--<MessagePrimitive.Content components={{ Text: MyText }} />
-+<MessagePrimitive.Parts>
-+  {({ part }) => part.type === "text" ? <MyText {...part} /> : null}
-+</MessagePrimitive.Parts>
-```
-
-### Migration
-
-To migrate your codebase automatically, use the migration codemod:
-
-```sh
-# IMPORTANT: make sure to commit all changes to git / create a backup before running the codemod
-npx assistant-ui@latest upgrade
-```
-
-Or run the specific migration:
-
-```sh
-npx assistant-ui@latest codemod v0-11/content-part-to-message-part .
-```
-
-#### Manual Migration Examples
-
-If you prefer to migrate manually, here are some examples:
-
-**Imports:**
-
-```diff
--import { TextContentPart, useContentPart, ToolCallContentPartComponent } from "@assistant-ui/react";
-+import { TextMessagePart, useMessagePart, ToolCallMessagePartComponent } from "@assistant-ui/react";
-```
-
-**Type annotations:**
-
-```diff
--function processContent(part: TextContentPart): void {
-+function processContent(part: TextMessagePart): void {
-   console.log(part.text);
- }
-
--const MyTool: ToolCallContentPartComponent = ({ toolName }) => {
-+const MyTool: ToolCallMessagePartComponent = ({ toolName }) => {
-   return <div>{toolName}</div>;
- };
-```
-
-**Hooks:**
-
-```diff
- function MyComponent() {
--  const part = useContentPart();
--  const text = useContentPartText();
--  const runtime = useContentPartRuntime();
-+  const part = useMessagePart();
-+  const text = useMessagePartText();
-+  const runtime = useMessagePartRuntime();
-   return null;
- }
-```
-
-**JSX Components:**
-
-```diff
--<ContentPartPrimitive.Text />
--<ContentPartPrimitive.Image />
-+<MessagePartPrimitive.Text />
-+<MessagePartPrimitive.Image />
-```
-
-**Providers:**
-
-```diff
--<TextContentPartProvider text="Hello" isRunning={false}>
-+<TextMessagePartProvider text="Hello" isRunning={false}>
-   <div>Content</div>
--</TextContentPartProvider>
-+</TextMessagePartProvider>
-```
-
-### Why this change?
-
-The ContentPart naming was inconsistent with the rest of the codebase, where "message parts" are used throughout. This change improves semantic clarity and makes the API more intuitive by aligning terminology across the entire library.
-
-The old ContentPart APIs have been completely removed. You must update all references to use the new MessagePart names.

package/.docs/raw/docs/migrations/v0-12.mdx

@@ -1,302 +0,0 @@
----
-title: Migration to v0.12
-description: Unified state API replaces individual context hooks.
----
-
-## Major Architecture Change: Unified State API
-
-Version 0.12 introduces a complete rewrite of the state management system with a more consistent API.
-
-## Automatic Migration
-
-We provide a codemod to automatically migrate your code:
-
-```bash
-npx assistant-ui@latest upgrade
-```
-
-This will automatically handle the hook renames and update your imports.
-
-## Breaking Changes
-
-### 1. Assistant API Hooks Renamed
-
-The core hooks have been renamed for consistency and clarity:
-
-- `useAssistantApi` → `useAui`
-- `useAssistantState` → `useAuiState`
-- `useAssistantEvent` → `useAuiEvent`
-- `AssistantIf` → `AuiIf`
-
-The variable naming convention has also changed from `api` to `aui`.
-
-#### Migration
-
-**Before:**
-
-```tsx
-import {
-  useAssistantApi,
-  useAssistantState,
-  useAssistantEvent,
-} from "@assistant-ui/react";
-
-function MyComponent() {
-  const api = useAssistantApi();
-  const isRunning = useAssistantState(({ thread }) => thread.isRunning);
-
-  useAssistantEvent("thread.run-start", () => {
-    console.log("Thread started running");
-  });
-
-  const handleSend = () => {
-    api.composer().send();
-  };
-
-  return <button onClick={handleSend}>Send</button>;
-}
-```
-
-**After:**
-
-```tsx
-import { useAui, useAuiState, useAuiEvent } from "@assistant-ui/react";
-
-function MyComponent() {
-  const aui = useAui();
-  const isRunning = useAuiState((s) => s.thread.isRunning);
-
-  useAuiEvent("thread.runStart", () => {
-    console.log("Run started");
-  });
-
-  const handleSend = () => {
-    aui.composer().send();
-  };
-
-  return <button onClick={handleSend}>Send</button>;
-}
-```
-
-**Automatic Migration:**
-
-Run the codemod to automatically update your code:
-
-```bash
-npx assistant-ui@latest upgrade
-```
-
-The codemod will:
-- Rename all hook imports (`useAssistantApi` → `useAui`, etc.)
-- Rename `const api = useAui()` declarations to `const aui = useAui()`
-- Update all references to the `api` variable throughout your codebase
-- Correctly handle scoping (won't rename `api` variables from other sources)
-
-**Backwards Compatibility:**
-
-The old names are still available as deprecated exports until v0.13:
-
-```tsx
-// Still works, but deprecated
-import {
-  useAssistantApi,
-  useAssistantState,
-  useAssistantEvent,
-} from "@assistant-ui/react";
-
-const api = useAssistantApi(); // deprecated but functional
-```
-
-### 2. Context Hooks Replaced with Unified State API
-
-All individual context hooks have been replaced with a single `useAuiState` hook and `useAui` for actions.
-
-#### What changed
-
-The following hooks have been removed:
-
-**Removed Hooks:**
-
-- `useMessageUtils` → Use `useAuiState((s) => s.message.isHovering)` / `useAuiState((s) => s.message.isCopied)`
-- `useMessageUtilsStore` → Use `useAui()` with `aui.message().setIsHovering()` / `aui.message().setIsCopied()`
-- `useToolUIs` → Removed with no direct equivalent. Use `useAssistantTool` / `makeAssistantToolUI` to register tool UIs instead.
-- `useToolUIsStore` → Removed with no direct equivalent.
-
-**Deprecated Hooks:**
-
-- `useAssistantRuntime` → Use `useAui()`
-- `useThread` → Use `useAuiState((s) => s.thread)`
-- `useThreadRuntime` → Use `useAui()` with `aui.thread()`
-- `useMessage` → Use `useAuiState((s) => s.message)`
-- `useMessageRuntime` → Use `useAui()` with `aui.message()`
-- `useComposer` → Use `useAuiState((s) => s.composer)`
-- `useComposerRuntime` → Use `useAui()` with `aui.composer()`
-- `useEditComposer` → Use `useAuiState((s) => s.message.composer)`
-- `useThreadListItem` → Use `useAuiState((s) => s.threadListItem)`
-- `useThreadListItemRuntime` → Use `useAui()` with `aui.threadListItem()`
-- `useMessagePart` → Use `useAuiState((s) => s.part)`
-- `useMessagePartRuntime` → Use `useAui()` with `aui.part()`
-- `useAttachment` → Use `useAuiState((s) => s.attachment)`
-- `useAttachmentRuntime` → Use `useAui()` with `aui.attachment()`
-- `useThreadModelContext` → Use `useAuiState((s) => s.thread.modelContext)`
-- `useThreadModelConfig` → Removed. Use `useAui().thread().getModelContext()` instead.
-- `useThreadComposer` → Use `useAuiState((s) => s.thread.composer)`
-- `useThreadList` → Use `useAuiState((s) => s.threads)`
-
-#### Migration Examples
-
-**Before:**
-
-```tsx
-import {
-  useThread,
-  useThreadRuntime,
-  useComposer,
-  useComposerRuntime,
-  useMessage,
-  useMessageRuntime,
-} from "@assistant-ui/react";
-
-function MyComponent() {
-  // Reading state
-  const messages = useThread((t) => t.messages);
-  const isRunning = useThread((t) => t.isRunning);
-  const composerText = useComposer((c) => c.text);
-  const messageRole = useMessage((m) => m.role);
-
-  // Using runtime for actions
-  const threadRuntime = useThreadRuntime();
-  const composerRuntime = useComposerRuntime();
-  const messageRuntime = useMessageRuntime();
-
-  const handleSend = () => {
-    composerRuntime.send();
-  };
-
-  const handleReload = () => {
-    messageRuntime.reload();
-  };
-
-  const handleCancel = () => {
-    threadRuntime.cancelRun();
-  };
-
-  return null;
-}
-```
-
-**After:**
-
-```tsx
-import { useAuiState, useAui } from "@assistant-ui/react";
-
-function MyComponent() {
-  // Reading state - all through single hook
-  const messages = useAuiState((s) => s.thread.messages);
-  const isRunning = useAuiState((s) => s.thread.isRunning);
-  const composerText = useAuiState((s) => s.composer.text);
-  const messageRole = useAuiState((s) => s.message.role);
-
-  // Using client for actions
-  const aui = useAui();
-
-  const handleSend = () => {
-    aui.composer().send();
-  };
-
-  const handleReload = () => {
-    aui.message().reload();
-  };
-
-  const handleCancel = () => {
-    aui.thread().cancelRun();
-  };
-
-  return null;
-}
-```
-
-### 3. Event Names Changed to camelCase
-
-Event names used with `useAuiEvent` have been standardized to use camelCase instead of kebab-case.
-
-#### What changed
-
-The following event names have been updated:
-
-| Old Name (kebab-case)               | New Name (camelCase)               |
-| ----------------------------------- | ---------------------------------- |
-| `thread.run-start`                  | `thread.runStart`                  |
-| `thread.run-end`                    | `thread.runEnd`                    |
-| `thread.model-context-update`       | `thread.modelContextUpdate`        |
-| `composer.attachment-add`           | `composer.attachmentAdd`           |
-| `thread-list-item.switched-to`      | `threadListItem.switchedTo`        |
-| `thread-list-item.switched-away`    | `threadListItem.switchedAway`      |
-
-Events that remain unchanged:
-- `thread.initialize`
-- `composer.send`
-
-#### Migration
-
-**Before:**
-
-```tsx
-import { useAuiEvent } from "@assistant-ui/react";
-
-function MyComponent() {
-  useAuiEvent("thread.run-start", () => {
-    console.log("Thread started running");
-  });
-
-  useAuiEvent("thread.run-end", () => {
-    console.log("Thread finished running");
-  });
-
-  useAuiEvent("composer.attachment-add", () => {
-    console.log("Attachment added");
-  });
-
-  return null;
-}
-```
-
-**After:**
-
-```tsx
-import { useAuiEvent } from "@assistant-ui/react";
-
-function MyComponent() {
-  useAuiEvent("thread.runStart", () => {
-    console.log("Thread started running");
-  });
-
-  useAuiEvent("thread.runEnd", () => {
-    console.log("Thread finished running");
-  });
-
-  useAuiEvent("composer.attachmentAdd", () => {
-    console.log("Attachment added");
-  });
-
-  return null;
-}
-```
-
-**Automatic Migration:**
-
-Run the codemod to automatically update event names:
-
-```bash
-npx assistant-ui@latest upgrade
-```
-
-The codemod will automatically replace all occurrences of the old kebab-case event names with their new camelCase equivalents.
-
-## Getting Help
-
-If you encounter issues during migration:
-
-1. Check the updated API documentation for detailed examples
-2. Review the example applications in the repository
-3. Report issues at https://github.com/assistant-ui/assistant-ui/issues