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

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

@@ -0,0 +1,278 @@
+---
+title: react-o11y
+description: Headless primitives for visualizing observability spans (traces, waterfalls).
+platforms: ["react"]
+---
+
+<Callout type="warn">
+`@assistant-ui/react-o11y` is currently v0.0.11 and 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.
+
+- **Headless** — Zero styling opinions, bring your own CSS / Tailwind.
+- **Composable** — Radix-style primitive parts you fully control.
+- **Tree-aware** — Automatic depth, parent / child collapse, time range computation.
+- **Tap-powered** — Built on the same `@assistant-ui/tap` reactive primitives as the runtimes.
+
+## Installation
+
+<InstallCommand npm={["@assistant-ui/react-o11y"]} />
+
+## Quick start
+
+Mount `SpanResource` with your span data, then render primitives that read from the resource's state:
+
+```tsx title="components/trace-view.tsx"
+"use client";
+
+import {
+  SpanPrimitive,
+  SpanResource,
+  type SpanData,
+} from "@assistant-ui/react-o11y";
+import { useAui, AuiProvider } from "@assistant-ui/store";
+
+function SpanRow() {
+  return (
+    <SpanPrimitive.Root className="flex items-center gap-2 py-1">
+      <SpanPrimitive.Indent />
+      <SpanPrimitive.CollapseToggle className="size-4 cursor-pointer">
+        ▸
+      </SpanPrimitive.CollapseToggle>
+      <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 }) });
+
+  return (
+    <AuiProvider value={aui}>
+      <SpanPrimitive.Children components={{ Span: SpanRow }} />
+    </AuiProvider>
+  );
+}
+```
+
+`SpanData` is the input shape your code produces (see [SpanData](#spandata)). `SpanResource` enriches it with depth, child counts, time range, and collapse state.
+
+## Anatomy
+
+```tsx
+import {
+  SpanPrimitive,
+  SpanResource,
+  SpanByIndexProvider,
+} from "@assistant-ui/react-o11y";
+
+// Top-level: mount SpanResource via useAui
+const aui = useAui({ resource: SpanResource({ spans }) });
+
+<AuiProvider value={aui}>
+  {/* Render visible spans (flat-list output respecting collapsed state) */}
+  <SpanPrimitive.Children components={{ Span: SpanRow }} />
+</AuiProvider>;
+
+// Each <SpanRow /> sits inside its own SpanByIndexProvider context and reads via primitives
+function SpanRow() {
+  return (
+    <SpanPrimitive.Root>
+      <SpanPrimitive.Indent />
+      <SpanPrimitive.CollapseToggle />
+      <SpanPrimitive.StatusIndicator />
+      <SpanPrimitive.TypeBadge />
+      <SpanPrimitive.Name />
+    </SpanPrimitive.Root>
+  );
+}
+```
+
+`SpanPrimitive.Children` produces a flat list of visible spans (collapsed subtrees are excluded). Each rendered child is wrapped in a `SpanByIndexProvider` so its primitives resolve to that specific span's state.
+
+## API reference
+
+### SpanResource
+
+Tap resource that ingests raw span data and exposes a tree-aware reactive state to primitives.
+
+```ts
+SpanResource({ spans }: { spans: SpanData[] }): ClientOutput<"span">;
+```
+
+Mount through `useAui({ resource: SpanResource({ spans }) })`.
+
+The resource computes:
+
+- **depth** of each span based on parent chain.
+- **hasChildren** flag.
+- **timeRange** (`min` / `max` across all spans).
+- **collapse state** managed internally; toggles through primitives.
+
+### SpanData
+
+Input shape you provide to `SpanResource`:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Unique span identifier. |
+| `parentSpanId` | `string \| null` | Parent span id, or `null` for root spans. |
+| `name` | `string` | Display name. |
+| `type` | `string` | Span category (e.g. `llm`, `tool`, `http`). Used by `TypeBadge`. |
+| `status` | `"running" \| "completed" \| "failed" \| "skipped"` | Lifecycle state. Used by `StatusIndicator`. |
+| `startedAt` | `number` | Start timestamp (ms). |
+| `endedAt` | `number \| null` | End timestamp (ms), or `null` if still running. |
+| `latencyMs` | `number \| null` | Pre-computed latency, or `null` if running. |
+
+### SpanState
+
+Returned by `useAuiState((s) => s.span)` inside any span-scoped subtree:
+
+```ts
+type SpanState = {
+  id: string;
+  parentSpanId: string | null;
+  name: string;
+  type: string;
+  status: "running" | "completed" | "failed" | "skipped";
+  startedAt: number;
+  endedAt: number | null;
+  latencyMs: number | null;
+  depth: number;
+  hasChildren: boolean;
+  isCollapsed: boolean;
+  children: SpanItemState[];
+  timeRange: { min: number; max: number };
+};
+```
+
+### SpanPrimitive.Root
+
+Container `<div>` exposing span state via data attributes for styling:
+
+| Attribute | Source |
+| --- | --- |
+| `data-span-id` | `span.id` |
+| `data-span-status` | `span.status` |
+| `data-span-type` | `span.type` |
+| `data-span-depth` | `span.depth` |
+| `data-collapsed` | `span.isCollapsed` |
+
+Accepts all standard `<div>` props.
+
+### SpanPrimitive.Indent
+
+A `<div>` that adds horizontal padding proportional to span depth.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `baseIndent` | `number` | `8` | Base padding in pixels. |
+| `indentPerLevel` | `number` | `12` | Additional padding per depth level. |
+
+Final `paddingLeft = baseIndent + depth * indentPerLevel`.
+
+### SpanPrimitive.CollapseToggle
+
+A `<button>` that toggles the current span's collapsed state. Renders only when the span has children. Stops click propagation so it can be nested inside a clickable row.
+
+Exposes `data-collapsed` for styling. Accepts all standard `<button>` props.
+
+### SpanPrimitive.StatusIndicator
+
+A `<span>` that exposes `data-span-status` for status-based styling (color, icon swap, etc.). Renders no built-in glyph; you provide the visual.
+
+```tsx
+<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 data-[span-status=skipped]:bg-gray-400" />
+```
+
+### SpanPrimitive.TypeBadge
+
+A `<span>` that defaults its children to `span.type` (override by passing custom children). Exposes `data-span-type`.
+
+### SpanPrimitive.Name
+
+A `<span>` that defaults its children to `span.name`. Override by passing custom children.
+
+### SpanPrimitive.Children
+
+Iterates over visible child spans and renders each.
+
+Two usage modes:
+
+**Render-prop:**
+
+```tsx
+<SpanPrimitive.Children>
+  {({ span }) => <CustomRow span={span} />}
+</SpanPrimitive.Children>
+```
+
+**Component prop (recommended for performance):**
+
+```tsx
+<SpanPrimitive.Children components={{ Span: SpanRow }} />
+```
+
+The `components.Span` form is memoized; pass a stable component reference to avoid re-renders on unrelated state changes.
+
+Each child is wrapped in `SpanByIndexProvider` automatically, so primitives inside `SpanRow` read that child's state.
+
+### SpanByIndexProvider
+
+Lower-level escape hatch. Selects one span by index and provides its scope to descendants:
+
+```tsx
+<SpanByIndexProvider index={0}>
+  <SpanPrimitive.Root>{/* reads span at index 0 */}</SpanPrimitive.Root>
+</SpanByIndexProvider>
+```
+
+Most users do not need to use this directly; `SpanPrimitive.Children` wires it up automatically.
+
+### SpanPrimitive.ChildByIndex
+
+Convenience component that pairs `SpanByIndexProvider` with a render component:
+
+```tsx
+<SpanPrimitive.ChildByIndex index={0} components={{ Span: SpanRow }} />
+```
+
+Useful when you want explicit control over which child indices to render (e.g. for virtualization).
+
+## Styling
+
+All primitives forward refs and accept standard DOM props (`className`, `style`, etc.). Use the data attributes for state-based styling:
+
+```css
+[data-span-status="running"] {
+  /* yellow indicator */
+}
+[data-span-status="failed"] {
+  /* red indicator */
+}
+[data-collapsed="true"] svg {
+  transform: rotate(0deg);
+}
+[data-collapsed="false"] svg {
+  transform: rotate(90deg);
+}
+```
+
+## Related
+
+<Cards>
+  <Card
+    title="heat-graph"
+    description="Activity heatmap primitives in the same Radix-style headless pattern."
+    href="/docs/utilities/heat-graph"
+  />
+  <Card
+    title="Primitives overview"
+    description="The broader assistant-ui primitive system."
+    href="/docs/primitives"
+  />
+</Cards>

package/.docs/raw/docs/utilities/tw-shimmer.mdx

@@ -1,6 +1,7 @@
 ---
 title: tw-shimmer
 description: Tailwind CSS v4 plugin for shimmer effects.
+platforms: ["react"]
 ---
 
 `tw-shimmer` is a zero-dependency Tailwind CSS v4 plugin that provides polished shimmer animations for both text and skeleton loaders. It uses sine-eased gradients with 17 carefully calculated stops and OKLCH color mixing for smooth, banding-free effects.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/mcp-docs-server",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "description": "MCP server for assistant-ui documentation and examples",
   "keywords": [
     "mcp",
@@ -34,13 +34,13 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "gray-matter": "^4.0.3",
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
     "tsx": "^4.21.0",
     "vitest": "^4.1.5",
-    "@assistant-ui/x-buildutils": "0.0.6"
+    "@assistant-ui/x-buildutils": "0.0.7"
   },
   "publishConfig": {
     "access": "public",

package/src/tools/tests/path-traversal.test.ts

@@ -26,7 +26,7 @@ describe("Path Traversal Security", () => {
 
     it("should handle multiple paths with one malicious", async () => {
       const result = await testContext.callTool("assistantUIDocs", {
-        paths: ["(docs)/index", "../../../../etc/passwd", "(docs)/guides"],
+        paths: ["(docs)/index", "../../../../etc/passwd", "guides"],
       });
 
       expect(result.results).toBeDefined();

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

@@ -1,65 +0,0 @@
----
-title: Message Branching
-description: Navigate between different conversation branches when editing or reloading messages.
----
-
-import { BranchingSample } from "@/components/docs/samples/branching";
-
-Switch between different conversation branches.
-
-<BranchingSample />
-
-A new branch is created when:
-
-- a user message is edited
-- an assistant message is reloaded
-
-Branches are automatically tracked by assistant-ui by observing changes to the `messages` array.
-
-## Enabling branch support
-
-You can show a branch picker by using `BranchPickerPrimitive`.
-
-```tsx {1, 8, 15-30}
-import { BranchPickerPrimitive } from "@assistant-ui/react";
-
-
-const Message = () => {
-  return (
-    <MessagePrimitive.Root>
-      ...
-      <BranchPicker /> {/* <-- show the branch picker */}
-      ...
-    </MessagePrimitive.Root>
-  );
-};
-
-
-const BranchPicker = () => {
-  return (
-    <BranchPickerPrimitive.Root hideWhenSingleBranch>
-      <BranchPickerPrimitive.Previous />
-      <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
-      <BranchPickerPrimitive.Next />
-    </BranchPickerPrimitive.Root>
-  );
-};
-```
-
-## API
-
-You can access the current branch state or navigate via the API as well.
-These APIs rely on the message scope and may only be called inside a message component.
-
-```tsx
-import { useAui, useAuiState } from "@assistant-ui/react";
-
-// read branch state
-const { branchNumber, branchCount } = useAuiState((s) => s.message);
-
-// navigation
-const aui = useAui();
-aui.message().switchToBranch({ position: "next" });
-aui.message().switchToBranch({ position: "previous" });
-aui.message().switchToBranch({ branchId: "some-id" });
-```

package/.docs/raw/docs/(docs)/guides/chain-of-thought.mdx

@@ -1,164 +0,0 @@
----
-title: Chain of Thought
-description: Group reasoning and tool calls into a collapsible accordion UI.
----
-
-LLMs often produce reasoning steps and tool calls in succession. Chain of Thought lets you visually group these consecutive parts into a single collapsible accordion, giving users a clean "thinking" UI.
-
-## Overview
-
-When a model like OpenAI's `o4-mini` responds, it may emit a sequence of reasoning tokens and tool calls before producing its final text answer. By default, these parts render individually. `ChainOfThoughtPrimitive` groups consecutive reasoning + tool-call parts together and renders them through a single component.
-
-Key benefits:
-
-- **Cleaner UI** — Collapse intermediate steps behind a "Thinking" toggle
-- **Better context** — Users see that reasoning and tool calls are related
-- **Built-in accordion** — Expand/collapse with a single click; collapsed by default
-
-## Quick Start
-
-<Steps>
-  <Step>
-
-### Pass a ChainOfThought component to MessagePrimitive.Parts
-
-`MessagePrimitive.Parts` accepts a `ChainOfThought` component. When provided, consecutive reasoning and tool-call parts are automatically grouped and rendered through it.
-
-```tsx
-import {
-  AuiIf,
-  ChainOfThoughtPrimitive,
-  MessagePrimitive,
-} from "@assistant-ui/react";
-import type { FC } from "react";
-
-const Reasoning: FC<{ text: string }> = ({ text }) => {
-  return (
-    <p className="whitespace-pre-wrap px-4 py-2 text-muted-foreground text-sm italic">
-      {text}
-    </p>
-  );
-};
-
-const ChainOfThought: FC = () => {
-  return (
-    <ChainOfThoughtPrimitive.Root className="my-2 rounded-lg border">
-      <ChainOfThoughtPrimitive.AccordionTrigger className="flex w-full cursor-pointer items-center gap-2 px-4 py-2 font-medium text-sm hover:bg-muted/50">
-        Thinking
-      </ChainOfThoughtPrimitive.AccordionTrigger>
-      <AuiIf condition={(s) => !s.chainOfThought.collapsed}>
-        <ChainOfThoughtPrimitive.Parts>
-          {({ part }) => {
-            if (part.type === "reasoning") return <Reasoning {...part} />;
-            if (part.type === "tool-call") return <ToolFallback {...part} />;
-            return null;
-          }}
-        </ChainOfThoughtPrimitive.Parts>
-      </AuiIf>
-    </ChainOfThoughtPrimitive.Root>
-  );
-};
-
-const AssistantMessage: FC = () => {
-  return (
-    <MessagePrimitive.Root>
-      <MessagePrimitive.Parts>
-        {({ part }) => {
-          if (part.type === "text") return <MarkdownText />;
-          return null;
-        }}
-      </MessagePrimitive.Parts>
-    </MessagePrimitive.Root>
-  );
-};
-```
-
-  </Step>
-  <Step>
-
-### Use a reasoning model
-
-Chain of Thought is most useful with models that produce reasoning tokens (e.g. OpenAI `o4-mini`). Here's an example backend route using the Vercel AI SDK:
-
-```tsx title="app/api/chat/route.ts"
-import { openai } from "@ai-sdk/openai";
-import { streamText, convertToModelMessages } from "ai";
-
-export async function POST(req: Request) {
-  const { messages } = await req.json();
-
-  const result = streamText({
-    model: openai("o4-mini"),
-    messages: await convertToModelMessages(messages),
-  });
-
-  return result.toUIMessageStreamResponse();
-}
-```
-
-  </Step>
-</Steps>
-
-## API Reference
-
-### ChainOfThoughtPrimitive.Root
-
-Container element for the chain of thought group. Renders a `<div>`.
-
-### ChainOfThoughtPrimitive.AccordionTrigger
-
-A button that toggles the collapsed/expanded state. Collapsed by default.
-
-### ChainOfThoughtPrimitive.Parts
-
-Renders the grouped parts when expanded (nothing when collapsed).
-
-```tsx
-<AuiIf condition={(s) => !s.chainOfThought.collapsed}>
-  <ChainOfThoughtPrimitive.Parts>
-    {({ part }) => {
-      if (part.type === "reasoning") return <Reasoning {...part} />;
-      if (part.type === "tool-call") return <ToolFallback {...part} />;
-      return null;
-    }}
-  </ChainOfThoughtPrimitive.Parts>
-</AuiIf>
-```
-
-| Prop | Type | Description |
-| --- | --- | --- |
-| `components.Reasoning` | `FC<{ text: string }>` | Component to render reasoning parts |
-| `components.tools.Fallback` | `ToolCallMessagePartComponent` | Fallback component for tool-call parts |
-| `components.Layout` | `ComponentType<PropsWithChildren>` | Wrapper component around each rendered part when expanded |
-
-## Reading Collapsed State
-
-Use `AuiIf` to conditionally render based on the accordion state:
-
-```tsx
-import { AuiIf, ChainOfThoughtPrimitive } from "@assistant-ui/react";
-import { ChevronDownIcon, ChevronRightIcon } from "lucide-react";
-
-const ChainOfThoughtAccordionTrigger = () => {
-  return (
-    <ChainOfThoughtPrimitive.AccordionTrigger className="flex w-full cursor-pointer items-center gap-2 px-4 py-2 text-sm">
-      <AuiIf condition={(s) => s.chainOfThought.collapsed}>
-        <ChevronRightIcon className="size-4" />
-      </AuiIf>
-      <AuiIf condition={(s) => !s.chainOfThought.collapsed}>
-        <ChevronDownIcon className="size-4" />
-      </AuiIf>
-      Thinking
-    </ChainOfThoughtPrimitive.AccordionTrigger>
-  );
-};
-```
-
-## Full Example
-
-See the complete [with-chain-of-thought example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-chain-of-thought) for a working implementation with tool calls and reasoning.
-
-## Related Guides
-
-- [Generative UI](/docs/guides/tool-ui) — Custom UI for tool calls
-- [Tools](/docs/guides/tools) — Defining and using tools

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

@@ -1,66 +0,0 @@
----
-title: Message Editing
-description: Allow users to edit their messages with custom editor interfaces.
----
-
-Give the user the ability to edit their message.
-
-## Enabling edit support
-
-You can show an editor interface by using `ComposerPrimitive`.
-
-```tsx {1-2,11,25,31-52}
-import { ComposerPrimitive, useAuiState } from "@assistant-ui/react";
-...
-
-const Thread = () => {
-  return (
-    <ThreadPrimitive.Root>
-      <ThreadPrimitive.Viewport>
-        ...
-        <ThreadPrimitive.Messages>
-          {({ message }) => {
-            // Show our new component during edit mode
-            return <MessageWithEditComposer />;
-          }}
-        </ThreadPrimitive.Messages>
-      </ThreadPrimitive.Viewport>
-      ...
-    </ThreadPrimitive.Root>
-  );
-};
-
-const UserMessage = () => {
-  return (
-    <MessagePrimitive.Root>
-      ...
-      <ActionBarPrimitive.Root>
-        ...
-        <ActionBarPrimitive.Edit /> {/* <-- add a button to enable edit mode */}
-      </ActionBarPrimitive.Root>
-    </MessagePrimitive.Root>
-  );
-};
-
-// define a wrapper component that handles both display and edit mode
-const MessageWithEditComposer = () => {
-  const isEditing = useAuiState((s) => s.composer.isEditing);
-  if (isEditing) return <EditComposer />;
-  return <UserMessage />;
-};
-
-// define the edit composer component
-const EditComposer = () => {
-  return (
-    // you can return a MessagePrimitive including a ComposerPrimitive, or only a ComposerPrimitive
-    <MessagePrimitive.Root>
-      ...
-      <ComposerPrimitive.Root>
-        <ComposerPrimitive.Input />
-        <ComposerPrimitive.Cancel />
-        <ComposerPrimitive.Send />
-      </ComposerPrimitive.Root>
-    </MessagePrimitive.Root>
-  );
-};
-```

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

@@ -1,38 +0,0 @@
----
-title: Text-to-Speech (Speech Synthesis)
-description: Read messages aloud with Web Speech API or custom TTS.
----
-
-import { SpeechSample } from "@/components/docs/samples/speech";
-
-assistant-ui supports text-to-speech via the `SpeechSynthesisAdapter` interface.
-
-<SpeechSample />
-
-## SpeechSynthesisAdapter
-
-Currently, the following speech synthesis adapters are supported:
-
-- `WebSpeechSynthesisAdapter`: Uses the browser's `Web Speech API`
-
-Support for other speech synthesis adapters is planned for the future.
-
-Passing a `SpeechSynthesisAdapter` to the runtime will enable text-to-speech support.
-
-## UI
-
-The default action bar does not include a speech button. You need to add `ActionBarPrimitive.Speak` and `ActionBarPrimitive.StopSpeaking` to your assistant message action bar manually. See the example above for a complete implementation.
-
-## Example
-
-The following example uses the `WebSpeechSynthesisAdapter`.
-
-```tsx
-import { WebSpeechSynthesisAdapter } from "@assistant-ui/react";
-
-const runtime = useChatRuntime({
-  adapters: {
-    speech: new WebSpeechSynthesisAdapter(),
-  },
-});
-```