@assistant-ui/mcp-docs-server 0.1.1

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

@@ -0,0 +1,496 @@
+---
+title: Tools
+---
+
+Tools enable LLMs to take actions and interact with external systems. assistant-ui provides a comprehensive toolkit for creating, managing, and visualizing tool interactions in real-time.
+
+## Overview
+
+Tools in assistant-ui are functions that the LLM can call to perform specific tasks. They bridge the gap between the LLM's reasoning capabilities and real-world actions like:
+
+- Fetching data from APIs
+- Performing calculations
+- Interacting with databases
+- Controlling UI elements
+- Executing workflows
+
+When tools are executed, you can display custom generative UI components that provide rich, interactive visualizations of the tool's execution and results. Learn more in the [Generative UI guide](/docs/guides/ToolUI).
+
+<Callout type="tip">
+If you haven't provided a custom UI for a tool, assistant-ui offers a [`ToolFallback`](/docs/ui/ToolFallback) component that you can add to your codebase to render a default UI for tool executions. You can customize this by creating your own Tool UI component for the tool's name.
+</Callout>
+
+## Tool Creation Methods
+
+assistant-ui offers multiple ways to create and register tools, each suited for different use cases:
+
+- **`makeAssistantTool`**: Register client-defined tools with the assistant context
+- **`useAssistantTool`**: Hook-based dynamic tool registration
+- **`makeAssistantToolUI`**: UI-only components for existing tools
+- **Direct context registration**: Advanced registration with full model context control
+
+### 1. Using `makeAssistantTool`
+
+Register tools with the assistant context. Returns a React component that registers the tool when rendered:
+
+```tsx
+import { makeAssistantTool, tool } from "@assistant-ui/react";
+import { z } from "zod";
+
+// Define the tool
+const weatherTool = tool({
+  description: "Get current weather for a location",
+  parameters: z.object({
+    location: z.string().describe("City name or zip code"),
+    unit: z.enum(["celsius", "fahrenheit"]).default("celsius")
+  }),
+  execute: async ({ location, unit }) => {
+    // Tool execution logic
+    const weather = await fetchWeatherAPI(location, unit);
+    return weather;
+  }
+});
+
+// Create the component
+const WeatherTool = makeAssistantTool(weatherTool);
+
+// Place the tool component inside AssistantRuntimeProvider
+function App() {
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <WeatherTool />
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+<Callout type="tip">
+When using server-side runtimes like Vercel AI SDK, you can pass client-defined tools to your backend using `frontendTools`. See the [Client-Defined Tools with frontendTools](#client-defined-tools-with-frontendtools) section below.
+</Callout>
+
+### 2. Using `useAssistantTool` Hook
+
+Register tools dynamically using React hooks. Useful for conditional tools or when tool availability depends on component state:
+
+```tsx
+import { useAssistantTool } from "@assistant-ui/react";
+import { z } from "zod";
+
+function DynamicTools() {
+  const [dataSource, setDataSource] = useState<"local" | "cloud">("local");
+  
+  useAssistantTool({
+    toolName: "searchData",
+    description: "Search through the selected data source",
+    parameters: z.object({
+      query: z.string()
+    }),
+    execute: async ({ query }) => {
+      if (dataSource === "local") {
+        return await searchLocalDatabase(query);
+      } else {
+        return await searchCloudDatabase(query);
+      }
+    },
+    // Re-register when data source changes
+    enabled: true
+  });
+  
+  return null;
+}
+```
+
+### 3. Using `makeAssistantToolUI`
+
+Create generative UI components for tools that are defined elsewhere. This is UI-only - the tool's execution logic must be registered separately (e.g., in your backend, MCP server, or another component):
+
+<Callout type="note">
+This creates only the UI component. The actual tool execution happens where you've defined it (typically in your API route with server-based runtimes like Vercel AI SDK).
+</Callout>
+
+```tsx
+import { makeAssistantToolUI, AssistantToolUI } from "@assistant-ui/react";
+
+const SearchResultsUI = makeAssistantToolUI<{
+  query: string;
+}, {
+  results: Array<{
+    id: string;
+    url: string;
+    title: string;
+    snippet: string;
+  }>;
+}>({
+  toolName: "webSearch", // Must match the registered tool's name
+  render: ({ args, result }) => {
+    return (
+      <div className="search-results">
+        <h3>Search: {args.query}</h3>
+        {result.results.map((item) => (
+          <div key={item.id}>
+            <a href={item.url}>{item.title}</a>
+            <p>{item.snippet}</p>
+          </div>
+        ))}
+      </div>
+    );
+  }
+});
+
+// Place the tool component inside AssistantRuntimeProvider
+function App() {
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <SearchResultsUI />
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+### 4. Advanced: Direct Context Registration
+
+Use `registerModelContextProvider` when you need to configure more than just tools:
+
+```tsx
+import { tool, useAssistantRuntime } from "@assistant-ui/react";
+import { useEffect, useState } from "react";
+import { z } from "zod";
+
+function MyComponent() {
+  const runtime = useAssistantRuntime();
+  const [isCreativeMode, setIsCreativeMode] = useState(false);
+  
+  useEffect(() => {
+    const calculateTool = tool({
+      description: "Perform mathematical calculations",
+      parameters: z.object({
+        expression: z.string()
+      }),
+      execute: async ({ expression }) => {
+        return eval(expression); // Note: Use proper math parser in production
+      }
+    });
+
+    // Register tools with model configuration
+    return runtime.registerModelContextProvider({
+      getModelContext: () => ({
+        tools: { calculate: calculateTool },
+        callSettings: {
+          temperature: isCreativeMode ? 0.9 : 0.2,
+          maxTokens: 1000
+        },
+        priority: 10 // Higher priority overrides other providers
+      })
+    });
+  }, [runtime, isCreativeMode]);
+  
+  return <div>{/* Your component */}</div>;
+}
+```
+
+Use this approach when you need:
+- Dynamic model parameters (temperature, maxTokens, etc.)
+- Priority-based context merging
+- Multiple context types in one registration
+
+## Tool Paradigms
+
+### Frontend Tools
+
+Tools that execute in the browser, accessing client-side resources:
+
+```tsx
+const screenshotTool = tool({
+  description: "Capture a screenshot of the current page",
+  parameters: z.object({
+    selector: z.string().optional()
+  }),
+  execute: async ({ selector }) => {
+    const element = selector ? document.querySelector(selector) : document.body;
+    const screenshot = await captureElement(element);
+    return { dataUrl: screenshot };
+  }
+});
+
+const ScreenshotTool = makeAssistantTool(screenshotTool);
+```
+
+### Backend Tools
+
+Tools that trigger server-side operations:
+
+```tsx
+// Backend route (AI SDK)
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  
+  const result = streamText({
+    model: openai("gpt-4o"),
+    messages,
+    tools: {
+      queryDatabase: {
+        description: "Query the application database",
+        parameters: z.object({
+          query: z.string(),
+          table: z.string()
+        }),
+        execute: async ({ query, table }) => {
+          // Server-side database access
+          const results = await db.query(query, { table });
+          return results;
+        }
+      }
+    }
+  });
+  
+  return result.toDataStreamResponse();
+}
+```
+
+### Client-Defined Tools with frontendTools
+
+Currently, the Vercel AI SDK adapter implements automatic serialization of client-defined tools. When using this adapter, tools registered via `makeAssistantTool`, `useAssistantTool`, or `registerModelContextProvider` are automatically included in API requests. The `frontendTools` utility helps you use these tools server-side:
+
+```tsx
+// Frontend: Define tool with makeAssistantTool
+import { makeAssistantTool, tool } from "@assistant-ui/react";
+
+const calculateTool = tool({
+  description: "Perform calculations",
+  parameters: z.object({
+    expression: z.string()
+  }),
+  execute: async ({ expression }) => {
+    return eval(expression); // Note: Use proper math parser in production
+  }
+});
+
+const CalculateTool = makeAssistantTool(calculateTool);
+
+// Backend: Use frontendTools to receive client tools
+import { frontendTools } from "@assistant-ui/react-ai-sdk";
+
+export async function POST(req: Request) {
+  const { messages, tools } = await req.json();
+  
+  const result = streamText({
+    model: openai("gpt-4o"),
+    messages,
+    tools: {
+      ...frontendTools(tools), // Client-defined tools
+      // Additional server-side tools
+      queryDatabase: {
+        description: "Query the application database",
+        parameters: z.object({ query: z.string() }),
+        execute: async ({ query }) => {
+          return await db.query(query);
+        }
+      }
+    }
+  });
+  
+  return result.toDataStreamResponse();
+}
+```
+
+<Callout type="note">
+The `frontendTools` utility is currently only available for the Vercel AI SDK integration. Other adapters like LangGraph follow a server-side tool definition model and don't yet implement client tool serialization. Learn more in the [Vercel AI SDK integration guide](/docs/runtimes/ai-sdk/use-chat-hook).
+</Callout>
+
+### Human-in-the-Loop Tools
+
+Tools that require human approval or input:
+
+```tsx
+import { makeAssistantTool, tool } from "@assistant-ui/react";
+import { z } from "zod";
+
+const refundTool = tool({
+  description: "Process a customer refund",
+  parameters: z.object({
+    orderId: z.string(),
+    amount: z.number(),
+    reason: z.string()
+  }),
+  execute: async ({ orderId, amount, reason }) => {
+    // Wait for human approval
+    const approved = await requestHumanApproval({
+      action: "refund",
+      details: { orderId, amount, reason }
+    });
+    
+    if (!approved) {
+      throw new Error("Refund rejected by administrator");
+    }
+    
+    return await processRefund(orderId, amount);
+  }
+});
+
+const RefundTool = makeAssistantTool(refundTool);
+```
+
+### MCP (Model Context Protocol) Tools
+
+Integration with MCP servers:
+
+```tsx
+// Using AI SDK's MCP support
+import { createMCPClient } from "ai/mcp";
+
+const mcpClient = createMCPClient({
+  servers: {
+    github: {
+      command: "npx",
+      args: ["@modelcontextprotocol/server-github"]
+    }
+  }
+});
+
+// Tools are automatically available through the runtime
+const runtime = useChatRuntime({
+  api: "/api/chat",
+  tools: await mcpClient.getTools()
+});
+```
+
+## Advanced Patterns
+
+### Tool Composition
+
+Combining multiple tools for complex workflows:
+
+```tsx
+const travelPlannerTool = tool({
+  description: "Plan a complete trip itinerary",
+  parameters: z.object({
+    destination: z.string(),
+    dates: z.object({
+      start: z.string(),
+      end: z.string()
+    })
+  }),
+  execute: async ({ destination, dates }) => {
+    // Execute multiple operations
+    const weather = await getWeatherAPI(destination);
+    const hotels = await searchHotelsAPI({ 
+      location: destination,
+      dates 
+    });
+    const activities = await findActivitiesAPI({
+      location: destination,
+      weather: weather.forecast
+    });
+    
+    return {
+      weather,
+      hotels,
+      activities,
+      itinerary: generateItinerary({ weather, hotels, activities })
+    };
+  }
+});
+
+const TravelPlannerTool = makeAssistantTool(travelPlannerTool);
+```
+
+### Conditional Tool Availability
+
+Tools that appear based on context:
+
+```tsx
+function ConditionalTools() {
+  const { user } = useAuth();
+  const { subscription } = useSubscription();
+  
+  // Premium features
+  useAssistantTool({
+    toolName: "advancedAnalysis",
+    description: "Perform advanced data analysis",
+    parameters: z.object({
+      dataset: z.string()
+    }),
+    execute: async (args) => {
+      // Premium analysis logic
+    },
+    enabled: subscription?.tier === "premium"
+  });
+  
+  // Role-based tools
+  useAssistantTool({
+    toolName: "adminPanel",
+    description: "Access admin controls",
+    parameters: z.object({}),
+    execute: async () => {
+      // Admin actions
+    },
+    enabled: user?.role === "admin"
+  });
+}
+```
+
+### Tool Error Handling
+
+Robust error handling and recovery:
+
+```tsx
+const resilientTool = tool({
+  description: "Fetch data with retry logic",
+  parameters: z.object({
+    endpoint: z.string()
+  }),
+  execute: async ({ endpoint }, { abortSignal }) => {
+    const maxRetries = 3;
+    let lastError;
+    
+    for (let i = 0; i < maxRetries; i++) {
+      try {
+        const response = await fetch(endpoint, { signal: abortSignal });
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        return await response.json();
+      } catch (error) {
+        lastError = error;
+        if (abortSignal.aborted) throw error; // Don't retry on abort
+        await new Promise(resolve => setTimeout(resolve, 1000 * i));
+      }
+    }
+    
+    throw new Error(`Failed after ${maxRetries} attempts: ${lastError.message}`);
+  }
+});
+
+const ResilientTool = makeAssistantTool(resilientTool);
+```
+
+## Best Practices
+
+1. **Clear Descriptions**: Write descriptive tool descriptions that help the LLM understand when to use each tool
+2. **Parameter Validation**: Use Zod schemas to ensure type safety and provide clear parameter descriptions
+3. **Error Handling**: Always handle potential errors gracefully with user-friendly messages
+4. **Loading States**: Provide visual feedback during tool execution
+5. **Security**: Validate permissions and sanitize inputs, especially for destructive operations
+6. **Performance**: Use abort signals for cancellable operations and implement timeouts
+7. **Testing**: Test tools in isolation and with the full assistant flow
+
+## Tool Execution Context
+
+Tools receive additional context during execution:
+
+```tsx
+execute: async (args, context) => {
+  // context.abortSignal - AbortSignal for cancellation
+  // context.toolCallId - Unique identifier for this invocation
+}
+```
+
+## Runtime Integration
+
+Each integration handles tools differently:
+
+- **Vercel AI SDK**: Tools defined in API routes with `streamText({ tools: {...} })`. Also supports client-defined tools via `frontendTools`.
+- **LangGraph**: Tools defined in your LangGraph graph configuration.
+- **Mastra**: Tools defined as typed functions used by agents and workflows.
+
+All integrations support tool UI customization via `makeAssistantToolUI`.

package/.docs/raw/docs/index.mdx

@@ -0,0 +1,7 @@
+---
+title: "Documentation"
+---
+
+import { redirect } from "next/navigation";
+
+<>{redirect("/docs/getting-started")}</>

package/.docs/raw/docs/legacy/styled/AssistantModal.mdx

@@ -0,0 +1,85 @@
+---
+title: AssistantModal
+---
+
+import { Steps, Step } from "fumadocs-ui/components/steps";
+import { Tabs, Tab } from "fumadocs-ui/components/tabs";
+
+## Overview
+
+A chat bubble shown in the bottom right corner of the screen. Useful for support or Q&A use cases.
+
+## Getting Started
+
+<Steps>
+  <Step>
+
+### Install `@assistant-ui/react-ui`
+
+```sh npm2yarn
+npm install @assistant-ui/react-ui
+```
+
+  </Step>
+  <Step>
+
+### Import CSS styles
+
+Add the following to your `tailwind.config.ts`:
+
+<Tabs items={["Tailwind", "Tailwind + shadcn-ui", "Not using Tailwind"]}>
+
+```ts title="/tailwind.config.ts" tab="Tailwind"
+{
+  plugins: [
+    require("tailwindcss-animate"), // make sure to "npm install tailwindcss-animate"
+    require("@assistant-ui/react-ui/tailwindcss")({
+      components: ["assistant-modal"],
+    })
+  ],
+}
+```
+
+```ts title="/tailwind.config.ts" tab="Tailwind + shadcn-ui"
+{
+  plugins: [
+    require("tailwindcss-animate"), // make sure to "npm install tailwindcss-animate"
+    require("@assistant-ui/react-ui/tailwindcss")({
+      components: ["assistant-modal"],
+      shadcn: true
+    })
+  ],
+}
+```
+
+```ts title="/app/layout.tsx" tab="Not using Tailwind"
+import "@assistant-ui/react-ui/styles/index.css";
+import "@assistant-ui/react-ui/styles/modal.css";
+```
+
+</Tabs>
+
+  </Step>
+  <Step>
+
+### Use it in your app
+
+```tsx title="/app/page.tsx"
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { AssistantModal } from "@assistant-ui/react-ui";
+
+const MyApp = () => {
+  const runtime = useChatRuntime({
+    api: "/api/chat",
+  });
+
+  return (
+    <div>
+      <AssistantModal runtime={runtime} />
+    </div>
+  );
+};
+```
+
+  </Step>
+</Steps>