@assistant-ui/mcp-docs-server 0.2.2 → 0.2.3

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

@@ -4,7 +4,12 @@ description: Sidebar or dropdown component for switching between AI chat convers
 platforms: ["react"]
 ---
 
-import { ThreadListSample } from "@/components/docs/samples/threadlist";
+import { ThreadListSample } from "@/components/pages/docs/samples/threadlist";
+import { PreviewCode } from "@/components/pages/docs/preview-code.server";
+import { ThreadListSidebarSample } from "@/components/pages/docs/samples/thread-list/sidebar-composition";
+import { ThreadListActiveSample } from "@/components/pages/docs/samples/thread-list/active-threads";
+import { ThreadListNewSample } from "@/components/pages/docs/samples/thread-list/new-thread";
+import { ThreadListArchiveSample } from "@/components/pages/docs/samples/thread-list/archive-thread";
 
 <ThreadListSample />
 
@@ -104,6 +109,40 @@ import { ThreadListPrimitive, ThreadListItemPrimitive } from "@assistant-ui/reac
 </ThreadListPrimitive.Root>
 ```
 
+## Examples
+
+### Active Threads
+
+Select a different seeded conversation, or use the search field to filter the threads by title.
+
+<PreviewCode file="components/pages/docs/samples/thread-list/active-threads" name="ActiveThreadList">
+  <ThreadListActiveSample />
+</PreviewCode>
+
+### New Thread
+
+The list starts empty, thus only the New Thread button shows. Click New Thread to make an active thread. The search field shows when a thread exists.
+
+<PreviewCode file="components/pages/docs/samples/thread-list/new-thread" name="EmptyThreadList">
+  <ThreadListNewSample />
+</PreviewCode>
+
+### Sidebar Composition
+
+`ThreadListSidebar` wraps the same `ThreadList` in a complete sidebar shell.
+
+<PreviewCode file="components/pages/docs/samples/thread-list/sidebar-composition" name="ThreadListSidebarDemo" className="p-0">
+  <ThreadListSidebarSample />
+</PreviewCode>
+
+### Archive a Thread
+
+Open the More menu of the active thread, then select Archive. The `onArchive` callback moves the thread to the archived list. Select Restore (`ThreadListItemPrimitive.Unarchive`) to move the thread back to the regular list.
+
+<PreviewCode file="components/pages/docs/samples/thread-list/archive-thread" name="ArchivableThreadList">
+  <ThreadListArchiveSample />
+</PreviewCode>
+
 ## API Reference
 
 ### ThreadListPrimitive.Root

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

@@ -4,7 +4,13 @@ description: Stream-ready React chat container with message list, composer, auto
 platforms: ["react"]
 ---
 
-import { ThreadSample } from "@/components/docs/samples/thread";
+import { ThreadSample } from "@/components/pages/docs/samples/thread";
+import { ThreadHistorySample } from "@/components/pages/docs/samples/thread/thread-history";
+import { ThreadActionsSample } from "@/components/pages/docs/samples/thread/message-actions";
+import { PreviewCode } from "@/components/pages/docs/preview-code.server";
+import { ThreadWelcomeSuggestionsSample } from "@/components/pages/docs/samples/thread/welcome-with-suggestions";
+import { ThreadBranchSample } from "@/components/pages/docs/samples/thread/branching-response";
+import { ThreadRunningSample } from "@/components/pages/docs/samples/thread/running-response";
 
 A complete chat interface that combines message rendering, auto-scrolling, composer input,
 attachments, and conditional UI states. Fully customizable and composable.
@@ -90,6 +96,13 @@ export default function Chat() {
 </AuiIf>
 ```
 
+### Thread with History
+
+The thread shows a completed multi-turn conversation. The composer stays below the
+messages, ready for the next input.
+
+<ThreadHistorySample />
+
 ### Conditional Send/Cancel Button
 
 ```tsx
@@ -106,10 +119,23 @@ export default function Chat() {
 </AuiIf>
 ```
 
+While the last assistant response runs, the composer shows the cancel action, not the send action, and the action bar of the response stays hidden. Click the stop button to cancel the run. The composer then shows the send action again.
+
+<ThreadRunningSample />
+
 ### Suggestions
 
 Display suggested prompts using the Suggestions API. See the [Suggestions guide](/docs/guides/suggestions) for detailed configuration.
 
+An empty thread centers the welcome screen and shows the configured suggestion chips. When you select a chip, the thread sends its prompt.
+
+<PreviewCode
+  file="components/pages/docs/samples/thread/welcome-with-suggestions"
+  name="ChatWithSuggestions"
+>
+  <ThreadWelcomeSuggestionsSample />
+</PreviewCode>
+
 ```tsx
 import type { ReactNode } from "react";
 import {
@@ -119,7 +145,7 @@ import {
   Suggestions,
   ThreadPrimitive,
 } from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { useChatRuntime } from "@assistant-ui/ai-sdk";
 
 // Configure suggestions in your runtime provider
 const config = AuiConfig({
@@ -152,6 +178,27 @@ const SuggestionItem = () => (
 );
 ```
 
+### Branching Response
+
+Select the refresh action below the assistant response to make an alternate branch. The built-in branch picker then shows `2 / 2` with arrows that switch between the two branches.
+
+<PreviewCode
+  file="components/pages/docs/samples/thread/branching-response"
+  name="Chat"
+>
+  <ThreadBranchSample />
+</PreviewCode>
+
+### Message Actions
+
+Hover over the first assistant response to show its action bar. When the thread is idle, the last response always shows its actions. The copied `Thread` component sets `hideWhenRunning` and `autohide="not-last"` on `ActionBarPrimitive.Root`. Refer to the [ActionBar primitive](/docs/primitives/action-bar) to change this behavior.
+
+<ThreadActionsSample />
+
+## Composer Focus
+
+Set `autoFocus={false}` to keep the page focus. This setting stops composer focus when the thread mounts, starts a run, changes threads, or scrolls to the bottom. The default value is `true`.
+
 ## 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.

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

@@ -6,11 +6,13 @@ platforms: ["react"]
 
 import {
   ToolFallbackSample,
-  ToolFallbackRunningSample,
+  ToolFallbackCompletedSample,
   ToolFallbackCancelledSample,
   ToolFallbackStreamingSample,
-  ToolFallbackRequiresActionSample,
-} from "@/components/docs/samples/tool-fallback";
+} from "@/components/pages/docs/samples/tool-fallback";
+import { PreviewCode } from "@/components/pages/docs/preview-code.server";
+import { ToolFallbackApprovalSample } from "@/components/pages/docs/samples/tool-fallback/approval";
+import { ToolFallbackErrorSample } from "@/components/pages/docs/samples/tool-fallback/failed-with-error";
 
 <ToolFallbackSample />
 
@@ -60,23 +62,34 @@ Interactive demo showing the full tool call lifecycle: running → complete.
 
 <ToolFallbackStreamingSample />
 
-### Running State
+### Completed With Result
 
-Shows a loading spinner and shimmer animation while the tool is executing.
+Shows the arguments and the structured result for the completed call.
 
-<ToolFallbackRunningSample />
+<ToolFallbackCompletedSample />
+
+### Failed With Error State
+
+Shows a service error above its arguments.
+
+<ToolFallbackErrorSample />
 
 ### Cancelled State
 
-Shows a muted appearance when a tool call was cancelled.
+The "Cancelled tool" label has a line through it. The arguments are muted after you open the call.
 
 <ToolFallbackCancelledSample />
 
 ### Approval State
 
-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.
+Select Allow or Deny. The `resume` callback records the choice, removes the buttons, and shows the result. The block opens automatically for `requires-action`, so you can select a decision without an extra click. A tool call whose approval gate is decided shows no buttons. Edit your project's copy of `tool-fallback.tsx` to add trust escalation, edit-args, custom labels, or analytics hooks.
 
-<ToolFallbackRequiresActionSample />
+<PreviewCode
+  file="components/pages/docs/samples/tool-fallback/approval"
+  name="ToolWithApproval"
+>
+  <ToolFallbackApprovalSample />
+</PreviewCode>
 
 ## Composable API
 
@@ -116,6 +129,7 @@ import {
       interrupt={interrupt}
       approval={approval}
       respondToApproval={respondToApproval}
+      status={status}
     />
     <ToolFallback.Result result={result} />
   </ToolFallback.Content>

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

@@ -7,7 +7,7 @@ platforms: ["react"]
 import {
   ToolGroupSample,
   ToolGroupStreamingSample,
-} from "@/components/docs/samples/tool-group";
+} from "@/components/pages/docs/samples/tool-group";
 
 A wrapper component that groups consecutive tool calls together, displaying them in a collapsible container with auto-expand behavior during streaming.
 

package/.docs/raw/docs/ui/voice.mdx

@@ -4,7 +4,7 @@ description: Realtime voice session controls with connect, mute, and status indi
 platforms: ["react"]
 ---
 
-import { VoiceSample, VoiceVariantsSample, VoiceStatesSample } from "@/components/docs/samples/voice";
+import { VoiceSample, VoiceVariantsSample, VoiceStatesSample } from "@/components/pages/docs/samples/voice";
 
 A control bar for realtime bidirectional voice sessions with an animated orb indicator. Works with any `RealtimeVoiceAdapter` (LiveKit, ElevenLabs, etc.).
 

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

@@ -4,12 +4,12 @@ description: Headless primitives for visualizing observability spans as collapsi
 platforms: ["react"]
 ---
 
-import { WaterfallSample } from "@/components/docs/samples/o11y/waterfall";
+import { WaterfallSample } from "@/components/pages/docs/samples/o11y/waterfall";
 import {
   StatusSample,
   CollapseSample,
   StreamingSample,
-} from "@/components/docs/samples/o11y/capability-samples";
+} from "@/components/pages/docs/samples/o11y/capability-samples";
 
 <Callout type="warn">
 `@assistant-ui/react-o11y` is experimental. The API may change without notice.

package/dist/xulux/catalog-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-client.d.ts","names":[],"sources":["../../src/xulux/catalog-client.ts"],"mappings":";;cAIa;iBAKG;iBA0CA;;;;;;iBAoBM,mBAAmB,QAAQ"}
+{"version":3,"file":"catalog-client.d.ts","names":[],"sources":["../../src/xulux/catalog-client.ts"],"mappings":";;cASa;iBAsDG;iBAiCA;;;;;;iBAoBM,mBAAmB,QAAQ"}

package/dist/xulux/catalog-client.js

@@ -1,18 +1,63 @@
 import { logger } from "../utils/logger.js";
+import "./types.js";
 import { FALLBACK_CATALOG, FALLBACK_NOTE } from "./fallback-catalog.js";
+import { z } from "zod";
 //#region src/xulux/catalog-client.ts
 const DEFAULT_CATALOG_URL = "https://www.assistant-ui.com/api/xulux/mcp-catalog";
 const CATALOG_TTL_MS = 3e5;
+const catalogUrlSchema = z.url();
+const catalogVersionSchema = z.looseObject({
+	id: z.string(),
+	entryId: z.string(),
+	name: z.string(),
+	description: z.string(),
+	previewUrl: catalogUrlSchema,
+	downloadUrl: catalogUrlSchema
+});
+const catalogTemplateSchema = z.looseObject({
+	id: z.string(),
+	templateId: z.string(),
+	versionId: z.string().nullable(),
+	kind: z.enum(["template", "example"]),
+	name: z.string(),
+	summary: z.string(),
+	assistantPlacement: z.string(),
+	features: z.array(z.string()),
+	customizable: z.array(z.string()),
+	versions: z.array(catalogVersionSchema),
+	previewUrl: catalogUrlSchema.optional(),
+	downloadUrl: catalogUrlSchema.optional(),
+	sandboxBaseUrl: catalogUrlSchema.optional(),
+	configRoots: z.record(z.string(), z.unknown()).optional(),
+	rules: z.looseObject({
+		required: z.array(z.string()),
+		unsupported: z.array(z.string()).optional()
+	}).optional(),
+	tools: z.looseObject({
+		builtIn: z.array(z.unknown()),
+		customToolSupported: z.boolean(),
+		renderers: z.array(z.unknown())
+	}).optional()
+});
+const catalogSchema = z.looseObject({
+	version: z.literal(1),
+	generatedAt: z.string(),
+	docsOrigin: z.string(),
+	templates: z.array(catalogTemplateSchema)
+});
 function getCatalogUrl() {
 	return process.env.XULUX_CATALOG_URL?.trim() || "https://www.assistant-ui.com/api/xulux/mcp-catalog";
 }
 function validateCatalog(data) {
-	if (!data || typeof data !== "object" || Array.isArray(data)) throw new Error("Catalog response is not a JSON object.");
-	const catalog = data;
-	if (catalog.version !== 1) throw new Error(`Unsupported catalog version: ${String(catalog.version)}. Expected 1.`);
-	if (!Array.isArray(catalog.templates)) throw new Error("Catalog response has no templates array.");
-	for (const template of catalog.templates) if (!template || typeof template !== "object" || typeof template.id !== "string" || typeof template.templateId !== "string" || template.kind !== "template" && template.kind !== "example") throw new Error("Catalog response contains a malformed template entry (missing id/templateId/kind).");
-	return catalog;
+	const version = data?.version;
+	if (version !== void 0 && version !== 1) throw new Error(`Unsupported catalog version: ${String(version)}. Expected 1.`);
+	const result = catalogSchema.safeParse(data);
+	if (!result.success) {
+		const issue = result.error.issues[0];
+		const path = issue?.path.length ? ` at ${issue.path.join(".")}` : "";
+		throw new Error(`Catalog response is malformed${path}: ${issue?.message ?? "invalid catalog"}.`);
+	}
+	return result.data;
 }
 let cache = null;
 function clearCatalogCache() {

package/dist/xulux/catalog-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-client.js","names":[],"sources":["../../src/xulux/catalog-client.ts"],"sourcesContent":["import { logger } from \"../utils/logger.js\";\nimport { FALLBACK_CATALOG, FALLBACK_NOTE } from \"./fallback-catalog.js\";\nimport type { XuluxCatalog, XuluxCatalogResult } from \"./types.js\";\n\nexport const DEFAULT_CATALOG_URL =\n  \"https://www.assistant-ui.com/api/xulux/mcp-catalog\";\n\nconst CATALOG_TTL_MS = 5 * 60 * 1000;\n\nexport function getCatalogUrl(): string {\n  const override = process.env.XULUX_CATALOG_URL?.trim();\n  return override || DEFAULT_CATALOG_URL;\n}\n\nfunction validateCatalog(data: unknown): XuluxCatalog {\n  if (!data || typeof data !== \"object\" || Array.isArray(data)) {\n    throw new Error(\"Catalog response is not a JSON object.\");\n  }\n  const catalog = data as XuluxCatalog;\n  if (catalog.version !== 1) {\n    throw new Error(\n      `Unsupported catalog version: ${String(catalog.version)}. Expected 1.`,\n    );\n  }\n  if (!Array.isArray(catalog.templates)) {\n    throw new Error(\"Catalog response has no templates array.\");\n  }\n  for (const template of catalog.templates) {\n    if (\n      !template ||\n      typeof template !== \"object\" ||\n      typeof template.id !== \"string\" ||\n      typeof template.templateId !== \"string\" ||\n      (template.kind !== \"template\" && template.kind !== \"example\")\n    ) {\n      throw new Error(\n        \"Catalog response contains a malformed template entry (missing id/templateId/kind).\",\n      );\n    }\n  }\n  return catalog;\n}\n\ninterface CacheEntry {\n  catalog: XuluxCatalog;\n  fetchedAt: number;\n  url: string;\n}\n\nlet cache: CacheEntry | null = null;\n\nexport function clearCatalogCache(): void {\n  cache = null;\n}\n\nasync function fetchCatalog(url: string): Promise<XuluxCatalog> {\n  const res = await fetch(url, {\n    headers: { Accept: \"application/json\" },\n  });\n  if (!res.ok) {\n    throw new Error(`Catalog fetch failed: HTTP ${res.status}`);\n  }\n  const data: unknown = await res.json();\n  return validateCatalog(data);\n}\n\n/**\n * Returns the assistant-ui template catalog. Uses an in-memory five-minute cache, and falls\n * back to a minimal bundled catalog (marked degraded) when the live fetch\n * fails and no cached copy exists.\n */\nexport async function getXuluxCatalog(): Promise<XuluxCatalogResult> {\n  const url = getCatalogUrl();\n  const now = Date.now();\n\n  if (cache && cache.url === url && now - cache.fetchedAt < CATALOG_TTL_MS) {\n    return { catalog: cache.catalog, degraded: false };\n  }\n\n  try {\n    const catalog = await fetchCatalog(url);\n    cache = { catalog, fetchedAt: now, url };\n    return { catalog, degraded: false };\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    logger.warn(\n      `assistant-ui template catalog fetch failed (${url}): ${message}`,\n    );\n\n    // Prefer a stale cached copy over the minimal fallback.\n    if (cache && cache.url === url) {\n      return {\n        catalog: cache.catalog,\n        degraded: true,\n        degradedReason: `Live catalog refresh failed (${message}); using previously fetched catalog.`,\n      };\n    }\n\n    return {\n      catalog: FALLBACK_CATALOG,\n      degraded: true,\n      degradedReason: `${message} ${FALLBACK_NOTE}`,\n    };\n  }\n}\n"],"mappings":";;;AAIA,MAAa,sBACX;AAEF,MAAM,iBAAiB;AAEvB,SAAgB,gBAAwB;CAEtC,OADiB,QAAQ,IAAI,mBAAmB,KAAK,KAAA;AAEvD;AAEA,SAAS,gBAAgB,MAA6B;CACpD,IAAI,CAAC,QAAQ,OAAO,SAAS,YAAY,MAAM,QAAQ,IAAI,GACzD,MAAM,IAAI,MAAM,wCAAwC;CAE1D,MAAM,UAAU;CAChB,IAAI,QAAQ,YAAY,GACtB,MAAM,IAAI,MACR,gCAAgC,OAAO,QAAQ,OAAO,EAAE,cAC1D;CAEF,IAAI,CAAC,MAAM,QAAQ,QAAQ,SAAS,GAClC,MAAM,IAAI,MAAM,0CAA0C;CAE5D,KAAK,MAAM,YAAY,QAAQ,WAC7B,IACE,CAAC,YACD,OAAO,aAAa,YACpB,OAAO,SAAS,OAAO,YACvB,OAAO,SAAS,eAAe,YAC9B,SAAS,SAAS,cAAc,SAAS,SAAS,WAEnD,MAAM,IAAI,MACR,oFACF;CAGJ,OAAO;AACT;AAQA,IAAI,QAA2B;AAE/B,SAAgB,oBAA0B;CACxC,QAAQ;AACV;AAEA,eAAe,aAAa,KAAoC;CAC9D,MAAM,MAAM,MAAM,MAAM,KAAK,EAC3B,SAAS,EAAE,QAAQ,mBAAmB,EACxC,CAAC;CACD,IAAI,CAAC,IAAI,IACP,MAAM,IAAI,MAAM,8BAA8B,IAAI,QAAQ;CAG5D,OAAO,gBAAgB,MADK,IAAI,KAAK,CACV;AAC7B;;;;;;AAOA,eAAsB,kBAA+C;CACnE,MAAM,MAAM,cAAc;CAC1B,MAAM,MAAM,KAAK,IAAI;CAErB,IAAI,SAAS,MAAM,QAAQ,OAAO,MAAM,MAAM,YAAY,gBACxD,OAAO;EAAE,SAAS,MAAM;EAAS,UAAU;CAAM;CAGnD,IAAI;EACF,MAAM,UAAU,MAAM,aAAa,GAAG;EACtC,QAAQ;GAAE;GAAS,WAAW;GAAK;EAAI;EACvC,OAAO;GAAE;GAAS,UAAU;EAAM;CACpC,SAAS,OAAO;EACd,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;EACrE,OAAO,KACL,+CAA+C,IAAI,KAAK,SAC1D;EAGA,IAAI,SAAS,MAAM,QAAQ,KACzB,OAAO;GACL,SAAS,MAAM;GACf,UAAU;GACV,gBAAgB,gCAAgC,QAAQ;EAC1D;EAGF,OAAO;GACL,SAAS;GACT,UAAU;GACV,gBAAgB,GAAG,QAAQ,GAAG;EAChC;CACF;AACF"}
+{"version":3,"file":"catalog-client.js","names":[],"sources":["../../src/xulux/catalog-client.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { logger } from \"../utils/logger.js\";\nimport { FALLBACK_CATALOG, FALLBACK_NOTE } from \"./fallback-catalog.js\";\nimport {\n  XULUX_MCP_CATALOG_VERSION,\n  type XuluxCatalog,\n  type XuluxCatalogResult,\n} from \"./types.js\";\n\nexport const DEFAULT_CATALOG_URL =\n  \"https://www.assistant-ui.com/api/xulux/mcp-catalog\";\n\nconst CATALOG_TTL_MS = 5 * 60 * 1000;\nconst catalogUrlSchema = z.url();\n\nconst catalogVersionSchema = z.looseObject({\n  id: z.string(),\n  entryId: z.string(),\n  name: z.string(),\n  description: z.string(),\n  previewUrl: catalogUrlSchema,\n  downloadUrl: catalogUrlSchema,\n});\n\nconst catalogTemplateSchema = z.looseObject({\n  id: z.string(),\n  templateId: z.string(),\n  versionId: z.string().nullable(),\n  kind: z.enum([\"template\", \"example\"]),\n  name: z.string(),\n  summary: z.string(),\n  assistantPlacement: z.string(),\n  features: z.array(z.string()),\n  customizable: z.array(z.string()),\n  versions: z.array(catalogVersionSchema),\n  previewUrl: catalogUrlSchema.optional(),\n  downloadUrl: catalogUrlSchema.optional(),\n  sandboxBaseUrl: catalogUrlSchema.optional(),\n  configRoots: z.record(z.string(), z.unknown()).optional(),\n  rules: z\n    .looseObject({\n      required: z.array(z.string()),\n      unsupported: z.array(z.string()).optional(),\n    })\n    .optional(),\n  tools: z\n    .looseObject({\n      builtIn: z.array(z.unknown()),\n      customToolSupported: z.boolean(),\n      renderers: z.array(z.unknown()),\n    })\n    .optional(),\n});\n\nconst catalogSchema = z.looseObject({\n  version: z.literal(XULUX_MCP_CATALOG_VERSION),\n  // Not read anywhere in the package; validated for shape only, so an unused\n  // field cannot veto the whole catalog.\n  generatedAt: z.string(),\n  docsOrigin: z.string(),\n  templates: z.array(catalogTemplateSchema),\n});\n\nexport function getCatalogUrl(): string {\n  const override = process.env.XULUX_CATALOG_URL?.trim();\n  return override || DEFAULT_CATALOG_URL;\n}\n\nfunction validateCatalog(data: unknown): XuluxCatalog {\n  // Checked ahead of the schema so a catalog rollout reports its version\n  // rather than reading as a malformed payload.\n  const version = (data as { version?: unknown } | null)?.version;\n  if (version !== undefined && version !== XULUX_MCP_CATALOG_VERSION) {\n    throw new Error(\n      `Unsupported catalog version: ${String(version)}. Expected ${XULUX_MCP_CATALOG_VERSION}.`,\n    );\n  }\n  const result = catalogSchema.safeParse(data);\n  if (!result.success) {\n    const issue = result.error.issues[0];\n    const path = issue?.path.length ? ` at ${issue.path.join(\".\")}` : \"\";\n    throw new Error(\n      `Catalog response is malformed${path}: ${issue?.message ?? \"invalid catalog\"}.`,\n    );\n  }\n  return result.data;\n}\n\ninterface CacheEntry {\n  catalog: XuluxCatalog;\n  fetchedAt: number;\n  url: string;\n}\n\nlet cache: CacheEntry | null = null;\n\nexport function clearCatalogCache(): void {\n  cache = null;\n}\n\nasync function fetchCatalog(url: string): Promise<XuluxCatalog> {\n  const res = await fetch(url, {\n    headers: { Accept: \"application/json\" },\n  });\n  if (!res.ok) {\n    throw new Error(`Catalog fetch failed: HTTP ${res.status}`);\n  }\n  const data: unknown = await res.json();\n  return validateCatalog(data);\n}\n\n/**\n * Returns the assistant-ui template catalog. Uses an in-memory five-minute cache, and falls\n * back to a minimal bundled catalog (marked degraded) when the live fetch\n * fails and no cached copy exists.\n */\nexport async function getXuluxCatalog(): Promise<XuluxCatalogResult> {\n  const url = getCatalogUrl();\n  const now = Date.now();\n\n  if (cache && cache.url === url && now - cache.fetchedAt < CATALOG_TTL_MS) {\n    return { catalog: cache.catalog, degraded: false };\n  }\n\n  try {\n    const catalog = await fetchCatalog(url);\n    cache = { catalog, fetchedAt: now, url };\n    return { catalog, degraded: false };\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    logger.warn(\n      `assistant-ui template catalog fetch failed (${url}): ${message}`,\n    );\n\n    // Prefer a stale cached copy over the minimal fallback.\n    if (cache && cache.url === url) {\n      return {\n        catalog: cache.catalog,\n        degraded: true,\n        degradedReason: `Live catalog refresh failed (${message}); using previously fetched catalog.`,\n      };\n    }\n\n    return {\n      catalog: FALLBACK_CATALOG,\n      degraded: true,\n      degradedReason: `${message} ${FALLBACK_NOTE}`,\n    };\n  }\n}\n"],"mappings":"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"}

package/dist/xulux/types.d.ts

@@ -19,19 +19,19 @@ interface XuluxCatalogTemplate {
   features: string[];
   customizable: string[];
   versions: XuluxCatalogVersion[];
-  previewUrl?: string;
-  downloadUrl?: string;
-  sandboxBaseUrl?: string;
-  configRoots?: Record<string, unknown>;
+  previewUrl?: string | undefined;
+  downloadUrl?: string | undefined;
+  sandboxBaseUrl?: string | undefined;
+  configRoots?: Record<string, unknown> | undefined;
   rules?: {
     required: string[];
-    unsupported?: string[];
-  };
+    unsupported?: string[] | undefined;
+  } | undefined;
   tools?: {
     builtIn: unknown[];
     customToolSupported: boolean;
     renderers: unknown[];
-  };
+  } | undefined;
 }
 interface XuluxCatalog {
   version: number;

package/dist/xulux/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/xulux/types.ts"],"mappings":";cAIa;UAEI;EACf;EACA;EACA;EACA;EACA;EACA;;UAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,UAAU;EACV;EACA;EACA;EACA,cAAc;EACd;IACE;IACA;;EAEF;IACE;IACA;IACA;;;UAIa;EACf;EACA;EACA;EACA,WAAW;;UAGI;EACf,SAAS;;EAET;;EAEA;;UAGe;EACf;EACA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/xulux/types.ts"],"mappings":";cAIa;UAEI;EACf;EACA;EACA;EACA;EACA;EACA;;UAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,UAAU;EACV;EACA;EACA;EACA,cAAc;EACd;IAEM;IACA;;EAGN;IAEM;IACA;IACA;;;UAKS;EACf;EACA;EACA;EACA,WAAW;;UAGI;EACf,SAAS;;EAET;;EAEA;;UAGe;EACf;EACA"}

package/dist/xulux/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../src/xulux/types.ts"],"sourcesContent":["// MCP-safe assistant-ui template catalog types. These mirror the payload served by the docs\n// app at GET /api/xulux/mcp-catalog. The MCP package never imports docs-app\n// internals; the endpoint payload is the contract.\n\nexport const XULUX_MCP_CATALOG_VERSION = 1;\n\nexport interface XuluxCatalogVersion {\n  id: string;\n  entryId: string;\n  name: string;\n  description: string;\n  previewUrl: string;\n  downloadUrl: string;\n}\n\nexport interface XuluxCatalogTemplate {\n  id: string;\n  templateId: string;\n  versionId: string | null;\n  kind: \"template\" | \"example\";\n  name: string;\n  summary: string;\n  assistantPlacement: string;\n  features: string[];\n  customizable: string[];\n  versions: XuluxCatalogVersion[];\n  previewUrl?: string;\n  downloadUrl?: string;\n  sandboxBaseUrl?: string;\n  configRoots?: Record<string, unknown>;\n  rules?: {\n    required: string[];\n    unsupported?: string[];\n  };\n  tools?: {\n    builtIn: unknown[];\n    customToolSupported: boolean;\n    renderers: unknown[];\n  };\n}\n\nexport interface XuluxCatalog {\n  version: number;\n  generatedAt: string;\n  docsOrigin: string;\n  templates: XuluxCatalogTemplate[];\n}\n\nexport interface XuluxCatalogResult {\n  catalog: XuluxCatalog;\n  /** True when the bundled fallback catalog was used instead of live data. */\n  degraded: boolean;\n  /** Present when the live fetch failed and the fallback was used. */\n  degradedReason?: string;\n}\n\nexport interface XuluxCatalogError {\n  error: string;\n  hint?: string;\n}\n"],"mappings":";AAIA,MAAa,4BAA4B"}
+{"version":3,"file":"types.js","names":[],"sources":["../../src/xulux/types.ts"],"sourcesContent":["// MCP-safe assistant-ui template catalog types. These mirror the payload served by the docs\n// app at GET /api/xulux/mcp-catalog. The MCP package never imports docs-app\n// internals; the endpoint payload is the contract.\n\nexport const XULUX_MCP_CATALOG_VERSION = 1;\n\nexport interface XuluxCatalogVersion {\n  id: string;\n  entryId: string;\n  name: string;\n  description: string;\n  previewUrl: string;\n  downloadUrl: string;\n}\n\nexport interface XuluxCatalogTemplate {\n  id: string;\n  templateId: string;\n  versionId: string | null;\n  kind: \"template\" | \"example\";\n  name: string;\n  summary: string;\n  assistantPlacement: string;\n  features: string[];\n  customizable: string[];\n  versions: XuluxCatalogVersion[];\n  previewUrl?: string | undefined;\n  downloadUrl?: string | undefined;\n  sandboxBaseUrl?: string | undefined;\n  configRoots?: Record<string, unknown> | undefined;\n  rules?:\n    | {\n        required: string[];\n        unsupported?: string[] | undefined;\n      }\n    | undefined;\n  tools?:\n    | {\n        builtIn: unknown[];\n        customToolSupported: boolean;\n        renderers: unknown[];\n      }\n    | undefined;\n}\n\nexport interface XuluxCatalog {\n  version: number;\n  generatedAt: string;\n  docsOrigin: string;\n  templates: XuluxCatalogTemplate[];\n}\n\nexport interface XuluxCatalogResult {\n  catalog: XuluxCatalog;\n  /** True when the bundled fallback catalog was used instead of live data. */\n  degraded: boolean;\n  /** Present when the live fetch failed and the fallback was used. */\n  degradedReason?: string;\n}\n\nexport interface XuluxCatalogError {\n  error: string;\n  hint?: string;\n}\n"],"mappings":";AAIA,MAAa,4BAA4B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/mcp-docs-server",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "MCP server for assistant-ui documentation and examples",
   "keywords": [
     "mcp",
@@ -37,11 +37,11 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@assistant-ui/x-buildutils": "0.0.24",
     "@modelcontextprotocol/core": "^2.0.0",
     "@types/node": "^26.2.0",
     "tsx": "^4.23.12",
-    "vitest": "^4.1.10",
-    "@assistant-ui/x-buildutils": "0.0.23"
+    "vitest": "^4.1.11"
   },
   "publishConfig": {
     "access": "public",

package/src/tools/tests/docs.test.ts

@@ -28,17 +28,17 @@ describe("assistantUIDocs", () => {
     expect(result.path).toBe("/");
     expect(result.found).toBe(true);
     expect(result.type).toBe("directory");
-    expect(result.directories).toContain("(docs)");
+    expect(result.directories).toContain("(getting-started)");
     expect(result.directories).toContain("(reference)");
     expect(result.directories).toContain("ui");
   });
 
   it("should retrieve specific documentation file", async () => {
     const result = await testContext.callTool("assistantUIDocs", {
-      paths: ["(docs)/index"],
+      paths: ["(getting-started)/index"],
     });
 
-    expect(result.path).toBe("(docs)/index");
+    expect(result.path).toBe("(getting-started)/index");
     expect(result.found).toBe(true);
     expect(result.type).toBe("file");
     expect(result.content).toBeDefined();
@@ -57,12 +57,15 @@ describe("assistantUIDocs", () => {
 
   it("should support multiple path requests", async () => {
     const result = await testContext.callTool("assistantUIDocs", {
-      paths: ["(docs)/index", "(reference)/api-reference/primitives/thread"],
+      paths: [
+        "(getting-started)/index",
+        "(reference)/api-reference/primitives/thread",
+      ],
     });
 
     expect(result.results).toBeDefined();
     expect(result.results).toHaveLength(2);
-    expect(result.results[0].path).toBe("(docs)/index");
+    expect(result.results[0].path).toBe("(getting-started)/index");
     expect(result.results[1].path).toBe(
       "(reference)/api-reference/primitives/thread",
     );
@@ -83,7 +86,7 @@ describe("assistantUIDocs", () => {
 
   it("should parse MDX files with frontmatter", async () => {
     const result = await testContext.callTool("assistantUIDocs", {
-      paths: ["(docs)/index"],
+      paths: ["(getting-started)/index"],
     });
 
     expect(result.content).toBeDefined();
@@ -93,7 +96,7 @@ describe("assistantUIDocs", () => {
 
   it("includes title and excerpt on a file response", async () => {
     const result = await testContext.callTool("assistantUIDocs", {
-      paths: ["(docs)/index"],
+      paths: ["(getting-started)/index"],
     });
     expect(result.type).toBe("file");
     expect(result.title ?? result.excerpt).toBeDefined();

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", "guides"],
+        paths: ["(getting-started)/index", "../../../../etc/passwd", "guides"],
       });
 
       expect(result.results).toBeDefined();
@@ -63,7 +63,10 @@ describe("Path Traversal Security", () => {
   describe("Valid paths should still work", () => {
     it("should allow valid documentation paths", async () => {
       const result = await testContext.callTool("assistantUIDocs", {
-        paths: ["(docs)/index", "(reference)/api-reference/primitives/thread"],
+        paths: [
+          "(getting-started)/index",
+          "(reference)/api-reference/primitives/thread",
+        ],
       });
 
       expect(result.results).toBeDefined();

package/src/tools/tests/xulux-templates.test.ts

@@ -134,6 +134,69 @@ describe("assistant-ui template MCP tools", () => {
     );
   });
 
+  it("uses the fallback catalog when a live template entry is malformed", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () =>
+        jsonResponse({
+          ...LIVE_CATALOG,
+          templates: [
+            {
+              id: "broken",
+              templateId: "broken",
+              kind: "template",
+            },
+          ],
+        }),
+      ),
+    );
+
+    const result = await callTool(xuluxTemplatesListTool, {});
+    expect(result.catalogDegraded).toBe(true);
+    expect(result.catalogDegradedReason).toContain(
+      "Catalog response is malformed",
+    );
+    expect(result.templates.map((t: { id: string }) => t.id)).toContain(
+      "base-assistant-ui",
+    );
+  });
+
+  it("names the version when the live catalog is a newer revision", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => jsonResponse({ ...LIVE_CATALOG, version: 2 })),
+    );
+
+    const result = await callTool(xuluxTemplatesListTool, {});
+    expect(result.catalogDegraded).toBe(true);
+    expect(result.catalogDegradedReason).toContain(
+      "Unsupported catalog version: 2. Expected 1.",
+    );
+  });
+
+  it("uses the fallback catalog when a live template URL is malformed", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () =>
+        jsonResponse({
+          ...LIVE_CATALOG,
+          templates: [
+            {
+              ...LIVE_CATALOG.templates[0],
+              sandboxBaseUrl: "not a URL",
+            },
+          ],
+        }),
+      ),
+    );
+
+    const result = await callTool(xuluxTemplatesListTool, {});
+    expect(result.catalogDegraded).toBe(true);
+    expect(result.catalogDegradedReason).toContain(
+      "Catalog response is malformed",
+    );
+  });
+
   it("returns details and fetches exampleConfig from the selected sandbox contract", async () => {
     const fetchMock = vi.fn(async (url: string | URL) => {
       const href = String(url);