@assistant-ui/mcp-docs-server 0.1.9 → 0.1.10

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

@@ -2,9 +2,9 @@
 title: Chat History for LangGraph Cloud
 ---
 
-import { Steps, Step } from 'fumadocs-ui/components/steps';
-import { Callout } from 'fumadocs-ui/components/callout';
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import { Steps, Step } from "fumadocs-ui/components/steps";
+import { Callout } from "fumadocs-ui/components/callout";
+import { Tab, Tabs } from "fumadocs-ui/components/tabs";
 
 ## Overview
 
@@ -13,7 +13,8 @@ assistant-cloud provides thread management and persistent chat history for appli
 ## Prerequisites
 
 <Callout type="info">
-  You need an assistant-cloud account to follow this guide. [Sign up here](https://cloud.assistant-ui.com/) to get started.
+  You need an assistant-cloud account to follow this guide. [Sign up
+  here](https://cloud.assistant-ui.com/) to get started.
 </Callout>
 
 ## Setup Guide
@@ -75,40 +76,12 @@ Create a runtime provider that integrates LangGraph with assistant-cloud. Choose
 import {
   AssistantCloud,
   AssistantRuntimeProvider,
-  useCloudThreadListRuntime,
-  useThreadListItemRuntime,
 } from "@assistant-ui/react";
 import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
 import { createThread, getThreadState, sendMessage } from "@/lib/chatApi";
 import { LangChainMessage } from "@assistant-ui/react-langgraph";
 import { useMemo } from "react";
 
-const useMyLangGraphRuntime = () => {
-  const threadListItemRuntime = useThreadListItemRuntime();
-  
-  const runtime = useLangGraphRuntime({
-    stream: async function* (messages) {
-      const { externalId } = await threadListItemRuntime.initialize();
-      if (!externalId) throw new Error("Thread not found");
-
-      return sendMessage({
-        threadId: externalId,
-        messages,
-      });
-    },
-
-    onSwitchToThread: async (externalId) => {
-      const state = await getThreadState(externalId);
-      return {
-        messages:
-          (state.values as { messages?: LangChainMessage[] }).messages ?? [],
-      };
-    },
-  });
-
-  return runtime;
-};
-
 export function MyRuntimeProvider({
   children,
 }: Readonly<{
@@ -123,13 +96,28 @@ export function MyRuntimeProvider({
     [],
   );
 
-  const runtime = useCloudThreadListRuntime({
+  const runtime = useLangGraphRuntime({
     cloud,
-    runtimeHook: useMyLangGraphRuntime,
+    stream: async function* (messages, { initialize }) {
+      const { externalId } = await initialize();
+      if (!externalId) throw new Error("Thread not found");
+
+      return sendMessage({
+        threadId: externalId,
+        messages,
+      });
+    },
     create: async () => {
       const { thread_id } = await createThread();
       return { externalId: thread_id };
     },
+    load: async (externalId) => {
+      const state = await getThreadState(externalId);
+      return {
+        messages:
+          (state.values as { messages?: LangChainMessage[] }).messages ?? [],
+      };
+    },
   });
 
   return (
@@ -150,8 +138,6 @@ export function MyRuntimeProvider({
 import {
   AssistantCloud,
   AssistantRuntimeProvider,
-  useCloudThreadListRuntime,
-  useThreadListItemRuntime,
 } from "@assistant-ui/react";
 import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
 import { createThread, getThreadState, sendMessage } from "@/lib/chatApi";
@@ -159,32 +145,6 @@ import { LangChainMessage } from "@assistant-ui/react-langgraph";
 import { useAuth } from "@clerk/nextjs";
 import { useMemo } from "react";
 
-const useMyLangGraphRuntime = () => {
-  const threadListItemRuntime = useThreadListItemRuntime();
-  
-  const runtime = useLangGraphRuntime({
-    stream: async function* (messages) {
-      const { externalId } = await threadListItemRuntime.initialize();
-      if (!externalId) throw new Error("Thread not found");
-
-      return sendMessage({
-        threadId: externalId,
-        messages,
-      });
-    },
-
-    onSwitchToThread: async (externalId) => {
-      const state = await getThreadState(externalId);
-      return {
-        messages:
-          (state.values as { messages?: LangChainMessage[] }).messages ?? []
-      };
-    },
-  });
-
-  return runtime;
-};
-
 export function MyRuntimeProvider({
   children,
 }: Readonly<{
@@ -201,13 +161,28 @@ export function MyRuntimeProvider({
     [getToken],
   );
 
-  const runtime = useCloudThreadListRuntime({
+  const runtime = useLangGraphRuntime({
     cloud,
-    runtimeHook: useMyLangGraphRuntime,
+    stream: async function* (messages, { initialize }) {
+      const { externalId } = await initialize();
+      if (!externalId) throw new Error("Thread not found");
+
+      return sendMessage({
+        threadId: externalId,
+        messages,
+      });
+    },
     create: async () => {
       const { thread_id } = await createThread();
       return { externalId: thread_id };
     },
+    load: async (externalId) => {
+      const state = await getThreadState(externalId);
+      return {
+        messages:
+          (state.values as { messages?: LangChainMessage[] }).messages ?? [],
+      };
+    },
   });
 
   return (
@@ -219,7 +194,8 @@ export function MyRuntimeProvider({
 ```
 
 <Callout type="info">
-  For Clerk authentication, configure the `"assistant-ui"` token template in your Clerk dashboard.
+  For Clerk authentication, configure the `"assistant-ui"` token template in
+  your Clerk dashboard.
 </Callout>
 
 </Tab>
@@ -227,7 +203,7 @@ export function MyRuntimeProvider({
 </Tabs>
 
 <Callout type="info">
-  The `useMyLangGraphRuntime` hook is extracted into a separate function because it will be mounted multiple times, once per active thread.
+  The `useLangGraphRuntime` hook now directly accepts `cloud`, `create`, and `load` parameters for simplified thread management. The runtime handles thread lifecycle internally.
 </Callout>
 
 </Step>

package/.docs/raw/docs/getting-started.mdx

@@ -283,8 +283,7 @@ const ThreadWelcomeSuggestions: FC = () => {
       <ThreadPrimitive.Suggestion
         className="aui-thread-welcome-suggestion"
         prompt="What is the weather in Tokyo?"
-        method="replace"
-        autoSend
+        send
       >
         <span className="aui-thread-welcome-suggestion-text">
           What is the weather in Tokyo?
@@ -293,8 +292,7 @@ const ThreadWelcomeSuggestions: FC = () => {
       <ThreadPrimitive.Suggestion
         className="aui-thread-welcome-suggestion"
         prompt="What is assistant-ui?"
-        method="replace"
-        autoSend
+        send
       >
         <span className="aui-thread-welcome-suggestion-text">
           What is assistant-ui?

package/.docs/raw/docs/guides/ToolUI.mdx

@@ -378,17 +378,42 @@ const DatePickerToolUI = makeAssistantToolUI<
 
 ### Multi-Step Interactions
 
-Build complex workflows with multiple user interactions:
+Build complex workflows with human-in-the-loop patterns for multi-step user interactions:
 
 ```tsx
-const ApprovalToolUI = makeAssistantToolUI<
-  { action: string; details: any },
-  { approved: boolean; reason?: string }
->({
+const DeleteProjectTool = makeAssistantTool({
+  toolName: "deleteProject",
+  execute: async ({ projectId }, { human }) => {
+    const response = await human({ action, details });
+    if (!response.approved) throw new Error("Project deletion cancelled");
+
+    await deleteProject(projectId);
+    return { success: true };
+  },
+});
+
+const ApprovalTool = makeAssistantTool({
+  ...tool({
+    description: "Request user approval for an action",
+    parameters: z.object({
+      action: z.string(),
+      details: z.any(),
+    }),
+    execute: async ({ action, details }, { human }) => {
+      // Request approval from user
+      const response = await human({ action, details });
+
+      return {
+        approved: response.approved,
+        reason: response.reason,
+      };
+    },
+  }),
   toolName: "requestApproval",
-  render: ({ args, result, addResult }) => {
+  render: ({ args, result, interrupt, resume }) => {
     const [reason, setReason] = useState("");
 
+    // Show result after approval/rejection
     if (result) {
       return (
         <div className={result.approved ? "text-green-600" : "text-red-600"}>
@@ -397,41 +422,53 @@ const ApprovalToolUI = makeAssistantToolUI<
       );
     }
 
-    return (
-      <div className="rounded border-2 border-yellow-400 p-4">
-        <h4 className="font-bold">Approval Required</h4>
-        <p className="my-2">{args.action}</p>
-        <pre className="rounded bg-gray-100 p-2 text-sm">
-          {JSON.stringify(args.details, null, 2)}
-        </pre>
-
-        <div className="mt-4 flex gap-2">
-          <button
-            onClick={() => addResult({ approved: true })}
-            className="rounded bg-green-500 px-4 py-2 text-white"
-          >
-            Approve
-          </button>
-          <button
-            onClick={() => addResult({ approved: false, reason })}
-            className="rounded bg-red-500 px-4 py-2 text-white"
-          >
-            Reject
-          </button>
-          <input
-            type="text"
-            placeholder="Rejection reason..."
-            value={reason}
-            onChange={(e) => setReason(e.target.value)}
-            className="flex-1 rounded border px-2"
-          />
+    // Show approval UI when waiting for user input
+    if (interrupt) {
+      return (
+        <div className="rounded border-2 border-yellow-400 p-4">
+          <h4 className="font-bold">Approval Required</h4>
+          <p className="my-2">{interrupt.payload.action}</p>
+          <pre className="rounded bg-gray-100 p-2 text-sm">
+            {JSON.stringify(interrupt.payload.details, null, 2)}
+          </pre>
+
+          <div className="mt-4 flex gap-2">
+            <button
+              onClick={() => resume({ approved: true })}
+              className="rounded bg-green-500 px-4 py-2 text-white"
+            >
+              Approve
+            </button>
+            <button
+              onClick={() => resume({ approved: false, reason })}
+              className="rounded bg-red-500 px-4 py-2 text-white"
+            >
+              Reject
+            </button>
+            <input
+              type="text"
+              placeholder="Rejection reason..."
+              value={reason}
+              onChange={(e) => setReason(e.target.value)}
+              className="flex-1 rounded border px-2"
+            />
+          </div>
         </div>
-      </div>
-    );
+      );
+    }
+
+    return <div>Processing...</div>;
   },
 });
 ```
 
+<Callout type="tip">
+  Use tool human input (`human()` / `resume()`) for workflows that need to
+  pause tool execution and wait for user input. Use `addResult()` for "human
+  tools" where the AI requests a tool call but the entire execution happens
+  through user interaction.
+</Callout>
+
 ## Advanced Features
 
 ### Tool Status Handling
@@ -589,14 +626,52 @@ type ToolUIRenderProps<TArgs, TResult> = {
   toolName: string;
   toolCallId: string;
 
-  // Interactive callback
+  // Interactive callbacks
   addResult: (result: TResult) => void;
+  resume: (payload: unknown) => void;
+
+  // Interrupt state
+  interrupt?: { type: "human"; payload: unknown }; // Payload from context.human()
 
   // Optional artifact data
   artifact?: unknown;
 };
 ```
 
+### Human Input Handling
+
+When a tool calls `human()` during execution, the payload becomes available in the render function as `interrupt.payload`:
+
+```tsx
+const ConfirmationToolUI = makeAssistantToolUI<
+  { action: string },
+  { confirmed: boolean }
+>({
+  toolName: "confirmAction",
+  render: ({ args, result, interrupt, resume }) => {
+    // Tool is waiting for user input
+    if (interrupt) {
+      return (
+        <div className="confirmation-dialog">
+          <p>Confirm: {interrupt.payload.message}</p>
+          <button onClick={() => resume(true)}>Yes</button>
+          <button onClick={() => resume(false)}>No</button>
+        </div>
+      );
+    }
+
+    // Tool completed
+    if (result) {
+      return <div>Action {result.confirmed ? "confirmed" : "cancelled"}</div>;
+    }
+
+    return <div>Processing...</div>;
+  },
+});
+```
+
+Learn more about tool human input in the [Tools Guide](/docs/guides/Tools#tool-human-input).
+
 ## Best Practices
 
 ### 1. Handle All Status States

package/.docs/raw/docs/guides/Tools.mdx

@@ -359,13 +359,167 @@ const RefundTool = makeAssistantTool({
 });
 ```
 
+### Tool Human Input
+
+Tools can pause their execution to request user input or approval before continuing. This is useful for:
+
+- Requesting user confirmation for sensitive operations
+- Collecting additional information mid-execution
+- Implementing progressive disclosure workflows
+- Building interactive, multi-step tool experiences
+
+```tsx
+import { makeAssistantTool, tool } from "@assistant-ui/react";
+import { z } from "zod";
+
+const confirmationTool = tool({
+  description: "Send an email with confirmation",
+  parameters: z.object({
+    to: z.string(),
+    subject: z.string(),
+    body: z.string(),
+  }),
+  execute: async ({ to, subject, body }, { human }) => {
+    // Request user confirmation before sending
+    const confirmed = await human({
+      type: "confirmation",
+      action: "send-email",
+      details: { to, subject },
+    });
+
+    if (!confirmed) {
+      return {
+        status: "cancelled",
+        message: "Email sending cancelled by user",
+      };
+    }
+
+    // Proceed with sending the email
+    await sendEmail({ to, subject, body });
+    return { status: "sent", message: `Email sent to ${to}` };
+  },
+});
+
+const EmailTool = makeAssistantTool({
+  ...confirmationTool,
+  toolName: "sendEmail",
+  render: ({ args, result, interrupt, resume }) => {
+    // The interrupt payload is available when the tool is waiting for user input
+    if (interrupt) {
+      return (
+        <div className="confirmation-dialog">
+          <h3>Confirm Email</h3>
+          <p>Send email to: {interrupt.payload.details.to}</p>
+          <p>Subject: {interrupt.payload.details.subject}</p>
+          <div className="actions">
+            <button onClick={() => resume(true)}>Confirm</button>
+            <button onClick={() => resume(false)}>Cancel</button>
+          </div>
+        </div>
+      );
+    }
+
+    // Show the result after completion
+    if (result) {
+      return (
+        <div className="email-result">
+          <p>{result.message}</p>
+        </div>
+      );
+    }
+
+    // Show loading state
+    return <div>Preparing email...</div>;
+  },
+});
+```
+
+#### Human Input Behavior
+
+- **Payload**: The object passed to `human()` is available in the `render` function as `interrupt.payload`
+- **Type**: The `interrupt` object has the structure `{ type: "human", payload: ... }`
+- **Resume**: Call `resume(payload)` to continue execution - the payload becomes the resolved value of the `human()` call
+- **Multiple Requests**: If `human()` is called multiple times, previous requests are automatically rejected with an error
+- **Cancellation**: If the tool execution is aborted (e.g., user cancels the message), all pending requests are rejected
+
+#### Advanced Human Input Patterns
+
+You can use human input for complex multi-step interactions:
+
+```tsx
+const wizardTool = tool({
+  description: "Multi-step data processing wizard",
+  parameters: z.object({
+    dataSource: z.string(),
+  }),
+  execute: async ({ dataSource }, { human }) => {
+    // Step 1: Load data
+    const data = await loadData(dataSource);
+
+    // Step 2: Request user to select columns
+    const selectedColumns = await human({
+      type: "column-selection",
+      availableColumns: data.columns,
+    });
+
+    // Step 3: Request processing options
+    const options = await human({
+      type: "processing-options",
+      columns: selectedColumns,
+    });
+
+    // Step 4: Process data with user selections
+    const result = await processData(data, selectedColumns, options);
+    return result;
+  },
+});
+
+const WizardTool = makeAssistantTool({
+  ...wizardTool,
+  toolName: "dataWizard",
+  render: ({ args, result, interrupt, resume }) => {
+    if (interrupt?.payload.type === "column-selection") {
+      return (
+        <ColumnSelector
+          columns={interrupt.payload.availableColumns}
+          onSelect={(cols) => resume(cols)}
+        />
+      );
+    }
+
+    if (interrupt?.payload.type === "processing-options") {
+      return (
+        <ProcessingOptions
+          columns={interrupt.payload.columns}
+          onConfirm={(opts) => resume(opts)}
+        />
+      );
+    }
+
+    if (result) {
+      return <ResultDisplay data={result} />;
+    }
+
+    return <div>Loading...</div>;
+  },
+});
+```
+
+<Callout type="note">
+  When a tool calls `human()` multiple times (e.g., for multi-step
+  workflows), each new request automatically rejects any previous pending
+  request. Make sure to handle potential errors if you need to support
+  cancellation of earlier steps.
+</Callout>
+
 ### MCP (Model Context Protocol) Tools
 
 Integration with MCP servers using AI SDK v5's experimental MCP support:
 
 <Callout type="warning">
-  MCP support in AI SDK v5 is experimental. The API may change in future releases.
-  Make sure to install the MCP SDK: `npm install @modelcontextprotocol/sdk`
+  MCP support in AI SDK v5 is experimental. The API may change in future
+  releases. Make sure to install the MCP SDK: `npm install
+  @modelcontextprotocol/sdk`
 </Callout>
 
 ```tsx
@@ -414,15 +568,13 @@ import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 // HTTP transport
 const httpClient = await experimental_createMCPClient({
   transport: new StreamableHTTPClientTransport(
-    new URL("http://localhost:3000/mcp")
+    new URL("http://localhost:3000/mcp"),
   ),
 });
 
 // Server-Sent Events transport
 const sseClient = await experimental_createMCPClient({
-  transport: new SSEClientTransport(
-    new URL("http://localhost:3000/sse")
-  ),
+  transport: new SSEClientTransport(new URL("http://localhost:3000/sse")),
 });
 ```
 
@@ -560,9 +712,21 @@ Tools receive additional context during execution:
 execute: async (args, context) => {
   // context.abortSignal - AbortSignal for cancellation
   // context.toolCallId - Unique identifier for this invocation
+  // context.human - Function to request human input
+
+  // Example: Request user confirmation
+  const userResponse = await context.human({
+    message: "Are you sure?",
+  });
 };
 ```
 
+The execution context provides:
+
+- **`abortSignal`**: An `AbortSignal` that triggers when the tool execution is cancelled
+- **`toolCallId`**: A unique identifier for this specific tool invocation
+- **`human`**: A function that pauses execution and requests user input. The payload passed to `human()` becomes available in the render function, and the value passed to `resume()` becomes the resolved value of the `human()` call
+
 ## Runtime Integration
 
 Each integration handles tools differently: