@assistant-ui/mcp-docs-server 0.1.28 → 0.1.30

package/.docs/raw/docs/ui/directive-text.mdx

@@ -0,0 +1,113 @@
+---
+title: Directive Text
+description: Render mention directives as inline chips in user messages.
+---
+
+import { DirectiveTextSample } from "@/components/docs/samples/directive-text";
+
+<DirectiveTextSample />
+
+`DirectiveText` parses the directive syntax written by [`ComposerTriggerPopover`](/docs/ui/composer-trigger-popover) (default: `:type[label]{name=id}`) and renders each segment as an inline chip. Use it as the `Text` component in user messages so the raw directive syntax never shows up.
+
+## Getting Started
+
+<Steps>
+  <Step>
+
+### Add `directive-text`
+
+<InstallCommand shadcn={["directive-text"]} />
+
+This adds `/components/assistant-ui/directive-text.tsx` with `DirectiveText` and the `createDirectiveText(formatter, options?)` factory.
+
+  </Step>
+  <Step>
+
+### Use in user messages
+
+Pass `DirectiveText` as the `Text` component in `MessagePrimitive.Parts`:
+
+```tsx title="components/assistant-ui/thread.tsx"
+import { DirectiveText } from "@/components/assistant-ui/directive-text";
+
+const UserMessage = () => (
+  <MessagePrimitive.Root>
+    <MessagePrimitive.Parts components={{ Text: DirectiveText }} />
+  </MessagePrimitive.Root>
+);
+```
+
+Keep your markdown renderer (e.g. `MarkdownText`) for assistant messages — assistants rarely emit directive syntax.
+
+  </Step>
+</Steps>
+
+## Icons per Directive Type
+
+`DirectiveText` ships icon-free by default — every parsed segment renders as a plain label chip regardless of its `type`. To add icons, use the `createDirectiveText` factory and pass an `iconMap` that routes each `type` string to an icon component, plus an optional `fallbackIcon` for unmapped types:
+
+```tsx
+import { createDirectiveText } from "@/components/assistant-ui/directive-text";
+import { unstable_defaultDirectiveFormatter } from "@assistant-ui/core";
+import { FileTextIcon, SparklesIcon, UserIcon, WrenchIcon } from "lucide-react";
+
+const DirectiveTextWithIcons = createDirectiveText(
+  unstable_defaultDirectiveFormatter,
+  {
+    iconMap: {
+      tool: WrenchIcon,
+      user: UserIcon,
+      file: FileTextIcon,
+    },
+    fallbackIcon: SparklesIcon,
+  },
+);
+
+<MessagePrimitive.Parts components={{ Text: DirectiveTextWithIcons }} />;
+```
+
+A matching `iconMap` / `fallbackIcon` option is accepted by [`ComposerTriggerPopover`](/docs/ui/composer-trigger-popover), where it routes `item.metadata.icon` strings instead of `type` — keeping icon configuration consistent across the composer and the rendered message.
+
+## Custom Formatter
+
+The default format is `:type[label]{name=id}`. For a different format, build a custom `Unstable_DirectiveFormatter` and wrap it with `createDirectiveText`:
+
+```tsx
+import type { Unstable_DirectiveFormatter } from "@assistant-ui/core";
+import { createDirectiveText } from "@/components/assistant-ui/directive-text";
+
+const slashFormatter: Unstable_DirectiveFormatter = {
+  serialize: (item) => `/${item.id}`,
+  parse: (text) => {
+    /* return alternating text / mention segments */
+  },
+};
+
+const SlashDirectiveText = createDirectiveText(slashFormatter);
+```
+
+Pass the **same formatter** to the composer trigger's `directive={{ formatter }}` (or `action={{ formatter }}`) so insertion and rendering stay consistent.
+
+## Customizing the Chip
+
+Because `directive-text.tsx` is copied into your project, you can also edit it directly — swap the chip styling, read `data-directive-id` to link to a detail page, or replace the chip wrapper entirely.
+
+## API Reference
+
+### `DirectiveText`
+
+A `TextMessagePartComponent` that parses `:type[label]{name=id}` directives and renders them as inline chips. Uses the default formatter from `@assistant-ui/core` and renders chips without icons. For per-type icons, build a component with `createDirectiveText(formatter, { iconMap })`.
+
+### `createDirectiveText(formatter, options?)`
+
+Factory that returns a `TextMessagePartComponent` bound to a custom `Unstable_DirectiveFormatter`.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `iconMap` | `Record<string, ComponentType<{ className?: string }>>` | Maps a directive segment's `type` to an icon rendered inside the chip |
+| `fallbackIcon` | `ComponentType<{ className?: string }>` | Icon used when no `iconMap` entry matches. When neither option resolves, the chip renders without an icon. |
+
+## Related
+
+- [Composer Trigger Popover](/docs/ui/composer-trigger-popover) — the picker that inserts directives
+- [Mentions guide](/docs/guides/mentions) — directive format, backend parsing

package/.docs/raw/docs/ui/reasoning.mdx

@@ -23,22 +23,26 @@ This adds a `/components/assistant-ui/reasoning.tsx` file to your project.
 
 ### Use in your application
 
-Pass the `Reasoning` and `ReasoningGroup` components to the `MessagePrimitive.Parts` component:
+Pass the `Reasoning` and `ReasoningGroup` components to `MessagePrimitive.Parts` via the `components` prop. Using them together is the recommended default — `ReasoningGroup` wraps consecutive reasoning parts in a collapsible container for a smooth out-of-the-box UI.
 
-```tsx title="/app/components/assistant-ui/thread.tsx" {2,10-11}
+```tsx title="/app/components/assistant-ui/thread.tsx"
 import { MessagePrimitive } from "@assistant-ui/react";
-import { Reasoning } from "@/components/assistant-ui/reasoning";
+import { MarkdownText } from "@/components/assistant-ui/markdown-text";
+import { ToolFallback } from "@/components/assistant-ui/tool-fallback";
+import { Reasoning, ReasoningGroup } from "@/components/assistant-ui/reasoning"; // [!code ++]
 
 const AssistantMessage: FC = () => {
   return (
     <MessagePrimitive.Root className="...">
       <div className="...">
-        <MessagePrimitive.Parts>
-          {({ part }) => {
-            if (part.type === "reasoning") return <Reasoning {...part} />;
-            return null;
+        <MessagePrimitive.Parts
+          components={{
+            Text: MarkdownText,
+            Reasoning, // [!code ++]
+            ReasoningGroup, // [!code ++]
+            tools: { Fallback: ToolFallback },
           }}
-        </MessagePrimitive.Parts>
+        />
       </div>
       <AssistantActionBar />
       <BranchPicker className="..." />
@@ -57,7 +61,7 @@ The component consists of two parts:
 1. `Reasoning`: Renders individual reasoning message part content (with markdown support)
 2. `ReasoningGroup`: Wraps consecutive reasoning parts in a collapsible container
 
-Consecutive reasoning parts are automatically grouped together by the `ReasoningGroup` component.
+Consecutive reasoning parts are automatically grouped together by `ReasoningGroup`. We recommend using both together as the default — you can drop `ReasoningGroup` or build your own layout with the composable API below if you need more flexibility.
 
 > When using the composable API, `Reasoning.Text` is a plain container. Add `<MarkdownText />` for markdown rendering.
 

package/dist/utils/logger.js

@@ -1,7 +1,7 @@
 import { IS_PREPARE_MODE } from "../constants.js";
 export const logger = {
     debug: (message, ...args) => {
-        if (process.env["DEBUG"]) {
+        if (process.env.DEBUG) {
             console.debug(`[DEBUG] ${message}`, ...args);
         }
     },

package/dist/utils/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,KAAK,EAAE,CAAC,OAAe,EAAE,GAAG,IAAW,EAAE,EAAE;QACzC,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACzB,OAAO,CAAC,KAAK,CAAC,WAAW,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,IAAI,EAAE,CAAC,OAAe,EAAE,GAAG,IAAW,EAAE,EAAE;QACxC,IAAI,eAAe,EAAE,CAAC;YACpB,OAAO,CAAC,GAAG,CAAC,UAAU,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IACD,KAAK,EAAE,CAAC,OAAe,EAAE,GAAG,IAAW,EAAE,EAAE;QACzC,OAAO,CAAC,KAAK,CAAC,WAAW,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,EAAE,CAAC,OAAe,EAAE,GAAG,IAAW,EAAE,EAAE;QACxC,OAAO,CAAC,IAAI,CAAC,UAAU,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;IAC7C,CAAC;CACF,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,KAAK,EAAE,CAAC,OAAe,EAAE,GAAG,IAAW,EAAE,EAAE;QACzC,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;YACtB,OAAO,CAAC,KAAK,CAAC,WAAW,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,IAAI,EAAE,CAAC,OAAe,EAAE,GAAG,IAAW,EAAE,EAAE;QACxC,IAAI,eAAe,EAAE,CAAC;YACpB,OAAO,CAAC,GAAG,CAAC,UAAU,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IACD,KAAK,EAAE,CAAC,OAAe,EAAE,GAAG,IAAW,EAAE,EAAE;QACzC,OAAO,CAAC,KAAK,CAAC,WAAW,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,EAAE,CAAC,OAAe,EAAE,GAAG,IAAW,EAAE,EAAE;QACxC,OAAO,CAAC,IAAI,CAAC,UAAU,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;IAC7C,CAAC;CACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/mcp-docs-server",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "MCP server for assistant-ui documentation and examples",
   "keywords": [
     "mcp",
@@ -37,10 +37,10 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/node": "^25.5.2",
+    "@types/node": "^25.6.0",
     "tsx": "^4.21.0",
-    "vitest": "^4.1.2",
-    "@assistant-ui/x-buildutils": "0.0.4"
+    "vitest": "^4.1.5",
+    "@assistant-ui/x-buildutils": "0.0.6"
   },
   "publishConfig": {
     "access": "public",

package/src/utils/logger.ts

@@ -2,7 +2,7 @@ import { IS_PREPARE_MODE } from "../constants.js";
 
 export const logger = {
   debug: (message: string, ...args: any[]) => {
-    if (process.env["DEBUG"]) {
+    if (process.env.DEBUG) {
       console.debug(`[DEBUG] ${message}`, ...args);
     }
   },

package/.docs/raw/docs/ui/mention.mdx

@@ -1,168 +0,0 @@
----
-title: Mention
-description: Let users @-mention tools in the composer with a keyboard-navigable popover picker and inline chips.
----
-
-## Getting Started
-
-<Steps>
-  <Step>
-
-### Add `composer-mention`
-
-<InstallCommand shadcn={["composer-mention"]} />
-
-This adds a `/components/assistant-ui/composer-mention.tsx` file with `ComposerMentionPopover`, `ComposerMentionRoot`, and `DirectiveText`.
-
-  </Step>
-  <Step>
-
-### Wrap the Composer
-
-Wrap your composer with `ComposerMentionPopover.Root` and add `<ComposerMentionPopover />` inside:
-
-```tsx title="components/assistant-ui/thread.tsx" {1,7,10}
-import { ComposerMentionPopover } from "@/components/assistant-ui/composer-mention";
-
-const Composer = () => {
-  return (
-    <ComposerMentionPopover.Root>
-      <ComposerPrimitive.Root>
-        <ComposerPrimitive.Input placeholder="Type @ to mention a tool..." />
-        <ComposerPrimitive.Send />
-        <ComposerMentionPopover />
-      </ComposerPrimitive.Root>
-    </ComposerMentionPopover.Root>
-  );
-};
-```
-
-The popover automatically shows registered tools when the user types `@`.
-
-  </Step>
-  <Step>
-
-### Render Mentions in User Messages
-
-Use `DirectiveText` as the `Text` component for **user messages** so mention directives render as inline chips instead of raw `:tool[label]` syntax:
-
-```tsx title="components/assistant-ui/thread.tsx" {1,8}
-import { DirectiveText } from "@/components/assistant-ui/composer-mention";
-
-const UserMessage = () => {
-  return (
-    <MessagePrimitive.Root>
-      <MessagePrimitive.Parts
-        components={{
-          Text: DirectiveText,
-        }}
-      />
-    </MessagePrimitive.Root>
-  );
-};
-```
-
-<Callout>
-  `DirectiveText` renders plain text with mention chips. For assistant messages
-  that contain markdown, keep using your markdown renderer (e.g. `MarkdownText`).
-</Callout>
-
-  </Step>
-</Steps>
-
-## With Lexical Rich Editor
-
-For inline mention chips in the composer (not just the popover), use `LexicalComposerInput` from `@assistant-ui/react-lexical`:
-
-```bash
-npm install @assistant-ui/react-lexical lexical @lexical/react
-```
-
-Replace `ComposerPrimitive.Input` with `LexicalComposerInput`:
-
-```tsx title="components/assistant-ui/thread.tsx" {1,8}
-import { LexicalComposerInput } from "@assistant-ui/react-lexical";
-
-const Composer = () => {
-  return (
-    <ComposerMentionPopover.Root>
-      <ComposerPrimitive.Root>
-        <LexicalComposerInput placeholder="Type @ to mention a tool..." />
-        <ComposerPrimitive.Send />
-        <ComposerMentionPopover />
-      </ComposerPrimitive.Root>
-    </ComposerMentionPopover.Root>
-  );
-};
-```
-
-`LexicalComposerInput` auto-wires to `MentionContext` — no extra props needed. Selected mentions appear as inline chips that are treated as atomic units (select, delete, undo as a whole).
-
-## Custom Formatter
-
-The default directive format is `:type[label]{name=id}`. To use a custom format, pass a `formatter` to both the mention root and the message renderer:
-
-```tsx
-import { ComposerMentionPopover } from "@/components/assistant-ui/composer-mention";
-import { createDirectiveText } from "@/components/assistant-ui/composer-mention";
-
-const myFormatter = {
-  serialize: (item) => `@${item.id}`,
-  parse: (text) => [{ kind: "text", text }], // implement your parsing
-};
-
-// In composer (textarea path):
-<ComposerMentionPopover.Root formatter={myFormatter}>
-  ...
-</ComposerMentionPopover.Root>
-
-// In composer (Lexical path — also pass formatter):
-<ComposerMentionPopover.Root formatter={myFormatter}>
-  <ComposerPrimitive.Root>
-    <LexicalComposerInput formatter={myFormatter} />
-    ...
-  </ComposerPrimitive.Root>
-</ComposerMentionPopover.Root>
-
-// In user messages:
-const MyDirectiveText = createDirectiveText(myFormatter);
-<MessagePrimitive.Parts components={{ Text: MyDirectiveText }} />
-```
-
-## Keyboard Navigation
-
-The mention popover supports full keyboard navigation out of the box:
-
-| Key | Action |
-| --- | --- |
-| <Kbd>ArrowDown</Kbd> | Highlight next item |
-| <Kbd>ArrowUp</Kbd> | Highlight previous item |
-| <Kbd>Enter</Kbd> | Select highlighted item / drill into category |
-| <Kbd>Escape</Kbd> | Close popover |
-| <Kbd>Backspace</Kbd> | Go back to categories (when query is empty) |
-
-## Components
-
-### `ComposerMentionPopover.Root`
-
-Wraps the composer with mention context and a tool mention adapter. Provides the `@`-trigger detection, keyboard navigation, and popover state.
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `adapter` | `Unstable_MentionAdapter` | Tool adapter | Custom mention adapter |
-| `trigger` | `string` | `"@"` | Character(s) that open the popover |
-| `formatter` | `Unstable_DirectiveFormatter` | Default | Custom directive serializer/parser |
-| `formatLabel` | `(name: string) => string` | Title case | Format tool names for display |
-| `categoryLabel` | `string` | `"Tools"` | Label for the tools category |
-
-### `ComposerMentionPopover`
-
-Pre-built popover containing categories and items lists. Only renders when the `@` trigger is active.
-
-### `DirectiveText`
-
-A `TextMessagePartComponent` that parses `:type[label]{name=id}` directives and renders them as styled inline chips.
-
-### `createDirectiveText(formatter)`
-
-Factory function that creates a `TextMessagePartComponent` using a custom `Unstable_DirectiveFormatter`.