@assistant-ui/mcp-docs-server 0.1.24 → 0.1.25

package/.docs/raw/docs/ink/hooks.mdx

@@ -0,0 +1,448 @@
+---
+title: Hooks
+description: Reactive hooks for accessing runtime state in React Ink.
+---
+
+## 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-ink";
+
+// 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-ink";
+
+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-ink";
+
+useAuiEvent("thread.runStart", (payload) => {
+  console.log("Run started:", payload);
+});
+```
+
+## Runtime Hooks
+
+### useLocalRuntime
+
+Create an `AssistantRuntime` with a `ChatModelAdapter`.
+
+```tsx
+import { useLocalRuntime } from "@assistant-ui/react-ink";
+
+const runtime = useLocalRuntime(chatModel, {
+  initialMessages: [],
+});
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `initialMessages` | `ThreadMessageLike[]` | Messages to pre-populate the thread with |
+| `maxSteps` | `number` | Maximum number of agentic steps before stopping |
+| `adapters.history` | `ThreadHistoryAdapter` | Adapter for persisting thread history |
+| `adapters.attachments` | `AttachmentAdapter` | Adapter for handling file attachments |
+| `adapters.speech` | `SpeechSynthesisAdapter` | Adapter for text-to-speech output |
+| `adapters.dictation` | `DictationAdapter` | Adapter for speech-to-text input |
+| `adapters.feedback` | `FeedbackAdapter` | Adapter for message feedback (thumbs up/down) |
+| `adapters.suggestion` | `SuggestionAdapter` | Adapter for suggested prompts |
+| `cloud` | `AssistantCloud` | Cloud instance for thread persistence via `@assistant-ui/cloud` |
+| `unstable_humanToolNames` | `string[]` | Tool names that trigger a run interruption to wait for human/external approval |
+
+### useRemoteThreadListRuntime
+
+Create an `AssistantRuntime` backed by a `RemoteThreadListAdapter` for multi-thread persistence. The `runtimeHook` is called for each thread to produce the per-thread runtime (typically `useLocalRuntime`).
+
+```tsx
+import { useRemoteThreadListRuntime, useLocalRuntime } from "@assistant-ui/react-ink";
+
+const runtime = useRemoteThreadListRuntime({
+  adapter: myRemoteAdapter,
+  runtimeHook: () => useLocalRuntime(chatModel),
+});
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `runtimeHook` | `() => AssistantRuntime` | Hook called to produce the per-thread runtime |
+| `adapter` | `RemoteThreadListAdapter` | Adapter implementing thread list persistence |
+| `allowNesting` | `boolean` | When true, becomes a no-op if nested inside another `RemoteThreadListRuntime` |
+
+## 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-ink";
+import { Text } from "ink";
+
+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 }) => (
+    <Text>{args.city}: {result?.temperature}°F</Text>
+  ),
+});
+```
+
+### useAssistantToolUI
+
+Register only a UI renderer for a tool (without tool definition or execute function).
+
+```tsx
+import { useAssistantToolUI } from "@assistant-ui/react-ink";
+import { Text } from "ink";
+
+useAssistantToolUI({
+  toolName: "get_weather",
+  render: ({ args, result, status }) => (
+    <Text>
+      {status?.type === "running"
+        ? `Loading weather for ${args.city}...`
+        : `${args.city}: ${result?.temperature}°F`}
+    </Text>
+  ),
+});
+```
+
+### useAssistantInstructions
+
+Register system instructions in the model context.
+
+```tsx
+import { useAssistantInstructions } from "@assistant-ui/react-ink";
+
+useAssistantInstructions("You are a helpful terminal assistant.");
+```
+
+### useAssistantDataUI
+
+Register a UI renderer for a named data part type. When a message contains a data part with the given `name`, the `render` component is used.
+
+```tsx
+import { useAssistantDataUI } from "@assistant-ui/react-ink";
+import { Text } from "ink";
+
+useAssistantDataUI({
+  name: "weather_card",
+  render: ({ data }) => (
+    <Text>{data.city}: {data.temperature}°F</Text>
+  ),
+});
+```
+### makeAssistantTool
+
+Create a component that registers a tool when mounted.
+
+```tsx
+import { makeAssistantTool } from "@assistant-ui/react-ink";
+import { Text } from "ink";
+
+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 AssistantRuntimeProvider to register
+<WeatherTool />
+```
+
+### makeAssistantToolUI
+
+Create a component that registers only a tool UI renderer (no tool definition or execute) when mounted.
+
+```tsx
+import { makeAssistantToolUI } from "@assistant-ui/react-ink";
+import { Text } from "ink";
+
+const WeatherToolUI = makeAssistantToolUI({
+  toolName: "get_weather",
+  render: ({ args, result, status }) => (
+    <Text>
+      {status?.type === "running"
+        ? `Loading weather for ${args.city}...`
+        : `${args.city}: ${result?.temperature}°F`}
+    </Text>
+  ),
+});
+
+// Mount inside AssistantRuntimeProvider to register
+<WeatherToolUI />
+```
+
+### makeAssistantDataUI
+
+Create a component that registers a data UI renderer when mounted.
+
+```tsx
+import { makeAssistantDataUI } from "@assistant-ui/react-ink";
+import { Text } from "ink";
+
+const WeatherCardUI = makeAssistantDataUI({
+  name: "weather_card",
+  render: ({ data }) => (
+    <Text>{data.city}: {data.temperature}°F</Text>
+  ),
+});
+
+// Mount inside AssistantRuntimeProvider to register
+<WeatherCardUI />
+```
+
+### useInlineRender
+
+Wrap a render function component so that it always uses the latest version without re-creating a stable reference. Useful when passing a render prop inline and the function closes over changing state.
+
+```tsx
+import { useInlineRender } from "@assistant-ui/react-ink";
+
+const render = useInlineRender(({ args, result }) => (
+  <Text>{args.city}: {result?.temperature}°F</Text>
+));
+
+useAssistantToolUI({ toolName: "get_weather", render });
+```
+
+## Runtime Providers
+
+### AssistantRuntimeProvider
+
+Connects an `AssistantRuntime` to the React tree. All primitives and hooks must be used inside this provider.
+
+```tsx
+import { AssistantRuntimeProvider, useLocalRuntime } from "@assistant-ui/react-ink";
+
+const runtime = useLocalRuntime(chatModel);
+
+<AssistantRuntimeProvider runtime={runtime}>
+  {/* app content */}
+</AssistantRuntimeProvider>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `runtime` | `AssistantRuntime` | The runtime instance to provide |
+
+## Context Providers
+
+These low-level providers are used to set up scoped contexts for rendering primitives outside of the standard `ThreadPrimitive.Messages` / `MessagePrimitive.Parts` hierarchy.
+
+### MessageByIndexProvider
+
+Sets up the message context for a given message index in the thread. Used internally by `ThreadPrimitive.Messages`.
+
+```tsx
+import { MessageByIndexProvider } from "@assistant-ui/react-ink";
+
+<MessageByIndexProvider index={0}>
+  <MessagePrimitive.Root>...</MessagePrimitive.Root>
+</MessageByIndexProvider>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `index` | `number` | Zero-based index of the message in the thread |
+
+### PartByIndexProvider
+
+Sets up the part context for a given part index in the current message. Used internally by `MessagePrimitive.Parts`.
+
+```tsx
+import { PartByIndexProvider } from "@assistant-ui/react-ink";
+
+<PartByIndexProvider index={0}>
+  {/* part content */}
+</PartByIndexProvider>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `index` | `number` | Zero-based index of the part in the message |
+
+### TextMessagePartProvider
+
+Provides a synthetic text part context with a fixed text value. Useful for rendering text content outside of a real message part (e.g., in previews or testing).
+
+```tsx
+import { TextMessagePartProvider } from "@assistant-ui/react-ink";
+
+<TextMessagePartProvider text="Hello world" isRunning={false}>
+  {/* content rendered with a text part context */}
+</TextMessagePartProvider>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `text` | `string` | The text content for the synthetic part |
+| `isRunning` | `boolean` | Whether the part should appear as running (default: `false`) |
+
+### ChainOfThoughtByIndicesProvider
+
+Sets up a chain-of-thought context spanning a range of message parts by start and end index. Used to group consecutive reasoning parts.
+
+```tsx
+import { ChainOfThoughtByIndicesProvider } from "@assistant-ui/react-ink";
+
+<ChainOfThoughtByIndicesProvider startIndex={1} endIndex={3}>
+  <ChainOfThoughtPrimitive.Root>...</ChainOfThoughtPrimitive.Root>
+</ChainOfThoughtByIndicesProvider>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `startIndex` | `number` | Index of the first part in the chain-of-thought range |
+| `endIndex` | `number` | Index of the last part in the chain-of-thought range |
+
+### ChainOfThoughtPartByIndexProvider
+
+Sets up the part context for a specific part within the current chain-of-thought by index.
+
+```tsx
+import { ChainOfThoughtPartByIndexProvider } from "@assistant-ui/react-ink";
+
+<ChainOfThoughtPartByIndexProvider index={0}>
+  {/* chain-of-thought part content */}
+</ChainOfThoughtPartByIndexProvider>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `index` | `number` | Zero-based index of the part within the chain-of-thought |
+
+### SuggestionByIndexProvider
+
+Sets up the suggestion context for a given suggestion index. Used internally by `ThreadPrimitive.Suggestions`.
+
+```tsx
+import { SuggestionByIndexProvider } from "@assistant-ui/react-ink";
+
+<SuggestionByIndexProvider index={0}>
+  <SuggestionPrimitive.Title />
+</SuggestionByIndexProvider>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `index` | `number` | Zero-based index of the suggestion |
+
+### ThreadListItemByIndexProvider
+
+Sets up the thread list item context for a given index, differentiating between regular and archived threads.
+
+```tsx
+import { ThreadListItemByIndexProvider } from "@assistant-ui/react-ink";
+
+<ThreadListItemByIndexProvider index={0} archived={false}>
+  <ThreadListItemPrimitive.Root>...</ThreadListItemPrimitive.Root>
+</ThreadListItemByIndexProvider>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `index` | `number` | Zero-based index in the thread list |
+| `archived` | `boolean` | Whether to index into the archived thread list |
+
+### ThreadListItemRuntimeProvider
+
+Sets up the thread list item context from a `ThreadListItemRuntime` instance directly.
+
+```tsx
+import { ThreadListItemRuntimeProvider } from "@assistant-ui/react-ink";
+
+<ThreadListItemRuntimeProvider runtime={threadListItemRuntime}>
+  <ThreadListItemPrimitive.Root>...</ThreadListItemPrimitive.Root>
+</ThreadListItemRuntimeProvider>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `runtime` | `ThreadListItemRuntime` | The thread list item runtime instance |
+
+### MessageAttachmentByIndexProvider
+
+Sets up the attachment context for a specific message attachment by index.
+
+```tsx
+import { MessageAttachmentByIndexProvider } from "@assistant-ui/react-ink";
+
+<MessageAttachmentByIndexProvider index={0}>
+  <AttachmentPrimitive.Name />
+</MessageAttachmentByIndexProvider>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `index` | `number` | Zero-based index of the attachment in the message |
+
+### ComposerAttachmentByIndexProvider
+
+Sets up the attachment context for a specific composer attachment by index.
+
+```tsx
+import { ComposerAttachmentByIndexProvider } from "@assistant-ui/react-ink";
+
+<ComposerAttachmentByIndexProvider index={0}>
+  <AttachmentPrimitive.Name />
+  <AttachmentPrimitive.Remove>
+    <Text color="red">[x]</Text>
+  </AttachmentPrimitive.Remove>
+</ComposerAttachmentByIndexProvider>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `index` | `number` | Zero-based index of the attachment in the composer |

package/.docs/raw/docs/ink/index.mdx

@@ -0,0 +1,239 @@
+---
+title: Getting Started
+description: Build AI chat interfaces for the terminal with @assistant-ui/react-ink.
+---
+
+## Quick Start
+
+The fastest way to get started with assistant-ui for the terminal.
+
+<Steps>
+  <Step>
+
+### Create a new project
+
+```sh
+npx assistant-ui@latest create --ink my-chat-app
+cd my-chat-app
+```
+
+  </Step>
+  <Step>
+
+### Install dependencies
+
+```sh
+pnpm install
+```
+
+  </Step>
+  <Step>
+
+### Start the app
+
+```sh
+pnpm dev
+```
+
+  </Step>
+</Steps>
+
+## Manual Setup
+
+If you prefer to add assistant-ui to an existing Node.js project, follow these steps.
+
+<Steps>
+  <Step>
+
+### Install dependencies
+
+```sh
+npm install @assistant-ui/react-ink @assistant-ui/react-ink-markdown ink react
+```
+
+  </Step>
+  <Step>
+
+### Create a chat model adapter
+
+Define how your app communicates with your AI backend. This example uses a simple streaming adapter:
+
+```ts title="adapters/my-chat-adapter.ts"
+import type { ChatModelAdapter } from "@assistant-ui/react-ink";
+
+export const myChatAdapter: ChatModelAdapter = {
+  async *run({ messages, abortSignal }) {
+    const response = await fetch("http://localhost:3000/api/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 }] };
+    }
+  },
+};
+```
+
+<Callout type="info">
+  This is the same `ChatModelAdapter` interface used in `@assistant-ui/react` and `@assistant-ui/react-native`. If you already have an adapter, you can reuse it as-is.
+</Callout>
+
+  </Step>
+  <Step>
+
+### Set up the runtime
+
+```tsx title="app.tsx"
+import { Box, Text } from "ink";
+import {
+  AssistantRuntimeProvider,
+  useLocalRuntime,
+} from "@assistant-ui/react-ink";
+import { myChatAdapter } from "./adapters/my-chat-adapter.js";
+
+export function App() {
+  const runtime = useLocalRuntime(myChatAdapter);
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Box flexDirection="column" padding={1}>
+        <Text bold color="cyan">My Terminal Chat</Text>
+        {/* your chat UI */}
+      </Box>
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+  </Step>
+  <Step>
+
+### Build your chat UI
+
+Use primitives to compose your terminal chat interface:
+
+```tsx title="components/thread.tsx"
+import { Box, Text } from "ink";
+import {
+  ThreadPrimitive,
+  ComposerPrimitive,
+  useAuiState,
+} from "@assistant-ui/react-ink";
+import { MarkdownText } from "@assistant-ui/react-ink-markdown";
+
+const Message = () => {
+  const message = useAuiState((s) => s.message);
+  const isUser = message.role === "user";
+  const text = message.content
+    .filter((p) => p.type === "text")
+    .map((p) => ("text" in p ? p.text : ""))
+    .join("");
+
+  if (isUser) {
+    return (
+      <Box marginBottom={1}>
+        <Text bold color="green">You: </Text>
+        <Text wrap="wrap">{text}</Text>
+      </Box>
+    );
+  }
+
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Text bold color="blue">AI:</Text>
+      <MarkdownText text={text} />
+    </Box>
+  );
+};
+
+const StatusIndicator = () => {
+  const isRunning = useAuiState((s) => s.thread.isRunning);
+  if (!isRunning) return null;
+  return (
+    <Box marginBottom={1}>
+      <Text color="yellow">Thinking...</Text>
+    </Box>
+  );
+};
+
+export const Thread = () => {
+  return (
+    <ThreadPrimitive.Root>
+      <ThreadPrimitive.Empty>
+        <Box marginBottom={1}>
+          <Text dimColor>No messages yet. Start typing below!</Text>
+        </Box>
+      </ThreadPrimitive.Empty>
+
+      <ThreadPrimitive.Messages>
+        {() => <Message />}
+      </ThreadPrimitive.Messages>
+
+      <StatusIndicator />
+
+      <Box borderStyle="round" borderColor="gray" paddingX={1}>
+        <Text color="gray">{"> "}</Text>
+        <ComposerPrimitive.Input
+          submitOnEnter
+          placeholder="Type a message..."
+          autoFocus
+        />
+      </Box>
+    </ThreadPrimitive.Root>
+  );
+};
+```
+
+  </Step>
+  <Step>
+
+### Render with Ink
+
+```tsx title="index.tsx"
+import { render } from "ink";
+import { App } from "./app.js";
+
+render(<App />);
+```
+
+  </Step>
+</Steps>
+
+## What's Next?
+
+<Cards>
+  <Card
+    title="Migration from Web"
+    description="Already using assistant-ui? Migrate your web app to the terminal."
+    href="/docs/ink/migration"
+  />
+  <Card
+    title="Custom Backend"
+    description="Connect to your own backend API or manage threads server-side."
+    href="/docs/ink/custom-backend"
+  />
+  <Card
+    title="Primitives"
+    description="Composable terminal UI components for building chat interfaces."
+    href="/docs/ink/primitives"
+  />
+  <Card
+    title="Example App"
+    description="Full terminal chat example with markdown rendering and streaming."
+    href="https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-react-ink"
+  />
+</Cards>