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

package/.docs/raw/docs/copilots/assistant-frame.mdx

@@ -0,0 +1,397 @@
+---
+title: Assistant Frame API
+description: Share model context across iframe boundaries
+---
+
+The Assistant Frame API enables iframes to provide model context (tools and instructions) to a parent window's assistant. This is particularly useful for embedded applications, plugins, or sandboxed components that need to contribute capabilities to the main assistant.
+
+## Overview
+
+The Assistant Frame system consists of two main components:
+
+- **AssistantFrameProvider**: Runs inside the iframe and provides model context
+- **AssistantFrameHost**: Runs in the parent window and consumes context from iframes
+
+## Basic Usage
+
+### In the iframe (Provider)
+
+The iframe acts as a provider of model context using `AssistantFrameProvider`:
+
+```tsx
+// iframe.tsx
+import { AssistantFrameProvider } from "@assistant-ui/react";
+import { ModelContextRegistry } from "@assistant-ui/react";
+import { z } from "zod";
+
+// Create a registry to manage your model context
+const registry = new ModelContextRegistry();
+
+// Expose the registry to the parent window
+AssistantFrameProvider.addModelContextProvider(registry);
+
+// Add tools that will be available to the parent assistant
+registry.addTool({
+  toolName: "searchProducts",
+  description: "Search for products in the catalog",
+  parameters: z.object({
+    query: z.string(),
+    category: z.string().optional(),
+  }),
+  execute: async ({ query, category }) => {
+    // Tool implementation runs in the iframe
+    const results = await searchAPI(query, category);
+    return { products: results };
+  },
+});
+
+// Add system instructions
+const instructionHandle = registry.addInstruction(
+  "You are a helpful assistant.",
+);
+
+// update the instruction
+instructionHandle.update("You have access to a product catalog search tool.");
+```
+
+### In the parent window (Host)
+
+The parent window consumes the iframe's context using `AssistantFrameHost`:
+
+```tsx
+// parent.tsx
+import { useAssistantFrameHost } from "@assistant-ui/react";
+import { useRef } from "react";
+
+function ParentComponent() {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+
+  // Connect to the iframe's model context
+  useAssistantFrameHost({
+    iframeRef,
+    targetOrigin: "https://trusted-iframe-domain.com", // optional for increased security
+  });
+
+  return (
+    <div>
+      <Thread /> {/* Your assistant UI */}
+      <iframe
+        ref={iframeRef}
+        src="https://trusted-iframe-domain.com/embed"
+        title="Embedded App"
+      />
+    </div>
+  );
+}
+```
+
+## Advanced Usage
+
+### ModelContextRegistry
+
+The `ModelContextRegistry` provides a flexible way to manage model context dynamically:
+
+```tsx
+const registry = new ModelContextRegistry();
+
+// Add a tool with handle for updates
+const toolHandle = registry.addTool({
+  toolName: "convertCurrency",
+  description: "Convert between currencies",
+  parameters: z.object({ 
+    amount: z.number(),
+    from: z.string(),
+    to: z.string() 
+  }),
+  execute: async ({ amount, from, to }) => {
+    const rate = await fetchExchangeRate(from, to);
+    return { result: amount * rate, currency: to };
+  },
+});
+
+// Update the tool later
+toolHandle.update({
+  toolName: "convertCurrency",
+  description: "Convert between currencies with live rates", // Updated description
+  parameters: z.object({ 
+    amount: z.number(),
+    from: z.string(),
+    to: z.string(),
+    includesFees: z.boolean().optional()
+  }),
+  execute: async ({ amount, from, to, includesFees }) => {
+    const rate = await fetchExchangeRate(from, to);
+    const fee = includesFees ? 0.02 : 0; // 2% fee
+    return { 
+      result: amount * rate * (1 - fee), 
+      currency: to,
+      fee: includesFees ? amount * rate * fee : 0
+    };
+  },
+});
+
+// Remove the tool when no longer needed
+toolHandle.remove();
+
+// Add multiple instructions
+const instruction1 = registry.addInstruction("Be helpful and concise.");
+const instruction2 = registry.addInstruction("Use metric units.");
+
+// Remove instructions
+instruction1.remove();
+```
+
+### Multiple Providers
+
+You can register multiple model context providers in the same iframe:
+
+```tsx
+const catalogRegistry = new ModelContextRegistry();
+const analyticsRegistry = new ModelContextRegistry();
+
+// Add different tools to each registry
+catalogRegistry.addTool({
+  /* ... */
+});
+analyticsRegistry.addTool({
+  /* ... */
+});
+
+// Register both providers
+const unsubscribe1 =
+  AssistantFrameProvider.addModelContextProvider(catalogRegistry);
+const unsubscribe2 =
+  AssistantFrameProvider.addModelContextProvider(analyticsRegistry);
+
+// Later, unsubscribe if needed
+unsubscribe1();
+unsubscribe2();
+```
+
+### Security Considerations
+
+#### Origin Validation
+
+Both the provider and host can specify allowed origins for security:
+
+```tsx
+// In iframe - only accept messages from specific parent
+AssistantFrameProvider.addModelContextProvider(
+  registry,
+  "https://parent-app.com",
+);
+
+// In parent - only accept messages from specific iframe
+useAssistantFrameHost({
+  iframeRef,
+  targetOrigin: "https://iframe-app.com",
+});
+```
+
+#### Tool Execution
+
+Tools are executed in the iframe's context, keeping sensitive operations sandboxed:
+
+```tsx
+registry.addTool({
+  toolName: "accessDatabase",
+  description: "Query the database",
+  parameters: z.object({ query: z.string() }),
+  execute: async ({ query }) => {
+    // This runs in the iframe with iframe's permissions
+    // Parent cannot directly access the database
+    const results = await db.query(query);
+    return results;
+  },
+});
+```
+
+## API Reference
+
+### AssistantFrameProvider
+
+Static class that manages model context providers in an iframe.
+
+#### Methods
+
+##### `addModelContextProvider(provider, targetOrigin?)`
+
+Registers a model context provider to share with parent windows.
+
+```tsx
+const unsubscribe = AssistantFrameProvider.addModelContextProvider(
+  registry,
+  "https://parent-domain.com", // Optional origin restriction
+);
+```
+
+##### `dispose()`
+
+Cleans up all resources and removes all providers.
+
+```tsx
+AssistantFrameProvider.dispose();
+```
+
+### AssistantFrameHost
+
+Class that connects to an iframe's model context providers.
+
+#### Constructor
+
+```tsx
+const host = new AssistantFrameHost(
+  iframeWindow,
+  targetOrigin? // Optional origin restriction
+);
+```
+
+#### Methods
+
+##### `getModelContext()`
+
+Returns the current merged model context from the iframe.
+
+```tsx
+const context = host.getModelContext();
+// { system: "...", tools: { ... } }
+```
+
+##### `subscribe(callback)`
+
+Subscribes to model context changes.
+
+```tsx
+const unsubscribe = host.subscribe(() => {
+  console.log("Context updated:", host.getModelContext());
+});
+```
+
+##### `dispose()`
+
+Cleans up the connection to the iframe.
+
+```tsx
+host.dispose();
+```
+
+### useAssistantFrameHost
+
+React hook that manages the lifecycle of an AssistantFrameHost.
+
+```tsx
+useAssistantFrameHost({
+  iframeRef: RefObject<HTMLIFrameElement>,
+  targetOrigin?: string,
+});
+```
+
+### ModelContextRegistry
+
+A flexible registry for managing model context with dynamic updates.
+
+#### Methods
+
+##### `addTool(tool)`
+
+Adds a tool and returns a handle for updates/removal.
+
+```tsx
+const handle = registry.addTool({
+  toolName: string,
+  description?: string,
+  parameters: ZodSchema | JSONSchema,
+  execute: (args, context) => Promise<any>,
+});
+
+handle.update(newTool); // Update the tool
+handle.remove(); // Remove the tool
+```
+
+##### `addInstruction(instruction)`
+
+Adds a system instruction and returns a handle.
+
+```tsx
+const handle = registry.addInstruction("Be concise.");
+handle.update("Be detailed."); // Update instruction
+handle.remove(); // Remove instruction
+```
+
+##### `addProvider(provider)`
+
+Adds another model context provider.
+
+```tsx
+const handle = registry.addProvider(anotherProvider);
+handle.remove(); // Remove provider
+```
+
+## Use Cases
+
+### Embedded Analytics Dashboard
+
+An analytics iframe can provide data query tools to the parent assistant:
+
+```tsx
+// In analytics iframe
+registry.addTool({
+  toolName: "queryMetrics",
+  description: "Query analytics data",
+  parameters: z.object({
+    metric: z.string(),
+    timeRange: z.string(),
+  }),
+  execute: async ({ metric, timeRange }) => {
+    const data = await analyticsAPI.query(metric, timeRange);
+    return { data, visualization: createChart(data) };
+  },
+});
+```
+
+### Plugin System
+
+Third-party plugins can extend the assistant's capabilities:
+
+```tsx
+// In plugin iframe
+registry.addTool({
+  toolName: "translateText",
+  description: "Translate text to another language",
+  parameters: z.object({
+    text: z.string(),
+    targetLanguage: z.string(),
+  }),
+  execute: async ({ text, targetLanguage }) => {
+    return await pluginAPI.translate(text, targetLanguage);
+  },
+});
+```
+
+### Data Visualization
+
+Provide data visualization tools in an iframe:
+
+```tsx
+// In visualization iframe
+registry.addTool({
+  toolName: "createChart",
+  description: "Generate a chart from data",
+  parameters: z.object({ 
+    data: z.array(z.object({
+      label: z.string(),
+      value: z.number()
+    })),
+    chartType: z.enum(["bar", "line", "pie"]),
+    title: z.string().optional()
+  }),
+  execute: async ({ data, chartType, title }) => {
+    // Generate chart using a library like Chart.js or D3
+    const chartUrl = await generateChart(data, chartType, title);
+    return { 
+      chartUrl,
+      summary: `Created ${chartType} chart with ${data.length} data points`
+    };
+  },
+});
+```

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

@@ -22,7 +22,10 @@ import { Card, Cards } from "fumadocs-ui/components/card";
 # Create a new project with the default template
 npx assistant-ui@latest create
 
-# Or start with a template:
+# Or choose one of the following templates:
+# Assistant Cloud for baked in persistence and thread management
+npx assistant-ui@latest create -t cloud
+
 # LangGraph
 npx assistant-ui@latest create -t langgraph
 
@@ -686,11 +689,11 @@ import { ComponentPropsWithoutRef, forwardRef } from "react";
 import {
   Tooltip,
   TooltipContent,
-  TooltipProvider,
   TooltipTrigger,
 } from "@/components/ui/tooltip";
 import { Button } from "@/components/ui/button";
 import { cn } from "@/lib/utils";
+import { Slottable } from "@radix-ui/react-slot";
 
 export type TooltipIconButtonProps = ComponentPropsWithoutRef<typeof Button> & {
   tooltip: string;
@@ -702,23 +705,21 @@ export const TooltipIconButton = forwardRef<
   TooltipIconButtonProps
 >(({ children, tooltip, side = "bottom", className, ...rest }, ref) => {
   return (
-    <TooltipProvider>
-      <Tooltip>
-        <TooltipTrigger asChild>
-          <Button
-            variant="ghost"
-            size="icon"
-            {...rest}
-            className={cn("", className)}
-            ref={ref}
-          >
-            {children}
-            <span className="aui-sr-only">{tooltip}</span>
-          </Button>
-        </TooltipTrigger>
-        <TooltipContent side={side}>{tooltip}</TooltipContent>
-      </Tooltip>
-    </TooltipProvider>
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button
+          variant="ghost"
+          size="icon"
+          {...rest}
+          className={cn("aui-button-icon", className)}
+          ref={ref}
+        >
+          <Slottable>{children}</Slottable>
+          <span className="aui-sr-only">{tooltip}</span>
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent side={side}>{tooltip}</TooltipContent>
+    </Tooltip>
   );
 });
 

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

@@ -41,29 +41,22 @@ This adds `/components/assistant-ui/attachment.tsx` to your project.
   </Step>
   <Step>
 
-### Configure Attachment Adapter
+### Set up Runtime (No Configuration Required)
 
-Set up an attachment adapter in your runtime provider:
+For `useChatRuntime`, attachments work automatically without additional configuration:
 
 ```tsx title="/app/MyRuntimeProvider.tsx"
 import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
-import {
-  CompositeAttachmentAdapter,
-  SimpleImageAttachmentAdapter,
-  SimpleTextAttachmentAdapter,
-} from "@assistant-ui/react";
 
 const runtime = useChatRuntime({
   api: "/api/chat",
-  adapters: {
-    attachments: new CompositeAttachmentAdapter([
-      new SimpleImageAttachmentAdapter(),
-      new SimpleTextAttachmentAdapter(),
-    ]),
-  },
 });
 ```
 
+<Callout type="info">
+  **Note:** The AI SDK runtime handles attachments automatically. For other runtimes like `useLocalRuntime`, you may still need to configure attachment adapters as shown in the [Creating Custom Attachment Adapters](#creating-custom-attachment-adapters) section below.
+</Callout>
+
   </Step>
   <Step>
 

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

@@ -361,25 +361,68 @@ const RefundTool = makeAssistantTool({
 
 ### MCP (Model Context Protocol) Tools
 
-Integration with MCP servers:
+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`
+</Callout>
 
 ```tsx
-// Using AI SDK's MCP support
-import { createMCPClient } from "ai/mcp";
+// Server-side usage (e.g., in your API route)
+import { experimental_createMCPClient, streamText } from "ai";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 
-const mcpClient = createMCPClient({
-  servers: {
-    github: {
+export async function POST(req: Request) {
+  // Create MCP client with stdio transport
+  const client = await experimental_createMCPClient({
+    transport: new StdioClientTransport({
       command: "npx",
       args: ["@modelcontextprotocol/server-github"],
-    },
-  },
-});
+    }),
+  });
+
+  try {
+    // Get tools from the MCP server
+    const tools = await client.tools();
+
+    const result = streamText({
+      model: openai("gpt-4o"),
+      tools,
+      messages: convertToModelMessages(messages),
+    });
 
-// Tools are automatically available through the runtime
+    return result.toUIMessageStreamResponse();
+  } finally {
+    // Always close the client to release resources
+    await client.close();
+  }
+}
+
+// Frontend usage with assistant-ui
 const runtime = useChatRuntime({
-  api: "/api/chat",
-  tools: await mcpClient.getTools(),
+  api: "/api/chat", // Your API route that uses MCP tools
+});
+```
+
+Alternative transport options:
+
+```tsx
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+
+// HTTP transport
+const httpClient = await experimental_createMCPClient({
+  transport: new StreamableHTTPClientTransport(
+    new URL("http://localhost:3000/mcp")
+  ),
+});
+
+// Server-Sent Events transport
+const sseClient = await experimental_createMCPClient({
+  transport: new SSEClientTransport(
+    new URL("http://localhost:3000/sse")
+  ),
 });
 ```
 
@@ -483,7 +526,7 @@ const resilientTool = tool({
       } catch (error) {
         lastError = error;
         if (abortSignal.aborted) throw error; // Don't retry on abort
-        await new Promise((resolve) => setTimeout(resolve, 1000 * i));
+        await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1)));
       }
     }