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

package/.docs/raw/docs/{integrations/tools/react-mcp.mdx → tools/user-managed-mcp.mdx}

@@ -3,7 +3,7 @@ title: User-managed MCP servers
 description: Let end users add and authenticate MCP servers from the browser with @assistant-ui/react-mcp.
 ---
 
-[`@assistant-ui/react-mcp`](https://npmjs.com/package/@assistant-ui/react-mcp) is the user-facing layer for MCP. Where the [server-side MCP guide](/docs/integrations/tools/mcp) wires a single fixed set of MCP servers into your API route, this package lets *end users* see a list of connectors, sign in via OAuth, paste a custom server URL, and have the resulting tool catalog flow into the chat — automatically.
+[`@assistant-ui/react-mcp`](https://npmjs.com/package/@assistant-ui/react-mcp) is the user-facing layer for MCP. Where the [server-side MCP guide](/docs/tools/mcp) wires a single fixed set of MCP servers into your API route, this package lets *end users* see a list of connectors, sign in via OAuth, paste a custom server URL, and have the resulting tool catalog flow into the chat — automatically.
 
 Two ways a server reaches the user:
 
@@ -327,11 +327,11 @@ What's deferred:
   <Card
     title="Server-side MCP"
     description="App-developer-controlled MCP servers wired into the API route."
-    href="/docs/integrations/tools/mcp"
+    href="/docs/tools/mcp"
   />
   <Card
     title="Tools and tool UI"
     description="Build custom renderers for tool calls and approvals."
-    href="/docs/guides/tools"
+    href="/docs/tools/defining-tools"
   />
 </Cards>

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

@@ -49,7 +49,7 @@ Keep your markdown renderer (e.g. `MarkdownText`) for assistant messages — ass
 
 ```tsx
 import { createDirectiveText } from "@/components/assistant-ui/directive-text";
-import { unstable_defaultDirectiveFormatter } from "@assistant-ui/core";
+import { unstable_defaultDirectiveFormatter } from "@assistant-ui/react";
 import { FileTextIcon, SparklesIcon, UserIcon, WrenchIcon } from "lucide-react";
 
 const DirectiveTextWithIcons = createDirectiveText(
@@ -74,7 +74,7 @@ A matching `iconMap` / `fallbackIcon` option is accepted by [`ComposerTriggerPop
 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 type { Unstable_DirectiveFormatter } from "@assistant-ui/react";
 import { createDirectiveText } from "@/components/assistant-ui/directive-text";
 
 const slashFormatter: Unstable_DirectiveFormatter = {
@@ -97,7 +97,7 @@ Because `directive-text.tsx` is copied into your project, you can also edit it d
 
 ### `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 })`.
+A `TextMessagePartComponent` that parses `:type[label]{name=id}` directives and renders them as inline chips. Uses the default formatter from `@assistant-ui/react` and renders chips without icons. For per-type icons, build a component with `createDirectiveText(formatter, { iconMap })`.
 
 ### `createDirectiveText(formatter, options?)`
 

package/.docs/raw/docs/ui/mcp-config.mdx

@@ -4,7 +4,7 @@ description: Drop-in shadcn dialog that lists MCP connectors and custom servers,
 platforms: ["react"]
 ---
 
-`McpConfigDialog` is a shadcn template that wraps the [`@assistant-ui/react-mcp`](/docs/integrations/tools/react-mcp) primitives. Render it anywhere inside an `McpManagerResource`-mounted client and your users get a styled MCP server panel — no manual primitive composition.
+`McpConfigDialog` is a shadcn template that wraps the [`@assistant-ui/react-mcp`](/docs/tools/user-managed-mcp) primitives. Render it anywhere inside an `McpManagerResource`-mounted client and your users get a styled MCP server panel — no manual primitive composition.
 
 ## Getting Started
 
@@ -81,7 +81,7 @@ Pass children to swap the default button for your own:
 
 ### Wire up the OAuth callback
 
-Required for any OAuth-enabled connector or custom server. See the [OAuth callback section in the react-mcp guide](/docs/integrations/tools/react-mcp#handle-the-oauth-callback) for the route handler.
+Required for any OAuth-enabled connector or custom server. See the [OAuth callback section in the react-mcp guide](/docs/tools/user-managed-mcp#handle-the-oauth-callback) for the route handler.
 
   </Step>
 </Steps>
@@ -92,11 +92,11 @@ Required for any OAuth-enabled connector or custom server. See the [OAuth callba
   <Card
     title="User-managed MCP servers"
     description="Full @assistant-ui/react-mcp guide — connectors, custom servers, OAuth, storage, custom primitives."
-    href="/docs/integrations/tools/react-mcp"
+    href="/docs/tools/user-managed-mcp"
   />
   <Card
     title="Server-side MCP"
     description="App-developer-controlled MCP servers wired into the API route."
-    href="/docs/integrations/tools/mcp"
+    href="/docs/tools/mcp"
   />
 </Cards>

package/.docs/raw/docs/ui/part-grouping.mdx

@@ -10,18 +10,19 @@ import { PartGroupingSample } from "@/components/docs/samples/part-grouping";
 
 ## Basic Usage
 
-For adjacent grouping, use `MessagePrimitive.GroupedParts`. Return a group-key path for each part; adjacent parts that share a group key are coalesced and rendered through the group case.
+For adjacent grouping, use `MessagePrimitive.GroupedParts`. For the common case — grouping by `part.type` — pass `groupPartByType` to map each part type to a group-key path. Adjacent parts that share a group key are coalesced and rendered through the group case.
 
 ```tsx title="/components/assistant-ui/thread.tsx"
+import { MessagePrimitive, groupPartByType } from "@assistant-ui/react";
+
 const AssistantMessage: FC = () => {
   return (
     <MessagePrimitive.Root className="...">
       <div className="...">
         <MessagePrimitive.GroupedParts
-          groupBy={(part) => {
-            if (part.type === "tool-call") return ["group-tool"];
-            return null;
-          }}
+          groupBy={groupPartByType({
+            "tool-call": ["group-tool"],
+          })}
         >
           {({ part, children }) => {
             switch (part.type) {
@@ -42,6 +43,8 @@ const AssistantMessage: FC = () => {
 };
 ```
 
+Reach for an inline `groupBy={(part) => …}` only when the helper isn't expressive enough — e.g. you need to branch on `part.toolName`, `part.parentId`, or part metadata.
+
 ## How Adjacent Grouping Works
 
 `groupBy` receives each part and returns either `null` for an ungrouped leaf or a group-key path such as `["group-chainOfThought", "group-tool"]`. Group keys must start with `"group-"` so your render function can distinguish synthetic groups from real part types.
@@ -89,7 +92,7 @@ function ParentGroup({
 
 <MessagePrimitive.GroupedParts
   groupBy={(part) => {
-    if (!part.parentId) return null;
+    if (!part.parentId) return [];
     return [`group-parent-${part.parentId}`];
   }}
 >
@@ -117,7 +120,7 @@ Organize adjacent tool calls by tool name:
 ```tsx
 <MessagePrimitive.GroupedParts
   groupBy={(part) => {
-    if (part.type !== "tool-call") return null;
+    if (part.type !== "tool-call") return [];
     return [`group-tool-${part.toolName}`];
   }}
 >
@@ -147,10 +150,9 @@ Combine multiple text parts into cohesive blocks:
 
 ```tsx
 <MessagePrimitive.GroupedParts
-  groupBy={(part) => {
-    if (part.type === "text") return ["group-text-block"];
-    return null;
-  }}
+  groupBy={groupPartByType({
+    text: ["group-text-block"],
+  })}
 >
   {({ part, children }) => {
     switch (part.type) {
@@ -177,12 +179,11 @@ Separate different types of content for distinct visual treatment:
 
 ```tsx
 <MessagePrimitive.GroupedParts
-  groupBy={(part) => {
-    if (part.type === "text") return ["group-content-text"];
-    if (part.type === "tool-call") return ["group-content-tools"];
-    if (part.type === "reasoning") return ["group-content-reasoning"];
-    return null;
-  }}
+  groupBy={groupPartByType({
+    text: ["group-content-text"],
+    "tool-call": ["group-content-tools"],
+    reasoning: ["group-content-reasoning"],
+  })}
 >
   {({ part, children }) => {
     switch (part.type) {
@@ -205,6 +206,52 @@ Separate different types of content for distinct visual treatment:
 </MessagePrimitive.GroupedParts>
 ```
 
+### Keep Standalone Tool UIs Out of the Trace
+
+Tool UIs fall into three buckets: prompting the user (human-in-the-loop), informing the user (generative UI), and traces of what the model is doing (routine tool calls). The first two should be surfaced on their own, while the last belongs folded into a collapsible chain-of-thought group.
+
+Mark a tool with `display: "standalone"` to keep its UI out of the grouped trace. `human` tools and MCP apps are standalone automatically; every other tool defaults to `"inline"` and opts in explicitly:
+
+```tsx
+const toolkit = {
+  ask_user: { type: "human", render: AskUI }, // standalone (forced)
+  search_web: { type: "frontend", render: SearchUI }, // inline trace (default)
+  checkout: {
+    type: "frontend",
+    render: CheckoutUI,
+    display: "standalone", // opt in
+  },
+} satisfies Toolkit;
+```
+
+The synthetic `"standalone-tool-call"` key on `groupPartByType` matches all of these. `MessagePrimitive.GroupedParts` passes the live tool-UI registry to `groupBy` as a second `context` argument, and the helper reads it to resolve the registry-driven cases — MCP-app calls are detected from the part alone, so nothing is threaded in:
+
+```tsx
+<MessagePrimitive.GroupedParts
+  groupBy={groupPartByType({
+    reasoning: ["group-chainOfThought", "group-reasoning"],
+    "tool-call": ["group-chainOfThought", "group-tool"],
+    "standalone-tool-call": [], // ungrouped — rendered on its own
+  })}
+>
+  {({ part, children }) => {
+    switch (part.type) {
+      case "group-chainOfThought":
+        return <div className="chain-of-thought">{children}</div>;
+      case "tool-call":
+        return part.toolUI ?? <ToolFallback {...part} />;
+      // ...
+      default:
+        return null;
+    }
+  }}
+</MessagePrimitive.GroupedParts>;
+```
+
+<Callout type="info">
+  The `"mcp-app"` key is deprecated in favor of `"standalone-tool-call"`, which is a superset (it also matches MCP-app tool calls). Existing `"mcp-app"` usage keeps working.
+</Callout>
+
 ### Group by Custom Metadata
 
 Use any custom metadata in your parts for grouping:
@@ -219,7 +266,7 @@ const priorityStyles = {
 <MessagePrimitive.GroupedParts
   groupBy={(part) => {
     const priority = part.metadata?.priority;
-    if (!priority) return null;
+    if (!priority) return [];
     return [`group-priority-${priority}`];
   }}
 >
@@ -300,9 +347,9 @@ const stream = createAssistantStream(async (controller) => {
   parameters={[
     {
       name: "groupBy",
-      type: "(part: PartState, index: number, parts: readonly PartState[]) => GroupKey",
+      type: "(part: PartState) => readonly `group-${string}`[]",
       description:
-        "Maps a part to a group-key path. Return null, undefined, or [] to leave the part ungrouped. Group keys must start with group-.",
+        "Maps a part to a group-key path. Return `[]` to leave the part ungrouped. Group keys must start with `group-`. Prefer `groupPartByType` for the common `part.type → path` case.",
       required: true,
     },
     {
@@ -315,6 +362,19 @@ const stream = createAssistantStream(async (controller) => {
   ]}
 />
 
+### groupPartByType helper
+
+`groupPartByType` builds a `groupBy` from a `part.type → group-key path` map. Part types missing from the map are left ungrouped. The returned function carries an internal memo fingerprint so the tree survives unrelated re-renders.
+
+```typescript
+import { groupPartByType } from "@assistant-ui/react";
+
+groupPartByType({
+  reasoning: ["group-thought", "group-reasoning"],
+  "tool-call": ["group-thought", "group-tool"],
+});
+```
+
 ### GroupPart Type
 
 ```typescript
@@ -331,34 +391,9 @@ type GroupPart<TKey extends `group-${string}` = `group-${string}`> = {
 2. **Handle ungrouped parts**: Always include leaf cases for the part types your message can render.
 3. **Only render `children` for groups**: Leaf parts receive a sentinel `children` value that throws if rendered accidentally.
 4. **Use `group-` prefixes**: Synthetic group keys must start with `group-` so they cannot collide with real part types.
-5. **Keep `groupBy` stable**: Prefer a module-level function or `useCallback` for frequently re-rendering message trees.
 
 ## Common Patterns
 
-### Conditional Grouping
-
-Only group when certain conditions are met:
-
-```tsx
-<MessagePrimitive.GroupedParts
-  groupBy={(part, index, parts) => {
-    const hasManyParts = parts.length >= 5;
-    if (!hasManyParts) return null;
-    if (part.type === "tool-call") return ["group-tools"];
-    return null;
-  }}
->
-  {({ part, children }) => {
-    if (part.type === "group-tools") {
-      return <div className="rounded-lg border p-3">{children}</div>;
-    }
-    if (part.type === "tool-call") return part.toolUI ?? <ToolFallback {...part} />;
-    if (part.type === "text") return <MarkdownText />;
-    return null;
-  }}
-</MessagePrimitive.GroupedParts>
-```
-
 ### Nested Grouping
 
 Create hierarchical adjacent groups by returning multiple keys:
@@ -370,7 +405,7 @@ Create hierarchical adjacent groups by returning multiple keys:
       return ["group-chainOfThought", "group-reasoning"];
     if (part.type === "tool-call")
       return ["group-chainOfThought", `group-tool-${part.toolName}`];
-    return null;
+    return [];
   }}
 >
   {({ part, children }) => {
@@ -391,10 +426,9 @@ Adjust group appearance based on the group node's status or indices:
 
 ```tsx
 <MessagePrimitive.GroupedParts
-  groupBy={(part) => {
-    if (part.type === "tool-call") return ["group-tools"];
-    return null;
-  }}
+  groupBy={groupPartByType({
+    "tool-call": ["group-tools"],
+  })}
 >
   {({ part, children }) => {
     if (part.type === "group-tools") {

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

@@ -31,7 +31,7 @@ Render reasoning parts through `MessagePrimitive.GroupedParts`. Group consecutiv
 While reasoning is streaming, `part.status.type === "running"`. Pass that to `defaultOpen` so the accordion auto-opens during streaming and lets the user collapse it once the model moves on.
 
 ```tsx title="/app/components/assistant-ui/thread.tsx"
-import { MessagePrimitive } from "@assistant-ui/react";
+import { MessagePrimitive, groupPartByType } from "@assistant-ui/react";
 import { MarkdownText } from "@/components/assistant-ui/markdown-text";
 import { ToolFallback } from "@/components/assistant-ui/tool-fallback";
 import {
@@ -47,10 +47,9 @@ const AssistantMessage: FC = () => {
     <MessagePrimitive.Root className="...">
       <div className="...">
         <MessagePrimitive.GroupedParts // [!code ++]
-          groupBy={(part) => { // [!code ++]
-            if (part.type === "reasoning") return ["group-reasoning"]; // [!code ++]
-            return null; // [!code ++]
-          }} // [!code ++]
+          groupBy={groupPartByType({ // [!code ++]
+            reasoning: ["group-reasoning"], // [!code ++]
+          })} // [!code ++]
         > // [!code ++]
           {({ part, children }) => { // [!code ++]
             switch (part.type) { // [!code ++]

package/.docs/raw/docs/ui/tool-group.mdx

@@ -29,10 +29,10 @@ This adds `/components/assistant-ui/tool-group.tsx` and `/components/assistant-u
 
 ### Use it in your application
 
-Use `MessagePrimitive.GroupedParts` and return `"group-tool"` for tool-call parts. The group case wraps `children`; the tool-call leaf renders the resolved tool UI or your fallback.
+Use `MessagePrimitive.GroupedParts` with `groupPartByType` to map tool-call parts to `"group-tool"`. The group case wraps `children`; the tool-call leaf renders the resolved tool UI or your fallback.
 
 ```tsx title="/components/assistant-ui/thread.tsx"
-import { MessagePrimitive } from "@assistant-ui/react";
+import { MessagePrimitive, groupPartByType } from "@assistant-ui/react";
 import { ToolFallback } from "@/components/assistant-ui/tool-fallback";
 import {
   ToolGroupContent,
@@ -44,10 +44,9 @@ const AssistantMessage = () => {
   return (
     <MessagePrimitive.Root>
       <MessagePrimitive.GroupedParts
-        groupBy={(part) => {
-          if (part.type === "tool-call") return ["group-tool"];
-          return null;
-        }}
+        groupBy={groupPartByType({
+          "tool-call": ["group-tool"],
+        })}
       >
         {({ part, children }) => {
           switch (part.type) {

package/.docs/raw/docs/utilities/heat-graph.mdx

@@ -4,7 +4,7 @@ description: Headless, composable activity heatmap components for React.
 platforms: ["react"]
 ---
 
-import { HeatGraphDemo } from "@/app/heat-graph/heat-graph-demo";
+import { HeatGraphDemo } from "@/app/(demos)/heat-graph/heat-graph-demo";
 
 `heat-graph` provides headless, Radix-style primitives for building GitHub-style activity heatmap graphs.
 

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;cAca,MAAA,EAAM,SAGjB;AAAA,iBAeoB,SAAA,CAAA,GAAS,OAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;cAca,MAAA,EAAM,SAGjB;AAAA,iBAeoB,SAAA,IAAS,OAAA"}

package/dist/prepare-docs/code-examples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-examples.d.ts","names":[],"sources":["../../src/prepare-docs/code-examples.ts"],"mappings":";iBA2FsB,mBAAA,CAAA,GAAuB,OAAO"}
+{"version":3,"file":"code-examples.d.ts","names":[],"sources":["../../src/prepare-docs/code-examples.ts"],"mappings":";iBA2FsB,mBAAA,IAAuB,OAAO"}

package/dist/prepare-docs/copy-raw.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"copy-raw.d.ts","names":[],"sources":["../../src/prepare-docs/copy-raw.ts"],"mappings":";iBAkCsB,OAAA,CAAA,GAAW,OAAO"}
+{"version":3,"file":"copy-raw.d.ts","names":[],"sources":["../../src/prepare-docs/copy-raw.ts"],"mappings":";iBAkCsB,OAAA,IAAW,OAAO"}

package/dist/utils/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","names":[],"sources":["../../src/utils/paths.ts"],"mappings":";iBAYsB,eAAA,CAAgB,OAAA,WAAkB,OAAO;EAC7D,WAAA;EACA,KAAA;AAAA;AAAA,iBA4BoB,iBAAA,CAAA,GAAqB,OAAO;AAAA,iBA0BlC,gBAAA,CACd,aAAA,UACA,cAAwB;AAAA,iBAoCJ,UAAA,CAAW,IAAA,WAAe,OAAO"}
+{"version":3,"file":"paths.d.ts","names":[],"sources":["../../src/utils/paths.ts"],"mappings":";iBAYsB,eAAA,CAAgB,OAAA,WAAkB,OAAO;EAC7D,WAAA;EACA,KAAA;AAAA;AAAA,iBA4BoB,iBAAA,IAAqB,OAAO;AAAA,iBA0BlC,gBAAA,CACd,aAAA,UACA,cAAwB;AAAA,iBAoCJ,UAAA,CAAW,IAAA,WAAe,OAAO"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/mcp-docs-server",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "MCP server for assistant-ui documentation and examples",
   "keywords": [
     "mcp",
@@ -38,9 +38,9 @@
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
-    "tsx": "^4.22.3",
+    "tsx": "^4.22.4",
     "vitest": "^4.1.7",
-    "@assistant-ui/x-buildutils": "0.0.9"
+    "@assistant-ui/x-buildutils": "0.0.11"
   },
   "publishConfig": {
     "access": "public",