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

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);

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/tools/interactables-legacy.mdx

@@ -1,423 +0,0 @@
----
-title: Interactables (legacy)
-description: Build persistent UI elements whose state the AI can read and update — copilot interactables in React with assistant-ui for forms, dashboards, and tools.
-platforms: ["react"]
----
-
-<Callout type="warn">
-This legacy API is deprecated. For new code, use the [`unstable_` interactables API](/docs/tools/interactables). We recomment switching beccause this legacy API passes state by mutating the system message, the new, `unstable_` tagged API solves this.
-</Callout>
-
-Interactables are React components that live outside the chat message flow and have state that both the user and the AI can read and write. This enables AI-driven UI patterns where the assistant controls parts of your application beyond the chat window.
-
-
-## Overview
-
-Unlike regular tool UIs that appear inline within messages, interactables:
-
-- **Persist across messages** — they live outside the chat thread
-- **Have shared state** — both the user (via React) and the AI (via auto-generated tools) can update them
-- **Support partial updates** — the AI only needs to send the fields it wants to change
-- **Are developer-placed** — you decide where they render in your app
-- **Auto-register tools** — the AI automatically gets a tool to update each interactable's state
-
-Common use cases:
-
-- Task boards that the AI can add items to
-- Data dashboards that update based on conversation
-- Forms that the AI pre-fills
-- Canvas/editor components that the AI can manipulate
-
-## Quick Start
-
-### 1. Register the Interactables scope
-
-```tsx
-import { AuiConfig, Interactables, AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
-
-function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
-  const runtime = useChatRuntime();
-  const config = AuiConfig({
-    interactables: Interactables(), // [!code ++]
-  });
-
-  return (
-    <AssistantRuntimeProvider
-      runtime={runtime}
-      config={config}
-    >
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-<Callout type="idea">
-  The legacy `interactables: Interactables()` scope and the new
-  `unstable_interactables: unstable_Interactables()` scope are mutually
-  exclusive. Mount only one interactables API in a single provider config.
-</Callout>
-
-### 2. Create an interactable
-
-```tsx
-import { useAssistantInteractable, useInteractableState } from "@assistant-ui/react";
-import { z } from "zod";
-
-const taskBoardSchema = z.object({
-  tasks: z.array(
-    z.object({
-      id: z.string(),
-      title: z.string(),
-      done: z.boolean(),
-    }),
-  ),
-});
-
-const taskBoardInitialState = { tasks: [] };
-
-function TaskBoard() {
-  const id = useAssistantInteractable("taskBoard", {
-    description: "A task board showing the user's tasks",
-    stateSchema: taskBoardSchema,
-    initialState: taskBoardInitialState,
-  });
-  const [state, { setState }] = useInteractableState(id, taskBoardInitialState);
-
-  return (
-    <div>
-      <h2>Tasks</h2>
-      <ul>
-        {state.tasks.map((task) => (
-          <li key={task.id}>
-            <label>
-              <input
-                type="checkbox"
-                checked={task.done}
-                onChange={() =>
-                  setState((prev) => ({
-                    tasks: prev.tasks.map((t) =>
-                      t.id === task.id ? { ...t, done: !t.done } : t,
-                    ),
-                  }))
-                }
-              />
-              {task.title}
-            </label>
-          </li>
-        ))}
-      </ul>
-    </div>
-  );
-}
-```
-
-<Callout type="warn">
-  Define the `stateSchema` and `initialState` **outside** the component (or
-  memoize them). Creating a new schema on every render will cause the
-  interactable to re-register and reset its state.
-</Callout>
-
-### 3. Place it in your layout
-
-```tsx
-function App() {
-  return (
-    <MyRuntimeProvider>
-      <div className="flex">
-        <Thread className="flex-1" />
-        <TaskBoard /> {/* Lives outside the chat */}
-      </div>
-    </MyRuntimeProvider>
-  );
-}
-```
-
-Now when the user says _"Add a task called 'Buy groceries'"_, the AI will automatically call the `update_taskBoard` tool to update the state. Thanks to partial updates, the AI only needs to send the fields it wants to change.
-
-## Partial Updates
-
-Auto-generated tools use a partial schema — all fields become optional. The AI only sends the fields it wants to change; omitted fields keep their current values.
-
-```tsx
-// If the state is { title: "My Note", content: "Hello", color: "yellow" }
-// The AI can call: update_note({ color: "blue" })
-// Result: { title: "My Note", content: "Hello", color: "blue" }
-```
-
-This is especially useful for large state objects where regenerating the entire state would be expensive and error-prone.
-
-<Callout type="info">
-  Merge is shallow (one level deep). If the AI sends a nested object, it replaces
-  that entire field rather than deep-merging into it.
-</Callout>
-
-## Multiple Instances
-
-You can render multiple interactables with the same `name` but different `id`s. Each gets its own update tool:
-
-```tsx
-import { useAssistantInteractable, useInteractableState } from "@assistant-ui/react";
-import { z } from "zod";
-
-const noteSchema = z.object({
-  title: z.string(),
-  content: z.string(),
-  color: z.enum(["yellow", "blue", "green", "pink"]),
-});
-
-const noteInitialState = { title: "New Note", content: "", color: "yellow" as const };
-
-function NoteCard({ noteId }: { noteId: string }) {
-  useAssistantInteractable("note", {
-    id: noteId,
-    description: "A sticky note",
-    stateSchema: noteSchema,
-    initialState: noteInitialState,
-  });
-  const [state] = useInteractableState(noteId, noteInitialState);
-
-  return <div>{state.title}</div>;
-}
-
-function App() {
-  return (
-    <>
-      <NoteCard noteId="note-1" /> {/* → update_note_note-1 tool */}
-      <NoteCard noteId="note-2" /> {/* → update_note_note-2 tool */}
-    </>
-  );
-}
-```
-
-When only one instance of a name exists, the tool is named `update_{name}` (e.g., `update_note`). When multiple instances exist, tools are named `update_{name}_{id}` (e.g., `update_note_note-1`).
-
-## Selection
-
-When multiple interactables are present, you can mark one as "selected" to tell the AI which one the user is focused on:
-
-```tsx
-function NoteCard({ noteId }: { noteId: string }) {
-  useAssistantInteractable("note", {
-    id: noteId,
-    description: "A sticky note",
-    stateSchema: noteSchema,
-    initialState: noteInitialState,
-  });
-  const [state, { setSelected }] = useInteractableState(noteId, noteInitialState);
-
-  return (
-    <div onClick={() => setSelected(true)}>
-      {state.title}
-    </div>
-  );
-}
-```
-
-The AI sees `(SELECTED)` in the system prompt for the focused interactable, allowing it to prioritize that one in responses. For example, the user can say _"Change the color to blue"_ and the AI knows which note to update.
-
-## API Reference
-
-### `useAssistantInteractable`
-
-Registers an interactable with the AI assistant. Returns the instance id.
-
-```tsx
-const id = useAssistantInteractable(name, config);
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `name` | `string` | Name for the interactable (used in tool names) |
-| `config.description` | `string` | Description shown to the AI |
-| `config.stateSchema` | `StandardSchemaV1 \| JSONSchema7` | Schema for the state (e.g., a Zod schema) |
-| `config.initialState` | `unknown` | Initial state value |
-| `config.id` | `string?` | Optional unique instance ID (auto-generated if omitted) |
-| `config.selected` | `boolean?` | Whether this interactable is selected |
-
-**Returns:** `string` — the instance id (auto-generated or provided).
-
-### `useInteractableState`
-
-Reads and writes the state of a registered interactable.
-
-```tsx
-const [state, { setState, setSelected, isPending, error, flush }] = useInteractableState<TState>(id, fallback?);
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `id` | `string` | The interactable instance id (from `useAssistantInteractable`) |
-| `fallback` | `TState?` | Fallback value before the interactable is registered |
-
-**Returns:** `[state, methods]`
-
-| Return | Type | Description |
-| --- | --- | --- |
-| `state` | `TState` | Current state |
-| `setState` | `(updater: TState \| (prev: TState) => TState) => void` | State setter (like `useState`) |
-| `setSelected` | `(selected: boolean) => void` | Mark this interactable as selected |
-| `isPending` | `boolean` | Whether a persistence save is in-flight |
-| `error` | `unknown` | Error from the last failed save |
-| `flush` | `() => Promise<void>` | Force an immediate persistence save |
-
-### `Interactables`
-
-The scope resource that manages all interactables. Register it via your provider's `config`:
-
-```tsx
-AuiConfig({
-  interactables: Interactables(),
-});
-```
-
-## How It Works
-
-When you call `useAssistantInteractable("taskBoard", config)`:
-
-1. **Registration** — the interactable is registered in the `interactables` scope with its name, description, schema, and initial state.
-2. **Tool generation** — an `update_taskBoard` frontend tool is automatically created with a partial schema (all fields optional). For multiple instances, tools are named `update_{name}_{id}`.
-3. **System prompt** — the AI receives a system message describing the interactable, its current state, and whether it is selected.
-4. **Streaming updates** — as the AI generates the tool arguments, the interactable's state updates progressively rather than waiting for complete arguments. This gives users immediate visual feedback.
-5. **Partial merge** — only the fields the AI sends are updated; the rest are preserved.
-6. **Bidirectional updates** — when the AI calls the tool, the state updates and React re-renders. When the user updates state via `setState`, the model context is notified so the AI sees the latest state on the next turn.
-
-## Persistence
-
-By default, interactable state is in-memory and lost on page refresh. You can add persistence by providing a save callback:
-
-```tsx
-import { useEffect } from "react";
-import { AuiConfig, AuiProvider, Interactables, useAui } from "@assistant-ui/react";
-
-function MyRuntimeProvider({ children }) {
-  const aui = useAui();
-  const config = AuiConfig({ interactables: Interactables() });
-  return (
-    <AuiProvider extends={aui} config={config}>
-      <PersistenceSetup />
-      {children}
-    </AuiProvider>
-  );
-}
-
-function PersistenceSetup() {
-  const aui = useAui();
-
-  useEffect(() => {
-    // Set up persistence adapter
-    aui.interactables.setPersistenceAdapter({
-      save: async (state) => {
-        localStorage.setItem("interactables", JSON.stringify(state));
-      },
-    });
-
-    // Restore saved state on mount
-    const saved = localStorage.getItem("interactables");
-    if (saved) {
-      aui.interactables.importState(JSON.parse(saved));
-    }
-  }, [aui]);
-
-  return null;
-}
-```
-
-### Sync Status
-
-When a persistence adapter is set, `useInteractableState` exposes sync metadata:
-
-```tsx
-const [state, { setState, isPending, error, flush }] = useInteractableState(id, fallback);
-
-// isPending — true while a save is in-flight
-// error — the error from the last failed save, if any
-// flush() — force an immediate save (useful before navigation)
-```
-
-State changes are automatically debounced (500ms) before saving. When a component unregisters, any pending save is flushed immediately.
-
-### Export / Import
-
-For custom persistence strategies, use `exportState` and `importState` directly:
-
-```tsx
-const snapshot = aui.interactables.exportState();
-// => { "note-1": { name: "note", state: { title: "Hello" } }, ... }
-
-aui.interactables.importState(snapshot);
-// Imported state is picked up when components next register
-```
-
-## Combining with Tools
-
-You can use `Interactables` alongside `Tools`:
-
-```tsx
-AuiConfig({
-  tools: Tools({ toolkit: myToolkit }),
-  interactables: Interactables(),
-});
-```
-
-## Streaming Updates
-
-While the AI is generating tool arguments, `useInteractableState` reflects the partial state in real time as fields stream in. You can use the partial state itself plus the thread's running status to show a skeleton UI while the AI is mid-stream:
-
-```tsx
-import { useAuiState } from "@assistant-ui/react";
-
-function TaskBoard() {
-  const id = useAssistantInteractable("taskBoard", config);
-  const [state] = useInteractableState(id, taskBoardInitialState);
-  const isRunning = useAuiState((s) => s.thread.isRunning);
-
-  const isLoading = isRunning && state.tasks.length === 0;
-
-  return (
-    <div>
-      <h2>Tasks</h2>
-      {isLoading ? (
-        <div className="animate-pulse h-8 rounded bg-muted" />
-      ) : (
-        <ul>
-          {state.tasks.map((task) => (
-            <li key={task.id}>{task.title}</li>
-          ))}
-        </ul>
-      )}
-    </div>
-  );
-}
-```
-
-The state object updates progressively as the AI streams in each field, so partial renders work without any extra wiring. Use the runtime's `isRunning` to distinguish "still streaming, no fields yet" from "model returned an empty result".
-
-## Schema Evolution
-
-<Callout type="warn">
-  If you change a Zod schema after state has been persisted, the imported snapshot may silently mis-match the new shape. The adapter does a shallow merge, so extra fields are preserved and missing fields keep their initial values, but type mismatches are not caught at runtime. To avoid silent corruption, version your schema key (e.g. `"taskBoard_v2"`) or namespace it by schema hash whenever you make breaking changes. Alternatively, add a migration step in your `importState` call.
-</Callout>
-
-## Unmount Behavior
-
-When a component that called `useAssistantInteractable` unmounts, the interactable is unregistered from the AI's tool list and system prompt. However, its state is preserved in the `Interactables` scope. When the component mounts again with the same name and id, the scope re-merges the preserved state rather than resetting to `initialState`. This means transient unmounts (such as React Strict Mode double-mounts or tab switches) do not lose state.
-
-## Full Example
-
-See the complete [with-interactables example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-interactables) for a working implementation featuring:
-
-- **Task Board** — single-instance interactable with a custom `manage_tasks` tool
-- **Sticky Notes** — multi-instance interactables with selection and partial updates
-- **localStorage persistence** — state survives page refresh via `setPersistenceAdapter`
-- **Sync indicator** — spinning icon while a save is in-flight (`isPending`)
-
-## Related
-
-- [Tool UI](/docs/tools/tool-ui) — Inline tool call UIs rendered inside messages
-- [LangGraph Generative UI](/docs/runtimes/langgraph/generative-ui) — Structured UI components emitted by a LangGraph graph alongside messages