@assistant-ui/mcp-docs-server 0.1.1

package/.docs/raw/docs/cloud/authorization.mdx

@@ -0,0 +1,152 @@
+---
+title: User Authorization
+---
+
+The assistant-ui API can be directly accessed by your frontend. This elliminates the need for a backend server from your side, except for authorization of your users.
+
+This document explains how you can setup your server to authorize users to access the assistant-ui API.
+
+## Workspaces
+
+Authorization is granted to a workspace. Depending on the structure of your app, you might want to use user_ids as the workspace_id, or you might want to use a more complex structure.
+For example, if your app supports multiple "projects", you might want to use the project_id + user_id as the workspace id (thread history scoped to user+project pairs).
+
+## Workspace Auth Tokens
+
+assistant-ui issues workspace auth tokens. These tokens give access to the assistant-ui API for a specific workspace.
+Tokens are short lived (5 minutes), so the client needs to periodically request a new token (handled by assistant-ui).
+
+There are two supported approaches to obtain a workspace auth token:
+
+- Direct integration with your auth provider
+- From a backend server / serverless function
+
+### Choosing the right approach
+
+Direct integration with your auth provider:
+
+- simpler to setup and maintain
+- assigns a workspace_id to every user (by using the user_id as the workspace_id)
+- requires a supported auth provider (Clerk, Auth0, Supabase, Firebase, Stytch, Kinde, ...)
+
+Backend server:
+
+- more complex to setup
+- more flexible workspace structure (multi-user workspaces, workspaces per project, etc.)
+- supports self hosted auth solutions, e.g. Auth.js
+- requires a backend server / serverless function
+
+You can always switch between the two approaches without any downtime or necessary database migrations.
+Choose direct integration with your auth provider if you can. Otherwise, use a backend server.
+
+### Auth Provider Integration
+In the AssistantUI dashboard, go to the "Auth Integrations" tab and add a new integration.
+Follow the steps to add your auth provider. (See the auth providers we have guides for at the bottom of this page.)
+
+Then, pass in a function to `authToken` that returns an ID token from your auth provider.
+
+```ts
+import { AssistantCloud } from "@assistant-ui/react";
+
+const assistantCloud = new AssistantCloud({
+  authToken: () => JWT_TOKEN
+});
+```
+
+### Integration with an Auth Provider
+
+#### Backend API Endpoint
+
+The following is an api route example to create an auth token based on an authenticated user's orgId and userId.
+
+In the Assistant Cloud dashboard, go to the "API Keys" tab and add a new API key, add the key the environment variable `ASSISTANT_API_KEY=[KEY]`
+
+```ts title="/app/api/assistant-ui-token/route.ts"
+import { AssistantCloud } from "@assistant-ui/react";
+import { auth } from "@clerk/nextjs/server";
+ 
+export const POST = async (req: Request) => {
+  const { userId, orgId } = await auth();
+ 
+  if (!userId) throw new Error("User not authenticated");
+ 
+  const workspaceId = orgId ? `${orgId}:${userId}` : userId;
+  const assistantCloud = new AssistantCloud({
+    apiKey: process.env["ASSISTANT_API_KEY"]!,
+    userId,
+    workspaceId,
+  });
+  const {token} = await assistantCloud.auth.tokens.create();
+
+  return new Response(token);
+};
+```
+
+#### Frontend Implementation
+
+The following is an api route example to create an auth token based on an authenticated user's orgId and userId.
+
+```ts title="client.ts"
+const cloud = new AssistantCloud({
+  baseUrl: process.env["NEXT_PUBLIC_ASSISTANT_BASE_URL"]!,
+  authToken: () =>
+    fetch("/api/assistant-ui-token", { method: "POST" }).then((r) =>
+      r.json().then((data) => data.token)
+    ),
+});
+
+const runtime = useChatRuntime({
+  api: "/api/chat",
+  cloud,
+});
+```
+
+### Anonymous (without auth provider) Frontend Implementation
+
+The following is a example to get auth tokens for Clerk based on the org_id and user_id:
+
+```ts title="/app/api/assistant-ui-token/route.ts"
+import { AssistantCloud } from "@assistant-ui/react";
+
+const cloud = new AssistantCloud({
+  baseUrl: process.env["NEXT_PUBLIC_ASSISTANT_BASE_URL"]!,
+  anonymous: true,
+});
+
+const runtime = useChatRuntime({
+  api: "/api/chat",
+  cloud,
+});
+
+return (
+  <AssistantRuntimeProvider runtime={runtime}>
+    <div className="grid h-dvh grid-cols-[200px_1fr] gap-x-2 px-4 py-4">
+      <ThreadList />
+      <MyThread />
+    </div>
+  </AssistantRuntimeProvider>
+);
+
+```
+
+
+### Setting up the Clerk Auth Provider
+
+First, go to the Clerk dashboard and under "Configure" tab, "JWT Templates" section, create a new template. Choose a blank template and name it "assistant-ui".
+
+As the "Claims" field, enter the following:
+
+```json
+{
+  "aud": "assistant-ui"
+}
+```
+
+<Callout emoji="⚠️">
+  <b>Note:</b> The aud claim ensures that the JWT is only valid for the
+  assistant-ui API.
+</Callout>
+
+You can leave everything else as default. Take note of the "Issuer" and "JWKS Endpoint" fields.
+
+Then, In the assistant-cloud dashboard, navigate to the "Auth Rules" tab and create a new rule. Choose "Clerk" and enter the Issuer and JWKS Endpoint from the previous step. As the "Audience" field, enter "assistant-ui".

package/.docs/raw/docs/cloud/overview.mdx

@@ -0,0 +1,55 @@
+---
+title: Overview
+---
+
+Assistant Cloud is a hosted service built for assistant-ui frontends that offers comprehensive thread management and message history. It automatically persists threads, supports human-in-the-loop workflows, and integrates with common auth providers to seamlessly allow users to resume conversations at any point.
+
+
+## Features
+
+### Thread management
+
+Using our `<ThreadList />` component, show the users a list of conversations. Allow the users to seamlessly switch between conversations and even let long running tasks run in the background.
+
+Assistant Cloud automatically persists a list of threads and corresponding metadata. It also automatically generates a title for conversations based on the initial messages.
+
+Supported backends:
+
+- AI SDK
+- LangGraph
+- Custom
+
+### Chat history
+
+For every conversation, Assistant Cloud can store the history of messages, allowing the user to resume the conversation at any point in time.
+This supports human in the loop workflows, where the execution of an agent is interrupted until user feedback is collected.
+
+Supported backends:
+
+- AI SDK
+- LangGraph
+- Custom (currently only Local Runtime)
+
+### Authorization
+
+Assistant Cloud integrates with your auth provider (Clerk, Auth0, Supabase, Firebase, ...) to identify your users and authorize them to access just the conversations they are allowed to see.
+
+Supported auth providers:
+
+- Clerk
+- Auth0
+- Supabase
+- Firebase
+- Your own
+
+## Getting Started
+
+To get started, create an account at [Assistant Cloud Dashboard](https://cloud.assistant-ui.com/) and follow one of the walkthroughs for your preferred backend:
+
+- [AI SDK](/docs/cloud/persistence/ai-sdk)
+- [LangGraph](/docs/cloud/persistence/langgraph)
+
+You can also check out our example repositories to see how to integrate Assistant Cloud with your frontend:
+
+- [With AI SDK](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-cloud)
+- [With LangGraph](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-langgraph)

package/.docs/raw/docs/cloud/persistence/ai-sdk.mdx

@@ -0,0 +1,54 @@
+---
+title: Chat History for AI SDK
+---
+
+## Overview
+
+With the help of assistant-cloud, you can add thread management and thread history capabilities to assistant-ui. This guide will walk you through the process of integrating assistant-cloud with the AI SDK by Vercel.
+
+### Prerequisites
+
+You need an assistant-cloud account to follow this guide. You can sign up here: [https://cloud.assistant-ui.com/](https://cloud.assistant-ui.com/)
+
+### Setting up assistant-cloud project in your react project:
+
+1. Create a new project on the assistant-cloud dashboard and copy the Frontend API URL (`https://proj-[ID].assistant-api.com`) from the settings page.
+2. Add the url as an environment variable `NEXT_PUBLIC_ASSISTANT_BASE_URL`
+
+```bash
+NEXT_PUBLIC_ASSISTANT_BASE_URL=[YOUR_FRONTEND_API_URL]
+```
+3. Create a client side AssistantCloud instance. Note: this will create an anonymous user id that is tied to the user's browser session. For connecting to an auth provider to persist threads for a user based on a workspace and/or user id, look at [Cloud Authorization Docs](/docs/cloud/authorization).
+
+```typescript
+"use client";
+import {
+  AssistantCloud,
+  AssistantRuntimeProvider,
+  ThreadList,
+  Thread
+} from "@assistant-ui/react";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+
+
+const cloud = new AssistantCloud({
+  baseUrl: process.env["NEXT_PUBLIC_ASSISTANT_BASE_URL"]!,
+  anonymous: true,
+});
+
+
+const runtime = useChatRuntime({
+  api: "/api/chat",
+  cloud,
+});
+
+ return (
+  <AssistantRuntimeProvider runtime={runtime}>
+    <div className="grid h-dvh grid-cols-[200px_1fr] gap-x-2 px-4 py-4">
+      <ThreadList />
+      <Thread />
+    </div>
+  </AssistantRuntimeProvider>
+);
+
+```

package/.docs/raw/docs/cloud/persistence/langgraph.mdx

@@ -0,0 +1,123 @@
+---
+title: Chat History for LangGraph Cloud
+---
+
+## Overview
+
+With the help of assistant-cloud, you can add thread management and thread history capabilities to assistant-ui.  
+This guide will walk you through the process of integrating assistant-cloud with LangGraph Cloud.
+
+### Prerequisites
+
+You need an assistant-cloud account to follow this guide.  
+You can sign up here: https://cloud.assistant-ui.com/
+
+### Setting up an assistant-cloud project
+
+To get started, follow the steps below:
+
+- Create a new project on the assistant-cloud dashboard.
+- Navigate to the "Settings" tab and copy the Frontend API URL.
+- Add this URL to your .env file
+
+```bash
+NEXT_PUBLIC_ASSISTANT_BASE_URL=https://<your-frontend-api-url>
+```
+
+### Connecting the runtime provider
+
+Now that we have everything set up, let's write the code for the runtime provider.
+
+The code below is a simple LangGraph runtime provider that uses the assistant-cloud API to create and manage threads.
+
+```tsx twoslash {1-2,5-6,19,27,29-36,38-45}
+// @errors: 2307
+
+"use client";
+
+import {
+  AssistantCloud,
+  AssistantRuntimeProvider,
+  useCloudThreadListRuntime,
+  useThreadListItemRuntime,
+} from "@assistant-ui/react";
+import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
+import { createThread, getThreadState, sendMessage } from "@/lib/chatApi";
+import { LangChainMessage } from "@assistant-ui/react-langgraph";
+import { useAuth } from "@clerk/nextjs";
+import { useMemo } from "react";
+
+// ---cut---
+const useMyLangGraphRuntime = () => {
+  const threadListItemRuntime = useThreadListItemRuntime();
+  const runtime = useLangGraphRuntime({
+    stream: async function* (messages) {
+      const { externalId } = await threadListItemRuntime.initialize();
+      if (!externalId) throw new Error("Thread not found");
+
+      return sendMessage({ threadId: externalId, messages });
+    },
+    onSwitchToThread: async (externalId) => {
+      const state = await getThreadState(externalId);
+      return {
+        messages:
+          (state.values as { messages?: LangChainMessage[] }).messages ?? [],
+      };
+    },
+  });
+
+  return runtime;
+};
+
+export function MyRuntimeProvider({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  const { getToken } = useAuth();
+
+  const cloud = useMemo(
+    () =>
+      new AssistantCloud({
+        baseUrl: process.env["NEXT_PUBLIC_ASSISTANT_BASE_URL"]!,
+        authToken: async () => getToken({ template: "assistant-ui" }),
+      }),
+    [getToken],
+  );
+
+  const runtime = useCloudThreadListRuntime({
+    cloud,
+    runtimeHook: useMyLangGraphRuntime,
+    create: async () => {
+      const { thread_id } = await createThread();
+      return { externalId: thread_id };
+    },
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+<Callout emoji="💡">
+  Observe that the `useMyLangGraphRuntime` hook is extracted into a separate
+  function. This hook will be mounted multiple times, once per active thread.
+</Callout>
+
+### Displaying a ThreadList component
+
+Now, you can add a ThreadList component to your application. This component will display a list of threads and allow users to switch between them.
+
+```sh
+npx shadcn@latest add "https://r.assistant-ui.com/thread-list"
+```
+
+```tsx
+<div className="grid grid-cols-[250px_1fr]">
+  <ThreadList />
+  <Thread />
+</div>
+```

package/.docs/raw/docs/concepts/architecture.mdx

@@ -0,0 +1,19 @@
+---
+title: Architecture
+---
+
+import Image from "next/image";
+import architecture from "@/assets/docs/architecture.png";
+
+### Architecture
+
+`assistant-ui` consists of two parts, **_Runtime_** and **_UI Components_**.
+
+<Image
+  src={architecture}
+  alt="Architecture diagram, UI components connected to the runtime layer and the runtime layer connected to LLM and tools"
+  height={300}
+  className="mx-auto my-2 dark:hue-rotate-180 dark:invert"
+/>
+
+The Runtime and UI Components each require independent setup and both must be set up.

package/.docs/raw/docs/concepts/runtime-layer.mdx

@@ -0,0 +1,163 @@
+---
+title: Runtime Layer
+---
+
+assistant-ui components are full stack components. This means that they include both the UI presentation, but also logic to communicate with an external system. This logic is handled by the runtime layer and APIs.
+
+You interact with the runtime layer in two ways:
+
+- defining a runtime for your app
+- using the runtime APIs to interact with the runtime
+
+## Defining a runtime
+
+assistant-ui ships with two low-level runtimes:
+
+- `useLocalRuntime`
+- `useExternalStoreRuntime`
+
+Both of these runtimes let you implement your own runtime. The conceptual difference between the two is that `useLocalRuntime` takes ownership of the data layer, while `useExternalStoreRuntime` does not.
+
+If you have a stateful API to integrate, use `useExternalStoreRuntime`, if you have a stateless API to integrate, use `useLocalRuntime`.
+
+### Higher level runtimes
+
+For many services and APIs, assistant-ui provides deeper integrations. These are built with the two low-level runtimes mentioned above.
+
+- `useChatRuntime`: Connect to Vercel AI SDK backends
+- `useVercelUseChatRuntime`: Integrate with Vercel AI SDK's `useChat` hook
+- `useVercelUseAssistantRuntime`: Integrate with Vercel AI SDK's `useAssistant` hook (OpenAI Assistants API)
+- `useVercelRSCRuntime`: Integrate with Vercel AI SDK React Server Components
+- `useLangGraphRuntime`: Connect to LangGraph Cloud
+- ...
+
+### Runtime Providers
+
+The following components accept a `runtime` prop:
+
+- `AssistantRuntimeProvider`
+- `Thread`
+
+These components put the Runtime in the React Context, so that all child components can access the runtime.
+
+### Runtime Adapters
+
+Most runtimes accept additional adapters to configure extra integrations:
+
+- ChatModelAdapter: Configures the backend API
+- AttachmentAdapter: Configures the file/media attachment API
+- SpeechSynthesisAdapter: Configures the speech API
+- FeedbackAdapter: Configures the feedback API
+- SuggestionAdapter: Configures dynamic suggestion generation based on conversation context
+
+## Using the runtime APIs
+
+The same API used by the assistant-ui components is also available to you. This allows you to build your own UI components and integrate them with the runtime layer.
+
+### Runtime Hierarchy
+
+The runtime API is nested as such:
+
+import { File, Folder, Files } from "fumadocs-ui/components/files";
+
+<Files>
+  <Folder name="AssistantRuntime" defaultOpen>
+    <Folder name="ThreadListRuntime" defaultOpen>
+      <Folder name="ThreadRuntime" defaultOpen>
+        <Folder name="MessageRuntime" defaultOpen>
+          <Folder
+            name="ContentPartRuntime (Text / Reasoning / Image / Audio / Tool-Call / UI)"
+            defaultOpen
+          ></Folder>
+          <Folder name="MessageAttachmentRuntime" defaultOpen></Folder>
+          <Folder name="EditComposerRuntime" defaultOpen>
+            <Folder name="EditComposerAttachmentRuntime" defaultOpen></Folder>
+          </Folder>
+        </Folder>
+        <Folder name="ThreadComposerRuntime" defaultOpen>
+          <Folder name="ThreadComposerAttachmentRuntime" defaultOpen></Folder>
+        </Folder>
+      </Folder>
+    </Folder>
+  </Folder>
+</Files>
+
+The AssistantRuntime (which encompasses everything), is sometimes simply called `Runtime`.
+
+### Runtime Context Provider Components
+
+The following components provide the runtime APIs:
+
+```tsx
+// provides AssistantRuntime, ThreadListRuntime, ThreadRuntime, ComposerRuntime (ThreadComposer)
+<AssistantRuntimeProvider runtime={runtime} />
+
+// renders every message, provides MessageRuntime, ComposerRuntime (EditComposer)
+<ThreadPrimitive.Messages components={{ Message, ... }} />
+
+// renders every content part, provides ContentPartRuntime
+<MessagePrimitive.Content components={{ Text, Reasoning, Image, Audio, UI, tools }} />
+
+// renders every attachment, provides AttachmentRuntime (Thread or EditComposer)
+<ComposerPrimitive.Attachments components={{ Attachment, ... }} />
+
+// renders every attachment, provides AtatchmentRuntime (Message)
+<MessagePrimitive.Attachments components={{ Attachment, ... }} />
+
+// provides a custom TextContentPartRuntime
+<TextContentPartProvider text="Hello!" />
+```
+
+### Accessing runtime APIs
+
+You can access the runtime APIs with react hooks:
+
+```tsx
+const runtime = useAssistantRuntime();
+const threadRuntime = useThreadRuntime();
+const messageRuntime = useMessageRuntime();
+const contentPartRuntime = useContentPartRuntime();
+
+// thread manager has no separate hook (1:1 relationship with assistant runtime)
+const ThreadListRuntime = useAssistantRuntime().threads;
+
+// composer runtime is multi-use
+const composerRuntime = useComposerRuntime(); // refers to edit composer if available, otherwise thread composer
+
+// thread manager has no separate hook (1:1 relationship with assistant runtime)
+const threadComposer = useThreadRuntime().composer;
+
+// thread manager has no separate hook (1:1 relationship with assistant runtime)
+const editComposerRuntime = useMessageRuntime().composer;
+
+// attachment runtime is multi-use
+const attachmentRuntime = useAttachmentRuntime(); // refers to the closest attachment runtime
+const threadComposerAttachmentRuntime = useThreadComposerAttachmentRuntime();
+const editComposerAttachmentRuntime = useEditComposerAttachmentRuntime();
+const messageAttachmentRuntime = useMessageAttachmentRuntime();
+```
+
+### Accessing runtime state
+
+Most runtimes also expose a state through two methods `getState` and `subscribe`. The following helper hooks subscribe to the state, so that your component is updated when the state changes:
+
+```tsx
+useThreadList(); // get thread manager state
+useThread(); // get thread state
+useMessage(); // get message state
+useContentPart(); // get content part state
+useComposer(); // get composer state
+useThreadComposer(); // get thread composer state
+useEditComposer(); // get edit composer state
+useAttachment(); // get attachment state
+useThreadComposerAttachment(); // get thread composer attachment state
+useEditComposerAttachment(); // get edit composer attachment state
+useMessageAttachment(); // get message attachment state
+```
+
+You might not want to subscribe to evey update. In that case, pass a callback selector to the hook:
+
+```tsx
+// only subscribe to role changes
+const role = useMessage((state) => message.role);
+```

package/.docs/raw/docs/concepts/why.mdx

@@ -0,0 +1,9 @@
+---
+title: Why assistant-ui?
+---
+
+assistant-ui is a collection of powerful, modular primitives to build AI chat interfaces.
+
+The modular approach means that you can incrementally adopt assistant-ui (e.g. use the backend connectors and bring your own components, or use the frontend compoents and bring your own backend).
+You can also partially opt out of assistant-ui whenever you hit any limitation in the library.
+

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

@@ -0,0 +1,71 @@
+---
+title: makeAssistantVisible
+---
+
+`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
+});
+```
+
+## 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
+
+### 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. Handle nested readable components (only the outermost component's HTML is provided)
+4. Forward refs and maintain component props
+
+## Example
+
+```tsx
+// Create a readable form input
+const Input = ({ label, ...props }) => (
+  <div>
+    <label>{label}</label>
+    <input {...props} />
+  </div>
+);
+
+const ReadableInput = makeAssistantVisible(Input);
+
+// Use in your component
+function Form() {
+  return (
+    <ReadableInput 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
+- All props and refs are properly forwarded to maintain component functionality