@assistant-ui/mcp-docs-server 0.1.1

package/.docs/raw/docs/migrations/v0-7.mdx

@@ -0,0 +1,188 @@
+---
+title: Migration to v0.7
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+This guide serves as a reference for users facing breaking changes during upgrade to v0.7. You do not need to read this guide to upgrade to v0.7.
+
+All breaking changes in v0.7 are renames or removals of existing APIs. Therefore, all breaking changes should cause a Typescript error, so you can simply check for errors after upgrading.
+
+### Component Property Types moved to `Component.Props`
+
+Component property types are now neatly organized under the component itself.
+
+```diff
+-import { ThreadPrimitiveMessagesProps } from "@assistant-ui/react";
++import { ThreadPrimitive } from "@assistant-ui/react";
+
+-type Props = ThreadPrimitiveMessagesProps;
++type Props = ThreadPrimitive.Messages.Props;
+```
+
+## Context API simplifications
+
+### `useThreadContext`, `useMessageContext`, ... replaced with direct imports of stores
+
+`useAssistantContext`, `useThreadContext`, `useMessageContext` and `useContentPartContext` have been removed in favor of direct exports from `@assistant-ui/react`;
+
+```diff
+-const { useThread } = useThreadContext();
+
++import { useThread } from "@assistant-ui/react";
+```
+
+# Assistant Context API simplifications
+
+### `useAssistantActions` replaced with `useAssistantRuntime`
+
+`useAssistantActions` has been removed in favor of `useAssistantRuntime`.
+
+```diff
+-const switchToNewThread = useAssistantActions(a => a.switchToNewThread);
++const runtime = useAssistantRuntime();
++runtime.switchToNewThread();
+```
+
+### `switchToThread(null)` replaced with `switchToNewThread()`
+
+```diff
+-useThreadRuntime().switchToThread(null);
++useThreadRuntime().switchToNewThread();
+```
+
+### useSwtichToNewThread() moved to useAssistantRuntime().switchToNewThread()
+
+```diff
+-useSwitchToNewThread();
++const runtime = useAssistantRuntime()
++runtime.switchToNewThread(); 
+```
+
+### `runtime.subscribe` removed, `subscribeToMainThread` removed
+
+Previously, you needed to subscribe to the runtime to receive updates whenever the main thread changed and resubscribe to the main thread whenever you switched to a new thread. The `runtime.thread` value now always refers to the current main thread, there is no need to subscribe to the runtime anymore.
+
+## ThreadRuntime API simplifications
+
+### `useAppendMessage` moved to `useThreadRuntime().append()`
+
+```diff
+-const append = useAppendMessage();
++const threadRuntime = useThreadRuntime();
+-append("hello world");
++threadRuntime.append("hello world");
+```
+
+### `useThreadActions` replaced with `useThreadRuntime`
+
+`useThreadActions` has been removed in favor of `useThreadRuntime`.
+
+```diff
+-const reload = useThreadActions(a => a.reload);
++const threadRuntime = useThreadRuntime();
++threadRuntime.reload();
+```
+
+### State values moved to `threadRuntime.getState()`
+
+In order to make it clear that accessing the state only provides a snapshot of the current state and will not cause a re-render on changes, the state values of `useThreadRuntime` have been moved to `threadRuntime.getState()`.
+
+```diff
+-const isRunning = useThreadRuntime().isRunning; // anti-pattern, your code will not update on change
++const isRunning = useThread(t => t.isRunning);
+```
+
+### `useThreadStore` replaced with `useThreadRuntime().getState()`
+
+`useThreadStore` has been removed in favor of `useThreadRuntime().getState()`.
+
+### `threadRuntime.getBranches()` replaced with `useThreadRuntime().getMessageByIndex(idx).getState().branchNumber/Count`
+
+The branch IDs are an internal implementation detail. The new Message Runtime API provides `branchNumber` and `branchCount` state fields that can be used instead.
+
+### New Message Runtime API replaces several methods from `useThreadRuntime`
+
+A few methods from `useThreadRuntime` have been moved to `useMessageRuntime()`.
+
+- `threadRuntime.switchToBranch()` has been removed in favor of `useThreadRuntime().getMessageByIndex(idx).switchToBranch()`.
+- `threadRuntime.addToolResult()` has been removed in favor of `useThreadRuntime().getMessageByIndex(idx).getContentPartByToolCallId(toolCallId).addToolResult()`.
+- `threadRuntime.speak()` has been removed in favor of `useThreadRuntime().getMessageByIndex(idx).speak()`.
+- `threadRuntime.submitFeedback()` has been removed in favor of `useThreadRuntime().getMessageByIndex(idx).submitFeedback()`.
+- `threadRuntime.getEditComposer()` has been removed in favor of `useThreadRuntime().getMessageById(id).getMessageByIndex(idx).composer`.
+- `threadRuntime.beginEdit()` has been removed in favor of `useThreadRuntime().getMessageById(id).getMessageByIndex(idx).composer.beginEdit()`.
+
+## Composer Runtime API simplifications
+
+### Methods inside `useComposer` moved to `useComposerRuntime`
+
+`useComposer()` used to provide several methods such as `setText`, `addAttachment`, `send`, `edit`, `cancel`, ...
+These methods have been moved to `useComposerRuntime()`.
+
+### `useComposerStore` replaced with `useComposerRuntime().getState()`
+
+`useComposerStore` has been removed in favor of `useComposerRuntime().getState()`.
+
+### `value` `setValue` replaced with `text` `setText`
+
+```diff
+-useComposer(c => c.value);
++useComposer(c => c.text);
+```
+
+### `focus`, `onFocus` methods removed
+
+These methods have been removed.
+
+## Message Context API simplifications
+
+### Flattened context values `useMessage().message` -> `useMessage()`
+
+`MessageState` is now itself a message, so you no longer need to access the nested `useMessage().message` field.
+
+```diff
+-useMessage(m => m.message.content);
++useMessage(m => m.content);
+```
+
+### `useMessageStore` replaced with `useMessageRuntime().getState()`
+
+`useMessageStore` has been removed in favor of `useMessageRuntime().getState()`.
+
+## Content Part Context API simplifications
+
+### Flattened context values `useContentPart().part` -> `useContentPart()`
+
+`ContentPartState` is now itself a content part, so you no longer need to access the nested `useContentPart().part` field.
+
+```diff
+-useContentPart(c => c.part.type);
++useContentPart(c => c.type);
+```
+
+This also applies to tool UI render functions:
+
+```diff
+ makeAssistantToolUI({
+   ...
+-  render: ({ part: { args } }) => <>{args}</>,
++  render: ({ args }) => <>{args}</>,
+ });
+```
+
+## Attachment Context API simplifications
+
+### Flattened context values `useAttachment().attachment` -> `useAttachment()`
+
+`AttachmentState` is now itself an attachment, so you no longer need to access the nested `useAttachment().attachment` field.
+
+```diff
+-useAttachment(a => a.attachment.type);
++useAttachment(a => a.type);
+```
+
+## Roundtrips renamed to steps
+
+`AssistantMessage.roundtrips` was renamed to `AssistantMessage.metadata.steps`.
+
+Edge runtime's `maxToolRoundtrips` was replaced with `maxSteps` (which is `maxToolRoundtrips` + 1; if you had `maxToolRoundtrips` at 2, set `maxSteps` to 3).

package/.docs/raw/docs/migrations/v0-8.mdx

@@ -0,0 +1,160 @@
+---
+title: Migration to v0.8
+---
+
+## Styled Components moved to @assistant-ui/react-ui
+
+All styled components (Thread, ThreadList, AssistantModal, makeMarkdownText, etc.) have been moved to a new package, `@assistant-ui/react-ui`.
+
+To migrate, use the migration codemod:
+
+```sh
+# IMPORTANT: make sure to commit all changes to git / creating a backup before running the codemod
+npx assistant-ui upgrade
+```
+
+## Vercel AI SDK RSC requires additional setup
+
+Built-in RSC support in assistant-ui has been removed, so an additional setup step is required.
+The RSC runtime now requires additional setup to display React Server Components.
+
+```ts
+import { RSCDisplay } from "@assistant-ui/react-ai-sdk";
+
+// if you are using the default Thread component
+// add RSCDisplay to assistantMessage.components.Text
+<Thread assistantMessage={{ components: { Text: RSCDisplay } }} />
+
+
+// if you are using unstyled primitives, update MyThread.tsx
+<MessagePrimitive.Content components={{ Text: RSCDisplay }} />
+```
+
+## Migrate away from UIContentPart
+
+For instructions on migrating for Vercel AI SDK RSC, see section above.
+This migration guide is for users of `useExternalStoreRuntime`.
+
+### Recommended Approach: Use ToolUI
+
+First, reconsider your approach.
+
+Creating UI components in the `convertMessage` callback is considered an anti-pattern.
+The recommended alternative approach is to pass tool-call content parts, and use `makeAssistantToolUI` to map these tool calls to UI components.
+
+This ensures that the data layer is separate and decoupled from the UI layer.
+
+#### Example
+
+Consider the following example, where you are using a UIContentPart to show a loading indicator.
+
+```ts title="bad.ts"
+// THIS IS BAD
+const convertMessage = (message: MyMessage): ThreadMessageLike => {
+  if (message.isLoading) {
+    return { content: [{ type: "ui", display:< MyLoader /> }] };
+  }
+  // ...
+};
+```
+
+```ts title="good.ts"
+const convertMessage = (message: MyMessage): ThreadMessageLike => {
+  if (message.isLoading) {
+    return { content: [] };
+  }
+  // ...
+};
+
+// use the empty content part to show the loading indicator
+<Thread assistantMessage={{ components: { Empty: MyLoader } }} />;
+```
+
+(if you are using unstyled primitives, update MyThread.tsx, and pass the component to MessagePrimitive.Content)
+
+#### Example 2
+
+Consider the following example, where you are displaying a custom chart based on data received from an external source.
+
+```ts title="bad.ts"
+// THIS IS BAD
+const convertMessage = (message: MyMessage): ThreadMessageLike => {
+  return { content: [{ type: "ui", display: <MyChart data={message.chartData} /> }] };
+};
+```
+
+```ts title="good.ts"
+const convertMessage = (message: MyMessage): ThreadMessageLike => {
+  return {
+    content: [
+      {
+        type: "tool-call",
+        toolName: "chart",
+        args: message.chartData,
+      },
+    ],
+  };
+};
+
+const ChartToolUI = makeAssistantToolUI({
+  toolName: "chart",
+  render: ({ args }) => <MyChart data={args} />,
+});
+
+// use tool UI to display the chart
+<Thread tools={[ChartToolUI]} />;
+```
+
+(if you are using unstyled primitives, render the `<ChartToolUI />` component anywhere inside your AssistantRuntimeProvider)
+
+### Fallback Approach: Override ContentPartText
+
+However, sometimes you receive UI components from an external source.
+
+The example below assumes that your custom `MyMessage` type has a `display` field.
+
+First, we define a dummy `UI_PLACEHOLDER` content part, which we will replace with the UI component later:
+
+```ts
+const UI_PLACEHOLDER = Object.freeze({
+  type: "text",
+  text: "UI content placeholder",
+});
+const convertMessage = (message: MyMessage): ThreadMessageLike => ({
+  content: [
+    // other content parts,
+    UI_PLACEHOLDER,
+  ],
+});
+```
+
+Then, we define a custom `TextContentPartComponent`:
+
+```tsx
+const MyText: TextContentPartComponent = () => {
+  const isUIPlaceholder = useContentPart((p) => p === UI_PLACEHOLDER);
+
+  // this assumes that you have a `display` field on your original message objects before conversion.
+  const ui = useMessage((m) =>
+    isUIPlaceholder ? getExternalStoreMessage(m).display : undefined,
+  );
+  if (ui) {
+    return ui;
+  }
+
+  return <MarkdownText />; // your default text component
+};
+```
+
+We pass this component to our Thread:
+
+```tsx
+<Thread
+  assistantMessage={{ components: { Text: MyText } }}
+  userMessage={{ components: { Text: MyText } }}
+/>
+```
+
+(if you are using unstyled primitives, update MyThread.tsx, and pass the component to MessagePrimitive.Content)
+
+Now, the `UI_PLACEHOLDER` content part is replaced with the UI component we defined earlier.

package/.docs/raw/docs/migrations/v0-9.mdx

@@ -0,0 +1,75 @@
+---
+title: Migration to v0.9
+---
+
+## Edge Runtime moved to @assistant-ui/react-edge
+
+The edge runtime, as well as the `CoreMessage` type, moved to `@assistant-ui/react-edge`.
+
+The following components and types have been moved to `@assistant-ui/react-edge`:
+
+- Edge Runtime
+
+  - `useEdgeRuntime`
+  - `EdgeRuntimeOptions`
+  - `EdgeModelAdapter`
+  - `EdgeChatAdapter`
+  - `EdgeRuntimeRequestOptions`
+  - `createEdgeRuntimeAPI`
+  - `getEdgeRuntimeResponse`
+
+- Core Types
+  - `CoreMessage`
+  - `CoreUserMessage`
+  - `CoreAssistantMessage`
+  - `CoreSystemMessage`
+  - `CoreUserContentPart`
+  - `CoreAssistantContentPart`
+  - `CoreToolCallContentPart`
+- Core message converters
+  - `fromCoreMessages`
+  - `fromCoreMessage`
+  - `toCoreMessages`
+  - `toCoreMessage`
+
+To migrate, use the migration codemod:
+
+```sh
+# IMPORTANT: make sure to commit all changes to git / creating a backup before running the codemod
+npx assistant-ui upgrade
+```
+
+## Language Model converters and useDangerousInBrowserRuntime moved to @assistant-ui/react-ai-sdk
+
+The following methods have been moved to `@assistant-ui/react-ai-sdk`:
+
+- Language Model converters
+  - `toLanguageModelMessages`
+  - `toLanguageModelTools`
+  - `fromLanguageModelMessages`
+  - `fromLanguageModelTools`
+- Dangerous in Browser Runtime
+  - `useDangerousInBrowserRuntime`
+
+To migrate, use the migration codemod:
+
+```sh
+# IMPORTANT: make sure to commit all changes to git / creating a backup before running the codemod
+npx assistant-ui upgrade
+```
+
+## LangGraph `unstable_allowImageAttachments` removed
+
+The `unstable_allowImageAttachments` option has been removed. Use the `adapters` option instead.
+
+```ts
+useLangGraphRuntime({
+  adapters: {
+    attachments: new SimpleImageAttachmentAdapter(),
+  },
+});
+```
+
+## Markdown `components.by_language` removed
+
+The `components.by_language` option has been removed. Use the `componentsByLanguage` option instead.

package/.docs/raw/docs/react-compatibility.mdx

@@ -0,0 +1,208 @@
+---
+title: Using old React versions
+description: Guide for using assistant-ui with older React versions (18, 17, 16)
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+<Callout type="warning" title="Older React Versions">
+  Older React versions are not continuously tested. If you encounter any issues
+  with integration, please contact us for help by joining our
+  [Discord](https://discord.gg/S9dwgCNEFs).
+</Callout>
+
+This guide provides instructions for configuring assistant-ui to work with React 18 or older versions.
+
+## React 18
+
+If you're using React 18, you need to update the shadcn/ui components to work with `forwardRef`. Specifically, you need to modify the Button component.
+
+### Updating the Button Component
+
+Navigate to your button component file (typically `/components/ui/button.tsx`) and wrap the Button component with `forwardRef`:
+
+```tsx
+// Before
+function Button({
+  className,
+  variant,
+  size,
+  asChild = false,
+  ...props
+}: React.ComponentProps<"button"> &
+  VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+  }) {
+  const Comp = asChild ? Slot : "button";
+
+  return (
+    <Comp
+      data-slot="button"
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  );
+}
+
+// After
+const Button = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentProps<"button"> &
+    VariantProps<typeof buttonVariants> & {
+      asChild?: boolean;
+    }
+>(({ className, variant, size, asChild = false, ...props }, ref) => {
+  const Comp = asChild ? Slot : "button";
+
+  return (
+    <Comp
+      data-slot="button"
+      className={cn(buttonVariants({ variant, size, className }))}
+      ref={ref}
+      {...props}
+    />
+  );
+});
+Button.displayName = "Button";
+```
+
+**Note:** If you're using a lower React version (17 or 16), you'll also need to follow the instructions for that version.
+
+## React 17
+
+For React 17 compatibility, in addition to the modifications outlined for React 18, you must also include a polyfill for the `useSyncExternalStore` hook (utilized by zustand).
+
+### Patching Zustand with patch-package
+
+Since the assistant-ui uses zustand internally, which depends on `useSyncExternalStore`, you'll need to patch the zustand package directly:
+
+1. Install the required packages:
+
+```bash
+npm install use-sync-external-store patch-package
+# or
+yarn add use-sync-external-store patch-package
+```
+
+2. Add a postinstall script to your package.json:
+
+```json
+{
+  "scripts": {
+    "postinstall": "patch-package"
+  }
+}
+```
+
+3. You'll want to follow the instructions in [patch-package](https://github.com/ds300/patch-package), by first making changes to the files of a particular package in your node_modules folder, then running either `yarn patch-package package-name` or `npx patch-package package-name`. You'll need a patch for zustand - within `node_modules/zustand`, open `zustand/react.js` and make the following code changes:
+
+```diff
+diff --git a/node_modules/zustand/react.js b/node_modules/zustand/react.js
+index 7599cfb..64530a8 100644
+--- a/node_modules/zustand/react.js
++++ b/node_modules/zustand/react.js
+@@ -1,6 +1,6 @@
+ 'use strict';
+
+-var React = require('react');
++var React = require('use-sync-external-store/shim');
+ var vanilla = require('zustand/vanilla');
+
+ const identity = (arg) => arg;
+@@ -10,7 +10,7 @@ function useStore(api, selector = identity) {
+     () => selector(api.getState()),
+     () => selector(api.getInitialState())
+   );
+-  React.useDebugValue(slice);
++  //React.useDebugValue(slice);
+   return slice;
+ }
+ const createImpl = (createState) => {
+
+This patch replaces the React import in zustand with the polyfill from `use-sync-external-store/shim` and comments out the `useDebugValue` call which isn't needed.
+
+You should then run the patch-package command `yarn patch-package zustand` or `npx patch-package zustand` which should create a `patches` folder with a zustand patch file similar looking to this:
+
+```diff
+diff --git a/node_modules/zustand/react.js b/node_modules/zustand/react.js
+index 7599cfb..64530a8 100644
+--- a/node_modules/zustand/react.js
++++ b/node_modules/zustand/react.js
+@@ -1,6 +1,6 @@
+ 'use strict';
+
+-var React = require('react');
++var React = require('use-sync-external-store/shim');
+ var vanilla = require('zustand/vanilla');
+
+ const identity = (arg) => arg;
+@@ -10,7 +10,7 @@ function useStore(api, selector = identity) {
+     () => selector(api.getState()),
+     () => selector(api.getInitialState())
+   );
+-  React.useDebugValue(slice);
++  //React.useDebugValue(slice);
+   return slice;
+ }
+ const createImpl = (createState) => {
+```
+
+4. You may also need to apply the same patches within `node_modules/@assistant-ui/react/` and possibly a nested dependency patch for `node_modules/@assistant-ui/react/node_modules/zustand`. Look for instances of `React.useSyncExternalStore` and replace with `{ useSyncExternalStore } from "use-sync-external-store/shim";` and comment out any `useDebugValue` calls. Finally, you may need to patch `useId` from React, so within `node_modules/@assistant-ui/react/dist/runtimes/remote-thread-list/RemoteThreadListThreadListRuntimeCore.js`, change the following:
+
+```diff
+-import { Fragment, useEffect, useId } from "react";
++import { Fragment, useEffect, useRef } from "react";
+ import { create } from "zustand";
+ import { AssistantMessageStream } from "assistant-stream";
+ import { RuntimeAdapterProvider } from "../adapters/RuntimeAdapterProvider.js";
+ import { jsx } from "react/jsx-runtime";
++
++// PATCH-PACKAGE: Polyfill for useId if not available in React 16
++let useId;
++try {
++  // Try to use React's useId if available
++  useId = require("react").useId;
++} catch (e) {}
++if (!useId) {
++  // Fallback polyfill
++  let globalId = 0;
++  useId = function() {
++    const idRef = useRef();
++    if (!idRef.current) {
++      globalId++;
++      idRef.current = `uid-${globalId}`;
++    }
++    return idRef.current;
++  };
++}
+```
+
+5. Run the postinstall script to apply the patches:
+
+```bash
+npm run postinstall
+# or
+yarn postinstall
+```
+
+This patch replaces the React import in zustand with the polyfill from `use-sync-external-store/shim` and comments out the `useDebugValue` call which isn't needed.
+
+**Note:** If you're using React 16, you'll also need to follow the instructions for that version.
+
+## React 16
+
+<Callout type="info" title="Incomplete Section">
+  This section is incomplete and contributions are welcome. If you're using
+  React 16 and have successfully integrated assistant-ui, please consider
+  contributing to this documentation.
+</Callout>
+
+For React 16 compatibility, you need to apply all the steps for **React 18** and **React 17** above.
+
+## Additional Resources
+
+If you encounter any issues with React compatibility, please:
+
+1. Check that all required dependencies are installed
+2. Ensure your component modifications are correctly implemented
+3. Join our [Discord](https://discord.gg/S9dwgCNEFs) community for direct support