@assistant-ui/mcp-docs-server 0.1.32 → 0.1.34

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

@@ -1,151 +0,0 @@
----
-title: makeAssistantToolUI
-description: Register custom UI components to render tool executions and their status.
-platforms: ["react"]
----
-
-<Callout type="info">
-  Prefer pre-registering tool UIs via the [`Tools()` API](/docs/guides/tools)
-  (set `render` on the tool definition) or by mounting `makeAssistantToolUI`
-  near the root of your tree. A tool UI that is only registered while a
-  specific component is mounted will not appear when chat history is replayed
-  or during server-side rendering, since the registering component may not be
-  mounted at that point. Tool execution can still be registered dynamically
-  via [`makeAssistantTool`](/docs/copilots/make-assistant-tool); this caveat
-  applies specifically to the UI render function.
-</Callout>
-
-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
-
-### 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: "ComponentType<ToolCallMessagePartProps<TArgs, TResult>>",
-      description:
-        "A React component that renders the tool UI. Receives the following props:",
-      required: true,
-      children: [
-        {
-          type: "ToolCallMessagePartProps<TArgs, TResult>",
-          parameters: [
-            {
-              name: "type",
-              type: '"tool-call"',
-              description: "The message part type",
-            },
-            {
-              name: "toolCallId",
-              type: "string",
-              description: "Unique identifier for this tool call",
-            },
-            {
-              name: "toolName",
-              type: "string",
-              description: "The name of the tool being called",
-            },
-            {
-              name: "args",
-              type: "TArgs",
-              description: "The arguments passed to the tool",
-            },
-            {
-              name: "argsText",
-              type: "string",
-              description: "String representation of the arguments",
-            },
-            {
-              name: "result",
-              type: "TResult | undefined",
-              description: "The result of the tool execution (if complete)",
-            },
-            {
-              name: "isError",
-              type: "boolean | undefined",
-              description: "Whether the result is an error",
-            },
-            {
-              name: "status",
-              type: "ToolCallMessagePartStatus",
-              description:
-                'The execution status object with a type property: "running", "complete", "incomplete", or "requires-action"',
-            },
-            {
-              name: "addResult",
-              type: "(result: TResult | ToolResponse<TResult>) => void",
-              description:
-                "Function to add a result (useful for human-in-the-loop tools)",
-            },
-            {
-              name: "artifact",
-              type: "unknown",
-              description:
-                "Optional artifact data associated with the tool call",
-            },
-          ],
-        },
-      ],
-    },
-  ]}
-/>
-
-### 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.type === "requires-action")
-      return <p>Getting weather for {args.location}...</p>;
-    if (status.type === "running") return <p>Loading...</p>;
-    if (status.type === "incomplete" && status.reason === "error")
-      return <p>Error getting weather.</p>;
-    if (status.type === "complete")
-      return <p>The weather is {result.weather}.</p>;
-    return null;
-  },
-});
-
-function App() {
-  const runtime = /* your runtime setup */;
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {/* ...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/(docs)/copilots/make-assistant-tool.mdx

@@ -1,230 +0,0 @@
----
-title: makeAssistantTool
-description: Create React components that provide reusable tools to the assistant.
-platforms: ["react"]
----
-
-<Callout type="info">
-  For most apps, the [`Tools()` API](/docs/guides/tools) is an easier starting
-  point: tool definitions live in a toolkit object rather than the component
-  tree. `makeAssistantTool` is fully supported and remains a good fit when a
-  tool's availability is tied to a component being mounted, for example a
-  product-specific tool that should only be exposed while that product's UI is
-  on screen (the [intelligent components](/docs/copilots/motivation) pattern).
-</Callout>
-
-`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,
-  toolName: "submitForm",
-});
-
-// Use in your component
-function Form() {
-  return (
-    <div>
-      <form>{/* form fields */}</form>
-      <SubmitFormTool />
-    </div>
-  );
-}
-```
-
-## API Reference
-
-### Parameters
-
-<ParametersTable
-  type="AssistantToolProps<TArgs, TResult>"
-  parameters={[
-    {
-      name: "toolName",
-      type: "string",
-      description: "The unique identifier for the tool",
-      required: true,
-    },
-    {
-      name: "parameters",
-      type: "StandardSchemaV1<TArgs> | JSONSchema7",
-      description:
-        "Schema defining the tool's parameters (typically a Zod schema)",
-      required: true,
-    },
-    {
-      name: "execute",
-      type: "(args: TArgs, context: ToolExecutionContext) => TResult | Promise<TResult>",
-      description:
-        "Function that implements the tool's behavior (required for frontend tools)",
-      required: true,
-    },
-    {
-      name: "description",
-      type: "string",
-      description: "Optional description of the tool's purpose",
-    },
-    {
-      name: "render",
-      type: "ComponentType<ToolCallMessagePartProps<TArgs, TResult>>",
-      description:
-        "Optional custom UI component for rendering the tool execution. Receives the following props:",
-      children: [
-        {
-          type: "ToolCallMessagePartProps<TArgs, TResult>",
-          parameters: [
-            {
-              name: "type",
-              type: '"tool-call"',
-              description: "The message part type",
-            },
-            {
-              name: "toolCallId",
-              type: "string",
-              description: "Unique identifier for this tool call",
-            },
-            {
-              name: "toolName",
-              type: "string",
-              description: "The name of the tool being called",
-            },
-            {
-              name: "args",
-              type: "TArgs",
-              description: "The arguments passed to the tool",
-            },
-            {
-              name: "argsText",
-              type: "string",
-              description: "String representation of the arguments",
-            },
-            {
-              name: "result",
-              type: "TResult | undefined",
-              description: "The result of the tool execution (if complete)",
-            },
-            {
-              name: "isError",
-              type: "boolean | undefined",
-              description: "Whether the result is an error",
-            },
-            {
-              name: "status",
-              type: "ToolCallMessagePartStatus",
-              description:
-                'The execution status object with a type property: "running", "complete", "incomplete", or "requires-action"',
-            },
-            {
-              name: "addResult",
-              type: "(result: TResult | ToolResponse<TResult>) => void",
-              description:
-                "Function to add a result (useful for human-in-the-loop tools)",
-            },
-            {
-              name: "artifact",
-              type: "unknown",
-              description:
-                "Optional artifact data associated with the tool call",
-            },
-          ],
-        },
-      ],
-    },
-  ]}
-/>
-
-### 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) => {
-    // Tool logic
-    return { sent: true };
-  },
-});
-
-// Create tool components
-const EmailValidator = makeAssistantTool({
-  ...validateEmail,
-  toolName: "validateEmail",
-});
-const EmailSender = makeAssistantTool({
-  ...sendEmail,
-  toolName: "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/guides/generative-ui.mdx

@@ -1,142 +0,0 @@
----
-title: Generative UI
-description: Render agent-described React UI from a JSON spec with a consumer-provided component allowlist.
----
-
-`MessagePrimitive.GenerativeUI` is a first-class primitive for rendering UI
-described by the agent at runtime as a JSON spec. Instead of hard-coding a
-component per tool, the agent emits a `generative-ui` message part containing
-a tree of components by name. assistant-ui resolves each name against a
-**consumer-provided allowlist** and renders the result.
-
-> The allowlist controls **which** components the agent may render: any name
-> not in it throws a typed `GenerativeUIRenderError` (no implicit fallback). It
-> does not constrain the props passed to those components; see [Security](#security).
-
-## Quick start
-
-### 1. Define your component allowlist
-
-```tsx title="components/gui.tsx"
-const Card = ({ title, children }) => (
-  <div className="rounded-xl border bg-card p-4 shadow-sm">
-    <div className="text-base font-semibold">{title}</div>
-    <div className="mt-2">{children}</div>
-  </div>
-);
-
-const Button = ({ label }) => (
-  <button className="rounded-md bg-primary px-3 py-1.5 text-primary-foreground">
-    {label}
-  </button>
-);
-
-export const componentsAllowlist = { Card, Button };
-```
-
-### 2. Wire the primitive into your message renderer
-
-```tsx title="components/assistant-message.tsx"
-import { MessagePrimitive } from "@assistant-ui/react";
-import { componentsAllowlist } from "./gui";
-
-export function AssistantMessage() {
-  return (
-    <MessagePrimitive.Parts
-      components={{
-        generativeUI: { components: componentsAllowlist },
-      }}
-    />
-  );
-}
-```
-
-You can also use the standalone primitive form:
-
-```tsx
-<MessagePrimitive.GenerativeUI components={componentsAllowlist} />
-```
-
-### 3. Have the agent emit a `generative-ui` part
-
-A `GenerativeUIMessagePart` carries a JSON spec:
-
-```ts
-{
-  type: "generative-ui",
-  spec: {
-    root: {
-      component: "Card",
-      props: { title: "Welcome" },
-      children: [
-        { component: "Button", props: { label: "Get started" } },
-      ],
-    },
-  },
-}
-```
-
-Bare strings act as inline text leaves.
-
-## Spec shape
-
-```ts
-type GenerativeUINode =
-  | string
-  | {
-      component: string;             // resolved against the allowlist
-      props?: Record<string, unknown>;
-      children?: GenerativeUINode[];
-      key?: string;                   // optional stable React key
-    };
-
-type GenerativeUISpec = {
-  root: GenerativeUINode | GenerativeUINode[];
-};
-```
-
-The spec is plain JSON — easy for any agent to emit, and easy to validate
-on the server before delivery.
-
-## Streaming
-
-The primitive is stream-friendly: any partial spec renders progressively. As
-new nodes arrive (filling in `children`, refining `props`), the rendered tree
-updates without reflows or lost local state for already-mounted children.
-
-## Security
-
-The allowlist is the boundary on **which** components render: a spec can only instantiate components you put in the registry, with no `eval` and no dynamic import (names are looked up in the registry and nothing else). An unknown name throws `GenerativeUIRenderError` or invokes your `Fallback`.
-
-It does **not** constrain the `props` the agent supplies. Spec props are spread directly onto your allowlisted components, so treat every allowlisted component as receiving untrusted input: never forward agent-supplied props into `dangerouslySetInnerHTML`, validate or reject `href` / `src` values (for example block `javascript:` URLs), and avoid passing spec props anywhere they become executable. The safest allowlisted components accept only primitive, display-oriented props.
-
-## Error handling
-
-Unknown component names throw `GenerativeUIRenderError` with a typed
-`componentName` field. Catch it with a React error boundary, or pass a
-`Fallback` component to opt into a soft-fail UX:
-
-```tsx
-<MessagePrimitive.GenerativeUI
-  components={componentsAllowlist}
-  Fallback={({ component }) => (
-    <span className="rounded bg-muted px-1.5 py-0.5 font-mono text-xs">
-      unknown component: {component}
-    </span>
-  )}
-/>
-```
-
-## Composing with other primitives
-
-`generative-ui` is a regular `MessagePart` type, so it composes cleanly with
-`MessagePrimitive.Parts`, `MessagePrimitive.PartByIndex`, and
-`MessagePrimitive.GroupedParts`. Render it alongside text, tool calls, and
-reasoning in the same message.
-
-## Why a primitive (not just a tool)
-
-Tool-call UI is great when the agent already invoked a known tool. Generative
-UI flips it: the agent _composes_ UI from a vocabulary you ship. Useful for
-forms, dashboards, status panels, multi-step flows, and anywhere the
-component library you want is broader than a single tool's render surface.