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

package/.docs/raw/docs/react-native/custom-backend.mdx

@@ -1,207 +0,0 @@
----
-title: Custom Backend
-description: Connect your React Native app to your own backend API.
----
-
-By default, `useLocalRuntime` manages threads and messages on-device. You can connect to your own backend in two ways depending on your needs.
-
-## Option 1: ChatModelAdapter only
-
-The simplest approach — keep thread management local, but send messages to your backend for inference.
-
-```tsx title="adapters/my-chat-adapter.ts"
-import type { ChatModelAdapter } from "@assistant-ui/react-native";
-
-export const myChatAdapter: ChatModelAdapter = {
-  async *run({ messages, abortSignal }) {
-    const response = await fetch("https://my-api.com/chat", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ messages }),
-      signal: abortSignal,
-    });
-
-    const reader = response.body?.getReader();
-    if (!reader) throw new Error("No response body");
-
-    const decoder = new TextDecoder();
-    let fullText = "";
-
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-
-      const chunk = decoder.decode(value, { stream: true });
-      fullText += chunk;
-      yield { content: [{ type: "text", text: fullText }] };
-    }
-  },
-};
-```
-
-```tsx title="hooks/use-app-runtime.ts"
-import { useLocalRuntime } from "@assistant-ui/react-native";
-import { myChatAdapter } from "@/adapters/my-chat-adapter";
-
-export function useAppRuntime() {
-  return useLocalRuntime(myChatAdapter);
-}
-```
-
-This gives you:
-
-- Streaming chat responses from your API
-- In-memory thread and message management
-- Automatic features like message editing, reloading, and branch switching
-
-## Option 2: Full backend thread management
-
-When you want your backend to own thread state (e.g. for cross-device sync, team sharing, or server-side history), implement a `RemoteThreadListAdapter`.
-
-<Steps>
-  <Step>
-
-### Implement the adapter
-
-```tsx title="adapters/my-thread-list-adapter.ts"
-import type { RemoteThreadListAdapter } from "@assistant-ui/react-native";
-import { createAssistantStream } from "assistant-stream";
-
-const API_BASE = "https://my-api.com";
-
-export const myThreadListAdapter: RemoteThreadListAdapter = {
-  async list() {
-    const res = await fetch(`${API_BASE}/threads`);
-    const threads = await res.json();
-    return {
-      threads: threads.map((t: any) => ({
-        remoteId: t.id,
-        status: t.archived ? "archived" : "regular",
-        title: t.title,
-      })),
-    };
-  },
-
-  async initialize(localId) {
-    const res = await fetch(`${API_BASE}/threads`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ localId }),
-    });
-    const { id } = await res.json();
-    return { remoteId: id, externalId: undefined };
-  },
-
-  async rename(remoteId, title) {
-    await fetch(`${API_BASE}/threads/${remoteId}`, {
-      method: "PATCH",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ title }),
-    });
-  },
-
-  async archive(remoteId) {
-    await fetch(`${API_BASE}/threads/${remoteId}/archive`, {
-      method: "POST",
-    });
-  },
-
-  async unarchive(remoteId) {
-    await fetch(`${API_BASE}/threads/${remoteId}/unarchive`, {
-      method: "POST",
-    });
-  },
-
-  async delete(remoteId) {
-    await fetch(`${API_BASE}/threads/${remoteId}`, { method: "DELETE" });
-  },
-
-  async fetch(remoteId) {
-    const res = await fetch(`${API_BASE}/threads/${remoteId}`);
-    const t = await res.json();
-    return {
-      remoteId: t.id,
-      status: t.archived ? "archived" : "regular",
-      title: t.title,
-    };
-  },
-
-  async generateTitle(remoteId, unstable_messages) {
-    return createAssistantStream(async (controller) => {
-      const res = await fetch(`${API_BASE}/threads/${remoteId}/title`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ messages: unstable_messages }),
-      });
-      const { title } = await res.json();
-      controller.appendText(title);
-    });
-  },
-};
-```
-
-  </Step>
-  <Step>
-
-### Compose the runtime
-
-```tsx title="hooks/use-app-runtime.ts"
-import {
-  useLocalRuntime,
-  useRemoteThreadListRuntime,
-} from "@assistant-ui/react-native";
-import { myChatAdapter } from "@/adapters/my-chat-adapter";
-import { myThreadListAdapter } from "@/adapters/my-thread-list-adapter";
-
-export function useAppRuntime() {
-  return useRemoteThreadListRuntime({
-    runtimeHook: () => useLocalRuntime(myChatAdapter),
-    adapter: myThreadListAdapter,
-  });
-}
-```
-
-  </Step>
-  <Step>
-
-### Use in your app
-
-```tsx title="app/index.tsx"
-import { AssistantRuntimeProvider } from "@assistant-ui/react-native";
-import { useAppRuntime } from "@/hooks/use-app-runtime";
-
-export default function App() {
-  const runtime = useAppRuntime();
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {/* your chat UI */}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-  </Step>
-</Steps>
-
-## Adapter methods
-
-| Method | Description |
-|--------|-------------|
-| `list()` | Return all threads on mount |
-| `initialize(localId)` | Create a thread server-side, return `{ remoteId }` |
-| `rename(remoteId, title)` | Persist title changes |
-| `archive(remoteId)` | Mark thread as archived |
-| `unarchive(remoteId)` | Restore archived thread |
-| `delete(remoteId)` | Permanently remove thread |
-| `fetch(remoteId)` | Fetch single thread metadata |
-| `generateTitle(remoteId, unstable_messages)` | Return an `AssistantStream` with the generated title |
-
-## Which option to choose?
-
-| | Option 1: ChatModelAdapter | Option 2: RemoteThreadListAdapter |
-|---|---|---|
-| **Thread storage** | In-memory | Your backend |
-| **Message storage** | In-memory | In-memory (can add history adapter for server-side) |
-| **Cross-device sync** | No | Yes |
-| **Setup complexity** | Minimal | Moderate |
-| **Best for** | Single-device apps, prototypes | Production apps with user accounts |

package/.docs/raw/docs/react-native/hooks.mdx

@@ -1,339 +0,0 @@
----
-title: Hooks
-description: Reactive hooks for accessing runtime state in React Native.
----
-
-## State Hooks
-
-### useAuiState
-
-The primary hook for accessing reactive state. It accepts a selector function for fine-grained re-renders — the component only re-renders when the selected value changes (shallow equality).
-
-```tsx
-import { useAuiState } from "@assistant-ui/react-native";
-
-// Thread state
-const messages = useAuiState((s) => s.thread.messages);
-const isRunning = useAuiState((s) => s.thread.isRunning);
-const isEmpty = useAuiState((s) => s.thread.isEmpty);
-
-// Composer state
-const text = useAuiState((s) => s.composer.text);
-const composerIsEmpty = useAuiState((s) => s.composer.isEmpty);
-const attachments = useAuiState((s) => s.composer.attachments);
-
-// Message state (inside a message context)
-const role = useAuiState((s) => s.message.role);
-const isLast = useAuiState((s) => s.message.isLast);
-
-// Thread list item state
-const threadId = useAuiState((s) => s.threadListItem.id);
-const title = useAuiState((s) => s.threadListItem.title);
-```
-
-### useAui
-
-Access the store methods for imperative actions.
-
-```tsx
-import { useAui } from "@assistant-ui/react-native";
-
-const aui = useAui();
-
-// Composer actions
-aui.composer.setText("Hello");
-aui.composer.send();
-
-// Thread actions
-aui.thread.cancelRun();
-```
-
-### useAuiEvent
-
-Subscribe to events without causing re-renders.
-
-```tsx
-import { useAuiEvent } from "@assistant-ui/react-native";
-
-useAuiEvent("thread.modelContextUpdate", ({ threadId }) => {
-  console.log("Model context updated:", threadId);
-});
-```
-
-## Runtime Hooks
-
-### useLocalRuntime
-
-Create an `AssistantRuntime` with a `ChatModelAdapter`.
-
-```tsx
-import { useLocalRuntime } from "@assistant-ui/react-native";
-
-const runtime = useLocalRuntime(chatModel, {
-  initialMessages: [],
-});
-```
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `initialMessages` | `ThreadMessageLike[]` | Messages to pre-populate |
-| `maxSteps` | `number` | Maximum tool call steps per run |
-| `cloud` | `AssistantCloud` | Optional cloud instance for persistence |
-| `adapters` | `object` | Optional adapter overrides (see below) |
-| `unstable_humanToolNames` | `string[]` | Tool names that pause the run until a result is added via `addResult` |
-
-The `adapters` option accepts the following fields (all optional):
-
-| Adapter | Type | Description |
-|---------|------|-------------|
-| `history` | `ThreadHistoryAdapter` | Load and save thread message history |
-| `attachments` | `AttachmentAdapter` | Handle file and attachment uploads |
-| `speech` | `SpeechSynthesisAdapter` | Text-to-speech playback |
-| `dictation` | `DictationAdapter` | Speech-to-text input |
-| `feedback` | `FeedbackAdapter` | Thumbs up/down feedback |
-| `suggestion` | `SuggestionAdapter` | Prompt suggestions |
-
-### useRemoteThreadListRuntime
-
-Create an `AssistantRuntime` with a persistent thread list backed by a `RemoteThreadListAdapter`. This wraps any runtime hook (such as one calling `useLocalRuntime` or a custom AI SDK hook) and layers thread-list management on top.
-
-```tsx
-import { useRemoteThreadListRuntime } from "@assistant-ui/react-native";
-
-const runtime = useRemoteThreadListRuntime({
-  runtimeHook: () => useLocalRuntime(chatModel),
-  adapter: myThreadListAdapter,
-});
-```
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `runtimeHook` | `() => AssistantRuntime` | Hook that returns a per-thread runtime |
-| `adapter` | `RemoteThreadListAdapter` | Backend adapter for listing/creating/archiving threads |
-| `allowNesting` | `boolean` | When `true`, silently becomes a no-op if already inside another `useRemoteThreadListRuntime` |
-
-## Model Context Hooks
-
-### Tools
-
-Author tools in a `"use generative"` file 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.
-
-Add the [`@assistant-ui/metro`](https://www.npmjs.com/package/@assistant-ui/metro) plugin so Metro compiles the `"use generative"` directive:
-
-```js title="metro.config.js"
-const { getDefaultConfig } = require("expo/metro-config");
-const { withAui } = require("@assistant-ui/metro");
-
-module.exports = withAui(getDefaultConfig(__dirname));
-```
-
-```tsx title="weather-toolkit.tsx"
-"use generative";
-
-import { defineToolkit } from "@assistant-ui/react-native";
-import { Text, View } from "react-native";
-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";
-      const res = await fetch(`https://api.weather.example/${city}`);
-      return res.json();
-    },
-    render: ({ args, result }) => (
-      <View>
-        <Text>
-          {args.city}: {result?.temperature}°F
-        </Text>
-      </View>
-    ),
-  },
-});
-```
-
-```tsx title="ToolProvider.tsx"
-import {
-  AuiConfig,
-  AuiProvider,
-  Tools,
-  useAui,
-} from "@assistant-ui/react-native";
-import toolkit from "./weather-toolkit";
-
-function ToolProvider({ children }: { children: React.ReactNode }) {
-  const aui = useAui();
-  const config = AuiConfig({ tools: Tools({ toolkit }) });
-  return (
-    <AuiProvider extends={aui} config={config}>
-      {children}
-    </AuiProvider>
-  );
-}
-```
-
-### useAssistantDataUI
-
-Register a UI renderer for a named data message part.
-
-```tsx
-import { useAssistantDataUI } from "@assistant-ui/react-native";
-
-useAssistantDataUI({
-  name: "weather_card",
-  render: ({ data }) => (
-    <View>
-      <Text>{data.city}: {data.temperature}°F</Text>
-    </View>
-  ),
-});
-```
-
-### useAssistantInstructions
-
-Register system instructions in the model context.
-
-```tsx
-import { useAssistantInstructions } from "@assistant-ui/react-native";
-
-useAssistantInstructions("You are a helpful weather assistant.");
-```
-
-### useInlineRender
-
-Wrap a tool UI component so that inline state updates (from a parent component's render) are reflected without remounting. Use this when the render function closes over props that change over time.
-
-```tsx title="my-tool-toolkit.tsx"
-import { defineToolkit, useInlineRender } from "@assistant-ui/react-native";
-import { Text } from "react-native";
-import { useMemo } from "react";
-
-export function useMyToolToolkit(someOuterProp: string) {
-  const stableRender = useInlineRender(({ args, result }) => (
-    <Text>{someOuterProp}: {result?.value}</Text>
-  ));
-
-  return useMemo(
-    () =>
-      defineToolkit({
-        my_tool: {
-          type: "backend",
-          render: stableRender,
-        },
-      }),
-    [stableRender],
-  );
-}
-```
-
-Import the toolkit hook, hoist `const aui = useAui()` and `const config = AuiConfig({ tools: Tools({ toolkit }) })` in the component body, and mount it with `<AuiProvider extends={aui} config={config}>`, as shown in the [Tools](#tools) section above.
-
-### makeAssistantDataUI
-
-Create a component that registers a data UI renderer when mounted.
-
-```tsx
-import { makeAssistantDataUI } from "@assistant-ui/react-native";
-
-const WeatherCard = makeAssistantDataUI({
-  name: "weather_card",
-  render: ({ data }) => <Text>{data.city}: {data.temperature}°F</Text>,
-});
-
-<WeatherCard />
-```
-
-## Shared Providers
-
-These context providers are re-exported from `@assistant-ui/core/react` and are used internally by the primitives to scope the `aui` store to a particular item (message, part, thread list item, etc.). They are available for advanced custom rendering scenarios.
-
-### MessageByIndexProvider
-
-Scopes the `aui` context to a specific message by its index in the thread.
-
-```tsx
-import { MessageByIndexProvider } from "@assistant-ui/react-native";
-
-<MessageByIndexProvider index={2}>
-  {/* children can read s.message, s.composer */}
-</MessageByIndexProvider>
-```
-
-### PartByIndexProvider
-
-Scopes the `aui` context to a specific message part by its index.
-
-```tsx
-import { PartByIndexProvider } from "@assistant-ui/react-native";
-
-<PartByIndexProvider index={0}>
-  {/* children can read s.part */}
-</PartByIndexProvider>
-```
-
-### TextMessagePartProvider
-
-Provides a synthetic text part context from a plain string. Useful for rendering text outside the normal message-part pipeline.
-
-```tsx
-import { TextMessagePartProvider } from "@assistant-ui/react-native";
-
-<TextMessagePartProvider text="Hello world" isRunning={false}>
-  {/* children can read s.part as a text part */}
-</TextMessagePartProvider>
-```
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `text` | `string` | The text content |
-| `isRunning` | `boolean` | Whether the part is still streaming (default `false`) |
-
-### ChainOfThoughtByIndicesProvider
-
-Scopes the `aui` context to a slice of message parts that form a chain-of-thought block.
-
-```tsx
-import { ChainOfThoughtByIndicesProvider } from "@assistant-ui/react-native";
-
-<ChainOfThoughtByIndicesProvider startIndex={1} endIndex={3}>
-  {/* children can read s.chainOfThought */}
-</ChainOfThoughtByIndicesProvider>
-```
-
-### ChainOfThoughtPartByIndexProvider
-
-Scopes the `aui` context to a specific part within a chain-of-thought block.
-
-```tsx
-import { ChainOfThoughtPartByIndexProvider } from "@assistant-ui/react-native";
-
-<ChainOfThoughtPartByIndexProvider index={0}>
-  {/* children can read s.part */}
-</ChainOfThoughtPartByIndexProvider>
-```
-
-### ThreadListItemByIndexProvider
-
-Scopes the `aui` context to a specific thread list item by its index.
-
-```tsx
-import { ThreadListItemByIndexProvider } from "@assistant-ui/react-native";
-
-<ThreadListItemByIndexProvider index={0} archived={false}>
-  {/* children can read s.threadListItem */}
-</ThreadListItemByIndexProvider>
-```
-
-### SuggestionByIndexProvider
-
-Scopes the `aui` context to a specific suggestion by its index.
-
-```tsx
-import { SuggestionByIndexProvider } from "@assistant-ui/react-native";
-
-<SuggestionByIndexProvider index={0}>
-  {/* children can read s.suggestion */}
-</SuggestionByIndexProvider>
-```