@assistant-ui/mcp-docs-server 0.1.1

package/.docs/raw/docs/copilots/make-assistant-tool-ui.mdx

@@ -0,0 +1,76 @@
+---
+title: makeAssistantToolUI
+---
+
+import { ParametersTable } from "@/components/docs";
+
+# `makeAssistantToolUI`
+
+The `makeAssistantToolUI` utility is used to register a tool UI component with the Assistant.
+
+## Usage
+
+```tsx
+import { makeAssistantToolUI } from "assistant-ui/react";
+
+const MyToolUI = makeAssistantToolUI({
+  toolName: "myTool",
+  render: ({ args, result, status }) => {
+    // render your tool UI here
+  },
+});
+```
+
+## API
+
+### `makeAssistantToolUI(tool)`
+
+#### Parameters
+
+<ParametersTable
+  type="AssistantToolUIProps<TArgs, TResult>"
+  parameters={[
+    {
+      name: "toolName",
+      type: "string",
+      description: "The name of the tool. This must match the name of the tool defined in the assistant.",
+    },
+    {
+      name: "render",
+      type: "function",
+      description: "A function that renders the tool UI. It receives an object with the following properties: `args` (any): The arguments passed to the tool. `result` (any): The result of the tool execution. `status` (\"requires_action\" | \"in_progress\" | \"complete\" | \"error\"): The status of the tool execution.",
+    },
+  ]}
+/>
+
+#### Returns
+
+A React functional component that should be included in your component tree. This component doesn't render anything itself, but it registers the tool UI with the Assistant.
+
+## Example
+
+```tsx
+import { makeAssistantToolUI } from "assistant-ui/react";
+import { AssistantRuntimeProvider } from "assistant-ui/react";
+
+const GetWeatherUI = makeAssistantToolUI({
+  toolName: "get_weather",
+  render: ({ args, result, status }) => {
+    if (status === "requires_action") return <p>Getting weather for {args.location}...</p>;
+    if (status === "in_progress") return <p>Loading...</p>;
+    if (status === "error") return <p>Error getting weather.</p>;
+    if (status === "complete") return <p>The weather is {result.weather}.</p>;
+    return null;
+  },
+});
+
+function App() {
+  return (
+    <AssistantRuntimeProvider>
+      {/* ...your other components */}
+      <GetWeatherUI />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+This example shows how to create a simple UI for a `get_weather` tool. The UI will display different messages depending on the status of the tool execution.

package/.docs/raw/docs/copilots/make-assistant-tool.mdx

@@ -0,0 +1,117 @@
+---
+title: makeAssistantTool
+---
+
+`makeAssistantTool` creates a React component that provides a tool to the assistant. This is useful for defining reusable tools that can be composed into your application.
+
+## Usage
+
+```tsx
+import { makeAssistantTool, tool } from "@assistant-ui/react";
+import { z } from "zod";
+
+// Define the tool using the tool() helper
+const submitForm = tool({
+  parameters: z.object({
+    email: z.string().email(),
+    name: z.string(),
+  }),
+  execute: async ({ email, name }) => {
+    // Implementation
+    return { success: true };
+  },
+});
+
+// Create a tool component
+const SubmitFormTool = makeAssistantTool(submitForm);
+
+// Use in your component
+function Form() {
+  return (
+    <div>
+      <form>{/* form fields */}</form>
+      <SubmitFormTool />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### Parameters
+
+- `tool`: A tool definition created using the `tool()` helper function
+  - `parameters`: Zod schema defining the tool's parameters
+  - `execute`: Function that implements the tool's behavior
+
+### Returns
+
+Returns a React component that:
+
+- Provides the tool to the assistant when mounted
+- Automatically removes the tool when unmounted
+- Renders nothing in the DOM (returns null)
+
+## Example with Multiple Tools
+
+```tsx
+import { makeAssistantTool, tool } from "@assistant-ui/react";
+import { z } from "zod";
+
+// Define tools
+const validateEmail = tool({
+  parameters: z.object({
+    email: z.string(),
+  }),
+  execute: ({ email }) => {
+    const isValid = email.includes("@");
+    return { isValid, reason: isValid ? "Valid email" : "Missing @" };
+  },
+});
+
+const sendEmail = tool({
+  parameters: z.object({
+    to: z.string().email(),
+    subject: z.string(),
+    body: z.string(),
+  }),
+  execute: async (params) => {
+    // Implementation
+    return { sent: true };
+  },
+});
+
+// Create tool components
+const EmailValidator = makeAssistantTool(validateEmail);
+const EmailSender = makeAssistantTool(sendEmail);
+
+// Use together
+function EmailForm() {
+  return (
+    <div>
+      <form>{/* form fields */}</form>
+      <EmailValidator />
+      <EmailSender />
+    </div>
+  );
+}
+```
+
+## Best Practices
+
+1. **Parameter Validation**
+
+   - Always use Zod schemas to define parameters
+   - Be specific about parameter types and constraints
+   - Add helpful error messages to schema validations
+
+2. **Error Handling**
+
+   - Return meaningful error messages
+   - Consider returning partial results when possible
+   - Handle async errors appropriately
+
+3. **Composition**
+   - Break complex tools into smaller, focused ones
+   - Consider tool dependencies and interactions
+   - Use multiple tools together for complex functionality

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

@@ -0,0 +1,135 @@
+---
+title: Model Context
+---
+
+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,
+  makeAssistantVisible,
+} from "@assistant-ui/react";
+
+// Via useAssistantInstructions
+useAssistantInstructions("You are a helpful assistant...");
+
+// Via makeAssistantVisible
+const ReadableComponent = makeAssistantVisible(MyComponent);
+// Automatically provides component HTML as system context
+```
+
+### Tools
+
+Tools are functions that the assistant can use to interact with your application. They can be provided through various mechanisms:
+
+```tsx
+import {
+  makeAssistantVisible,
+  makeAssistantTool,
+  tool,
+  useAssistantRuntime,
+} from "@assistant-ui/react";
+import { z } from "zod";
+
+// Via makeAssistantVisible's clickable option
+const ClickableButton = makeAssistantVisible(Button, {
+  clickable: true, // Provides a click tool
+});
+
+// Via makeAssistantTool
+const submitForm = tool({
+  parameters: z.object({
+    email: z.string().email(),
+    name: z.string(),
+  }),
+  execute: async ({ email, name }) => {
+    // Implementation
+    return { success: true };
+  },
+});
+
+const SubmitFormTool = makeAssistantTool(submitForm);
+
+// Use in your component
+function Form() {
+  return (
+    <div>
+      <form>{/* form fields */}</form>
+      <SubmitFormTool />
+    </div>
+  );
+}
+```
+
+## Context Provider System
+
+The context provider system allows components to contribute to the model context. Here's a typical usage pattern:
+
+```tsx
+import { useAssistantRuntime, tool } from "@assistant-ui/react";
+import { useEffect } from "react";
+import { z } from "zod";
+
+function MyComponent() {
+  const assistantRuntime = useAssistantRuntime();
+
+  // Define tool using the tool() helper
+  const myTool = tool({
+    parameters: z.object({
+      query: z.string(),
+    }),
+    execute: async ({ query }) => {
+      const result = await searchDatabase(query);
+      return { result };
+    },
+  });
+
+  useEffect(() => {
+    // Register context provider
+    return assistantRuntime.registerModelContextProvider({
+      getModelContext: () => ({
+        system: "You are a helpful search assistant...",
+        tools: { myTool },
+      }),
+    });
+  }, [assistantRuntime]); // Re-register if runtime 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 the tool() helper to define tool schemas and behavior
+   - Prefer makeAssistantTool 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

package/.docs/raw/docs/copilots/motivation.mdx

@@ -0,0 +1,191 @@
+---
+title: Intelligent Components
+---
+
+React revolutionized web development with components that combine logic, structure, and style. Now, with assistant-ui, we're adding a fourth dimension: intelligence. Let's learn how to build smart components through a practical banking app example.
+
+## The Evolution of Components
+
+Traditional React components combine three elements:
+
+```tsx
+// Traditional React Component
+function TransactionHistory({ transactions }) {
+  // 1. Logic (JavaScript/TypeScript)
+  const handleRefund = (transactionId) => {
+    // Process refund...
+  };
+
+  // 2. Structure (JSX/TSX)
+  return (
+    // 3. Style (CSS via className)
+    <div className="transaction-list">
+      {transactions.map((transaction) => (
+        <div key={transaction.id} className="transaction-item">
+          <span>${transaction.amount}</span>
+          <span>{transaction.merchant}</span>
+          <button onClick={() => handleRefund(transaction.id)}>
+            Request Refund
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Adding Intelligence
+
+With assistant-ui, we can enhance this component with intelligence using four powerful APIs:
+
+### 1. Making Components Readable (makeAssistantVisible)
+
+First, let's make our buttons "readable" and interactive:
+
+```tsx
+import { makeAssistantVisible } from "@assistant-ui/react";
+
+// Make the refund button intelligent
+const SmartButton = makeAssistantVisible(
+  ({ onClick, children }) => <button onClick={onClick}>{children}</button>,
+  {
+    clickable: true, // Allow the assistant to click the button
+  },
+);
+
+function TransactionHistory({ transactions }) {
+  return (
+    <div className="transaction-list">
+      {transactions.map((transaction) => (
+        <div key={transaction.id} className="transaction-item">
+          <span>${transaction.amount}</span>
+          <span>{transaction.merchant}</span>
+          <SmartButton onClick={() => handleRefund(transaction.id)}>
+            Request Refund
+          </SmartButton>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+Now the assistant can:
+
+- Understand the transaction history structure
+- Interact with refund buttons
+- Help users manage their transactions
+
+### 2. Adding System Instructions (useAssistantInstructions)
+
+Next, let's give the assistant specific instructions about its role:
+
+```tsx
+import { useAssistantInstructions } from "@assistant-ui/react";
+
+function SmartTransactionHistory() {
+  useAssistantInstructions(`
+    You are a helpful banking assistant that:
+    1. Helps users understand their transactions
+    2. Explains refund policies
+    3. Identifies suspicious transactions
+    4. Guides users through the refund process
+  `);
+
+  return <TransactionHistory transactions={transactions} />;
+}
+```
+
+### 3. Creating Tools (makeAssistantTool)
+
+Let's add transaction-specific tools for the assistant:
+
+```tsx
+import { makeAssistantTool, tool } from "@assistant-ui/react";
+import { z } from "zod";
+
+// Define a tool to analyze transactions
+const analyzeTransaction = tool({
+  parameters: z.object({
+    transactionId: z.string(),
+    merchantName: z.string(),
+  }),
+  execute: async ({ transactionId, merchantName }) => {
+    // Analyze transaction patterns, merchant reputation, etc.
+    return {
+      isSuspicious: false,
+      merchantRating: 4.5,
+      similarTransactions: 3,
+      refundEligible: true,
+    };
+  },
+});
+
+// Create a tool component
+const TransactionAnalyzer = makeAssistantTool(analyzeTransaction);
+
+function SmartTransactionHistory() {
+  // Previous instructions...
+  return (
+    <>
+      <TransactionHistory transactions={transactions} />
+      <TransactionAnalyzer />
+    </>
+  );
+}
+```
+
+### 4. Adding Custom Context (Model Context)
+
+Finally, let's add dynamic context based on the user's transaction patterns:
+
+```tsx
+import { useAssistantRuntime } from "@assistant-ui/react";
+import { useEffect } from "react";
+
+function SmartTransactionHistory({ userProfile }) {
+  const assistantRuntime = useAssistantRuntime();
+
+  useEffect(() => {
+    return assistantRuntime.registerModelContextProvider({
+      getModelContext: () => ({
+        system: `
+          User spending patterns:
+          - Average transaction: ${userProfile.avgTransaction}
+          - Common merchants: ${userProfile.frequentMerchants.join(", ")}
+          - Refund history: ${userProfile.refundCount} requests
+        `,
+      }),
+    });
+  }, [assistantRuntime, userProfile]);
+
+  // Previous components...
+}
+```
+
+## The Result: An Intelligent Banking Experience
+
+This enhanced component now provides:
+
+- Natural language interaction with transaction history
+- Contextual help for understanding transactions
+- Automated transaction analysis
+- Smart refund assistance
+
+The assistant can now:
+
+1. Read and understand transaction details
+2. Follow banking-specific guidelines
+3. Use tools to analyze transactions
+4. Access user patterns for personalized help
+
+This creates a more intuitive and safer banking experience while maintaining the familiar React component model.
+
+## Next Steps
+
+Learn more about each API:
+
+- [makeAssistantVisible](make-assistant-readable) for component understanding
+- [makeAssistantTool](make-assistant-tool) for transaction analysis
+- [useAssistantInstructions](use-assistant-instructions) for behavior guidance
+- [Model Context](model-context) for dynamic context management

package/.docs/raw/docs/copilots/use-assistant-instructions.mdx

@@ -0,0 +1,62 @@
+---
+title: useAssistantInstructions
+---
+
+`useAssistantInstructions` is a React hook that allows you to set system instructions for your assistant-ui components.
+
+## Usage
+
+```tsx
+import { useAssistantInstructions } from "@assistant-ui/react";
+
+function MyComponent() {
+  // Simple string usage
+  useAssistantInstructions("You are a helpful form assistant...");
+
+  // With configuration object
+  useAssistantInstructions({
+    instruction: "You are a helpful form assistant...",
+    disabled: false, // Optional: disable the instructions
+  });
+
+  return <div>My Component</div>;
+}
+```
+
+## API Reference
+
+### Parameters
+
+The hook accepts either:
+
+- A string containing the system instructions
+- A configuration object with:
+  - `instruction`: The system instructions
+  - `disabled`: Optional boolean to disable the instructions
+
+### Behavior
+
+The hook will:
+
+1. Register the provided instructions as system instructions in the model context
+2. Automatically clean up when the component unmounts
+3. Update when the instructions change
+4. Do nothing if disabled is set to true
+
+## Example
+
+```tsx
+function SmartForm() {
+  useAssistantInstructions({
+    instruction: `
+      You are a form assistant that:
+      - Validates user input
+      - Provides helpful suggestions
+      - Explains any errors
+      - Guides users through complex fields
+    `,
+  });
+
+  return <form>{/* Your form fields here */}</form>;
+}
+```