@assistant-ui/mcp-docs-server 0.1.22 → 0.1.23

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

@@ -0,0 +1,364 @@
+---
+title: Hooks
+description: Reactive hooks for accessing runtime state in React Native.
+---
+
+All hooks support an optional **selector** function for fine-grained re-renders. Without a selector, the component re-renders on every state change. With a selector, it only re-renders when the selected value changes (shallow equality).
+
+```tsx
+// Re-renders on every thread state change
+const thread = useThread();
+
+// Re-renders only when isRunning changes
+const isRunning = useThread((s) => s.isRunning);
+```
+
+## State Hooks
+
+### useThread
+
+Access thread state.
+
+```tsx
+import { useThread } from "@assistant-ui/react-native";
+
+const messages = useThread((s) => s.messages);
+const isRunning = useThread((s) => s.isRunning);
+```
+
+**ThreadState fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `messages` | `ThreadMessage[]` | All messages in the thread |
+| `isRunning` | `boolean` | Whether the model is generating |
+| `isDisabled` | `boolean` | Whether the thread is disabled |
+| `capabilities` | `RuntimeCapabilities` | What actions are supported |
+
+### useComposer
+
+Access composer state.
+
+```tsx
+import { useComposer } from "@assistant-ui/react-native";
+
+const text = useComposer((s) => s.text);
+const isEmpty = useComposer((s) => s.isEmpty);
+```
+
+**ComposerState fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `text` | `string` | Current input text |
+| `isEmpty` | `boolean` | Whether the input is empty |
+| `attachments` | `Attachment[]` | Current attachments |
+| `canCancel` | `boolean` | Whether a run can be cancelled |
+
+### useMessage
+
+Access the current message state. Must be used inside a `MessageProvider` or a `renderMessage` / `renderItem` callback.
+
+```tsx
+import { useMessage } from "@assistant-ui/react-native";
+
+const role = useMessage((s) => s.role);
+const isLast = useMessage((s) => s.isLast);
+```
+
+**MessageState fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `message` | `ThreadMessage` | The message object |
+| `role` | `MessageRole` | `"user"`, `"assistant"`, or `"system"` |
+| `isLast` | `boolean` | Whether this is the last message |
+| `branchNumber` | `number` | Current branch index |
+| `branchCount` | `number` | Total number of branches |
+
+### useContentPart
+
+Access a specific content part by index within a message.
+
+```tsx
+import { useContentPart } from "@assistant-ui/react-native";
+
+const part = useContentPart(0); // first content part
+```
+
+### useThreadList
+
+Access the thread list state.
+
+```tsx
+import { useThreadList } from "@assistant-ui/react-native";
+
+const { threadIds, mainThreadId, threadItems } = useThreadList();
+
+// With selector
+const mainThreadId = useThreadList((s) => s.mainThreadId);
+```
+
+**ThreadListState fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `threadIds` | `string[]` | All thread IDs |
+| `mainThreadId` | `string` | Currently active thread ID |
+| `threadItems` | `Record<string, ThreadListItemState>` | Thread metadata (title, etc.) |
+
+## Runtime Hooks
+
+### useAssistantRuntime
+
+Get the `AssistantRuntime` from context. This is the top-level runtime with access to thread management.
+
+```tsx
+import { useAssistantRuntime } from "@assistant-ui/react-native";
+
+const runtime = useAssistantRuntime();
+
+// Switch threads
+runtime.threads.switchToThread(threadId);
+runtime.threads.switchToNewThread();
+
+// Thread management
+runtime.threads.rename(threadId, "New Title");
+runtime.threads.delete(threadId);
+
+// Access the current thread runtime
+runtime.thread; // ThreadRuntime
+```
+
+### useThreadRuntime
+
+Get the `ThreadRuntime` for the current thread.
+
+```tsx
+import { useThreadRuntime } from "@assistant-ui/react-native";
+
+const threadRuntime = useThreadRuntime();
+
+threadRuntime.cancelRun();
+threadRuntime.appendMessage(message);
+```
+
+### useComposerRuntime
+
+Get the `ComposerRuntime` for the current composer.
+
+```tsx
+import { useComposerRuntime } from "@assistant-ui/react-native";
+
+const composerRuntime = useComposerRuntime();
+
+composerRuntime.setText("Hello");
+composerRuntime.send();
+```
+
+### useMessageRuntime
+
+Get the `MessageRuntime` for the current message.
+
+```tsx
+import { useMessageRuntime } from "@assistant-ui/react-native";
+
+const messageRuntime = useMessageRuntime();
+
+messageRuntime.reload();
+messageRuntime.switchToBranch({ position: "next" });
+```
+
+### useLocalRuntime
+
+Create an `AssistantRuntime` with a `ChatModelAdapter`. Optionally pass `storage` for persistence.
+
+```tsx
+import { useLocalRuntime } from "@assistant-ui/react-native";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+const runtime = useLocalRuntime(chatModel, {
+  storage: AsyncStorage,
+  titleGenerator: createSimpleTitleAdapter(),
+});
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `initialMessages` | `ThreadMessageLike[]` | Messages to pre-populate |
+| `storage` | `AsyncStorageLike` | Thread and message persistence |
+| `storagePrefix` | `string` | Key prefix for storage (default `"@assistant-ui:"`) |
+| `titleGenerator` | `TitleGenerationAdapter` | Auto-generate thread titles |
+
+## Primitive Hooks
+
+Low-level hooks for building custom components.
+
+### useThreadMessages
+
+```tsx
+import { useThreadMessages } from "@assistant-ui/react-native";
+
+const messages = useThreadMessages(); // ThreadMessage[]
+```
+
+### useThreadIsRunning
+
+```tsx
+import { useThreadIsRunning } from "@assistant-ui/react-native";
+
+const isRunning = useThreadIsRunning(); // boolean
+```
+
+### useThreadIsEmpty
+
+```tsx
+import { useThreadIsEmpty } from "@assistant-ui/react-native";
+
+const isEmpty = useThreadIsEmpty(); // boolean
+```
+
+### useComposerSend
+
+```tsx
+import { useComposerSend } from "@assistant-ui/react-native";
+
+const { send, canSend } = useComposerSend();
+```
+
+### useComposerCancel
+
+```tsx
+import { useComposerCancel } from "@assistant-ui/react-native";
+
+const { cancel, canCancel } = useComposerCancel();
+```
+
+### useComposerAddAttachment
+
+Add an attachment to the composer. Returns `{ addAttachment }` — call it with a `File` or `CreateAttachment` object. Pair with your own file picker (e.g. `expo-image-picker`).
+
+```tsx
+import { useComposerAddAttachment } from "@assistant-ui/react-native";
+
+const { addAttachment } = useComposerAddAttachment();
+
+// With expo-image-picker
+const pickImage = async () => {
+  const result = await ImagePicker.launchImageLibraryAsync({
+    base64: true,
+    quality: 0.8,
+  });
+  if (result.canceled) return;
+
+  for (const asset of result.assets) {
+    await addAttachment({
+      name: asset.fileName ?? "image.jpg",
+      type: "image",
+      content: [
+        { type: "image", image: `data:image/jpeg;base64,${asset.base64}` },
+      ],
+    });
+  }
+};
+```
+
+<Callout type="info">
+  You must configure an `AttachmentAdapter` (e.g. `SimpleImageAttachmentAdapter`) in your runtime options for attachments to work.
+</Callout>
+
+### useMessageReload
+
+```tsx
+import { useMessageReload } from "@assistant-ui/react-native";
+
+const { reload, canReload } = useMessageReload();
+```
+
+### useMessageBranching
+
+```tsx
+import { useMessageBranching } from "@assistant-ui/react-native";
+
+const { branchNumber, branchCount, goToPrev, goToNext } =
+  useMessageBranching();
+```
+
+## Model Context Hooks
+
+### useAssistantTool
+
+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.
+
+```tsx
+import { useAssistantTool } from "@assistant-ui/react-native";
+
+useAssistantTool({
+  toolName: "get_weather",
+  description: "Get the current weather for a city",
+  parameters: {
+    type: "object",
+    properties: {
+      city: { type: "string" },
+    },
+    required: ["city"],
+  },
+  execute: async ({ city }) => {
+    const res = await fetch(`https://api.weather.example/${city}`);
+    return res.json();
+  },
+  render: ({ args, result }) => (
+    <View>
+      <Text>{args.city}: {result?.temperature}°F</Text>
+    </View>
+  ),
+});
+```
+
+### useAssistantToolUI
+
+Register only a UI renderer for a tool (without tool definition or execute function).
+
+```tsx
+import { useAssistantToolUI } from "@assistant-ui/react-native";
+
+useAssistantToolUI({
+  toolName: "get_weather",
+  render: ({ args, result, status }) => (
+    <View>
+      {status?.type === "running"
+        ? <Text>Loading weather for {args.city}...</Text>
+        : <Text>{args.city}: {result?.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.");
+```
+
+### makeAssistantTool
+
+Create a component that registers a tool when mounted. Useful for declarative tool registration.
+
+```tsx
+import { makeAssistantTool } from "@assistant-ui/react-native";
+
+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 AssistantProvider to register
+<WeatherTool />
+```

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

@@ -0,0 +1,332 @@
+---
+title: Getting Started
+description: Build AI chat interfaces for iOS and Android with @assistant-ui/react-native.
+---
+
+## Overview
+
+`@assistant-ui/react-native` brings assistant-ui to React Native. It provides composable primitives, reactive hooks, and a local runtime — the same layered architecture as the web package, built on native components (`View`, `TextInput`, `FlatList`, `Pressable`).
+
+**Key features:**
+
+- **Primitives** — `Thread`, `Composer`, `Message`, `ThreadList`, `ThreadListItem`, `ChainOfThought`, `Suggestion`, `ActionBar`, `BranchPicker`, `Attachment` components that compose with standard React Native props
+- **Reactive state** — `useAuiState` with selector support for fine-grained re-renders
+- **Local runtime** — `useLocalRuntime` with pluggable `ChatModelAdapter` for any LLM API
+- **Thread management** — Multi-thread support with create, switch, rename, delete
+- **Tool system** — `useAssistantTool`, `makeAssistantTool` for registering tools with custom UI renderers
+- **Attachments** — Image and file attachments with `useComposerAddAttachment` and attachment primitives
+
+<Callout type="info">
+  `@assistant-ui/react-native` shares its runtime core with `@assistant-ui/react` via `@assistant-ui/core`. The type system, state management, and runtime logic are identical — only the UI layer differs.
+</Callout>
+
+## Getting Started
+
+This guide uses [Expo](https://expo.dev) with the OpenAI API. You can substitute any LLM provider.
+
+<Steps>
+  <Step>
+
+### Create an Expo project
+
+```sh
+npx create-expo-app@latest my-chat-app
+cd my-chat-app
+```
+
+  </Step>
+  <Step>
+
+### Install dependencies
+
+```sh
+npx expo install @assistant-ui/react-native
+```
+
+  </Step>
+  <Step>
+
+### Create a ChatModelAdapter
+
+The adapter connects your LLM API to the runtime. Here's an example for the OpenAI chat completions API with streaming:
+
+```tsx title="adapters/openai-chat-adapter.ts"
+import type {
+  ChatModelAdapter,
+  ChatModelRunResult,
+} from "@assistant-ui/react-native";
+
+type OpenAIModelConfig = {
+  apiKey: string;
+  model?: string;
+  baseURL?: string;
+  fetch?: typeof globalThis.fetch;
+};
+
+export function createOpenAIChatModelAdapter(
+  config: OpenAIModelConfig,
+): ChatModelAdapter {
+  const {
+    apiKey,
+    model = "gpt-4o-mini",
+    baseURL = "https://api.openai.com/v1",
+    fetch: customFetch = globalThis.fetch,
+  } = config;
+
+  return {
+    async *run({ messages, abortSignal }) {
+      const openAIMessages = messages
+        .filter((m) => m.role !== "system")
+        .map((m) => ({
+          role: m.role as "user" | "assistant",
+          content: m.content
+            .filter((p) => p.type === "text")
+            .map((p) => ("text" in p ? p.text : ""))
+            .join("\n"),
+        }));
+
+      const response = await customFetch(
+        `${baseURL}/chat/completions`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify({
+            model,
+            messages: openAIMessages,
+            stream: true,
+          }),
+          signal: abortSignal,
+        },
+      );
+
+      if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(
+          `OpenAI API error: ${response.status} ${body}`,
+        );
+      }
+
+      const reader = response.body?.getReader();
+      if (!reader) {
+        const json = await response.json();
+        const text = json.choices?.[0]?.message?.content ?? "";
+        yield {
+          content: [{ type: "text" as const, text }],
+        } satisfies ChatModelRunResult;
+        return;
+      }
+
+      const decoder = new TextDecoder();
+      let fullText = "";
+
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          const chunk = decoder.decode(value, { stream: true });
+          for (const line of chunk.split("\n")) {
+            if (!line.startsWith("data: ")) continue;
+            const data = line.slice(6);
+            if (data === "[DONE]") continue;
+            try {
+              const parsed = JSON.parse(data);
+              const content =
+                parsed.choices?.[0]?.delta?.content ?? "";
+              fullText += content;
+              yield {
+                content: [
+                  { type: "text" as const, text: fullText },
+                ],
+              } satisfies ChatModelRunResult;
+            } catch {
+              // skip invalid JSON
+            }
+          }
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    },
+  };
+}
+```
+
+<Callout type="tip">
+  On Expo, import `fetch` from `expo/fetch` for streaming support and pass it as the `fetch` option.
+</Callout>
+
+  </Step>
+  <Step>
+
+### Set up the runtime
+
+```tsx title="hooks/use-app-runtime.ts"
+import { useMemo } from "react";
+import { fetch } from "expo/fetch";
+import { useLocalRuntime } from "@assistant-ui/react-native";
+import { createOpenAIChatModelAdapter } from "@/adapters/openai-chat-adapter";
+
+export function useAppRuntime() {
+  const chatModel = useMemo(
+    () =>
+      createOpenAIChatModelAdapter({
+        apiKey: process.env.EXPO_PUBLIC_OPENAI_API_KEY ?? "",
+        model: "gpt-4o-mini",
+        fetch,
+      }),
+    [],
+  );
+
+  return useLocalRuntime(chatModel);
+}
+```
+
+  </Step>
+  <Step>
+
+### Build the UI
+
+Wrap your app with `AssistantProvider` — thread and composer contexts are set up automatically:
+
+```tsx title="app/index.tsx"
+import {
+  AssistantProvider,
+  useAuiState,
+  useAui,
+} from "@assistant-ui/react-native";
+import type { ThreadMessage } from "@assistant-ui/react-native";
+import {
+  View,
+  Text,
+  TextInput,
+  FlatList,
+  Pressable,
+  KeyboardAvoidingView,
+  Platform,
+} from "react-native";
+import { useAppRuntime } from "@/hooks/use-app-runtime";
+
+function MessageBubble({ message }: { message: ThreadMessage }) {
+  const isUser = message.role === "user";
+  const text = message.content
+    .filter((p) => p.type === "text")
+    .map((p) => ("text" in p ? p.text : ""))
+    .join("\n");
+
+  return (
+    <View
+      style={{
+        alignSelf: isUser ? "flex-end" : "flex-start",
+        backgroundColor: isUser ? "#007aff" : "#f0f0f0",
+        borderRadius: 16,
+        padding: 12,
+        marginVertical: 4,
+        marginHorizontal: 16,
+        maxWidth: "80%",
+      }}
+    >
+      <Text style={{ color: isUser ? "#fff" : "#000" }}>{text}</Text>
+    </View>
+  );
+}
+
+function Composer() {
+  const aui = useAui();
+  const text = useAuiState((s) => s.composer.text);
+  const isEmpty = useAuiState((s) => s.composer.isEmpty);
+
+  return (
+    <View
+      style={{
+        flexDirection: "row",
+        padding: 12,
+        alignItems: "flex-end",
+      }}
+    >
+      <TextInput
+        value={text}
+        onChangeText={(t) => aui.composer().setText(t)}
+        placeholder="Message..."
+        multiline
+        style={{
+          flex: 1,
+          borderWidth: 1,
+          borderColor: "#ddd",
+          borderRadius: 20,
+          paddingHorizontal: 16,
+          paddingVertical: 10,
+          maxHeight: 120,
+        }}
+      />
+      <Pressable
+        onPress={() => aui.composer().send()}
+        disabled={isEmpty}
+        style={{
+          marginLeft: 8,
+          backgroundColor: !isEmpty ? "#007aff" : "#ccc",
+          borderRadius: 20,
+          width: 36,
+          height: 36,
+          justifyContent: "center",
+          alignItems: "center",
+        }}
+      >
+        <Text style={{ color: "#fff", fontWeight: "bold" }}>↑</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+function ChatScreen() {
+  const messages = useAuiState(
+    (s) => s.thread.messages,
+  ) as ThreadMessage[];
+
+  return (
+    <KeyboardAvoidingView
+      style={{ flex: 1 }}
+      behavior={Platform.OS === "ios" ? "padding" : "height"}
+    >
+      <FlatList
+        data={messages}
+        keyExtractor={(m) => m.id}
+        renderItem={({ item }) => <MessageBubble message={item} />}
+      />
+      <Composer />
+    </KeyboardAvoidingView>
+  );
+}
+
+export default function App() {
+  const runtime = useAppRuntime();
+
+  return (
+    <AssistantProvider runtime={runtime}>
+      <ChatScreen />
+    </AssistantProvider>
+  );
+}
+```
+
+  </Step>
+</Steps>
+
+## Architecture
+
+```
+useLocalRuntime(chatModel, options?)
+  └─ AssistantProvider
+       ├─ useAuiState((s) => s.thread)    → thread state (messages, isRunning, …)
+       ├─ useAuiState((s) => s.composer)   → composer state (text, isEmpty, …)
+       ├─ useAuiState((s) => s.message)    → single message state (inside renderItem)
+       └─ Primitives                       → ThreadRoot, ComposerInput, MessageContent, …
+```
+
+The runtime core is shared with `@assistant-ui/react` — only the UI primitives are React Native-specific.
+
+## Example
+
+For a complete Expo example with drawer navigation, thread list, and styled chat UI, see the [`with-expo` example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-expo).