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

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

@@ -0,0 +1,39 @@
+---
+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>
+</Cards>

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

@@ -0,0 +1,127 @@
+---
+title: Tool Rendering
+description: Register React renderers for assistant-ui tool calls, tool results, and model data parts.
+---
+
+import { 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
+
+Registers renderers for `data` message parts.
+
+Data renderers are looked up by the part's `name` field. Use this resource
+directly for a renderer scope, or prefer [useAssistantDataUI](/docs/api-reference/tools/rendering#useassistantdataui) /
+[makeAssistantDataUI](/docs/api-reference/tools/rendering#makeassistantdataui) when registering from React components.
+
+```ts
+const DataRenderers: () => ResourceElement<ClientOutput<"dataRenderers">, undefined>;
+```
+
+### 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;
+```
+
+### 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;
+```
+
+### McpAppRenderer
+
+Creates a tool-call renderer for MCP Apps embedded in assistant messages.
+
+Compose this into the `Tools` resource through its `mcpApp` option. When a
+tool-call part carries `mcp.app` metadata for a `ui://` resource, the
+renderer loads that resource from the configured host and displays it in a
+sandboxed frame.
+
+<ParametersTable {...McpAppRenderer} />
+
+### McpAppsRemoteHost
+
+Creates the default HTTP host for MCP App widgets.
+
+The host POSTs widget requests to the configured route as `{ method,
+params }`, using the method names expected by the assistant-ui MCP Apps
+guide.
+
+<ParametersTable {...McpAppsRemoteHost} />
+
+### useAssistantDataUI
+
+Registers a renderer for named `data` message parts while the component is
+mounted.
+
+<ParametersTable {...useAssistantDataUI} />
+
+### 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

@@ -0,0 +1,42 @@
+---
+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>;
+```
+{/* api-reference:end */}

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

@@ -0,0 +1,91 @@
+---
+title: Toolkits
+description: Define model-facing tools and compose them into named toolkits registered with an assistant-ui runtime scope.
+---
+
+import { ToolDefinition, Tools, 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).
+Inference from parameter schemas is currently limited, so provide generic
+arguments when you need precise args or result types.
+
+```ts
+const getWeather = tool<{ city: string }, string>({
+  type: "frontend",
+  description: "Get the weather for a city.",
+  parameters: {
+    type: "object",
+    properties: { city: { type: "string" } },
+    required: ["city"],
+  },
+  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 = {
+  get_weather: {
+    type: "frontend",
+    description: "Get the weather for a city.",
+    parameters: weatherSchema,
+    execute: async ({ city }: { city: string }) => fetchWeather(city),
+    render: WeatherToolUI,
+  },
+} satisfies Toolkit;
+```
+
+```ts
+type Toolkit = Record<string, ToolDefinition<any, any>>;
+```
+
+### Tools
+
+Registers tools with model context and installs tool-call renderers.
+
+Mount this resource near an assistant subtree when you want to expose a
+group of tools declaratively. Tool definitions are registered with model
+context, while each tool renderer is registered with the tools scope for
+message rendering.
+
+<ParametersTable {...Tools} />
+{/* api-reference:end */}

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

@@ -0,0 +1,48 @@
+---
+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 */}

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

@@ -0,0 +1,62 @@
+---
+title: Assistant Frame
+description: Frame bridge APIs and serialized message types for embedding assistant-ui runtimes in external contexts.
+---
+
+import { AssistantFrameHost, AssistantFrameProvider, FrameMessage, SerializedModelContext, SerializedTool, useAssistantFrameHost } 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
+
+### AssistantFrameHost
+
+<ParametersTable {...AssistantFrameHost} />
+
+### AssistantFrameProvider
+
+<ParametersTable {...AssistantFrameProvider} />
+
+### FRAME_MESSAGE_CHANNEL
+
+```ts
+const FRAME_MESSAGE_CHANNEL: "assistant-ui-frame";
+```
+
+### FrameMessage
+
+<ParametersTable {...FrameMessage} />
+
+### SerializedModelContext
+
+<ParametersTable {...SerializedModelContext} />
+
+### SerializedTool
+
+<ParametersTable {...SerializedTool} />
+
+### useAssistantFrameHost
+
+React hook that manages the lifecycle of an AssistantFrameHost and its binding to the current AssistantRuntime.
+
+Usage example:
+```typescript
+function MyComponent() {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+
+  useAssistantFrameHost({
+    iframeRef,
+    targetOrigin: "https://trusted-domain.com", // optional
+  });
+
+  return <iframe ref={iframeRef} src="..." />;
+}
+```
+
+<ParametersTable {...useAssistantFrameHost} />
+{/* api-reference:end */}

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

@@ -0,0 +1,22 @@
+---
+title: Transport API Reference
+description: Transport commands, frame messages, and protocol types for synchronizing assistant-ui runtimes across process or iframe boundaries.
+---
+
+{/* 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 */}
+Transport APIs are for runtimes that cross a network, worker, iframe, or other execution boundary. They document the command and frame contracts that keep assistant-ui state synchronized with an external process.
+{/* api-manual:end */}
+
+## Pages
+
+<Cards>
+  <Card title={"Assistant Transport"} href={"/docs/api-reference/transport/assistant-transport"}>
+    {"Command, protocol, and transport types for connecting assistant-ui runtimes across execution boundaries."}
+  </Card>
+  <Card title={"Assistant Frame"} href={"/docs/api-reference/transport/frame"}>
+    {"Frame bridge APIs and serialized message types for embedding assistant-ui runtimes in external contexts."}
+  </Card>
+</Cards>

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

@@ -0,0 +1,19 @@
+---
+title: Utilities API Reference
+description: Utility exports for custom rendering, composition, and advanced assistant-ui behavior that does not fit a larger API family.
+---
+
+{/* 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 */}
+Utilities collect small public exports that are useful when building custom assistant-ui components but do not belong to a larger feature area. Start here when you recognize an export name but not its surrounding API family.
+{/* api-manual:end */}
+
+## Pages
+
+<Cards>
+  <Card title={"Utilities"} href={"/docs/api-reference/utilities/miscellaneous"}>
+    {"Miscellaneous @assistant-ui/react utilities for custom rendering, composition, and advanced assistant UI behavior."}
+  </Card>
+</Cards>

package/.docs/raw/docs/(reference)/api-reference/utilities/miscellaneous.mdx

@@ -0,0 +1,143 @@
+---
+title: Utilities
+description: Miscellaneous @assistant-ui/react utilities for custom rendering, composition, and advanced assistant UI behavior.
+---
+
+import { AssistantCloud, ChainOfThoughtClient, DevToolsHooks, InMemoryThreadList, SingleThreadList, defineMcpToolkit, defineToolkit, providerTool } 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
+
+### AssistantCloud
+
+<ParametersTable {...AssistantCloud} />
+
+### ChainOfThoughtClient
+
+<ParametersTable {...ChainOfThoughtClient} />
+
+### defineMcpToolkit
+
+Defines MCP server tools as a spreadable toolkit fragment.
+
+<ParametersTable {...defineMcpToolkit} />
+
+### defineToolkit
+
+Authoring helper for a `"use generative"` toolkit. Accepts the permissive
+ToolkitDefinition (a `backend` tool may carry its server `execute`)
+and types the result as the canonical [Toolkit](/docs/api-reference/tools/toolkits#toolkit).
+
+It has **no runtime implementation**. A `"use generative"` compiler (e.g.
+`@assistant-ui/next` or `@assistant-ui/vite`) strips the `defineToolkit(...)`
+wrapper (and its import) per build, so a correctly compiled
+`export default defineToolkit({...})` never calls this. If it *does* run, the
+module was not compiled by a use-generative loader — e.g. `defineToolkit` used
+outside a `"use generative"` file — which would ship a backend `execute` to the
+client. So it throws instead of silently leaking.
+
+<ParametersTable {...defineToolkit} />
+
+### DevToolsHooks
+
+<ParametersTable {...DevToolsHooks} />
+
+### hitl
+
+<Callout type="warn">
+<strong>Deprecated.</strong> Use [hitlTool](/docs/api-reference/utilities/miscellaneous#hitltool).
+</Callout>
+
+```ts
+const hitl: typeof hitlTool;
+```
+
+### hitlTool
+
+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: hitlTool(), render: (props) => <Confirm {...props} /> }
+```
+
+Like [defineToolkit](/docs/api-reference/utilities/miscellaneous#definetoolkit), it has **no runtime implementation**: a
+`"use generative"` compiler (e.g. `@assistant-ui/next` or `@assistant-ui/vite`)
+detects `execute: hitlTool()`, 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 hitlTool(): never;
+```
+
+### InMemoryThreadList
+
+<ParametersTable {...InMemoryThreadList} />
+
+### Interactables
+
+```ts
+const Interactables: () => ResourceElement<ClientOutput<"interactables">, undefined>;
+```
+
+### providerTool
+
+Marks a tool as provider-executed. The use-generative compiler converts
+`execute: providerTool(...)` into a `type: "provider"` tool entry.
+
+<ParametersTable {...providerTool} />
+
+### SingleThreadList
+
+A minimal threads scope that wraps a single thread.
+Automatically provided by ExternalThread when no threads scope exists.
+Mounts the provided thread resource element.
+
+<ParametersTable {...SingleThreadList} />
+
+### 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;
+```
+
+### Suggestions
+
+```ts
+const Suggestions: {
+  (): ResourceElement<
+    ClientOutput<"suggestions">,
+    undefined
+  >;
+  (
+    suggestions: SuggestionConfig[],
+  ): ResourceElement<
+    ClientOutput<"suggestions">,
+    SuggestionConfig[]
+  >;
+};
+```
+
+### unstable_defaultDirectiveFormatter
+
+Default directive formatter using the `:type[label]{name=id}` syntax.
+
+When `id` equals `label`, the `{name=…}` attribute is omitted for brevity.
+
+```ts
+const unstable_defaultDirectiveFormatter: Unstable_DirectiveFormatter;
+```
+{/* api-reference:end */}

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

@@ -0,0 +1,22 @@
+---
+title: Voice API Reference
+description: Realtime voice, speech synthesis, and dictation contracts for wiring spoken assistant flows into React chat UIs.
+---
+
+{/* 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 */}
+Voice APIs cover the state and adapters needed for spoken assistant experiences. Use this section when connecting realtime voice sessions, speech synthesis controls, or dictation input to an assistant-ui runtime.
+{/* api-manual:end */}
+
+## Pages
+
+<Cards>
+  <Card title={"Voice Sessions"} href={"/docs/api-reference/voice/session"}>
+    {"Create and control realtime assistant-ui voice sessions, state, controls, and helpers."}
+  </Card>
+  <Card title={"Speech and Dictation"} href={"/docs/api-reference/voice/speech-dictation"}>
+    {"Connect speech synthesis and dictation adapters to assistant-ui voice and composer workflows."}
+  </Card>
+</Cards>

package/.docs/raw/docs/(reference)/api-reference/voice/session.mdx

@@ -0,0 +1,54 @@
+---
+title: Voice Sessions
+description: Create and control realtime assistant-ui voice sessions, state, controls, and helpers.
+---
+
+import { RealtimeVoiceAdapter, VoiceSessionControls, VoiceSessionHelpers, VoiceSessionState, createVoiceSession } 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
+
+### createVoiceSession
+
+<ParametersTable {...createVoiceSession} />
+
+### RealtimeVoiceAdapter
+
+<ParametersTable {...RealtimeVoiceAdapter} />
+
+### useVoiceControls
+
+```ts
+const useVoiceControls: () => { connect: () => void; disconnect: () => void; mute: () => void; unmute: () => void; };
+```
+
+### useVoiceState
+
+```ts
+const useVoiceState: () => VoiceSessionState;
+```
+
+### useVoiceVolume
+
+```ts
+const useVoiceVolume: () => number;
+```
+
+### VoiceSessionControls
+
+<ParametersTable {...VoiceSessionControls} />
+
+### VoiceSessionHelpers
+
+<ParametersTable {...VoiceSessionHelpers} />
+
+### VoiceSessionState
+
+<ParametersTable {...VoiceSessionState} />
+{/* api-reference:end */}