@assistant-ui/mcp-docs-server 0.2.3 → 0.3.0

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

@@ -1,411 +0,0 @@
----
-title: Assistant Frame API
-description: Share model context across iframe boundaries
-platforms: ["react"]
----
-
-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,
-  "https://parent-app.com",
-);
-
-// 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",
-  });
-
-  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,
-    "https://parent-app.com",
-  );
-const unsubscribe2 =
-  AssistantFrameProvider.addModelContextProvider(
-    analyticsRegistry,
-    "https://parent-app.com",
-  );
-
-// Later, unsubscribe if needed
-unsubscribe1();
-unsubscribe2();
-```
-
-### Security Considerations
-
-#### Origin Validation
-
-Both the provider and host validate message origins. They default to the current page's origin, so cross-origin frames must specify the exact trusted origin on both sides:
-
-```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",
-);
-```
-
-When `targetOrigin` is omitted, the provider only communicates with `window.location.origin`. All providers in a frame share one origin policy. Registering an explicit origin tightens an existing wildcard policy, while registering two different explicit origins throws an error. Unsubscribing drops that registration's requirement. The wildcard value `*` is available as an explicit opt-in, but it should not be used for contexts that expose tools or sensitive instructions.
-
-##### `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?, // Defaults to window.location.origin
-);
-```
-
-#### 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, // Defaults to window.location.origin
-});
-```
-
-### 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/copilots/make-assistant-visible.mdx

@@ -1,82 +0,0 @@
----
-title: makeAssistantVisible
-description: Make React components visible and interactive to assistants via higher-order component wrapping.
-platforms: ["react"]
----
-
-`makeAssistantVisible` is a higher-order component (HOC) that makes React components "visible" by the assistant, allowing it to understand and interact with the component's HTML structure.
-
-## Usage
-
-```tsx
-import { makeAssistantVisible } from "@assistant-ui/react";
-
-const Button = ({ onClick, children }) => (
-  <button onClick={onClick}>{children}</button>
-);
-
-// Basic usage - makes component HTML readable
-const ReadableButton = makeAssistantVisible(Button);
-
-// With clickable configuration
-const ClickableButton = makeAssistantVisible(Button, {
-  clickable: true, // Enables the click tool
-});
-
-// With editable configuration
-const EditableInput = makeAssistantVisible(Input, {
-  editable: true, // Enables the edit tool
-});
-```
-
-## API Reference
-
-### Parameters
-
-- `Component`: The base React component to enhance
-- `config`: Optional configuration object
-  - `clickable`: When true, enables the assistant to programmatically click the component
-  - `editable`: When true, enables the assistant to programmatically set the value of an input or textarea within the component
-
-### Behavior
-
-The HOC will:
-
-1. Make the component's HTML structure available to the assistant via the system context
-2. Optionally provide a `click` tool if `clickable` is true
-3. Optionally provide an `edit` tool if `editable` is true, which sets the value of an `<input>` or `<textarea>` inside the component
-4. Handle nested readable components (only the outermost component's HTML is provided)
-5. Forward refs and maintain component props
-
-## Example
-
-```tsx
-// Create a readable form input that the assistant can also edit
-const Input = ({ label, ...props }) => (
-  <div>
-    <label>{label}</label>
-    <input {...props} />
-  </div>
-);
-
-const EditableInput = makeAssistantVisible(Input, { editable: true });
-
-// Use in your component
-function Form() {
-  return (
-    <EditableInput label="Email" type="email" placeholder="Enter your email" />
-  );
-}
-```
-
-## Technical Details
-
-When a component is made readable:
-
-- It's wrapped in a `ReadableContext.Provider` to handle nesting
-- The component's `outerHTML` is provided as system context
-- If `clickable` is true, a unique `data-click-id` is added and a `click` tool is provided
-- The click tool uses `querySelector` and simulates a click event
-- If `editable` is true, a unique `data-edit-id` is added and an `edit` tool is provided
-- The edit tool uses `querySelector` to find an `<input>` or `<textarea>` and sets its value, dispatching `input` and `change` events
-- All props and refs are properly forwarded to maintain component functionality

package/.docs/raw/docs/copilots/model-context.mdx

@@ -1,156 +0,0 @@
----
-title: Model Context
-description: Configure assistant behavior through system instructions, tools, and context providers.
-platforms: ["react"]
----
-
-Model Context is the foundation of intelligence in assistant-ui components. It provides configuration and capabilities to the assistant through a context provider system.
-
-## Core Concepts
-
-### System Instructions
-
-System instructions define the base behavior and knowledge available to the assistant. These can be provided in several ways:
-
-```tsx
-import {
-  useAssistantInstructions,
-  useAssistantContext,
-  makeAssistantVisible,
-} from "@assistant-ui/react";
-
-// Static instructions
-useAssistantInstructions("You are a helpful assistant...");
-
-// Dynamic context — callback is evaluated lazily at send-time
-useAssistantContext({
-  getContext: () => `Current page: ${window.location.href}`,
-});
-
-// Via makeAssistantVisible
-const ReadableComponent = makeAssistantVisible(MyComponent);
-// Automatically provides component HTML as system context
-```
-
-`useAssistantInstructions` takes a static string that re-registers when changed. `useAssistantContext` takes a callback that is evaluated fresh each time the model context is read, making it ideal for injecting frequently-changing application state without triggering re-registrations.
-
-### Tools
-
-Tools are functions that the assistant can use to interact with your application. They can be provided through various mechanisms:
-
-```tsx title="app/form-toolkit.tsx"
-"use generative";
-
-import { defineToolkit } from "@assistant-ui/react";
-import { z } from "zod";
-
-export default defineToolkit({
-  submitForm: {
-    description: "Submit the form with the user's details.",
-    parameters: z.object({
-      email: z.string().email(),
-      name: z.string(),
-    }),
-    execute: async ({ email, name }) => {
-      "use client";
-      // Implementation
-      return { success: true };
-    },
-    renderText: { running: "Submitting…", complete: "Submitted" },
-  },
-});
-```
-
-```tsx title="app/Form.tsx"
-import {
-  AuiConfig,
-  AuiProvider,
-  makeAssistantVisible,
-  Tools,
-  useAui,
-} from "@assistant-ui/react";
-import toolkit from "./form-toolkit";
-
-// Via makeAssistantVisible's clickable option
-const ClickableButton = makeAssistantVisible(Button, {
-  clickable: true, // Provides a click tool
-});
-
-// Use in your component
-function Form() {
-  const aui = useAui();
-  const config = AuiConfig({ tools: Tools({ toolkit }) });
-  return (
-    <AuiProvider extends={aui} config={config}>
-      <form>{/* form fields */}</form>
-    </AuiProvider>
-  );
-}
-```
-
-## Context Provider System
-
-The context provider system allows components to contribute to the model context. Here's a typical usage pattern:
-
-```tsx
-import { useAui, tool } from "@assistant-ui/react";
-import { useEffect } from "react";
-import { z } from "zod";
-
-// Define tool outside the component (no runtime dependencies)
-const myTool = tool({
-  parameters: z.object({
-    query: z.string(),
-  }),
-  execute: async ({ query }) => {
-    const result = await searchDatabase(query);
-    return { result };
-  },
-});
-
-function MyComponent() {
-  const aui = useAui();
-
-  useEffect(() => {
-    // Register context provider
-    return aui.modelContext.register({
-      getModelContext: () => ({
-        system: "You are a helpful search assistant...",
-        tools: { myTool },
-      }),
-    });
-  }, [aui]); // Re-register if api changes
-
-  return <div>{/* component content */}</div>;
-}
-```
-
-### Provider Composition
-
-Multiple providers can be registered, and their contexts will be composed:
-
-- System instructions are concatenated
-- Tool sets are merged
-- Nested readable components only contribute their context at the outermost level
-
-## Best Practices
-
-1. **System Instructions**
-
-   - Keep them focused and specific to the component's purpose
-   - Use useAssistantInstructions for explicit instructions
-   - Let makeAssistantVisible handle component structure
-
-2. **Tools**
-
-   - Use toolkit entries to define tool schemas and behavior
-   - Prefer `Tools({ toolkit })` for reusable tools
-   - Handle errors gracefully
-   - Consider async operations and loading states
-   - Use the built-in click tool when possible
-
-3. **Context Management**
-   - Register providers in useEffect for proper cleanup
-   - Clean up providers when components unmount
-   - Avoid deeply nested readable components
-   - Consider performance implications of large HTML structures