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

package/.docs/raw/docs/guides/Attachments.mdx

@@ -5,6 +5,7 @@ title: Attachments
 import { AttachmentSample } from "../../../components/samples/attachment-sample";
 import { Steps, Step } from "fumadocs-ui/components/steps";
 import { Callout } from "fumadocs-ui/components/callout";
+import { Tab, Tabs } from "fumadocs-ui/components/tabs";
 
 Enable users to attach files to their messages, enhancing conversations with images, documents, and other content.
 
@@ -27,10 +28,30 @@ The attachment system in assistant-ui provides a flexible framework for handling
 
 First, add the attachment UI components to your project:
 
+<Tabs items={["assistant-ui", "shadcn (namespace)", "shadcn"]}>
+  <Tab>
+
+```sh
+npx assistant-ui@latest add attachment
+```
+
+  </Tab>
+  <Tab>
+
+```sh
+npx shadcn@latest add @assistant-ui/attachment
+```
+
+  </Tab>
+  <Tab>
+
 ```sh
 npx shadcn@latest add "https://r.assistant-ui.com/attachment"
 ```
 
+  </Tab>
+</Tabs>
+
 This adds `/components/assistant-ui/attachment.tsx` to your project.
 
 <Callout type="tip">

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: