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

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:

package/.docs/raw/docs/migrations/react-langgraph-v0-7.mdx

@@ -0,0 +1,324 @@
+---
+title: Migrating to react-langgraph v0.7
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+import { Steps, Step } from "fumadocs-ui/components/steps";
+
+## Overview
+
+This guide helps you migrate from the previous LangGraph integration pattern to the new simplified API introduced in `@assistant-ui/react-langgraph` v0.7. The new API consolidates thread management directly into `useLangGraphRuntime`, eliminating the need for separate runtime hooks and manual thread state management.
+
+## Key Changes
+
+### 1. Simplified Thread Management
+
+The `useLangGraphRuntime` hook now directly handles thread lifecycle:
+- No more `useRemoteThreadListRuntime` wrapper
+- No more separate runtime hook functions
+- Thread management is built into the core runtime
+
+### 2. New `initialize` Parameter
+
+The `stream` function now receives an `initialize` parameter that handles thread creation and loading automatically.
+
+### 3. Direct Cloud Integration
+
+Cloud persistence can now be configured directly in `useLangGraphRuntime` with the `cloud` parameter.
+
+## Migration Steps
+
+<Steps>
+
+<Step>
+
+### Update Your Runtime Implementation
+
+#### Before (Old Pattern)
+
+```tsx
+import {
+  useCloudThreadListRuntime,
+  useThreadListItemRuntime,
+} from "@assistant-ui/react";
+import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
+
+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.messages,
+      };
+    },
+  });
+
+  return runtime;
+};
+
+// In your component:
+const runtime = useCloudThreadListRuntime({
+  cloud,
+  runtimeHook: useMyLangGraphRuntime,
+  create: async () => {
+    const { thread_id } = await createThread();
+    return { externalId: thread_id };
+  },
+});
+```
+
+#### After (New Pattern)
+
+```tsx
+import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
+
+// Directly in your component:
+const runtime = useLangGraphRuntime({
+  cloud, // Optional: for cloud persistence
+  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.messages,
+    };
+  },
+});
+```
+
+</Step>
+
+<Step>
+
+### Update Import Statements
+
+Remove unused imports:
+
+```diff
+- import {
+-   useCloudThreadListRuntime,
+-   useThreadListItemRuntime,
+- } from "@assistant-ui/react";
++ import { AssistantCloud } from "@assistant-ui/react";
+```
+
+</Step>
+
+<Step>
+
+### Simplify Component Structure
+
+You no longer need a separate runtime hook function. Everything can be defined directly in your component or provider:
+
+```tsx
+export function MyRuntimeProvider({ children }) {
+  const cloud = useMemo(
+    () => new AssistantCloud({
+      baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL,
+    }),
+    []
+  );
+
+  const runtime = useLangGraphRuntime({
+    cloud,
+    // All configuration inline
+    stream: async function* (messages, { initialize }) {
+      // Your stream implementation
+    },
+    create: async () => {
+      // Your create implementation
+    },
+    load: async (externalId) => {
+      // Your load implementation
+    },
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Step>
+
+<Step>
+
+### Update Method Names
+
+Rename methods to match the new API:
+
+- `onSwitchToThread` → `load`
+- `onSwitchToNewThread` → handled automatically via `create`
+- Thread ID management is now automatic
+
+</Step>
+
+</Steps>
+
+## API Reference Changes
+
+### Old API
+
+```typescript
+type OldLangGraphRuntimeOptions = {
+  threadId?: string;
+  stream: (messages: Message[]) => AsyncGenerator;
+  onSwitchToNewThread?: () => Promise<void>;
+  onSwitchToThread?: (threadId: string) => Promise<ThreadState>;
+};
+```
+
+### New API
+
+```typescript
+type NewLangGraphRuntimeOptions = {
+  cloud?: AssistantCloud;
+  stream: (
+    messages: Message[],
+    context: {
+      initialize: () => Promise<{
+        remoteId: string;
+        externalId: string | undefined;
+      }>
+    }
+  ) => AsyncGenerator;
+  create?: () => Promise<{ externalId: string }>;
+  load?: (externalId: string) => Promise<ThreadState>;
+  delete?: (externalId: string) => Promise<void>;
+};
+```
+
+## Benefits of the New API
+
+1. **Simpler Setup**: No need for multiple runtime hooks and wrappers
+2. **Cleaner Code**: All configuration in one place
+3. **Better Type Safety**: More explicit types for thread management
+4. **Automatic Thread Handling**: The runtime manages thread lifecycle internally
+5. **Optional Cloud Integration**: Add cloud persistence with a single parameter
+
+## Common Migration Issues
+
+<Callout type="warning">
+  **Breaking Change**: The `threadId` and `onSwitchToNewThread` parameters are no longer supported. Use the new `create` and `load` methods instead.
+</Callout>
+
+### Issue: `threadListItemRuntime` is not defined
+
+**Solution**: Remove references to `useThreadListItemRuntime()`. Use the `initialize` parameter in the stream function instead.
+
+### Issue: Thread switching doesn't work
+
+**Solution**: Ensure you've implemented both `create` and `load` functions. The runtime needs both to manage thread lifecycle.
+
+### Issue: Cloud persistence not working
+
+**Solution**: Pass the `AssistantCloud` instance directly to `useLangGraphRuntime` via the `cloud` parameter.
+
+## Example: Complete Migration
+
+Here's a complete before and after example for a typical LangGraph integration:
+
+### Before
+
+```tsx title="runtime-provider.tsx"
+import {
+  AssistantCloud,
+  AssistantRuntimeProvider,
+  useCloudThreadListRuntime,
+  useThreadListItemRuntime,
+} from "@assistant-ui/react";
+import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
+
+const useMyRuntime = () => {
+  const threadListItemRuntime = useThreadListItemRuntime();
+
+  return useLangGraphRuntime({
+    stream: async function* (messages) {
+      const { externalId } = await threadListItemRuntime.initialize();
+      // ... implementation
+    },
+    onSwitchToThread: async (externalId) => {
+      // ... implementation
+    },
+  });
+};
+
+export function Provider({ children }) {
+  const cloud = new AssistantCloud({ /* config */ });
+
+  const runtime = useCloudThreadListRuntime({
+    cloud,
+    runtimeHook: useMyRuntime,
+    create: async () => { /* ... */ },
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+### After
+
+```tsx title="runtime-provider.tsx"
+import {
+  AssistantCloud,
+  AssistantRuntimeProvider,
+} from "@assistant-ui/react";
+import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
+
+export function Provider({ children }) {
+  const cloud = new AssistantCloud({ /* config */ });
+
+  const runtime = useLangGraphRuntime({
+    cloud,
+    stream: async function* (messages, { initialize }) {
+      const { externalId } = await initialize();
+      // ... implementation
+    },
+    create: async () => { /* ... */ },
+    load: async (externalId) => {
+      // ... implementation (formerly onSwitchToThread)
+    },
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+## Need Help?
+
+If you encounter issues during migration:
+1. Check the updated [LangGraph documentation](/docs/runtimes/langgraph)
+2. Review the [example implementation](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-langgraph)
+3. Report issues on [GitHub](https://github.com/assistant-ui/assistant-ui/issues)

package/.docs/raw/docs/runtimes/ai-sdk/use-chat.mdx

@@ -130,7 +130,7 @@ const runtime = useChatRuntime({
 <Callout type="info">
   By default, `useChatRuntime` uses `AssistantChatTransport` which automatically
   forwards system messages and frontend tools to your backend API. This enables
-  your backend to receive the full context from the Assistant UI.
+  your backend to receive the full context from the assistant-ui.
 </Callout>
 
 ### Custom Transport Configuration
@@ -165,7 +165,7 @@ const runtime = useChatRuntime({
 
 #### Transport Options
 
-- **`AssistantChatTransport`** (default): Automatically forwards system messages and frontend tools from the Assistant UI context to your backend
+- **`AssistantChatTransport`** (default): Automatically forwards system messages and frontend tools from the assistant-ui context to your backend
 - **`DefaultChatTransport`**: Standard AI SDK transport without automatic forwarding
 
 ### Using Frontend Tools with `frontendTools`

package/.docs/raw/docs/runtimes/custom/local.mdx

@@ -732,7 +732,7 @@ Provide follow-up suggestions:
 
 ```tsx
 const suggestionAdapter: SuggestionAdapter = {
-  async *get({ messages }) {
+  async *generate({ messages }) {
     // Analyze conversation context
     const lastMessage = messages[messages.length - 1];
 

package/.docs/raw/docs/runtimes/langgraph/index.mdx

@@ -61,7 +61,6 @@ npm install @assistant-ui/react @assistant-ui/react-ui @assistant-ui/react-langg
 ```tsx twoslash title="@/api/api/[...path]/route.ts"
 import { NextRequest, NextResponse } from "next/server";
 
-
 function getCorsHeaders() {
   return {
     "Access-Control-Allow-Origin": "*",
@@ -188,7 +187,6 @@ export const sendMessage = async (params: {
 // ---cut---
 "use client";
 
-import { useRef } from "react";
 import { Thread } from "@/components/assistant-ui";
 import { AssistantRuntimeProvider } from "@assistant-ui/react";
 import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
@@ -196,27 +194,21 @@ import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
 import { createThread, getThreadState, sendMessage } from "@/lib/chatApi";
 
 export function MyAssistant() {
-  const threadIdRef = useRef<string | undefined>();
   const runtime = useLangGraphRuntime({
-    threadId: threadIdRef.current,
-    stream: async (messages) => {
-      if (!threadIdRef.current) {
-        const { thread_id } = await createThread();
-        threadIdRef.current = thread_id;
-      }
-      const threadId = threadIdRef.current;
+    stream: async (messages, { initialize }) => {
+      const { externalId } = await initialize();
+      if (!externalId) throw new Error("Thread not found");
       return sendMessage({
-        threadId,
+        threadId: externalId,
         messages,
       });
     },
-    onSwitchToNewThread: async () => {
+    create: async () => {
       const { thread_id } = await createThread();
-      threadIdRef.current = thread_id;
+      return { externalId: thread_id };
     },
-    onSwitchToThread: async (threadId) => {
-      const state = await getThreadState(threadId);
-      threadIdRef.current = threadId;
+    load: async (externalId) => {
+      const state = await getThreadState(externalId);
       return {
         messages: state.values.messages,
         interrupts: state.tasks[0]?.interrupts,
@@ -306,14 +298,57 @@ import { convertLangChainMessages } from "@assistant-ui/react-langgraph";
 const threadMessage = convertLangChainMessages(langChainMessage);
 ```
 
-## Interrupt Persistence
+## Thread Management
+
+### Basic Thread Support
+
+The `useLangGraphRuntime` hook now includes built-in thread management capabilities:
+
+```typescript
+const runtime = useLangGraphRuntime({
+  stream: async (messages, { initialize }) => {
+    // initialize() creates or loads a thread and returns its IDs
+    const { remoteId, externalId } = await initialize();
+    // Use externalId (your backend's thread ID) for API calls
+    return sendMessage({ threadId: externalId, messages });
+  },
+  create: async () => {
+    // Called when creating a new thread
+    const { thread_id } = await createThread();
+    return { externalId: thread_id };
+  },
+  load: async (externalId) => {
+    // Called when loading an existing thread
+    const state = await getThreadState(externalId);
+    return {
+      messages: state.values.messages,
+      interrupts: state.tasks[0]?.interrupts,
+    };
+  },
+});
+```
 
-LangGraph supports interrupting the execution flow to request user input or handle specific interactions. These interrupts can be persisted and restored when switching between threads. This means that if a user switches away from a thread during an interaction (like waiting for user approval), the interaction state will be preserved when they return to that thread.
+### Cloud Persistence
+
+For persistent thread history across sessions, integrate with assistant-cloud:
+
+```typescript
+const runtime = useLangGraphRuntime({
+  cloud: new AssistantCloud({
+    baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL,
+  }),
+  // ... stream, create, load functions
+});
+```
+
+See the [Cloud Persistence guide](/docs/cloud/persistence/langgraph) for detailed setup instructions.
+
+## Interrupt Persistence
 
-To handle interrupts in your application:
+LangGraph supports interrupting the execution flow to request user input or handle specific interactions. These interrupts can be persisted and restored when switching between threads:
 
 1. Make sure your thread state type includes the `interrupts` field
-2. Return the interrupts from `onSwitchToThread` along with the messages
+2. Return the interrupts from the `load` function along with the messages
 3. The runtime will automatically restore the interrupt state when switching threads
 
 This feature is particularly useful for applications that require user approval flows, multi-step forms, or any other interactive elements that might span multiple thread switches.