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

package/src/xulux/catalog-client.ts

@@ -1,11 +1,65 @@
+import { z } from "zod";
 import { logger } from "../utils/logger.js";
 import { FALLBACK_CATALOG, FALLBACK_NOTE } from "./fallback-catalog.js";
-import type { XuluxCatalog, XuluxCatalogResult } from "./types.js";
+import {
+  XULUX_MCP_CATALOG_VERSION,
+  type XuluxCatalog,
+  type XuluxCatalogResult,
+} from "./types.js";
 
 export const DEFAULT_CATALOG_URL =
   "https://www.assistant-ui.com/api/xulux/mcp-catalog";
 
 const CATALOG_TTL_MS = 5 * 60 * 1000;
+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(XULUX_MCP_CATALOG_VERSION),
+  // Not read anywhere in the package; validated for shape only, so an unused
+  // field cannot veto the whole catalog.
+  generatedAt: z.string(),
+  docsOrigin: z.string(),
+  templates: z.array(catalogTemplateSchema),
+});
 
 export function getCatalogUrl(): string {
   const override = process.env.XULUX_CATALOG_URL?.trim();
@@ -13,32 +67,23 @@ export function getCatalogUrl(): string {
 }
 
 function validateCatalog(data: unknown): XuluxCatalog {
-  if (!data || typeof data !== "object" || Array.isArray(data)) {
-    throw new Error("Catalog response is not a JSON object.");
-  }
-  const catalog = data as XuluxCatalog;
-  if (catalog.version !== 1) {
+  // Checked ahead of the schema so a catalog rollout reports its version
+  // rather than reading as a malformed payload.
+  const version = (data as { version?: unknown } | null)?.version;
+  if (version !== undefined && version !== XULUX_MCP_CATALOG_VERSION) {
     throw new Error(
-      `Unsupported catalog version: ${String(catalog.version)}. Expected 1.`,
+      `Unsupported catalog version: ${String(version)}. Expected ${XULUX_MCP_CATALOG_VERSION}.`,
     );
   }
-  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).",
-      );
-    }
+  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 catalog;
+  return result.data;
 }
 
 interface CacheEntry {

package/src/xulux/types.ts

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

package/.docs/raw/docs/ui/accordion.mdx

@@ -1,266 +0,0 @@
----
-title: Accordion
-description: A vertically stacked set of interactive headings that reveal or hide content sections.
-links:
-  - label: Radix UI Accordion (Radix styles)
-    url: https://www.radix-ui.com/primitives/docs/components/accordion
-  - label: Base UI Accordion (base styles)
-    url: https://base-ui.com/react/components/accordion
-platforms: ["react"]
----
-
-import { PreviewCode } from "@/components/docs/preview-code.server";
-import {
-  AccordionSample,
-  AccordionVariantsSample,
-  AccordionMultipleSample,
-  AccordionWithIconsSample,
-  AccordionControlledSample,
-  AccordionFAQSample,
-} from "@/components/docs/samples/accordion";
-import * as AccordionRadixSamples from "@/components/docs/samples/accordion.radix";
-import { Flavored, FlavorSwitcher } from "@/components/docs/contexts/flavor.server";
-
-<Callout>
-  This is a **standalone component** that does not depend on the assistant-ui runtime. Use it anywhere in your application.
-</Callout>
-
-<FlavorSwitcher />
-
-<Flavored radix={<AccordionRadixSamples.AccordionSample />} base={<AccordionSample />} />
-
-## Installation
-
-<InstallCommand shadcn={["accordion"]} />
-
-## Usage
-
-```tsx
-import {
-  Accordion,
-  AccordionItem,
-  AccordionTrigger,
-  AccordionContent,
-} from "@/components/assistant-ui/accordion";
-
-export function Example() {
-  return (
-    <Accordion type="single" collapsible>
-      <AccordionItem value="item-1">
-        <AccordionTrigger>Section 1</AccordionTrigger>
-        <AccordionContent>Content for section 1.</AccordionContent>
-      </AccordionItem>
-      <AccordionItem value="item-2">
-        <AccordionTrigger>Section 2</AccordionTrigger>
-        <AccordionContent>Content for section 2.</AccordionContent>
-      </AccordionItem>
-    </Accordion>
-  );
-}
-```
-
-## Examples
-
-### Variants
-
-Use the `variant` prop on `Accordion` to change the visual style. Child components inherit the variant automatically.
-
-<Flavored radix={<AccordionRadixSamples.AccordionVariantsSample />} base={<AccordionVariantsSample />} />
-
-```tsx
-// Default - border-bottom separator
-<Accordion type="single" collapsible variant="default">
-  <AccordionItem value="item-1">
-    <AccordionTrigger>...</AccordionTrigger>
-    <AccordionContent>...</AccordionContent>
-  </AccordionItem>
-</Accordion>
-
-// Outline - bordered container
-<Accordion type="single" collapsible variant="outline">
-  <AccordionItem value="item-1">
-    <AccordionTrigger>...</AccordionTrigger>
-    <AccordionContent>...</AccordionContent>
-  </AccordionItem>
-</Accordion>
-
-// Ghost - separated cards
-<Accordion type="single" collapsible variant="ghost">
-  <AccordionItem value="item-1">
-    <AccordionTrigger>...</AccordionTrigger>
-    <AccordionContent>...</AccordionContent>
-  </AccordionItem>
-</Accordion>
-```
-
-### Multiple Items Open
-
-Use `type="multiple"` to allow multiple items to be open simultaneously.
-
-<Flavored radix={<AccordionRadixSamples.AccordionMultipleSample />} base={<AccordionMultipleSample />} />
-
-```tsx
-<Accordion type="multiple">
-  <AccordionItem value="item-1">
-    <AccordionTrigger>First Section</AccordionTrigger>
-    <AccordionContent>Content 1</AccordionContent>
-  </AccordionItem>
-  <AccordionItem value="item-2">
-    <AccordionTrigger>Second Section</AccordionTrigger>
-    <AccordionContent>Content 2</AccordionContent>
-  </AccordionItem>
-</Accordion>
-```
-
-### With Icons
-
-Add icons or custom elements inside the trigger.
-
-<PreviewCode file="components/docs/samples/accordion" name="AccordionWithIconsSample" base={<AccordionWithIconsSample />}>
-  <AccordionRadixSamples.AccordionWithIconsSample />
-</PreviewCode>
-
-### Controlled
-
-Use `value` and `onValueChange` for controlled accordion state.
-
-<PreviewCode file="components/docs/samples/accordion" name="AccordionControlledSample" base={<AccordionControlledSample />}>
-  <AccordionRadixSamples.AccordionControlledSample />
-</PreviewCode>
-
-### FAQ Section
-
-A practical example of using accordion for a FAQ section.
-
-<PreviewCode file="components/docs/samples/accordion" name="AccordionFAQSample" base={<AccordionFAQSample />}>
-  <AccordionRadixSamples.AccordionFAQSample />
-</PreviewCode>
-
-## API Reference
-
-### Composable API
-
-| Component | Description |
-|-----------|-------------|
-| `Accordion` | The root component that manages accordion state and variant. |
-| `AccordionItem` | A single collapsible section container. |
-| `AccordionTrigger` | The clickable header that toggles content visibility. |
-| `AccordionContent` | The collapsible content panel. |
-
-### Accordion
-
-The root component that manages accordion state. Set `variant` here to style all child components.
-
-<ParametersTable
-  type="AccordionProps"
-  parameters={[
-    {
-      name: "type",
-      type: '"single" | "multiple"',
-      required: true,
-      description: "Whether only one or multiple items can be open at once.",
-    },
-    {
-      name: "collapsible",
-      type: "boolean",
-      default: "false",
-      description: "When type is 'single', allows closing the open item by clicking it again.",
-    },
-    {
-      name: "defaultValue",
-      type: "string | string[]",
-      description: "The default open item(s) (uncontrolled).",
-    },
-    {
-      name: "value",
-      type: "string | string[]",
-      description: "The controlled open item(s).",
-    },
-    {
-      name: "onValueChange",
-      type: "(value: string | string[]) => void",
-      description: "Callback when the open item(s) change.",
-    },
-    {
-      name: "variant",
-      type: '"default" | "outline" | "ghost"',
-      default: '"default"',
-      description: "The visual style of the accordion. Child components inherit this automatically.",
-    },
-    {
-      name: "className",
-      type: "string",
-      description: "Additional CSS classes.",
-    },
-  ]}
-/>
-
-### AccordionItem
-
-A single collapsible section container.
-
-<ParametersTable
-  type="AccordionItemProps"
-  parameters={[
-    {
-      name: "value",
-      type: "string",
-      required: true,
-      description: "A unique identifier for this item.",
-    },
-    {
-      name: "disabled",
-      type: "boolean",
-      description: "Whether the item is disabled.",
-    },
-    {
-      name: "className",
-      type: "string",
-      description: "Additional CSS classes.",
-    },
-  ]}
-/>
-
-### AccordionTrigger
-
-The clickable header that toggles content visibility.
-
-<ParametersTable
-  type="AccordionTriggerProps"
-  parameters={[
-    {
-      name: "className",
-      type: "string",
-      description: "Additional CSS classes.",
-    },
-  ]}
-/>
-
-### AccordionContent
-
-The collapsible content panel.
-
-<ParametersTable
-  type="AccordionContentProps"
-  parameters={[
-    {
-      name: "className",
-      type: "string",
-      description: "Additional CSS classes.",
-    },
-  ]}
-/>
-
-### Style Variants (CVA)
-
-| Export | Description |
-|--------|-------------|
-| `accordionVariants` | Styles for the accordion container. |
-
-```tsx
-import { accordionVariants } from "@/components/assistant-ui/accordion";
-
-<div className={accordionVariants({ variant: "outline" })}>
-  Custom Accordion Container
-</div>
-```

package/.docs/raw/docs/ui/badge.mdx

@@ -1,150 +0,0 @@
----
-title: Badge
-description: A small label component for displaying status, categories, or metadata.
-links:
-  - label: Radix UI Slot (Radix styles)
-    url: https://www.radix-ui.com/primitives/docs/utilities/slot
-  - label: Base UI useRender (base styles)
-    url: https://base-ui.com/react/utils/use-render
-platforms: ["react"]
----
-
-import { PreviewCode } from "@/components/docs/preview-code.server";
-import {
-  BadgeSample,
-  BadgeSizesSample,
-  BadgeWithIconSample,
-  BadgeAsLinkSample,
-  BadgeAnimatedSample,
-} from "@/components/docs/samples/badge";
-import * as BadgeRadixSamples from "@/components/docs/samples/badge.radix";
-import { Flavored, FlavorSwitcher } from "@/components/docs/contexts/flavor.server";
-
-<Callout>
-  This is a **standalone component** that does not depend on the assistant-ui runtime. Use it anywhere in your application.
-</Callout>
-
-<FlavorSwitcher />
-
-<Flavored radix={<BadgeRadixSamples.BadgeSample />} base={<BadgeSample />} />
-
-## Installation
-
-<InstallCommand shadcn={["badge"]} />
-
-## Usage
-
-```tsx
-import { Badge } from "@/components/assistant-ui/badge";
-
-export function Example() {
-  return <Badge>Label</Badge>;
-}
-```
-
-## Examples
-
-### Variants
-
-Use the `variant` prop to change the visual style.
-
-<Flavored radix={<BadgeRadixSamples.BadgeSample />} base={<BadgeSample />} />
-
-```tsx
-<Badge variant="outline" />     // Border (default)
-<Badge variant="secondary" />   // Secondary background
-<Badge variant="muted" />       // Muted background
-<Badge variant="ghost" />       // No background
-<Badge variant="info" />        // Blue/info style
-<Badge variant="warning" />     // Amber/warning style
-<Badge variant="success" />     // Green/success style
-<Badge variant="destructive" /> // Red/error style
-```
-
-### Sizes
-
-Use the `size` prop to change the badge size.
-
-<Flavored radix={<BadgeRadixSamples.BadgeSizesSample />} base={<BadgeSizesSample />} />
-
-```tsx
-<Badge size="sm" />      // Small
-<Badge size="default" /> // Default
-<Badge size="lg" />      // Large
-```
-
-### With Icons
-
-Badges automatically style SVG icons.
-
-<PreviewCode file="components/docs/samples/badge" name="BadgeWithIconSample" base={<BadgeWithIconSample />}>
-  <BadgeRadixSamples.BadgeWithIconSample />
-</PreviewCode>
-
-### As Link
-
-Compose with `render` (Base UI) or `asChild` (Radix) to render the badge as a different element, like a link.
-
-<PreviewCode file="components/docs/samples/badge" name="BadgeAsLinkSample" base={<BadgeAsLinkSample />}>
-  <BadgeRadixSamples.BadgeAsLinkSample />
-</PreviewCode>
-
-### Animated
-
-Combine with CSS transitions for scroll and color animations.
-
-<PreviewCode file="components/docs/samples/badge" name="BadgeAnimatedSample" base={<BadgeAnimatedSample />}>
-  <BadgeRadixSamples.BadgeAnimatedSample />
-</PreviewCode>
-
-## API Reference
-
-### Badge
-
-<ParametersTable
-  type="BadgeProps"
-  parameters={[
-    {
-      name: "variant",
-      type: '"outline" | "secondary" | "muted" | "ghost" | "info" | "warning" | "success" | "destructive"',
-      default: '"outline"',
-      description: "The visual style of the badge.",
-    },
-    {
-      name: "size",
-      type: '"sm" | "default" | "lg"',
-      default: '"default"',
-      description: "The size of the badge.",
-    },
-    {
-      name: "render",
-      type: "ReactElement | function",
-      description: "Base UI: compose as a different element instead of rendering a span.",
-    },
-    {
-      name: "asChild",
-      type: "boolean",
-      default: "false",
-      description: "Radix: merge props with a child element instead of rendering a span.",
-    },
-    {
-      name: "className",
-      type: "string",
-      description: "Additional CSS classes.",
-    },
-  ]}
-/>
-
-### Style Variants (CVA)
-
-| Export | Description |
-|--------|-------------|
-| `badgeVariants` | Styles for the badge component. |
-
-```tsx
-import { badgeVariants } from "@/components/assistant-ui/badge";
-
-<span className={badgeVariants({ variant: "muted", size: "sm" })}>
-  Custom Badge
-</span>
-```