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

package/.docs/raw/docs/(reference)/api-reference/tools/index.mdx

@@ -1,45 +0,0 @@
----
-title: Tools API Reference
-description: Tool definitions, React renderers, status helpers, and toolkits for exposing callable app capabilities to assistant-ui chat models.
----
-
-{/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
-{/* The page list is generated from exported APIs; edit only the manual prose slot. */}
-
-{/* api-manual:start */}
-Use these APIs when your assistant needs to call application code, render a custom tool result, or expose tool state inside a React UI.
-
-Toolkits are the current registration API. Tool **rendering** and **status** are independent of the tool's execution location and apply to frontend, backend, human, and MCP tools.
-
-| | `Tools({ toolkit })` |
-| --- | --- |
-| Scope | Entire assistant subtree below the mount point |
-| Lifecycle | Tied to the runtime / provider tree |
-| Typical use | App-wide tools, dynamic scoped tools, MCP merging, tools defined alongside the runtime |
-| Stable reference | Pass a stable `toolkit` (module scope or `useMemo`) |
-
-`useAssistantTool`, `makeAssistantTool`, `useAssistantToolUI`, and `makeAssistantToolUI` are deprecated compatibility APIs. See [Migrating Tools to Toolkits](/docs/migrations/toolkit-tools).
-{/* api-manual:end */}
-
-## Pages
-
-<Cards>
-  <Card title={"Toolkits"} href={"/docs/api-reference/tools/toolkits"}>
-    {"Define model-facing tools and compose them into named toolkits registered with an assistant-ui runtime scope."}
-  </Card>
-  <Card title={"Component Tools"} href={"/docs/api-reference/tools/component-tools"}>
-    {"Register assistant tools from mounted React components, scoped to the lifetime of part of the UI tree."}
-  </Card>
-  <Card title={"Tool Rendering"} href={"/docs/api-reference/tools/rendering"}>
-    {"Register React renderers for assistant-ui tool calls, tool results, and model data parts."}
-  </Card>
-  <Card title={"Tool Status"} href={"/docs/api-reference/tools/status"}>
-    {"Read tool arguments, execution status, and result state inside assistant-ui tool UI components."}
-  </Card>
-  <Card title={"Interactables"} href={"/docs/api-reference/tools/interactables"}>
-    {"Unstable interactables APIs for model-editable app and message state, including hooks, resources, toolkit helpers, and snapshot utilities."}
-  </Card>
-  <Card title={"Interactables (legacy)"} href={"/docs/api-reference/tools/interactables-legacy"}>
-    {"Deprecated legacy interactables APIs for registering model-editable components with per-instance update tools."}
-  </Card>
-</Cards>

package/.docs/raw/docs/(reference)/api-reference/tools/interactables-legacy.mdx

@@ -1,55 +0,0 @@
----
-title: Interactables (legacy)
-description: Deprecated legacy interactables APIs for registering model-editable components with per-instance update tools.
----
-
-import { Interactables, useAssistantInteractable, useInteractableState } from "@/generated/typeDocs";
-
-{/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
-{/* Do not edit manually. */}
-
-{/* api-reference:start */}
-{/* AUTO-GENERATED by scripts/generate-api-reference.mts */}
-{/* Do not edit this block manually. */}
-
-## API Reference
-
-### Interactables
-
-<Callout type="warn">
-<strong>Deprecated.</strong> Since 2026-06-14 — migrate to the Unstable / Experimental API.
-Scheduled for removal on/after 2026-09-14. See
-[Interactables migration guide](https://www.assistant-ui.com/docs/tools/interactables#migrating-from-the-previous-api).
-</Callout>
-
-<ParametersTable {...Interactables} />
-
-### useAssistantInteractable
-
-<Callout type="warn">
-<strong>Deprecated.</strong> Since 2026-06-14 — migrate to the Unstable / Experimental API.
-Scheduled for removal on/after 2026-09-14. See
-[Interactables migration guide](https://www.assistant-ui.com/docs/tools/interactables#migrating-from-the-previous-api).
-</Callout>
-
-Registers an interactable with the AI assistant.
-
-This hook handles registration only. To read and write the interactable's
-state, use [useInteractableState](/docs/api-reference/tools/interactables-legacy#useinteractablestate) with the returned id.
-
-<ParametersTable {...useAssistantInteractable} />
-
-### useInteractableState
-
-<Callout type="warn">
-<strong>Deprecated.</strong> Since 2026-06-14 — migrate to the Unstable / Experimental API.
-Scheduled for removal on/after 2026-09-14. See
-[Interactables migration guide](https://www.assistant-ui.com/docs/tools/interactables#migrating-from-the-previous-api).
-</Callout>
-
-Reads and writes the state of a registered interactable.
-
-Pair with [useAssistantInteractable](/docs/api-reference/tools/interactables-legacy#useassistantinteractable) which handles registration.
-
-<ParametersTable {...useInteractableState} />
-{/* api-reference:end */}

package/.docs/raw/docs/(reference)/api-reference/tools/interactables.mdx

@@ -1,151 +0,0 @@
----
-title: Interactables
-description: Unstable interactables APIs for model-editable app and message state, including hooks, resources, toolkit helpers, and snapshot utilities.
----
-
-import { unstable_formatInteractableSnapshot, unstable_getInteractableSnapshots, unstable_getInteractableVersions, unstable_useInteractable, unstable_useInteractableState, unstable_useInteractableVersions } from "@/generated/typeDocs";
-
-{/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
-{/* Do not edit manually. */}
-
-{/* api-reference:start */}
-{/* AUTO-GENERATED by scripts/generate-api-reference.mts */}
-{/* Do not edit this block manually. */}
-
-## API Reference
-
-### unstable_Interactables
-
-<Callout type="tip">
-<strong>Experimental.</strong> Unstable / Experimental (not actually removed).
-</Callout>
-
-Registers the unstable interactables store scope.
-
-```ts
-const unstable_Interactables: Resource<ClientOutput<"unstable_interactables">, [(Unstable_InteractablesConfig | undefined)?]>;
-```
-
-### unstable_useInteractable
-
-<Callout type="tip">
-<strong>Experimental.</strong> Unstable / Experimental (not actually removed).
-</Callout>
-
-Registers an interactable with the AI assistant and returns its live state,
-like `useState` that the model can also read and update.
-
-Call this once per place that shows the interactable. Other components can
-read and write the same instance by passing its `id` to
-`unstable_useInteractableState`.
-
-For tool-created interactables rendered inside tool-call message parts,
-`version` carries this message's version of the instance — its state as of
-that point in the conversation, whether it is the most recent tool-driven
-version, and a `restore()` back to it. Whether older messages render frozen history or stay
-live-editable is the component's choice. Inside an `update_{name}` part the
-instance `id` is inferred from the call, so the same component works at the
-creating call and at update calls.
-
-<ParametersTable {...unstable_useInteractable} />
-
-### unstable_useInteractableState
-
-<Callout type="tip">
-<strong>Experimental.</strong> Unstable / Experimental (not actually removed).
-</Callout>
-
-Reads and writes the state of an interactable registered elsewhere, by id.
-
-Use this from secondary readers (children, siblings); the owning component
-registers with `unstable_useInteractable`, which returns state directly. Returns
-`undefined` until the owning interactable is registered.
-
-<ParametersTable {...unstable_useInteractableState} />
-
-### unstable_useInteractableVersions
-
-<Callout type="tip">
-<strong>Experimental.</strong> Unstable / Experimental (not actually removed).
-</Callout>
-
-Every version of a tool-created interactable recorded in the current
-thread, oldest first: the creating tool call, each user edit, and each
-`update_*` call. Each entry carries the full state as of that version and a
-`restore()` that sets the live instance back to it — enough for a version
-picker like an artifact's history dropdown.
-
-<ParametersTable {...unstable_useInteractableVersions} />
-
-### unstable_interactableTool
-
-<Callout type="tip">
-<strong>Experimental.</strong> Unstable / Experimental (not actually removed).
-</Callout>
-
-Defines a tool that creates a thread-scoped interactable from its arguments,
-for assignment to a toolkit entry — the entry key is the interactable name:
-
-```tsx
-notepad: unstable_interactableTool({
-  description: "A notepad the user can read and edit.",
-  stateSchema: notepadSchema,
-  render: (props) => <Notepad {...props} />,
-}),
-```
-
-`render` shows at the creating call and — installed automatically — at every
-`update_{name}` call, with streaming previews, instance-id wiring, and
-registration handled. It receives the live `state`/`setState` plus this
-message's `version`; whether older messages render frozen history or stay
-live-editable is the render function's choice.
-
-```ts
-const unstable_interactableTool: <TSchema extends Unstable_InteractableStateSchema>(config: Unstable_InteractableToolConfig<TSchema>) => ToolDefinition<Record<string, unknown>, { success: true; }>;
-```
-
-### unstable_getInteractableSnapshots
-
-<Callout type="tip">
-<strong>Experimental.</strong> Unstable / Experimental (not actually removed).
-</Callout>
-
-Reads the interactable snapshots stamped on a message's
-`metadata.custom.interactables`, or `undefined` if none. This is the read
-half of the snapshot channel — integrations use it to surface interactable
-state to the model (see `unstable_injectInteractableContext` in
-`@assistant-ui/ai-sdk` for the AI SDK implementation).
-
-<ParametersTable {...unstable_getInteractableSnapshots} />
-
-### unstable_formatInteractableSnapshot
-
-<Callout type="tip">
-<strong>Experimental.</strong> Unstable / Experimental (not actually removed).
-</Callout>
-
-Canonical model-facing wording for one snapshot entry.
-
-<ParametersTable {...unstable_formatInteractableSnapshot} />
-
-### unstable_getInteractableVersions
-
-<Callout type="tip">
-<strong>Experimental.</strong> Unstable / Experimental (not actually removed).
-</Callout>
-
-Every version of interactable `id` recorded in the thread, oldest first,
-folded chronologically:
-
-- the tool call whose `toolCallId` equals `id` seeds the baseline with its
-  args (`origin: "create"`) — the `id: toolCallId` convention for
-  tool-created interactables,
-- a snapshot stamped on a user message is a `"user-edit"` version (a full
-  snapshot replaces the state; a partial one shallow-merges),
-- each accepted `update_*` call shallow-merges an `"update"` version.
-
-The last entry is the state the model knows. Partial snapshots and update
-calls with no baseline to merge into are skipped.
-
-<ParametersTable {...unstable_getInteractableVersions} />
-{/* api-reference:end */}

package/.docs/raw/docs/(reference)/api-reference/tools/rendering.mdx

@@ -1,106 +0,0 @@
----
-title: Tool Rendering
-description: Register React renderers for assistant-ui tool calls, tool results, and model data parts.
----
-
-import { DataRenderers, McpAppRenderer, McpAppsRemoteHost, getMcpAppFromToolPart, useAssistantDataUI, useAssistantToolUI } from "@/generated/typeDocs";
-
-{/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
-{/* Do not edit manually. */}
-
-{/* api-reference:start */}
-{/* AUTO-GENERATED by scripts/generate-api-reference.mts */}
-{/* Do not edit this block manually. */}
-
-## API Reference
-
-### DataRenderers
-
-<ParametersTable {...DataRenderers} />
-
-### getMcpAppFromToolPart
-
-Returns MCP app metadata for a tool-call part that points at a `ui://`
-resource.
-
-Returns `undefined` when the part has no MCP app metadata or the metadata
-does not reference an assistant-ui MCP app resource.
-
-<ParametersTable {...getMcpAppFromToolPart} />
-
-### makeAssistantDataUI
-
-Creates a React component that registers a named data-part renderer when
-rendered.
-
-```ts
-type AssistantDataUIProps = {
-  /** Data part name this renderer handles. */
-  name: string;
-  /** Component rendered for matching data message parts. */
-  render: DataMessagePartComponent<T>;
-};
-
-const makeAssistantDataUI: <T = any>(dataUI: AssistantDataUIProps<T>) => AssistantDataUI;
-```
-
-### McpAppRenderer
-
-<ParametersTable {...McpAppRenderer} />
-
-### McpAppsRemoteHost
-
-<ParametersTable {...McpAppsRemoteHost} />
-
-### useAssistantDataUI
-
-Registers a renderer for named `data` message parts while the component is
-mounted.
-
-<ParametersTable {...useAssistantDataUI} />
-
-### makeAssistantToolUI
-
-<Callout type="warn">
-<strong>Deprecated.</strong> Put `render`/`renderText` on the matching toolkit entry, or use
-`MessagePrimitive.Parts` inline tool render overrides for per-message UI.
-See https://assistant-ui.com/docs/migrations/toolkit-tools.
-</Callout>
-
-Creates a React component that registers a tool-call renderer when rendered.
-
-Use this to package reusable display components for tools whose definitions
-are registered elsewhere.
-
-```ts
-type AssistantToolUIProps = {
-  /** Name of the tool whose calls should use this renderer. */
-  toolName: string;
-  /** Component rendered for matching tool-call message parts. */
-  render: ToolCallMessagePartComponent<TArgs, TResult>;
-  /**
-   * How the UI is presented relative to the chain-of-thought trace. Set
-   * `"standalone"` to surface it on its own (e.g. human-in-the-loop or
-   * generative UI for a backend/MCP tool). Defaults to `"inline"`.
-   */
-  display?: "standalone" | "inline";
-};
-
-const makeAssistantToolUI: <TArgs, TResult>(tool: AssistantToolUIProps<TArgs, TResult>) => AssistantToolUI;
-```
-
-### useAssistantToolUI
-
-<Callout type="warn">
-<strong>Deprecated.</strong> Put `render`/`renderText` on the matching toolkit entry, or use
-`MessagePrimitive.Parts` inline tool render overrides for per-message UI.
-See https://assistant-ui.com/docs/migrations/toolkit-tools.
-</Callout>
-
-Registers a tool-call renderer while the component is mounted.
-
-This only affects rendering. Pair it with [Tools](/docs/api-reference/tools/toolkits#tools) or a backend tool
-registry to expose the actual tool definition to the model.
-
-<ParametersTable {...useAssistantToolUI} />
-{/* api-reference:end */}

package/.docs/raw/docs/(reference)/api-reference/tools/status.mdx

@@ -1,62 +0,0 @@
----
-title: Tool Status
-description: Read tool arguments, execution status, and result state inside assistant-ui tool UI components.
----
-
-{/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
-{/* Do not edit manually. */}
-
-{/* api-reference:start */}
-{/* AUTO-GENERATED by scripts/generate-api-reference.mts */}
-{/* Do not edit this block manually. */}
-
-## API Reference
-
-### useToolArgsStatus
-
-Reads whether each argument field for the current tool-call message part is
-still streaming or complete.
-
-Use inside a tool-call renderer to avoid showing incomplete argument values
-as final.
-
-```tsx
-function WeatherToolUI({
-  args,
-}: ToolCallMessagePartProps<{ city: string }>) {
-  const { propStatus } = useToolArgsStatus<{ city: string }>();
-
-  return (
-    <span>
-      {propStatus.city === "streaming" ? "Reading city..." : args.city}
-    </span>
-  );
-}
-```
-
-```ts
-const useToolArgsStatus: <TArgs extends Record<string, unknown> = Record<string, unknown>>() => ToolArgsStatus<TArgs>;
-```
-
-### useToolCallElapsed
-
-Hook that returns the elapsed wall-clock time of the current tool call in
-milliseconds, ticking once per second while the call runs.
-
-Reads `part.timing`. Returns `undefined` when the part is not a tool call,
-carries no timing, ended without a recorded completion (the duration is
-unknown), or when no message part scope is available (so kit components
-stay renderable standalone, e.g. in docs previews).
-
-```tsx
-function ToolDuration() {
-  const elapsedMs = useToolCallElapsed();
-  if (elapsedMs === undefined) return null;
-  return <span>{(elapsedMs / 1000).toFixed(1)}s</span>;
-}
-```
-
-```ts
-const useToolCallElapsed: () => number | undefined;
-```
-{/* api-reference:end */}

package/.docs/raw/docs/(reference)/api-reference/tools/toolkits.mdx

@@ -1,178 +0,0 @@
----
-title: Toolkits
-description: Define model-facing tools and compose them into named toolkits registered with an assistant-ui runtime scope.
----
-
-import { ToolDefinition, Tools, defineMcpToolkit, defineToolkit, providerTool, tool } from "@/generated/typeDocs";
-
-{/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
-{/* Do not edit manually. */}
-
-{/* api-manual:start */}
-A `Toolkit` is a named map of model-facing tool definitions. The `Tools` resource installs a toolkit into an assistant subtree, registering each tool with the model context and each `render` component with the tool-call renderer scope.
-
-Use these APIs when you want a tool's availability to follow your runtime or provider tree. The older component-scoped registration APIs are deprecated; see [Migrating Tools to Toolkits](/docs/migrations/toolkit-tools).
-{/* api-manual:end */}
-
-{/* api-reference:start */}
-{/* AUTO-GENERATED by scripts/generate-api-reference.mts */}
-{/* Do not edit this block manually. */}
-
-## API Reference
-
-### tool
-
-Defines a model tool with its argument schema, execution behavior, and
-optional model-output conversion.
-
-This helper keeps reusable tool definitions type-checked and convenient to
-export for a [Toolkit](/docs/api-reference/tools/toolkits#toolkit) registered with [Tools](/docs/api-reference/tools/toolkits#tools).
-When `parameters` is a Standard Schema (for example Zod v4), its input type
-is inferred for `execute`, `streamCall`, and model-output callbacks. Plain
-JSON Schema objects do not carry TypeScript input types, so provide generic
-arguments or annotate callbacks when you need precise args for JSON Schema.
-
-```ts
-import { z } from "zod";
-
-const getWeather = tool({
-  type: "frontend",
-  description: "Get the weather for a city.",
-  parameters: z.object({ city: z.string() }),
-  execute: async ({ city }) => `Sunny in ${city}`,
-});
-```
-
-<ParametersTable {...tool} />
-
-### ToolDefinition
-
-Tool definition accepted by the React tool registry.
-
-Extends the core tool contract with tool-call display options. Human tools
-rely on `render` to collect input from the user. Frontend tools execute in
-the browser and require either `render` or `renderText` for their progress
-and result. Backend tools execute server-side and may omit a renderer.
-
-<ParametersTable {...ToolDefinition} />
-
-### Toolkit
-
-Named collection of tools exposed to the assistant model.
-
-Keys are the tool names the model receives and uses in tool calls.
-
-```tsx
-const toolkit = defineToolkit({
-  get_weather: {
-    type: "frontend",
-    description: "Get the weather for a city.",
-    parameters: weatherSchema,
-    execute: async ({ city }: { city: string }) => fetchWeather(city),
-    render: WeatherToolUI,
-  },
-});
-```
-
-```ts
-type Toolkit = Record<string, ToolDefinition<any, any>>;
-```
-
-### Tools
-
-<ParametersTable {...Tools} />
-
-### defineMcpToolkit
-
-Defines MCP server tools as a spreadable toolkit fragment. Pass a raw
-`McpServerConfig` for always-on servers, or `{ server, disabled, tools }`
-when a server should stay configured but not expose all tools for the current
-request.
-
-<ParametersTable {...defineMcpToolkit} />
-
-### defineToolkit
-
-Toolkit authoring helper. Accepts the permissive ToolkitDefinition
-(a generative `backend` tool may carry its server `execute`) and types the
-result as the canonical [Toolkit](/docs/api-reference/tools/toolkits#toolkit).
-
-In a `"use generative"` file, the compiler strips the wrapper per build so it
-can split schemas, renderers, and executors across the client/server boundary.
-Outside generative compilation, it returns the toolkit unchanged and can be
-used for plain frontend/backend/human toolkit objects.
-
-<ParametersTable {...defineToolkit} />
-
-### externalTool
-
-Marks a generative toolkit entry as an externally executed backend tool.
-
-Use this when another system (for example a backend route or LangGraph node)
-already defines and executes the tool, but assistant-ui should render its
-tool calls. The use-generative compiler omits `execute: externalTool()`
-entries from the server build and keeps a `type: "backend"` renderer on the
-client build.
-
-```ts
-function externalTool(): never;
-```
-
-### humanTool
-
-Marks a tool as **human-in-the-loop**: the agent pauses and the UI (`render`)
-supplies the result instead of code. Use it as the tool's `execute`:
-
-```tsx
-confirm: { execute: humanTool(), render: (props) => <Confirm {...props} /> }
-```
-
-Unlike [defineToolkit](/docs/api-reference/tools/toolkits#definetoolkit), it has **no runtime implementation**: a
-`"use generative"` compiler (e.g. `@assistant-ui/next` or `@assistant-ui/vite`)
-detects `execute: humanTool()`, drops it, and stamps the tool `type: "human"`.
-Reaching it at runtime means the module wasn't compiled (used outside a
-`"use generative"` file), so it throws.
-
-```ts
-function humanTool(): never;
-```
-
-### providerTool
-
-Marks a tool as provider-executed. The use-generative compiler converts
-`execute: providerTool(...)` into a `type: "provider"` tool entry.
-
-<ParametersTable {...providerTool} />
-
-### stubTool
-
-Marks a generative toolkit entry as a frontend tool whose executor will be
-supplied by `useAuiToolOverrides(...)`.
-
-`stubTool()` has no runtime implementation. It must be used inside a
-`"use generative"` toolkit file so the compiler can strip it.
-
-```ts
-function stubTool(): never;
-```
-
-### hitl
-
-<Callout type="warn">
-<strong>Deprecated.</strong> Use [humanTool](/docs/api-reference/tools/toolkits#humantool).
-</Callout>
-
-```ts
-const hitl: typeof humanTool;
-```
-
-### hitlTool
-
-<Callout type="warn">
-<strong>Deprecated.</strong> Use [humanTool](/docs/api-reference/tools/toolkits#humantool).
-</Callout>
-
-```ts
-const hitlTool: typeof humanTool;
-```
-{/* api-reference:end */}

package/.docs/raw/docs/(reference)/api-reference/transport/assistant-transport.mdx

@@ -1,48 +0,0 @@
----
-title: Assistant Transport
-description: Command, protocol, and transport types for connecting assistant-ui runtimes across execution boundaries.
----
-
-import { AssistantTransportCommand, AssistantTransportConnectionMetadata, AssistantTransportProtocol, SendCommandsRequestBody, useAssistantTransportRuntime } from "@/generated/typeDocs";
-
-{/* AUTO-GENERATED PAGE by scripts/generate-api-reference.mts */}
-{/* Do not edit manually. */}
-
-{/* api-reference:start */}
-{/* AUTO-GENERATED by scripts/generate-api-reference.mts */}
-{/* Do not edit this block manually. */}
-
-## API Reference
-
-### AssistantTransportCommand
-
-<ParametersTable {...AssistantTransportCommand} />
-
-### AssistantTransportConnectionMetadata
-
-<ParametersTable {...AssistantTransportConnectionMetadata} />
-
-### AssistantTransportProtocol
-
-<ParametersTable {...AssistantTransportProtocol} />
-
-### SendCommandsRequestBody
-
-<ParametersTable {...SendCommandsRequestBody} />
-
-### useAssistantTransportRuntime
-
-<ParametersTable {...useAssistantTransportRuntime} />
-
-### useAssistantTransportSendCommand
-
-```ts
-const useAssistantTransportSendCommand: () => (command: AssistantTransportCommand) => void;
-```
-
-### useAssistantTransportState
-
-```ts
-function useAssistantTransportState(): UserExternalState;
-```
-{/* api-reference:end */}