@assistant-ui/mcp-docs-server 0.1.35 → 0.1.36

package/.docs/raw/docs/tools/mcp.mdx

@@ -7,10 +7,10 @@ description: Connect MCP servers as a tool catalog in your assistant-ui app.
 
 ## How it works
 
-```
-client  ──►  /api/chat  ──►  MCP client  ──►  MCP server (HTTP, SSE, stdio)
-                            │
-                            └─ tools()  ──►  passed to streamText({ tools })
+```mermaid
+flowchart LR
+    client["client"] --> api["/api/chat"] --> mcp["MCP client"] --> server["MCP server<br/>(HTTP, SSE, stdio)"]
+    mcp --> tools["tools()"] --> stream["passed to<br/>streamText({ tools })"]
 ```
 
 The MCP client lives on the server inside your AI SDK route handler. It connects to one or more MCP servers, calls `tools()` to get a tool map, and hands that map to `streamText`. assistant-ui's existing tool-call UI (`ToolFallback`, or toolkit entries with `render`) renders the results.

package/.docs/raw/docs/tools/multi-agent.mdx

@@ -16,6 +16,10 @@ Key behaviors:
 - **Recursive** — Sub-agent messages can contain tool calls that themselves have nested messages. Just use `MessagePartPrimitive.Messages` again.
 - **Read-only** — Sub-agent messages are rendered in a readonly context. No editing, branching, or composing.
 
+<Callout type="info">
+  This renders a sub-agent's **messages**. To visualize a sub-agent's **execution trace** instead (timing, span hierarchy, waterfalls), see [react-o11y](/docs/utilities/react-o11y), which renders observability spans as collapsible trees and timelines.
+</Callout>
+
 ## Quick Start
 
 <Steps>
@@ -226,6 +230,7 @@ function SubConversation({
 ## Related
 
 - [Generative UI](/docs/tools/tool-ui) — Creating tool call UIs
+- [react-o11y](/docs/utilities/react-o11y) — Visualize sub-agent execution as collapsible span trees, waterfalls, and call timelines
 - [MessagePartPrimitive](/docs/api-reference/primitives/message-part) — API reference for message part primitives
 - [Sub-Agent Model Tracking](/docs/cloud/ai-sdk#sub-agent-model-tracking) — Track delegated model usage and costs in the Cloud dashboard
 - [LangGraph Streaming](/docs/runtimes/langgraph/streaming) — Event handlers, subgraph events, and message metadata

package/.docs/raw/docs/ui/composer-trigger-popover.mdx

@@ -185,6 +185,8 @@ The popover implements the WAI-ARIA editable combobox pattern.
 | `backLabel` | `string` | `"Back"` | Back button label |
 | `emptyCategoriesLabel` | `string` | `"No items available"` | Shown when no categories are available |
 | `emptyItemsLabel` | `string` | `"No matching items"` | Shown when no items match |
+| `isLoading` | `boolean` | `false` | Whether the adapter is resolving items (async sources). Pair with `unstable_useLiveCompletionAdapter`. |
+| `loadingLabel` | `string` | `"Loading…"` | Shown in place of `emptyItemsLabel` while `isLoading` and no items are present |
 
 All other props (`className`, etc.) forward to the underlying popover `div`.
 

package/.docs/raw/docs/ui/file.mdx

@@ -27,7 +27,7 @@ Pass `File` to `MessagePrimitive.Parts`:
 ```tsx title="/components/assistant-ui/thread.tsx" {1,8}
 import { File } from "@/components/assistant-ui/file";
 
-const AssistantMessage: FC = () => {
+const UserMessage: FC = () => {
   return (
     <MessagePrimitive.Root className="...">
       <MessagePrimitive.Parts>

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

@@ -252,6 +252,44 @@ The synthetic `"standalone-tool-call"` key on `groupPartByType` matches all of t
   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>
 
+### Render Tool Calls as Flat Rows
+
+The previous section keeps `"tool-call"` folded into the chain-of-thought and only lifts standalone tool UIs out. To keep reasoning collapsed in a group while every tool call renders as its own row in the message flow, map both tool keys to `[]`:
+
+```tsx
+<MessagePrimitive.GroupedParts
+  groupBy={groupPartByType({
+    reasoning: ["group-thought", "group-reasoning"],
+    "tool-call": [],
+    "standalone-tool-call": [],
+  })}
+>
+  {({ part, children }) => {
+    switch (part.type) {
+      case "group-thought":
+      case "group-reasoning":
+        return <ReasoningBlock>{children}</ReasoningBlock>;
+      case "reasoning":
+        return <Reasoning {...part} />;
+      case "tool-call":
+        return part.toolUI ?? <ToolFallback {...part} />;
+      case "text":
+        return <MarkdownText />;
+      case "indicator":
+        return <LoadingDots />;
+      default:
+        return null;
+    }
+  }}
+</MessagePrimitive.GroupedParts>
+```
+
+Adjacent `reasoning` parts still coalesce into one `group-thought`, while each tool call is a leaf at the same level as text — the `"standalone-tool-call"` entry is mapped to `[]` too so human-in-the-loop and generative-UI tools stay flat alongside routine calls instead of falling through to `"tool-call"`. Tool-call leaves keep their stable identity keys across re-renders, so rows don't remount as the message streams.
+
+<Callout type="warn">
+  This renders tool calls flat **in the message flow** — each leaf sits where the part appears, in order. It does not pin, portal, float, or otherwise move tool UIs out of the flow into a sidebar or fixed region. For out-of-flow placement you still own the layout outside `GroupedParts`.
+</Callout>
+
 ### Group by Custom Metadata
 
 Use any custom metadata in your parts for grouping:

package/.docs/raw/docs/utilities/react-o11y.mdx

@@ -1,11 +1,18 @@
 ---
 title: react-o11y
-description: Headless primitives for visualizing observability spans (traces, waterfalls).
+description: Headless primitives for visualizing observability spans as collapsible trace trees, waterfalls, and agent and LLM call timelines.
 platforms: ["react"]
 ---
 
+import { WaterfallSample } from "@/components/docs/samples/o11y/waterfall";
+import {
+  StatusSample,
+  CollapseSample,
+  StreamingSample,
+} from "@/components/docs/samples/o11y/capability-samples";
+
 <Callout type="warn">
-`@assistant-ui/react-o11y` is currently v0.0.11 and experimental. The API may change without notice.
+`@assistant-ui/react-o11y` is experimental. The API may change without notice.
 </Callout>
 
 `@assistant-ui/react-o11y` provides headless, Radix-style primitives for rendering observability spans as collapsible, indented hierarchical UIs. Use it to build trace inspectors, waterfall debug panels, or LLM call timelines on top of your own span data source.
@@ -15,6 +22,10 @@ platforms: ["react"]
 - **Tree-aware** — Automatic depth, parent / child collapse, time range computation.
 - **Reactive** — Built on the same reactive core as the runtimes, so spans stream into your UI as they change.
 
+<div className="not-prose my-6">
+  <WaterfallSample />
+</div>
+
 ## Installation
 
 <InstallCommand npm={["@assistant-ui/react-o11y"]} />
@@ -43,13 +54,12 @@ function SpanRow() {
       <SpanPrimitive.StatusIndicator className="size-2 rounded-full data-[span-status=running]:bg-yellow-500 data-[span-status=completed]:bg-green-500 data-[span-status=failed]:bg-red-500" />
       <SpanPrimitive.TypeBadge className="rounded bg-muted px-1.5 text-xs" />
       <SpanPrimitive.Name className="text-sm" />
-      <SpanPrimitive.Children components={{ Span: SpanRow }} />
     </SpanPrimitive.Root>
   );
 }
 
 export function TraceView({ spans }: { spans: SpanData[] }) {
-  const aui = useAui({ resource: SpanResource({ spans }) });
+  const aui = useAui({ span: SpanResource({ spans }) });
 
   return (
     <AuiProvider value={aui}>
@@ -61,6 +71,32 @@ export function TraceView({ spans }: { spans: SpanData[] }) {
 
 `SpanData` is the input shape your code produces (see [SpanData](#spandata)). `SpanResource` enriches it with depth, child counts, time range, and collapse state.
 
+## Examples
+
+### Status states
+
+`data-span-status` exposes each span's lifecycle, so running, completed, failed, and skipped are styled with pure CSS.
+
+<div className="not-prose my-6">
+  <StatusSample />
+</div>
+
+### Collapsible subtrees
+
+`SpanPrimitive.CollapseToggle` removes a span's descendants from the visible flat list, not just hides them. Click a chevron to collapse a subtree.
+
+<div className="not-prose my-6">
+  <CollapseSample />
+</div>
+
+### Streaming spans
+
+`SpanResource` re-derives the tree whenever the `spans` prop changes, so spans stream in and update live.
+
+<div className="not-prose my-6">
+  <StreamingSample />
+</div>
+
 ## Anatomy
 
 ```tsx
@@ -71,7 +107,7 @@ import {
 } from "@assistant-ui/react-o11y";
 
 // Top-level: mount SpanResource via useAui
-const aui = useAui({ resource: SpanResource({ spans }) });
+const aui = useAui({ span: SpanResource({ spans }) });
 
 <AuiProvider value={aui}>
   {/* Render visible spans (flat-list output respecting collapsed state) */}
@@ -104,7 +140,7 @@ Resource that ingests raw span data and exposes a tree-aware reactive state to p
 SpanResource({ spans }: { spans: SpanData[] }): ClientOutput<"span">;
 ```
 
-Mount through `useAui({ resource: SpanResource({ spans }) })`.
+Mount through `useAui({ span: SpanResource({ spans }) })`.
 
 The resource computes:
 
@@ -243,6 +279,56 @@ Convenience component that pairs `SpanByIndexProvider` with a render component:
 
 Useful when you want explicit control over which child indices to render (e.g. for virtualization).
 
+### SpanPrimitive.Timeline
+
+A `<div>` that provides a timeline range to descendant `TimelineBar` primitives and exposes range CSS variables.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `timeRange` | `{ min: number; max: number }` | `span.timeRange` | Override the range used for positioning bars. |
+| `paddingEnd` | `number` | `0` | Extends the max by this ratio of the range duration, useful for right-side breathing room. |
+
+Exposes `data-span-timeline` and CSS variables:
+
+| Variable | Description |
+| --- | --- |
+| `--span-timeline-min-ms` | Timeline start timestamp. |
+| `--span-timeline-max-ms` | Timeline end timestamp after padding. |
+| `--span-timeline-range-ms` | Timeline duration after padding. |
+
+### SpanPrimitive.TimelineBar
+
+A `<div>` that positions the current span within the nearest `SpanPrimitive.Timeline` range. It reads `startedAt`, `endedAt`, `status`, `type`, and `timeRange` from the current span scope.
+
+```tsx
+<SpanPrimitive.Timeline>
+  <SpanPrimitive.Children>
+    {() => (
+      <div className="relative h-8">
+        <SpanPrimitive.TimelineBar className="top-1 h-6 rounded bg-blue-500" />
+      </div>
+    )}
+  </SpanPrimitive.Children>
+</SpanPrimitive.Timeline>
+```
+
+Running spans use the timeline range max when `now` is omitted, keeping SSR and hydration deterministic. For live ticking, update a timestamp from an effect or animation loop and pass it as `now`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `now` | `number` | `undefined` | Explicit timestamp used as the end of running spans. |
+| `timeRange` | `{ min: number; max: number }` | nearest `Timeline` range | Override the range used for this bar. |
+
+Exposes `data-span-status`, `data-span-type`, `data-span-running`, and these CSS variables:
+
+| Variable | Description |
+| --- | --- |
+| `--span-timeline-left` | Bar start position as a percentage. |
+| `--span-timeline-end` | Bar end position as a percentage. |
+| `--span-timeline-width` | Bar width as a percentage. |
+| `--span-timeline-duration-ms` | Bar duration in milliseconds. |
+| `--span-timeline-min-width` | Optional consumer-set minimum width used by the default inline size. |
+
 ## Styling
 
 All primitives forward refs and accept standard DOM props (`className`, `style`, etc.). Use the data attributes for state-based styling:

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,IAAS,OAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;cAca,MAAA,EAAM,SAGjB;AAAA,iBAuBoB,SAAA,IAAS,OAAA"}

package/dist/index.js

@@ -12,8 +12,24 @@ const server = new McpServer({
 	name: "assistant-ui-docs",
 	version: packageJson.version
 });
-server.tool(docsTools.name, docsTools.description, docsTools.parameters, docsTools.execute);
-server.tool(examplesTools.name, examplesTools.description, examplesTools.parameters, examplesTools.execute);
+server.registerTool(docsTools.name, {
+	title: "assistant-ui Documentation",
+	description: docsTools.description,
+	inputSchema: docsTools.parameters,
+	annotations: {
+		readOnlyHint: true,
+		openWorldHint: false
+	}
+}, docsTools.execute);
+server.registerTool(examplesTools.name, {
+	title: "assistant-ui Examples",
+	description: examplesTools.description,
+	inputSchema: examplesTools.parameters,
+	annotations: {
+		readOnlyHint: true,
+		openWorldHint: false
+	}
+}, examplesTools.execute);
 async function runServer() {
 	try {
 		logger.info(`Starting assistant-ui MCP docs server v${packageJson.version}`);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { docsTools } from \"./tools/docs.js\";\nimport { examplesTools } from \"./tools/examples.js\";\nimport { logger } from \"./utils/logger.js\";\nimport { PACKAGE_DIR } from \"./constants.js\";\n\nimport { readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\nconst packageJson = JSON.parse(\n  readFileSync(join(PACKAGE_DIR, \"package.json\"), \"utf-8\"),\n);\n\nexport const server = new McpServer({\n  name: \"assistant-ui-docs\",\n  version: packageJson.version,\n});\n\nserver.tool(\n  docsTools.name,\n  docsTools.description,\n  docsTools.parameters,\n  docsTools.execute,\n);\nserver.tool(\n  examplesTools.name,\n  examplesTools.description,\n  examplesTools.parameters,\n  examplesTools.execute,\n);\n\nexport async function runServer() {\n  try {\n    logger.info(\n      `Starting assistant-ui MCP docs server v${packageJson.version}`,\n    );\n    const transport = new StdioServerTransport();\n    await server.connect(transport);\n  } catch (error) {\n    logger.error(\"Failed to start MCP server\", error);\n    process.exit(1);\n  }\n}\n\nif (import.meta.url === `file://${process.argv[1]}`) {\n  void runServer().catch((error) => {\n    console.error(\"Failed to start server:\", error);\n    process.exit(1);\n  });\n}\n"],"mappings":";;;;;;;;;AAUA,MAAM,cAAc,KAAK,MACvB,aAAa,KAAK,aAAa,cAAc,GAAG,OAAO,CACzD;AAEA,MAAa,SAAS,IAAI,UAAU;CAClC,MAAM;CACN,SAAS,YAAY;AACvB,CAAC;AAED,OAAO,KACL,UAAU,MACV,UAAU,aACV,UAAU,YACV,UAAU,OACZ;AACA,OAAO,KACL,cAAc,MACd,cAAc,aACd,cAAc,YACd,cAAc,OAChB;AAEA,eAAsB,YAAY;CAChC,IAAI;EACF,OAAO,KACL,0CAA0C,YAAY,SACxD;EACA,MAAM,YAAY,IAAI,qBAAqB;EAC3C,MAAM,OAAO,QAAQ,SAAS;CAChC,SAAS,OAAO;EACd,OAAO,MAAM,8BAA8B,KAAK;EAChD,QAAQ,KAAK,CAAC;CAChB;AACF;AAEA,IAAI,OAAO,KAAK,QAAQ,UAAU,QAAQ,KAAK,MAC7C,UAAe,CAAC,CAAC,OAAO,UAAU;CAChC,QAAQ,MAAM,2BAA2B,KAAK;CAC9C,QAAQ,KAAK,CAAC;AAChB,CAAC"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { docsTools } from \"./tools/docs.js\";\nimport { examplesTools } from \"./tools/examples.js\";\nimport { logger } from \"./utils/logger.js\";\nimport { PACKAGE_DIR } from \"./constants.js\";\n\nimport { readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\nconst packageJson = JSON.parse(\n  readFileSync(join(PACKAGE_DIR, \"package.json\"), \"utf-8\"),\n);\n\nexport const server = new McpServer({\n  name: \"assistant-ui-docs\",\n  version: packageJson.version,\n});\n\nserver.registerTool(\n  docsTools.name,\n  {\n    title: \"assistant-ui Documentation\",\n    description: docsTools.description,\n    inputSchema: docsTools.parameters,\n    annotations: { readOnlyHint: true, openWorldHint: false },\n  },\n  docsTools.execute,\n);\nserver.registerTool(\n  examplesTools.name,\n  {\n    title: \"assistant-ui Examples\",\n    description: examplesTools.description,\n    inputSchema: examplesTools.parameters,\n    annotations: { readOnlyHint: true, openWorldHint: false },\n  },\n  examplesTools.execute,\n);\n\nexport async function runServer() {\n  try {\n    logger.info(\n      `Starting assistant-ui MCP docs server v${packageJson.version}`,\n    );\n    const transport = new StdioServerTransport();\n    await server.connect(transport);\n  } catch (error) {\n    logger.error(\"Failed to start MCP server\", error);\n    process.exit(1);\n  }\n}\n\nif (import.meta.url === `file://${process.argv[1]}`) {\n  void runServer().catch((error) => {\n    console.error(\"Failed to start server:\", error);\n    process.exit(1);\n  });\n}\n"],"mappings":";;;;;;;;;AAUA,MAAM,cAAc,KAAK,MACvB,aAAa,KAAK,aAAa,cAAc,GAAG,OAAO,CACzD;AAEA,MAAa,SAAS,IAAI,UAAU;CAClC,MAAM;CACN,SAAS,YAAY;AACvB,CAAC;AAED,OAAO,aACL,UAAU,MACV;CACE,OAAO;CACP,aAAa,UAAU;CACvB,aAAa,UAAU;CACvB,aAAa;EAAE,cAAc;EAAM,eAAe;CAAM;AAC1D,GACA,UAAU,OACZ;AACA,OAAO,aACL,cAAc,MACd;CACE,OAAO;CACP,aAAa,cAAc;CAC3B,aAAa,cAAc;CAC3B,aAAa;EAAE,cAAc;EAAM,eAAe;CAAM;AAC1D,GACA,cAAc,OAChB;AAEA,eAAsB,YAAY;CAChC,IAAI;EACF,OAAO,KACL,0CAA0C,YAAY,SACxD;EACA,MAAM,YAAY,IAAI,qBAAqB;EAC3C,MAAM,OAAO,QAAQ,SAAS;CAChC,SAAS,OAAO;EACd,OAAO,MAAM,8BAA8B,KAAK;EAChD,QAAQ,KAAK,CAAC;CAChB;AACF;AAEA,IAAI,OAAO,KAAK,QAAQ,UAAU,QAAQ,KAAK,MAC7C,UAAe,CAAC,CAAC,OAAO,UAAU;CAChC,QAAQ,MAAM,2BAA2B,KAAK;CAC9C,QAAQ,KAAK,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/mcp-docs-server",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "description": "MCP server for assistant-ui documentation and examples",
   "keywords": [
     "mcp",
@@ -37,10 +37,10 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.0.0",
     "tsx": "^4.22.4",
-    "vitest": "^4.1.8",
-    "@assistant-ui/x-buildutils": "0.0.14"
+    "vitest": "^4.1.9",
+    "@assistant-ui/x-buildutils": "0.0.16"
   },
   "publishConfig": {
     "access": "public",

package/src/index.ts

@@ -17,16 +17,24 @@ export const server = new McpServer({
   version: packageJson.version,
 });
 
-server.tool(
+server.registerTool(
   docsTools.name,
-  docsTools.description,
-  docsTools.parameters,
+  {
+    title: "assistant-ui Documentation",
+    description: docsTools.description,
+    inputSchema: docsTools.parameters,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
   docsTools.execute,
 );
-server.tool(
+server.registerTool(
   examplesTools.name,
-  examplesTools.description,
-  examplesTools.parameters,
+  {
+    title: "assistant-ui Examples",
+    description: examplesTools.description,
+    inputSchema: examplesTools.parameters,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
   examplesTools.execute,
 );
 

package/src/tools/tests/mcp-protocol.test.ts

@@ -73,6 +73,15 @@ describe("MCP Protocol Integration", () => {
     expect(examplesTool.inputSchema).toBeDefined();
     expect(examplesTool.inputSchema.type).toBe("object");
     expect(examplesTool.inputSchema.properties).toBeDefined();
+
+    // registerTool metadata is surfaced on tools/list: `title` is a
+    // top-level field, `annotations` carries only the hint flags.
+    expect(docsTool.title).toBe("assistant-ui Documentation");
+    expect(docsTool.annotations?.readOnlyHint).toBe(true);
+    expect(docsTool.annotations?.openWorldHint).toBe(false);
+    expect(examplesTool.title).toBe("assistant-ui Examples");
+    expect(examplesTool.annotations?.readOnlyHint).toBe(true);
+    expect(examplesTool.annotations?.openWorldHint).toBe(false);
   });
 
   it("should handle CallTool request for assistantUIDocs", async () => {