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

package/.docs/raw/docs/ui/number-roll.mdx

@@ -0,0 +1,154 @@
+---
+title: Number Roll
+description: Animated number that rolls digits odometer-style when the value changes.
+platforms: ["react"]
+---
+
+import { PreviewCode } from "@/components/docs/preview-code.server";
+import {
+  NumberRollSample,
+  NumberRollCompactSample,
+  NumberRollFormatSample,
+  NumberRollLiveSample,
+} from "@/components/docs/samples/number-roll";
+
+<Callout>
+  This is a **standalone component** that does not depend on the assistant-ui runtime. Use it anywhere in your application.
+</Callout>
+
+<NumberRollSample />
+
+## Installation
+
+<InstallCommand shadcn={["number-roll"]} />
+
+This adds a `/components/assistant-ui/number-roll.tsx` file to your project, which you can adjust as needed. The component has no dependencies beyond React.
+
+## Usage
+
+```tsx
+import { NumberRoll } from "@/components/assistant-ui/number-roll";
+
+export function TokenCounter({ count }: { count: number }) {
+  return <NumberRoll value={count} format={{ notation: "compact" }} />;
+}
+```
+
+When `value` changes, each digit rolls in place to its new value. Formatting is handled by `Intl.NumberFormat`, so structural changes animate too: when `700` becomes `1.1K` with compact notation, the surviving ones digit rolls from 0 to 1 while the leading `70` slides out and the decimal point, fraction digit, and `K` suffix slide in.
+
+## Examples
+
+### Compact Notation
+
+Pass any `Intl.NumberFormatOptions` via the `format` prop. Crossing a compact-notation threshold animates the formatting change instead of remounting the whole string.
+
+<PreviewCode file="components/docs/samples/number-roll" name="NumberRollCompactSample">
+  <NumberRollCompactSample />
+</PreviewCode>
+
+### Formats and Locales
+
+Currencies, percentages, suffixes, and non-English locales all work through the same `Intl.NumberFormat` pipeline. Compact thresholds and suffixes are locale-dependent (`1.2万` in `zh-CN`), so never hardcode them.
+
+<PreviewCode file="components/docs/samples/number-roll" name="NumberRollFormatSample">
+  <NumberRollFormatSample />
+</PreviewCode>
+
+### Live Counter
+
+Rapid successive updates retarget the in-flight roll smoothly, which makes the component suitable for streaming token counts and other live metrics.
+
+<PreviewCode file="components/docs/samples/number-roll" name="NumberRollLiveSample">
+  <NumberRollLiveSample />
+</PreviewCode>
+
+## How It Works
+
+The value is formatted with `Intl.NumberFormat.formatToParts` and split into keyed parts. Integer digits are keyed by place value counted from the right, so when `999` becomes `1,000` the existing columns keep their identity and roll in place while only the new leading digit and separator enter. Symbols (decimal point, group separators, currency signs, compact suffixes) cross-fade and collapse via animated `grid-template-columns`.
+
+Each digit renders a strip of 0 to 9 and animates a registered CSS custom property; CSS `mod()` math wraps the strip into an endless ribbon, so rolling from 9 to 0 continues in the trend direction instead of spinning backwards. There is no JavaScript animation loop and no animation library dependency.
+
+In browsers without CSS `mod()` support, and during server rendering, the component renders the plain formatted string. With `prefers-reduced-motion`, values swap instantly without rolling. When server rendering, pass an explicit `locales`: the server's default locale can differ from the visitor's browser locale, and a mismatched formatted string causes a React hydration error. Locales whose default numbering system is non-Latin (such as `ar-EG`) cross-fade their digits as symbols instead of rolling.
+
+The formatted value is exposed to screen readers as plain text while the animated digits are `aria-hidden`. Value changes are not announced automatically; wrap the component in an `aria-live` region if you need announcements.
+
+## API Reference
+
+### NumberRoll
+
+<ParametersTable
+  type="NumberRollProps"
+  parameters={[
+    {
+      name: "value",
+      type: "number",
+      required: true,
+      description: "The number to display.",
+    },
+    {
+      name: "format",
+      type: "Intl.NumberFormatOptions",
+      description:
+        "Number formatting options, e.g. `{ notation: \"compact\" }` or `{ style: \"currency\", currency: \"USD\" }`.",
+    },
+    {
+      name: "locales",
+      type: "Intl.LocalesArgument",
+      description:
+        "Locale(s) passed to `Intl.NumberFormat`. Pass an explicit value in server-rendered apps so the server and client format identically.",
+    },
+    {
+      name: "prefix",
+      type: "string",
+      description: "Static text rendered before the number.",
+    },
+    {
+      name: "suffix",
+      type: "string",
+      description: "Static text rendered after the number.",
+    },
+    {
+      name: "trend",
+      type: '"auto" | "up" | "down"',
+      default: '"auto"',
+      description:
+        "Roll direction. `auto` follows the sign of the value change; `up` and `down` force a direction, wrapping digits through 9/0 as needed.",
+    },
+    {
+      name: "duration",
+      type: "number",
+      default: "500",
+      description:
+        "Digit roll duration in milliseconds. Enter/exit fades run at 60% of this value.",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Additional CSS classes.",
+    },
+  ]}
+/>
+
+### Styling
+
+The root applies `tabular-nums` so digits keep a constant width while rolling; the font you use must provide tabular figures for the layout to stay stable. Size and color are inherited from the surrounding text, so style it like any span:
+
+```tsx
+<NumberRoll value={value} className="text-4xl font-semibold" />
+```
+
+Change the animation speed via the `duration` prop; it drives both the CSS timing and the cleanup that unmounts exited characters, so overriding the duration variable in CSS alone would remove them mid-fade. The fade and easing variables are safe to override via the `style` prop (the defaults are set as inline styles, so plain `className` overrides do not apply):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--aui-number-roll-duration` | `500ms` (from the `duration` prop) | Digit roll duration. |
+| `--aui-number-roll-fade` | 60% of the duration | Enter/exit fade and width-collapse duration. |
+| `--aui-number-roll-ease` | `cubic-bezier(0.23, 1, 0.32, 1)` | Digit roll easing. |
+
+Parts are targetable via data attributes: `[data-slot="number-roll"]`, `[data-slot="number-roll-part"]`, `[data-slot="number-roll-digit"]`, and `[data-slot="number-roll-symbol"]`.
+
+## Related Components
+
+- [Context Display](/docs/ui/context-display) - Live token usage ring and bar
+- [Message Timing](/docs/ui/message-timing) - Streaming stats badge
+- [Badge](/docs/ui/badge) - Small status and metadata labels

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/ui/reasoning.mdx

@@ -28,7 +28,7 @@ Previously, reasoning parts were rendered via `components.Reasoning` and grouped
 
 Render reasoning parts through `MessagePrimitive.GroupedParts`. Group consecutive reasoning parts with `"group-reasoning"`, then compose `ReasoningRoot`, `ReasoningTrigger`, `ReasoningContent`, and `ReasoningText` around the grouped children.
 
-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.
+While reasoning is streaming, `part.status.type === "running"`. Pass that to `streaming` so the accordion auto-opens during streaming with a bottom-pinned live preview of the newest tokens, auto-collapses when the model moves on, and permanently defers to the first manual toggle. When `streaming` is provided it supersedes `defaultOpen`.
 
 ```tsx title="/app/components/assistant-ui/thread.tsx"
 import { MessagePrimitive, groupPartByType } from "@assistant-ui/react";
@@ -56,7 +56,7 @@ const AssistantMessage: FC = () => {
               case "group-reasoning": { // [!code ++]
                 const running = part.status.type === "running"; // [!code ++]
                 return ( // [!code ++]
-                  <ReasoningRoot defaultOpen={running}> // [!code ++]
+                  <ReasoningRoot streaming={running}> // [!code ++]
                     <ReasoningTrigger active={running} /> // [!code ++]
                     <ReasoningContent aria-busy={running}> // [!code ++]
                       <ReasoningText>{children}</ReasoningText> // [!code ++]
@@ -139,7 +139,7 @@ const ReasoningGroupImpl: ReasoningGroupComponent = ({
   });
 
   return (
-    <ReasoningRoot defaultOpen={isReasoningStreaming}>
+    <ReasoningRoot streaming={isReasoningStreaming}>
       <ReasoningTrigger active={isReasoningStreaming} />
       <ReasoningContent aria-busy={isReasoningStreaming}>
         <ReasoningText>{children}</ReasoningText>

package/.docs/raw/docs/ui/streamdown.mdx

@@ -119,6 +119,8 @@ const StreamdownText = () => (
 | `components` | `object` | - | Custom components including `SyntaxHighlighter` and `CodeHeader` |
 | `componentsByLanguage` | `object` | - | Language-specific component overrides |
 | `preprocess` | `(text: string) => string` | - | Text preprocessing function |
+| `defer` | `boolean` | `false` | Defer markdown parsing to a lower priority via `useDeferredValue` so typing and scrolling stay responsive during streaming |
+| `smooth` | `boolean \| SmoothOptions` | `false` | Typewriter-style reveal via `useSmooth`; the caret and controls stay active until the reveal catches up. Prefer the native `animated` prop for entrance animations |
 | `controls` | `boolean \| object` | `true` | Enable/disable UI controls for code blocks and tables |
 | `caret` | `"block" \| "circle"` | - | Streaming caret style |
 | `mermaid` | `MermaidOptions` | - | Mermaid diagram configuration |

package/.docs/raw/docs/ui/syntax-highlighting.mdx

@@ -29,7 +29,7 @@ import { SyntaxHighlightingSample } from "@/components/docs/samples/syntax-highl
 
 This adds a `/components/assistant-ui/shiki-highlighter.tsx` file to your project and
 installs the `react-shiki` dependency. The highlighter can be customized by editing
-the config in the `shiki-highlighter.tsx` file.
+the config in the `shiki-highlighter.tsx` file. While a message part is still streaming, the component renders the plain code without tokenization and highlights once the part settles, so streaming stays cheap.
 
   </Step>
   <Step>

package/.docs/raw/docs/ui/thread.mdx

@@ -133,6 +133,58 @@ const SuggestionItem = () => (
 );
 ```
 
+## Component Overrides
+
+`Thread` accepts an optional `components` prop that swaps parts of the rendering without editing the copied file. All slots are optional; omitted slots keep the built-in rendering.
+
+```tsx
+import { Thread, type ThreadComponents } from "@/components/assistant-ui/thread";
+
+const THREAD_COMPONENTS: ThreadComponents = {
+  ToolFallback: MyToolFallback,
+  ToolGroup: MyToolGroup,
+};
+
+export default function Chat() {
+  return <Thread components={THREAD_COMPONENTS} />;
+}
+```
+
+<ParametersTable
+  type="ThreadComponents"
+  parameters={[
+    {
+      name: "AssistantMessage",
+      type: "ComponentType",
+      description: "Replaces the entire assistant message, including the action bar and branch picker.",
+    },
+    {
+      name: "Welcome",
+      type: "ComponentType",
+      description: "Replaces the welcome screen shown for a new chat.",
+    },
+    {
+      name: "ToolFallback",
+      type: "ToolCallMessagePartComponent",
+      description: "Renders tool calls that have no tool UI registered by name. Registered tool UIs take precedence over this slot.",
+    },
+    {
+      name: "ToolGroup",
+      type: "ComponentType<PropsWithChildren<{ group: ThreadGroupPart }>>",
+      description: "Wraps runs of consecutive tool calls. Receives the group part (`indices`, `status`) and the rendered children.",
+    },
+    {
+      name: "ReasoningGroup",
+      type: "ComponentType<PropsWithChildren<{ group: ThreadGroupPart }>>",
+      description: "Wraps runs of consecutive reasoning parts. Receives the group part and the rendered children.",
+    },
+  ]}
+/>
+
+Define the `components` object once at module scope (or memoize it) so message subtrees do not re-render whenever the parent re-renders.
+
+For per-tool UI, prefer registering a renderer by tool name over overriding `ToolFallback`: put `render` on the matching toolkit entry (see [Tool UI](/docs/tools/tool-ui)). `data` message parts render through renderers registered with `useAssistantDataUI`; parts without a registered renderer are not displayed.
+
 ## API Reference
 
 The following primitives are used within the Thread component and can be customized in your `/components/assistant-ui/thread.tsx` file.

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

@@ -74,7 +74,7 @@ Shows a muted appearance when a tool call was cancelled.
 
 ### Approval State
 
-Shows the default Allow / Deny buttons rendered when a tool call enters `requires-action`. The block auto-expands so the decision is visible without a click. Edit your project's copy of `tool-fallback.tsx` to add trust escalation, edit-args, custom labels, or analytics hooks — the shadcn philosophy is you own the file.
+Shows the default Allow / Deny buttons rendered when a tool call enters `requires-action`. A tool call whose approval gate is already decided renders no buttons. The block auto-expands so the decision is visible without a click. Edit your project's copy of `tool-fallback.tsx` to add trust escalation, edit-args, custom labels, or analytics hooks — the shadcn philosophy is you own the file.
 
 <ToolFallbackRequiresActionSample />
 
@@ -90,7 +90,7 @@ All sub-components are exported for custom layouts:
 | `ToolFallback.Args` | Displays tool arguments |
 | `ToolFallback.Result` | Displays tool execution result |
 | `ToolFallback.Error` | Displays error or cancellation messages |
-| `ToolFallback.Approval` | Renders Allow / Deny buttons for `requires-action` tools; wires `resume` / `addResult` / `respondToApproval` |
+| `ToolFallback.Approval` | Renders Allow / Deny buttons for `requires-action` tools until a decision is recorded; wires `resume` / `addResult` / `respondToApproval` |
 
 ```tsx
 import {

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.34",
+  "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.2",
+    "@types/node": "^26.0.0",
     "tsx": "^4.22.4",
-    "vitest": "^4.1.8",
-    "@assistant-ui/x-buildutils": "0.0.12"
+    "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 () => {