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

package/.docs/raw/docs/cloud/ai-sdk-assistant-ui.mdx

@@ -26,7 +26,7 @@ The `useChatRuntime` hook from `@assistant-ui/react-ai-sdk` wraps AI SDK's `useC
 3. Generates a conversation title after the assistant's first response
 4. Loads historical messages when switching threads via `<ThreadList />`
 
-You provide the AI SDK endpoint (`api: "/api/chat"`) and the cloud configuration—everything else is handled.
+You provide the cloud configuration—everything else is handled. The default `AssistantChatTransport` automatically sends requests to `/api/chat`.
 
 ## Prerequisites
 
@@ -84,16 +84,21 @@ Create a client-side AssistantCloud instance and integrate it with your AI SDK r
 ```tsx title="app/chat/page.tsx"
 "use client";
 
+import { useMemo } from "react";
 import { AssistantCloud, AssistantRuntimeProvider } from "@assistant-ui/react";
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
 import { ThreadList } from "@/components/assistant-ui/thread-list";
 import { Thread } from "@/components/assistant-ui/thread";
 
 export default function ChatPage() {
-  const cloud = new AssistantCloud({
-    baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
-    anonymous: true, // Creates browser-session based user ID
-  });
+  const cloud = useMemo(
+    () =>
+      new AssistantCloud({
+        baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
+        anonymous: true, // Creates browser-session based user ID
+      }),
+    [],
+  );
 
   const runtime = useChatRuntime({
     cloud,
@@ -114,6 +119,74 @@ export default function ChatPage() {
 
 </Steps>
 
+## `useChatRuntime` Options
+
+<ParametersTable
+  parameters={[
+    {
+      name: "cloud",
+      type: "AssistantCloud",
+      description:
+        "Optional AssistantCloud instance for chat persistence and thread management.",
+    },
+    {
+      name: "adapters",
+      type: "RuntimeAdapters",
+      description:
+        "Optional runtime adapters to extend or override built-in functionality.",
+      children: [
+        {
+          type: "RuntimeAdapters",
+          parameters: [
+            {
+              name: "attachments",
+              type: "AttachmentAdapter",
+              description:
+                "Custom attachment adapter for file uploads. Defaults to the Vercel AI SDK attachment adapter.",
+            },
+            {
+              name: "speech",
+              type: "SpeechSynthesisAdapter",
+              description:
+                "Adapter for text-to-speech functionality.",
+            },
+            {
+              name: "dictation",
+              type: "DictationAdapter",
+              description:
+                "Adapter for speech-to-text dictation input.",
+            },
+            {
+              name: "feedback",
+              type: "FeedbackAdapter",
+              description:
+                "Adapter for collecting user feedback on messages.",
+            },
+            {
+              name: "history",
+              type: "ThreadHistoryAdapter",
+              description:
+                "Adapter for loading and saving thread history. Used to restore previous messages when switching threads.",
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "toCreateMessage",
+      type: "(message: AppendMessage) => CreateUIMessage",
+      description:
+        "Optional custom function to convert an assistant-ui AppendMessage into an AI SDK CreateUIMessage before sending. Use this to customize how outgoing messages are formatted, for example to add custom metadata or transform content parts.",
+    },
+    {
+      name: "transport",
+      type: "ChatTransport",
+      description:
+        "Custom transport implementation. Defaults to AssistantChatTransport which sends requests to '/api/chat'.",
+    },
+  ]}
+/>
+
 ## Telemetry
 
 The `useChatRuntime` hook captures full run telemetry including timing data. This integrates with the assistant-ui runtime to provide:
@@ -134,19 +207,26 @@ To capture model and usage data, add the `messageMetadata` callback to your AI S
 
 ```tsx title="app/api/chat/route.ts"
 import { streamText } from "ai";
+import { openai } from "@ai-sdk/openai";
 
 export async function POST(req: Request) {
+  const { messages } = await req.json();
+
   const result = streamText({
-    model: openai("gpt-5-mini"),
+    model: openai("gpt-4o-mini"),
     messages,
   });
 
   return result.toUIMessageStreamResponse({
     messageMetadata: ({ part }) => {
+      if (part.type === "finish") {
+        return {
+          usage: part.totalUsage,
+        };
+      }
       if (part.type === "finish-step") {
         return {
           modelId: part.response.modelId,
-          usage: part.usage,
         };
       }
       return undefined;
@@ -164,6 +244,7 @@ Use the `beforeReport` hook to add custom metadata or filter reports:
 ```tsx
 const cloud = new AssistantCloud({
   baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
+  anonymous: true,
   telemetry: {
     beforeReport: (report) => ({
       ...report,
@@ -180,6 +261,7 @@ Return `null` from `beforeReport` to skip reporting a specific run. To disable t
 The example above uses anonymous mode (browser session-based user ID) via the env var. For production apps with user accounts, pass an explicit cloud instance:
 
 ```tsx
+import { useMemo } from "react";
 import { useAuth } from "@clerk/nextjs";
 import { AssistantCloud } from "@assistant-ui/react";
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

package/.docs/raw/docs/cloud/ai-sdk.mdx

@@ -49,7 +49,7 @@ NEXT_PUBLIC_ASSISTANT_BASE_URL=https://proj-[YOUR-ID].assistant-api.com
 
 ### Install Dependencies
 
-<InstallCommand npm={["@assistant-ui/cloud-ai-sdk", "assistant-cloud", "@ai-sdk/react", "ai"]} />
+<InstallCommand npm={["@assistant-ui/cloud-ai-sdk", "@ai-sdk/react", "ai"]} />
 
 </Step>
 
@@ -151,7 +151,7 @@ const chat = useCloudChat({ threads: myThreads });
 | `options.threads` | `UseThreadsResult` | External thread management from `useThreads()`. Use when you need thread operations in a separate component or custom thread options like `includeArchived` |
 | `options.onSyncError` | `(error: Error) => void` | Callback invoked when a sync error occurs |
 
-All other [AI SDK `useChat` options](https://sdk.vercel.ai/docs/reference/ai-sdk-ui/use-chat) are also accepted.
+A subset of [AI SDK `useChat` options](https://sdk.vercel.ai/docs/reference/ai-sdk-ui/use-chat) are also accepted (those defined on `ChatInit`). Some options available on `useChat` such as `experimental_throttle` and `resume` are not supported.
 
 **Returns:** `UseCloudChatResult`
 
@@ -169,12 +169,15 @@ Plus all other properties from AI SDK's [`UseChatHelpers`](https://sdk.vercel.ai
 
 | Value | Type | Description |
 |-------|------|-------------|
+| `threads.cloud` | `AssistantCloud` | The cloud instance used for thread operations |
 | `threads.threads` | `CloudThread[]` | Active threads sorted by recency |
 | `threads.threadId` | `string \| null` | Current thread ID (`null` for a new unsaved chat) |
 | `threads.selectThread` | `(id: string \| null) => void` | Switch threads or pass `null` for a new chat |
 | `threads.isLoading` | `boolean` | `true` during initial load or refresh |
 | `threads.error` | `Error \| null` | Last error, if any |
 | `threads.refresh` | `() => Promise<boolean>` | Re-fetch the thread list |
+| `threads.get` | `(id: string) => Promise<CloudThread \| null>` | Fetch a single thread by ID |
+| `threads.create` | `(options?: \{ externalId?: string \}) => Promise<CloudThread \| null>` | Create a new thread |
 | `threads.delete` | `(id: string) => Promise<boolean>` | Delete a thread |
 | `threads.rename` | `(id: string, title: string) => Promise<boolean>` | Rename a thread |
 | `threads.archive` | `(id: string) => Promise<boolean>` | Archive a thread |
@@ -206,31 +209,40 @@ The `useCloudChat` hook automatically reports run telemetry to Assistant Cloud a
 
 **Automatically captured:**
 - `status` — `"completed"` or `"incomplete"` based on response content
-- `tool_calls` — Tool invocations with name, arguments, results, and source (MCP, frontend, or backend)
+- `tool_calls` — Tool invocations with name, arguments, and results. MCP tool calls are explicitly tagged with `tool_source: "mcp"`
 - `total_steps` — Number of reasoning/tool steps in the response
 - `output_text` — Full response text (truncated at 50K characters)
 
 **Requires route configuration:**
 - `model_id` — The model used for the response
 - `input_tokens` / `output_tokens` — Token usage statistics
+- `reasoning_tokens` — Tokens used for chain-of-thought reasoning (e.g. o1/o3 models)
+- `cached_input_tokens` — Input tokens served from the provider's prompt cache
 
 To capture model and usage data, configure the `messageMetadata` callback in your AI SDK route:
 
 ```tsx title="app/api/chat/route.ts"
 import { streamText } from "ai";
+import { openai } from "@ai-sdk/openai";
 
 export async function POST(req: Request) {
+  const { messages } = await req.json();
+
   const result = streamText({
-    model: openai("gpt-5-mini"),
+    model: openai("gpt-4o-mini"),
     messages,
   });
 
   return result.toUIMessageStreamResponse({
     messageMetadata: ({ part }) => {
+      if (part.type === "finish") {
+        return {
+          usage: part.totalUsage,
+        };
+      }
       if (part.type === "finish-step") {
         return {
           modelId: part.response.modelId,
-          usage: part.usage,
         };
       }
       return undefined;
@@ -250,6 +262,7 @@ Use the `beforeReport` hook to enrich or filter telemetry:
 ```tsx
 const cloud = new AssistantCloud({
   baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
+  anonymous: true,
   telemetry: {
     beforeReport: (report) => ({
       ...report,
@@ -266,6 +279,7 @@ Return `null` from `beforeReport` to skip reporting a specific run. To disable t
 The example above uses anonymous mode (browser session-based user ID) via the env var. For production apps with user accounts, pass an explicit cloud instance:
 
 ```tsx
+import { useMemo } from "react";
 import { useAuth } from "@clerk/nextjs";
 import { AssistantCloud } from "assistant-cloud";
 import { useCloudChat } from "@assistant-ui/cloud-ai-sdk";

package/.docs/raw/docs/cloud/langgraph.mdx

@@ -74,7 +74,7 @@ import {
   AssistantRuntimeProvider,
 } from "@assistant-ui/react";
 import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
-import { createThread, getThreadState, sendMessage } from "@/lib/chatApi";
+import { createThread, deleteThread, getThreadState, sendMessage } from "@/lib/chatApi";
 import { LangChainMessage } from "@assistant-ui/react-langgraph";
 import { useMemo } from "react";
 
@@ -114,6 +114,9 @@ export function MyRuntimeProvider({
           (state.values as { messages?: LangChainMessage[] }).messages ?? [],
       };
     },
+    delete: async (externalId) => {
+      await deleteThread(externalId);
+    },
   });
 
   return (
@@ -136,7 +139,7 @@ import {
   AssistantRuntimeProvider,
 } from "@assistant-ui/react";
 import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
-import { createThread, getThreadState, sendMessage } from "@/lib/chatApi";
+import { createThread, deleteThread, getThreadState, sendMessage } from "@/lib/chatApi";
 import { LangChainMessage } from "@assistant-ui/react-langgraph";
 import { useAuth } from "@clerk/nextjs";
 import { useMemo } from "react";
@@ -179,6 +182,9 @@ export function MyRuntimeProvider({
           (state.values as { messages?: LangChainMessage[] }).messages ?? [],
       };
     },
+    delete: async (externalId) => {
+      await deleteThread(externalId);
+    },
   });
 
   return (
@@ -199,7 +205,11 @@ export function MyRuntimeProvider({
 </Tabs>
 
 <Callout type="info">
-  The `useLangGraphRuntime` hook now directly accepts `cloud`, `create`, and `load` parameters for simplified thread management. The runtime handles thread lifecycle internally.
+  The `useLangGraphRuntime` hook accepts `cloud`, `create`, `load`, and `delete` parameters for simplified thread management. The runtime handles the thread lifecycle internally.
+
+  - **`create`**: Called when creating a new thread. Returns `{ externalId }` with your backend's thread ID.
+  - **`load`**: Called when switching to an existing thread. Returns the thread's messages (and optionally interrupts).
+  - **`delete`**: Called when deleting a thread. Receives the thread's `externalId`. When provided, users can delete threads from the thread list UI.
 </Callout>
 
 </Step>

package/.docs/raw/docs/ink/adapters.mdx

@@ -0,0 +1,41 @@
+---
+title: Adapters
+description: Title generation adapters for React Ink.
+---
+
+Adapters customize runtime behavior. They can be passed as options to `useLocalRuntime` or `useRemoteThreadListRuntime`.
+
+## RemoteThreadListAdapter
+
+Title generation is configured via the `generateTitle` method on `RemoteThreadListAdapter`. See the [Custom Backend](/docs/ink/custom-backend) page for a full example.
+
+```tsx
+import type { RemoteThreadListAdapter } from "@assistant-ui/react-ink";
+import { createAssistantStream } from "assistant-stream";
+
+const myAdapter: RemoteThreadListAdapter = {
+  // ... other methods ...
+
+  async generateTitle(remoteId, unstable_messages) {
+    return createAssistantStream(async (controller) => {
+      const res = await fetch(`/api/threads/${remoteId}/title`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ messages: unstable_messages }),
+      });
+      const { title } = await res.json();
+      controller.appendText(title);
+    });
+  },
+};
+```
+
+## Which option to choose?
+
+| | ChatModelAdapter + `useLocalRuntime` | RemoteThreadListAdapter + `useRemoteThreadListRuntime` |
+|---|---|---|
+| **Thread storage** | In-memory | Your backend |
+| **Message storage** | In-memory | In-memory (can add history adapter for server-side) |
+| **Cross-session persistence** | No | Yes |
+| **Setup complexity** | Minimal | Moderate |
+| **Best for** | CLI tools, demos, prototypes | Production apps with persistence |

package/.docs/raw/docs/ink/custom-backend.mdx

@@ -0,0 +1,203 @@
+---
+title: Custom Backend
+description: Connect your terminal app to your own backend API.
+---
+
+By default, `useLocalRuntime` manages threads and messages in memory. 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-ink";
+
+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="app.tsx"
+import { useLocalRuntime, AssistantRuntimeProvider } from "@assistant-ui/react-ink";
+import { myChatAdapter } from "./adapters/my-chat-adapter.js";
+
+export function App() {
+  const runtime = useLocalRuntime(myChatAdapter);
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {/* your chat UI */}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+This gives you:
+
+- Streaming chat responses from your API
+- In-memory thread list (lost on process exit)
+- Multi-thread support
+
+## Option 2: Full backend thread management
+
+When you want your backend to own thread state (e.g. for persistence across sessions, 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-ink";
+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="app.tsx"
+import {
+  useLocalRuntime,
+  useRemoteThreadListRuntime,
+  AssistantRuntimeProvider,
+} from "@assistant-ui/react-ink";
+import { myChatAdapter } from "./adapters/my-chat-adapter.js";
+import { myThreadListAdapter } from "./adapters/my-thread-list-adapter.js";
+
+function useAppRuntime() {
+  return useRemoteThreadListRuntime({
+    runtimeHook: () => useLocalRuntime(myChatAdapter),
+    adapter: myThreadListAdapter,
+  });
+}
+
+export 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 (process lifetime) | Your backend |
+| **Message storage** | In-memory | On-device (can add history adapter for server-side) |
+| **Cross-session persistence** | No | Yes |
+| **Setup complexity** | Minimal | Moderate |
+| **Best for** | CLI tools, demos, prototypes | Production apps with persistence |