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

package/.docs/organized/code-examples/with-google-adk.md

@@ -317,7 +317,7 @@ export default nextConfig;
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
     "@tailwindcss/postcss": "^4.2.2",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "postcss": "^8.5.8",

package/.docs/organized/code-examples/with-heat-graph.md

@@ -277,7 +277,7 @@ export default nextConfig;
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
     "@tailwindcss/postcss": "^4.2.2",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "postcss": "^8.5.8",

package/.docs/organized/code-examples/with-interactables.md

@@ -735,11 +735,11 @@ export default nextConfig;
     "start": "next start"
   },
   "dependencies": {
-    "@ai-sdk/openai": "^3.0.50",
+    "@ai-sdk/openai": "^3.0.51",
     "@assistant-ui/react": "workspace:*",
     "@assistant-ui/react-ai-sdk": "workspace:*",
     "@assistant-ui/ui": "workspace:*",
-    "ai": "^6.0.144",
+    "ai": "^6.0.148",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^1.7.0",
@@ -752,7 +752,7 @@ export default nextConfig;
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
     "@tailwindcss/postcss": "^4.2.2",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "postcss": "^8.5.8",

package/.docs/organized/code-examples/with-langgraph.md

@@ -871,7 +871,7 @@ export default nextConfig;
     "@assistant-ui/react-langgraph": "workspace:*",
     "@assistant-ui/react-markdown": "workspace:*",
     "@assistant-ui/ui": "workspace:*",
-    "@langchain/langgraph-sdk": "^1.8.4",
+    "@langchain/langgraph-sdk": "^1.8.8",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^1.7.0",
@@ -883,7 +883,7 @@ export default nextConfig;
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
     "@tailwindcss/postcss": "^4.2.2",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "postcss": "^8.5.8",

package/.docs/organized/code-examples/with-livekit.md

@@ -512,14 +512,14 @@ export default nextConfig;
   "version": "0.0.0",
   "type": "module",
   "dependencies": {
-    "@ai-sdk/openai": "^3.0.50",
-    "@ai-sdk/react": "^3.0.146",
+    "@ai-sdk/openai": "^3.0.51",
+    "@ai-sdk/react": "^3.0.150",
     "@assistant-ui/react": "workspace:^",
     "@assistant-ui/react-ai-sdk": "workspace:*",
     "@assistant-ui/react-markdown": "workspace:^",
     "@assistant-ui/ui": "workspace:*",
     "@tailwindcss/postcss": "^4.2.2",
-    "ai": "^6.0.144",
+    "ai": "^6.0.148",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "livekit-client": "^2.18.1",
@@ -536,7 +536,7 @@ export default nextConfig;
   },
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "tw-animate-css": "^1.4.0",

package/.docs/organized/code-examples/with-parent-id-grouping.md

@@ -474,7 +474,7 @@ export default nextConfig;
     "start": "next start"
   },
   "dependencies": {
-    "@ai-sdk/openai": "^3.0.50",
+    "@ai-sdk/openai": "^3.0.51",
     "@assistant-ui/react": "workspace:*",
     "@assistant-ui/react-markdown": "workspace:*",
     "@assistant-ui/ui": "workspace:*",
@@ -489,7 +489,7 @@ export default nextConfig;
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
     "@tailwindcss/postcss": "^4.2.2",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "postcss": "^8.5.8",

package/.docs/organized/code-examples/with-react-hook-form.md

@@ -537,26 +537,26 @@ export default nextConfig;
     "start": "next start"
   },
   "dependencies": {
-    "@ai-sdk/openai": "^3.0.50",
+    "@ai-sdk/openai": "^3.0.51",
     "@assistant-ui/react": "workspace:*",
     "@assistant-ui/react-ai-sdk": "workspace:*",
     "@assistant-ui/react-hook-form": "workspace:*",
     "@assistant-ui/react-markdown": "workspace:*",
     "@assistant-ui/ui": "workspace:*",
-    "ai": "^6.0.144",
+    "ai": "^6.0.148",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^1.7.0",
     "next": "^16.2.2",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "react-hook-form": "^7.72.0",
+    "react-hook-form": "^7.72.1",
     "tailwind-merge": "^3.5.0"
   },
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
     "@tailwindcss/postcss": "^4.2.2",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "postcss": "^8.5.8",

package/.docs/organized/code-examples/with-react-router.md

@@ -789,13 +789,13 @@ export default function Home() {
   "devDependencies": {
     "@react-router/dev": "^7.14.0",
     "@tailwindcss/vite": "^4.2.2",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "tailwindcss": "^4.2.2",
     "tw-animate-css": "^1.4.0",
     "typescript": "5.9.3",
-    "vite": "^8.0.3",
+    "vite": "^8.0.5",
     "vite-tsconfig-paths": "^6.1.1"
   }
 }

package/.docs/organized/code-examples/with-store.md

@@ -495,7 +495,7 @@ export default nextConfig;
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
     "@tailwindcss/postcss": "^4.2.2",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "postcss": "^8.5.8",

package/.docs/organized/code-examples/with-tanstack.md

@@ -81,12 +81,12 @@
   },
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
     "typescript": "5.9.3",
-    "vite": "^8.0.3"
+    "vite": "^8.0.5"
   }
 }
 

package/.docs/organized/code-examples/with-tap-runtime.md

@@ -606,7 +606,7 @@ export default nextConfig;
   "devDependencies": {
     "@assistant-ui/x-buildutils": "workspace:*",
     "@tailwindcss/postcss": "^4.2.2",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "postcss": "^8.5.8",

package/.docs/raw/docs/(docs)/guides/mentions.mdx

@@ -0,0 +1,406 @@
+---
+title: Mentions
+description: Let users @-mention tools or custom items in the composer to guide the LLM.
+---
+
+Mentions let users type `@` in the composer to open a popover picker, select an item (e.g. a tool), and insert a directive into the message text. The LLM can then use the directive as a hint.
+
+## How It Works
+
+```
+User types "@"  →  Trigger detected  →  Adapter provides categories/items
+                                              ↓
+              Directive inserted  ←  User selects item from popover
+                   ↓
+         Message sent with ":tool[Label]{name=id}" in text
+```
+
+The mention system has three layers:
+
+1. **Trigger detection** — watches the composer text for a trigger character (`@` by default) and extracts the query
+2. **Adapter** — provides the categories and items to display in the popover (e.g. registered tools)
+3. **Formatter** — serializes a selected item into directive text (`:type[label]{name=id}`) and parses it back for rendering
+
+## Quick Start
+
+The fastest path is the pre-built [Mention UI component](/docs/ui/mention), which wires everything together with a single shadcn component:
+
+```bash
+npx shadcn@latest add "https://r.assistant-ui.com/composer-mention"
+```
+
+See the [Mention UI guide](/docs/ui/mention) for setup steps.
+
+The rest of this guide covers the underlying concepts and customization points.
+
+## Mention Adapter
+
+A `Unstable_MentionAdapter` provides the data for the popover. All methods are **synchronous** — use external state management (React Query, SWR, local state) for async data, then expose loaded results through the adapter.
+
+```ts
+import type { Unstable_MentionAdapter } from "@assistant-ui/core";
+
+const myAdapter: Unstable_MentionAdapter = {
+  categories() {
+    return [
+      { id: "tools", label: "Tools" },
+      { id: "users", label: "Users" },
+    ];
+  },
+
+  categoryItems(categoryId) {
+    if (categoryId === "tools") {
+      return [
+        { id: "search", type: "tool", label: "Search" },
+        { id: "calculator", type: "tool", label: "Calculator" },
+      ];
+    }
+    if (categoryId === "users") {
+      return [
+        { id: "alice", type: "user", label: "Alice" },
+        { id: "bob", type: "user", label: "Bob" },
+      ];
+    }
+    return [];
+  },
+
+  // Optional — global search across all categories
+  search(query) {
+    const lower = query.toLowerCase();
+    const all = [
+      ...this.categoryItems("tools"),
+      ...this.categoryItems("users"),
+    ];
+    return all.filter(
+      (item) =>
+        item.label.toLowerCase().includes(lower) ||
+        item.id.toLowerCase().includes(lower),
+    );
+  },
+};
+```
+
+Pass the adapter to `MentionRoot`:
+
+```tsx
+<ComposerPrimitive.Unstable_MentionRoot adapter={myAdapter}>
+  <ComposerPrimitive.Root>
+    <ComposerPrimitive.Input placeholder="Type @ to mention..." />
+  </ComposerPrimitive.Root>
+</ComposerPrimitive.Unstable_MentionRoot>
+```
+
+### Built-in Tool Adapter
+
+For the common case of mentioning registered tools, use `unstable_useToolMentionAdapter`:
+
+```tsx
+import { unstable_useToolMentionAdapter } from "@assistant-ui/react";
+
+const adapter = unstable_useToolMentionAdapter({
+  // Format tool names for display (default: raw name)
+  formatLabel: (name) =>
+    name.replaceAll("_", " ").replace(/\b\w/g, (c) => c.toUpperCase()),
+
+  // Custom category label (default: "Tools")
+  categoryLabel: "Tools",
+
+  // Explicit tool list (overrides model context tools)
+  // tools: [{ id: "search", type: "tool", label: "Search" }],
+
+  // Include model context tools alongside explicit tools
+  // includeModelContextTools: true,
+});
+```
+
+The adapter automatically reads tools from the model context (registered via `Tools()` or `useAssistantTool`). When `tools` is provided, model context tools are excluded unless `includeModelContextTools` is set to `true`.
+
+## Directive Format
+
+When a user selects a mention item, it is serialized into the composer text as a **directive**. The default format is:
+
+```
+:type[label]{name=id}
+```
+
+For example, selecting a tool named "get_weather" with label "Get Weather" produces:
+
+```
+:tool[Get Weather]{name=get_weather}
+```
+
+When `id` equals `label`, the `{name=…}` attribute is omitted for brevity:
+
+```
+:tool[search]
+```
+
+### Custom Formatter
+
+Implement `Unstable_DirectiveFormatter` to use a different format:
+
+```ts
+import type { Unstable_DirectiveFormatter } from "@assistant-ui/core";
+
+const slashFormatter: Unstable_DirectiveFormatter = {
+  serialize(item) {
+    return `/${item.id}`;
+  },
+
+  parse(text) {
+    const segments = [];
+    const re = /\/(\w+)/g;
+    let lastIndex = 0;
+    let match;
+
+    while ((match = re.exec(text)) !== null) {
+      if (match.index > lastIndex) {
+        segments.push({ kind: "text" as const, text: text.slice(lastIndex, match.index) });
+      }
+      segments.push({
+        kind: "mention" as const,
+        type: "tool",
+        label: match[1]!,
+        id: match[1]!,
+      });
+      lastIndex = re.lastIndex;
+    }
+
+    if (lastIndex < text.length) {
+      segments.push({ kind: "text" as const, text: text.slice(lastIndex) });
+    }
+
+    return segments;
+  },
+};
+```
+
+Pass it to both the mention root and the message renderer:
+
+```tsx
+// Composer
+<ComposerPrimitive.Unstable_MentionRoot adapter={adapter} formatter={slashFormatter}>
+  ...
+</ComposerPrimitive.Unstable_MentionRoot>
+
+// User messages
+const SlashDirectiveText = createDirectiveText(slashFormatter);
+<MessagePrimitive.Parts components={{ Text: SlashDirectiveText }} />
+```
+
+## Textarea vs Lexical
+
+The mention system supports two input modes:
+
+| | Textarea (default) | Lexical |
+| --- | --- | --- |
+| **Input component** | `ComposerPrimitive.Input` | `LexicalComposerInput` |
+| **Mention display in composer** | Raw directive text (`:tool[Label]`) | Inline chips (atomic nodes) |
+| **Dependencies** | None | `@assistant-ui/react-lexical`, `lexical`, `@lexical/react` |
+| **Best for** | Simple setups, minimal bundle | Rich editing, polished UX |
+
+With **textarea**, selecting a mention inserts the directive string directly into the text. The user sees `:tool[Get Weather]{name=get_weather}` in the input.
+
+With **Lexical**, selected mentions appear as styled inline chips that behave as atomic units — they can be selected, deleted, and undone as a whole. The underlying text still uses the directive format.
+
+```tsx
+import { LexicalComposerInput } from "@assistant-ui/react-lexical";
+
+<ComposerPrimitive.Unstable_MentionRoot adapter={adapter}>
+  <ComposerPrimitive.Root>
+    <LexicalComposerInput placeholder="Type @ to mention..." />
+    <ComposerPrimitive.Send />
+  </ComposerPrimitive.Root>
+</ComposerPrimitive.Unstable_MentionRoot>
+```
+
+`LexicalComposerInput` auto-wires to the mention context — no extra props needed.
+
+## Rendering Mentions in Messages
+
+Use `DirectiveText` as the `Text` component for user messages so directives render as inline chips instead of raw syntax:
+
+```tsx
+import { DirectiveText } from "@/components/assistant-ui/composer-mention";
+
+<MessagePrimitive.Parts
+  components={{
+    Text: DirectiveText,
+  }}
+/>
+```
+
+For assistant messages, keep using your markdown renderer (e.g. `MarkdownText`) — the LLM typically does not emit directive syntax.
+
+For a custom formatter, use `createDirectiveText`:
+
+```tsx
+import { createDirectiveText } from "@/components/assistant-ui/composer-mention";
+
+const MyDirectiveText = createDirectiveText(myFormatter);
+```
+
+## Processing Mentions on the Backend
+
+The message text arrives at your backend with directives inline. Parse them to extract mentioned items:
+
+```ts
+// Default format: :type[label]{name=id}
+const DIRECTIVE_RE = /:([\w-]+)\[([^\]]+)\](?:\{name=([^}]+)\})?/g;
+
+function parseMentions(text: string) {
+  const mentions = [];
+  let match;
+  while ((match = DIRECTIVE_RE.exec(text)) !== null) {
+    mentions.push({
+      type: match[1],        // e.g. "tool"
+      label: match[2],       // e.g. "Get Weather"
+      id: match[3] ?? match[2], // e.g. "get_weather"
+    });
+  }
+  return mentions;
+}
+
+// Example:
+// parseMentions("Use :tool[Get Weather]{name=get_weather} to check")
+// → [{ type: "tool", label: "Get Weather", id: "get_weather" }]
+```
+
+You can use the extracted mentions to:
+- Force-enable specific tools for the LLM call
+- Add context about mentioned users or documents to the system prompt
+- Log which tools users request most often
+
+## Reading Mention State
+
+Use `unstable_useMentionContext` to programmatically access the mention popover state:
+
+```tsx
+import { unstable_useMentionContext } from "@assistant-ui/react";
+
+function MyComponent() {
+  const mention = unstable_useMentionContext();
+
+  // mention.open — whether the popover is visible
+  // mention.query — current search text after "@"
+  // mention.categories — filtered category list
+  // mention.items — filtered item list
+  // mention.highlightedIndex — keyboard-navigated index
+  // mention.isSearchMode — true when global search is active
+  // mention.selectItem(item) — programmatically select an item
+  // mention.close() — close the popover
+}
+```
+
+This hook must be used within a `ComposerPrimitive.Unstable_MentionRoot`.
+
+## Building a Custom Popover
+
+Use the mention primitives to build a fully custom popover:
+
+```tsx
+<ComposerPrimitive.Unstable_MentionRoot adapter={adapter}>
+  <ComposerPrimitive.Root>
+    <ComposerPrimitive.Input />
+
+    <ComposerPrimitive.Unstable_MentionPopover className="popover">
+      <ComposerPrimitive.Unstable_MentionBack>
+        ← Back
+      </ComposerPrimitive.Unstable_MentionBack>
+
+      <ComposerPrimitive.Unstable_MentionCategories>
+        {(categories) =>
+          categories.map((cat) => (
+            <ComposerPrimitive.Unstable_MentionCategoryItem
+              key={cat.id}
+              categoryId={cat.id}
+            >
+              {cat.label}
+            </ComposerPrimitive.Unstable_MentionCategoryItem>
+          ))
+        }
+      </ComposerPrimitive.Unstable_MentionCategories>
+
+      <ComposerPrimitive.Unstable_MentionItems>
+        {(items) =>
+          items.map((item) => (
+            <ComposerPrimitive.Unstable_MentionItem
+              key={item.id}
+              item={item}
+            >
+              {item.label}
+            </ComposerPrimitive.Unstable_MentionItem>
+          ))
+        }
+      </ComposerPrimitive.Unstable_MentionItems>
+    </ComposerPrimitive.Unstable_MentionPopover>
+
+    <ComposerPrimitive.Send />
+  </ComposerPrimitive.Root>
+</ComposerPrimitive.Unstable_MentionRoot>
+```
+
+### Primitives Reference
+
+| Primitive | Description |
+| --- | --- |
+| `Unstable_MentionRoot` | Provider — wraps the composer with trigger detection, keyboard navigation, and popover state |
+| `Unstable_MentionPopover` | Container — only renders when a trigger is active (`role="listbox"`) |
+| `Unstable_MentionCategories` | Render-function for the top-level category list |
+| `Unstable_MentionCategoryItem` | Button that drills into a category (`role="option"`, auto `data-highlighted`) |
+| `Unstable_MentionItems` | Render-function for items within the active category or search results |
+| `Unstable_MentionItem` | Button that inserts a mention (`role="option"`, auto `data-highlighted`) |
+| `Unstable_MentionBack` | Button that navigates back from items to categories |
+
+See the [Composer API reference](/docs/api-reference/primitives/composer) for full prop details.
+
+## Combining with Slash Commands
+
+Mentions and [slash commands](/docs/guides/slash-commands) can coexist on the same composer. Both are built on the same [trigger popover architecture](/docs/guides/slash-commands#trigger-popover-architecture) — nest both roots and they work independently:
+
+```tsx
+<ComposerPrimitive.Unstable_MentionRoot adapter={mentionAdapter}>
+  <ComposerPrimitive.Unstable_SlashCommandRoot adapter={slashAdapter}>
+    <ComposerPrimitive.Root>
+      <ComposerPrimitive.Input placeholder="Type @ to mention, / for commands..." />
+      <ComposerPrimitive.Send />
+
+      {/* Mention popover (shows on @) */}
+      <ComposerPrimitive.Unstable_MentionPopover>
+        <ComposerPrimitive.Unstable_MentionCategories>
+          {(categories) => categories.map((cat) => (
+            <ComposerPrimitive.Unstable_MentionCategoryItem key={cat.id} categoryId={cat.id}>
+              {cat.label}
+            </ComposerPrimitive.Unstable_MentionCategoryItem>
+          ))}
+        </ComposerPrimitive.Unstable_MentionCategories>
+        <ComposerPrimitive.Unstable_MentionItems>
+          {(items) => items.map((item) => (
+            <ComposerPrimitive.Unstable_MentionItem key={item.id} item={item}>
+              {item.label}
+            </ComposerPrimitive.Unstable_MentionItem>
+          ))}
+        </ComposerPrimitive.Unstable_MentionItems>
+      </ComposerPrimitive.Unstable_MentionPopover>
+
+      {/* Slash command popover (shows on /) */}
+      <ComposerPrimitive.Unstable_TriggerPopoverPopover>
+        <ComposerPrimitive.Unstable_TriggerPopoverItems>
+          {(items) => items.map((item, index) => (
+            <ComposerPrimitive.Unstable_TriggerPopoverItem key={item.id} item={item} index={index}>
+              {item.label}
+            </ComposerPrimitive.Unstable_TriggerPopoverItem>
+          ))}
+        </ComposerPrimitive.Unstable_TriggerPopoverItems>
+      </ComposerPrimitive.Unstable_TriggerPopoverPopover>
+    </ComposerPrimitive.Root>
+  </ComposerPrimitive.Unstable_SlashCommandRoot>
+</ComposerPrimitive.Unstable_MentionRoot>
+```
+
+## Related
+
+- [Mention UI Component](/docs/ui/mention) — pre-built shadcn component
+- [Slash Commands Guide](/docs/guides/slash-commands) — `/` command system built on the same architecture
+- [Tools Guide](/docs/guides/tools) — register tools that appear in the mention picker
+- [Composer Primitives](/docs/primitives/composer) — underlying composer primitives