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

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

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "vitest";
+import { server } from "../../index.js";
+
+function handler(method: string) {
+  const handlers = (server as any).server._requestHandlers;
+  const h = handlers.get(method);
+  if (!h) throw new Error(`No handler for ${method}`);
+  return h;
+}
+
+describe("MCP resources", () => {
+  it("lists docs and example resources", async () => {
+    const result = await handler("resources/list")(
+      { method: "resources/list", params: {} },
+      {},
+    );
+    expect(result.resources.length).toBeGreaterThan(0);
+    expect(
+      result.resources.some((r: any) => r.uri.startsWith("aui-docs:///")),
+    ).toBe(true);
+    expect(
+      result.resources.some((r: any) => r.uri.startsWith("aui-example:///")),
+    ).toBe(true);
+  });
+
+  it("reads a documentation resource as markdown", async () => {
+    const list = await handler("resources/list")(
+      { method: "resources/list", params: {} },
+      {},
+    );
+    const doc = list.resources.find((r: any) =>
+      r.uri.startsWith("aui-docs:///"),
+    );
+    const read = await handler("resources/read")(
+      { method: "resources/read", params: { uri: doc.uri } },
+      {},
+    );
+    expect(read.contents[0].mimeType).toBe("text/markdown");
+    expect(typeof read.contents[0].text).toBe("string");
+    expect(read.contents[0].text.length).toBeGreaterThan(0);
+  });
+
+  it("reads a slash-containing documentation resource", async () => {
+    const list = await handler("resources/list")(
+      { method: "resources/list", params: {} },
+      {},
+    );
+    const prefix = "aui-docs:///";
+    const nested = list.resources.find(
+      (r: any) =>
+        r.uri.startsWith(prefix) && r.uri.slice(prefix.length).includes("/"),
+    );
+    expect(nested).toBeDefined();
+    const read = await handler("resources/read")(
+      { method: "resources/read", params: { uri: nested.uri } },
+      {},
+    );
+    expect(read.contents[0].mimeType).toBe("text/markdown");
+    expect(read.contents[0].text.length).toBeGreaterThan(0);
+  });
+
+  it("errors on an unknown documentation resource", async () => {
+    await expect(
+      handler("resources/read")(
+        {
+          method: "resources/read",
+          params: { uri: "aui-docs:///definitely-not-a-real-doc" },
+        },
+        {},
+      ),
+    ).rejects.toThrow();
+  });
+
+  it("reads an example resource as markdown", async () => {
+    const list = await handler("resources/list")(
+      { method: "resources/list", params: {} },
+      {},
+    );
+    const example = list.resources.find((r: any) =>
+      r.uri.startsWith("aui-example:///"),
+    );
+    const read = await handler("resources/read")(
+      { method: "resources/read", params: { uri: example.uri } },
+      {},
+    );
+    expect(read.contents[0].mimeType).toBe("text/markdown");
+    expect(typeof read.contents[0].text).toBe("string");
+    expect(read.contents[0].text.length).toBeGreaterThan(0);
+  });
+
+  it("errors on an unknown example resource", async () => {
+    await expect(
+      handler("resources/read")(
+        {
+          method: "resources/read",
+          params: { uri: "aui-example:///definitely-not-a-real-example" },
+        },
+        {},
+      ),
+    ).rejects.toThrow();
+  });
+});

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

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { testContext } from "./test-setup.js";
+
+describe("assistantUISearch", () => {
+  it("returns ranked matches for a known term", async () => {
+    const result = await testContext.callTool("assistantUISearch", {
+      query: "thread",
+    });
+    expect(result.total).toBeGreaterThan(0);
+    expect(result.results[0].path).toBeDefined();
+    expect(result.results[0].title).toBeDefined();
+    expect(result.results[0].snippet).toBeDefined();
+  });
+
+  it("returns no matches for a nonsense query", async () => {
+    const result = await testContext.callTool("assistantUISearch", {
+      query: "zzzqqxnotarealdocterm",
+    });
+    expect(result.total).toBe(0);
+    expect(result.results).toHaveLength(0);
+  });
+
+  it("respects the limit", async () => {
+    const result = await testContext.callTool("assistantUISearch", {
+      query: "ui",
+      limit: 3,
+    });
+    expect(result.results.length).toBeLessThanOrEqual(3);
+  });
+
+  it("defaults to at most 10 results when no limit is given", async () => {
+    const result = await testContext.callTool("assistantUISearch", {
+      query: "ui",
+    });
+    expect(result.results.length).toBeLessThanOrEqual(10);
+  });
+});

package/src/tools/tests/test-setup.ts

@@ -4,10 +4,20 @@ import { join } from "node:path";
 import { PACKAGE_DIR } from "../../constants.js";
 import { docsTools } from "../docs.js";
 import { examplesTools } from "../examples.js";
+import { searchTools } from "../search.js";
+import {
+  xuluxTemplatesListTool,
+  xuluxTemplateDetailsTool,
+  xuluxTemplatePreviewTool,
+} from "../xulux-templates.js";
 
 const tools = {
   assistantUIDocs: docsTools,
   assistantUIExamples: examplesTools,
+  assistantUISearch: searchTools,
+  assistantUITemplates: xuluxTemplatesListTool,
+  assistantUITemplateDetails: xuluxTemplateDetailsTool,
+  assistantUITemplatePreview: xuluxTemplatePreviewTool,
 };
 
 export const testContext = {

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

@@ -0,0 +1,262 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { clearCatalogCache } from "../../xulux/catalog-client.js";
+import {
+  xuluxTemplatesListTool,
+  xuluxTemplateDetailsTool,
+  xuluxTemplatePreviewTool,
+} from "../xulux-templates.js";
+
+const LIVE_CATALOG = {
+  version: 1,
+  generatedAt: "2026-07-10T00:00:00.000Z",
+  docsOrigin: "https://www.assistant-ui.com",
+  templates: [
+    {
+      id: "base-assistant-ui",
+      templateId: "base-assistant-ui",
+      versionId: "default",
+      kind: "template",
+      name: "Configurable Base Assistant UI",
+      summary: "Base chat template",
+      assistantPlacement: "full-page chat shell",
+      features: ["threads", "composer"],
+      customizable: ["assistant", "brandTheme"],
+      versions: [
+        {
+          id: "default",
+          entryId: "base-assistant-ui-default",
+          name: "Default",
+          description: "Default base chat",
+          previewUrl: "https://base.example.com",
+          downloadUrl: "https://base.example.com/api/download",
+        },
+      ],
+      previewUrl: "https://base.example.com",
+      downloadUrl: "https://base.example.com/api/download",
+      sandboxBaseUrl: "https://base.example.com",
+      configRoots: {
+        assistant: { description: "Assistant config" },
+      },
+      rules: {
+        required: ["Only pass documented top-level config roots."],
+      },
+      tools: {
+        builtIn: [{ id: "getWeather" }],
+        customToolSupported: true,
+        renderers: [{ type: "generic" }],
+      },
+    },
+    {
+      id: "base",
+      templateId: "base",
+      versionId: null,
+      kind: "example",
+      name: "Base Demo",
+      summary: "Fixed base demo",
+      assistantPlacement: "full-page demo route",
+      features: ["fixed demo"],
+      customizable: [],
+      versions: [],
+      previewUrl: "https://www.assistant-ui.com/demos/base",
+      downloadUrl:
+        "https://www.assistant-ui.com/api/xulux/demo-download?slug=base",
+      rules: {
+        required: [
+          "This entry is a fixed demo and is not schema-customizable.",
+        ],
+      },
+    },
+  ],
+};
+
+function jsonResponse(body: unknown, init?: ResponseInit) {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+    ...init,
+  });
+}
+
+async function callTool(
+  tool:
+    | typeof xuluxTemplatesListTool
+    | typeof xuluxTemplateDetailsTool
+    | typeof xuluxTemplatePreviewTool,
+  args: unknown,
+) {
+  const result = await tool.execute(args as never);
+  const text = result.content?.[0]?.text;
+  if (!text) throw new Error(`Tool ${tool.name} returned no text content`);
+  return JSON.parse(text);
+}
+
+describe("assistant-ui template MCP tools", () => {
+  beforeEach(() => {
+    clearCatalogCache();
+    vi.stubEnv("XULUX_CATALOG_URL", "https://catalog.example.com/mcp-catalog");
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.unstubAllGlobals();
+    clearCatalogCache();
+  });
+
+  it("lists templates from the live catalog", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => jsonResponse(LIVE_CATALOG)),
+    );
+
+    const result = await callTool(xuluxTemplatesListTool, {});
+    expect(result.catalogDegraded).toBeUndefined();
+    expect(result.templates).toHaveLength(2);
+    expect(result.templates[0]).toMatchObject({
+      id: "base-assistant-ui",
+      kind: "template",
+      name: "Configurable Base Assistant UI",
+    });
+  });
+
+  it("uses the minimal fallback catalog when the live catalog is unavailable", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw new Error("network unavailable");
+      }),
+    );
+
+    const result = await callTool(xuluxTemplatesListTool, {});
+    expect(result.catalogDegraded).toBe(true);
+    expect(result.catalogDegradedReason).toContain("network unavailable");
+    expect(result.templates.map((t: any) => t.id)).toContain(
+      "base-assistant-ui",
+    );
+  });
+
+  it("returns details and fetches exampleConfig from the selected sandbox contract", async () => {
+    const fetchMock = vi.fn(async (url: string | URL) => {
+      const href = String(url);
+      if (href === "https://catalog.example.com/mcp-catalog") {
+        return jsonResponse(LIVE_CATALOG);
+      }
+      if (href === "https://base.example.com/api/template/contract?v=default") {
+        return jsonResponse({
+          exampleCompleteConfig: {
+            assistant: { appName: "Example" },
+          },
+        });
+      }
+      throw new Error(`Unexpected fetch: ${href}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const result = await callTool(xuluxTemplateDetailsTool, {
+      templateId: "base-assistant-ui",
+      versionId: "default",
+    });
+    expect(result.selectedVersionId).toBe("default");
+    expect(result.configRoots.assistant).toBeDefined();
+    expect(result.exampleConfig).toEqual({
+      assistant: { appName: "Example" },
+    });
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://base.example.com/api/template/contract?v=default",
+      expect.objectContaining({
+        cache: "no-store",
+        headers: expect.any(Headers),
+      }),
+    );
+    const sandboxCall = fetchMock.mock.calls.find((call) =>
+      String(call[0]).includes("/api/template/contract"),
+    ) as [string | URL, RequestInit] | undefined;
+    expect(sandboxCall?.[1].headers).toBeInstanceOf(Headers);
+    expect((sandboxCall?.[1].headers as Headers).get("User-Agent")).toBe(
+      "curl/8.7.1",
+    );
+  });
+
+  it("returns fixed demo preview URLs and rejects config for fixed demos", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => jsonResponse(LIVE_CATALOG)),
+    );
+
+    const ok = await callTool(xuluxTemplatePreviewTool, {
+      templateId: "base",
+    });
+    expect(ok).toMatchObject({
+      success: true,
+      templateId: "base",
+      previewUrl: "https://www.assistant-ui.com/demos/base",
+      customized: false,
+    });
+
+    const rejected = await callTool(xuluxTemplatePreviewTool, {
+      templateId: "base",
+      config: { assistant: { appName: "Nope" } },
+    });
+    expect(rejected.success).toBe(false);
+    expect(rejected.error).toContain("fixed demo");
+  });
+
+  it("creates configured hosted previews through the sandbox session endpoint", async () => {
+    const fetchMock = vi.fn(async (url: string | URL, init?: RequestInit) => {
+      const href = String(url);
+      if (href === "https://catalog.example.com/mcp-catalog") {
+        return jsonResponse(LIVE_CATALOG);
+      }
+      if (href === "https://base.example.com/api/preview/session?v=default") {
+        expect(init?.method).toBe("POST");
+        expect(init?.body).toBe(
+          JSON.stringify({ assistant: { appName: "Custom" } }),
+        );
+        return jsonResponse({
+          previewUrl: "/preview/session-1",
+          downloadUrl: "/api/download?session=1",
+          validationWarnings: [],
+        });
+      }
+      throw new Error(`Unexpected fetch: ${href}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const result = await callTool(xuluxTemplatePreviewTool, {
+      templateId: "base-assistant-ui-default",
+      config: { assistant: { appName: "Custom" } },
+    });
+    expect(result).toMatchObject({
+      success: true,
+      templateId: "base-assistant-ui",
+      versionId: "default",
+      previewUrl: "https://base.example.com/preview/session-1?v=default",
+      downloadUrl: "https://base.example.com/api/download?session=1&v=default",
+      customized: true,
+    });
+  });
+
+  it("matches the web tool shape for configured preview network failures", async () => {
+    const fetchMock = vi.fn(async (url: string | URL) => {
+      const href = String(url);
+      if (href === "https://catalog.example.com/mcp-catalog") {
+        return jsonResponse(LIVE_CATALOG);
+      }
+      if (href === "https://base.example.com/api/preview/session?v=default") {
+        throw new Error("fetch failed");
+      }
+      throw new Error(`Unexpected fetch: ${href}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const result = await callTool(xuluxTemplatePreviewTool, {
+      templateId: "base-assistant-ui",
+      config: { assistant: { appName: "Custom" } },
+    });
+    expect(result).toEqual({
+      success: false,
+      templateId: "base-assistant-ui",
+      versionId: "default",
+      error: "fetch failed",
+    });
+  });
+});

package/src/tools/xulux-templates.ts

@@ -0,0 +1,141 @@
+import { z } from "zod/v3";
+import { logger } from "../utils/logger.js";
+import { formatMCPResponse } from "../utils/mcp-format.js";
+import { getXuluxCatalog } from "../xulux/catalog-client.js";
+import {
+  createTemplatePreview,
+  getTemplateDetails,
+  listTemplates,
+} from "../xulux/template-service.js";
+
+const emptyInputSchema = z.object({});
+
+const detailsInputSchema = z.object({
+  templateId: z.string().describe("The template id from assistantUITemplates"),
+  versionId: z
+    .string()
+    .optional()
+    .describe(
+      "Optional version id. When provided, exampleConfig reflects that version's resolved defaults.",
+    ),
+});
+
+const previewInputSchema = z.object({
+  templateId: z.string().describe("The template id from assistantUITemplates"),
+  versionId: z
+    .string()
+    .optional()
+    .describe("Version id to use. Uses the template default if omitted."),
+  config: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe(
+      "Customization config for the preview. Must contain only the top-level keys: hostUi, assistant, and brandTheme. " +
+        "Use the schemas from assistantUITemplateDetails.configRoots as the source of truth for each root. " +
+        "Do not pass any other root keys.",
+    ),
+});
+
+function withDegradedNote<T extends Record<string, unknown>>(
+  payload: T,
+  degraded: boolean,
+  degradedReason?: string,
+): T & { catalogDegraded?: true; catalogDegradedReason?: string } {
+  if (!degraded) return payload;
+  return {
+    ...payload,
+    catalogDegraded: true,
+    ...(degradedReason ? { catalogDegradedReason: degradedReason } : {}),
+  };
+}
+
+export const xuluxTemplatesListTool = {
+  name: "assistantUITemplates",
+  description:
+    "List the available assistant-ui hosted app templates and fixed demos with their features, customizable surfaces, and versions. " +
+    "Call this first for any assistant-ui app-building request. Use the features and customizable fields to decide which template fits. " +
+    "If customizable is empty, the entry is a fixed demo that should be used as-is rather than configured. " +
+    "Call assistantUITemplateDetails on the chosen template before requesting a preview.",
+  parameters: emptyInputSchema.shape,
+  execute: async (_args: z.infer<typeof emptyInputSchema>) => {
+    logger.info("Listing assistant-ui templates");
+    try {
+      const { catalog, degraded, degradedReason } = await getXuluxCatalog();
+      return formatMCPResponse(
+        withDegradedNote(listTemplates(catalog), degraded, degradedReason),
+      );
+    } catch (error) {
+      logger.error("Failed to list assistant-ui templates", error);
+      return formatMCPResponse({
+        error: "Failed to list assistant-ui templates",
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  },
+};
+
+export const xuluxTemplateDetailsTool = {
+  name: "assistantUITemplateDetails",
+  description:
+    "Get the full authoring surface for a specific assistant-ui hosted template. " +
+    "Returns configRoots schemas (with types, defaults, and enums), rules, built-in tool input/outputShape, renderer contracts, and an exampleConfig. " +
+    "Fixed demos return no configRoots; use those as-is without config. " +
+    "Use this before calling assistantUITemplatePreview to understand exactly what config to write. " +
+    "If assistantUITemplatePreview returns validationWarnings, call this again and cross-reference configRoots to correct the config.",
+  parameters: detailsInputSchema.shape,
+  execute: async (args: z.infer<typeof detailsInputSchema>) => {
+    logger.info(
+      `Getting assistant-ui template details for: ${args.templateId}`,
+    );
+    try {
+      const { catalog, degraded, degradedReason } = await getXuluxCatalog();
+      const details = await getTemplateDetails(catalog, args);
+      return formatMCPResponse(
+        withDegradedNote(
+          details as unknown as Record<string, unknown>,
+          degraded,
+          degradedReason,
+        ),
+      );
+    } catch (error) {
+      logger.error("Failed to get assistant-ui template details", error);
+      return formatMCPResponse({
+        error: "Failed to get assistant-ui template details",
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  },
+};
+
+export const xuluxTemplatePreviewTool = {
+  name: "assistantUITemplatePreview",
+  description:
+    "Return preview and download URLs for a selected assistant-ui hosted template. " +
+    "The previewUrl is a hosted app URL; show it to the user first, or open it with an available browser/in-app-browser tool if your client provides one. " +
+    "If you pass config, a preview session is created on the hosted template sandbox and the returned URLs reflect that configuration. " +
+    "Do not pass config for fixed demos that have no configRoots in assistantUITemplateDetails. " +
+    "This tool only returns URLs.",
+  parameters: previewInputSchema.shape,
+  execute: async (args: z.infer<typeof previewInputSchema>) => {
+    logger.info(
+      `Creating assistant-ui template preview for: ${args.templateId}`,
+    );
+    try {
+      const { catalog, degraded, degradedReason } = await getXuluxCatalog();
+      const result = await createTemplatePreview(catalog, args);
+      return formatMCPResponse(
+        withDegradedNote(
+          result as unknown as Record<string, unknown>,
+          degraded,
+          degradedReason,
+        ),
+      );
+    } catch (error) {
+      logger.error("Failed to create assistant-ui template preview", error);
+      return formatMCPResponse({
+        error: "Failed to create assistant-ui template preview",
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  },
+};

package/src/utils/cache.ts

@@ -0,0 +1,20 @@
+export function cacheListing(
+  scan: () => Promise<string[]>,
+): () => Promise<string[]> {
+  let cache: Promise<string[]> | null = null;
+  return () => {
+    if (!cache) {
+      cache = scan().then(
+        (result) => {
+          if (result.length === 0) cache = null;
+          return result;
+        },
+        (error) => {
+          cache = null;
+          throw error;
+        },
+      );
+    }
+    return cache;
+  };
+}

package/src/utils/mcp-format.ts

@@ -1,12 +1,14 @@
 export function formatMCPResponse(data: any): {
   content: Array<{ type: "text"; text: string }>;
+  structuredContent?: Record<string, unknown>;
 } {
+  const text = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+  const isStructured =
+    typeof data === "object" && data !== null && !Array.isArray(data);
   return {
-    content: [
-      {
-        type: "text",
-        text: typeof data === "string" ? data : JSON.stringify(data, null, 2),
-      },
-    ],
+    content: [{ type: "text", text }],
+    ...(isStructured && {
+      structuredContent: data as Record<string, unknown>,
+    }),
   };
 }

package/src/utils/mdx.ts

@@ -1,5 +1,6 @@
-import { readFile } from "node:fs/promises";
+import { readFile, lstat } from "node:fs/promises";
 import matter from "gray-matter";
+import { MAX_FILE_SIZE } from "../constants.js";
 import { logger } from "./logger.js";
 
 interface MDXContent {
@@ -32,6 +33,25 @@ export async function readMDXFile(
   }
 }
 
+export async function readMDXFileSafe(
+  filePath: string,
+): Promise<MDXContent | null> {
+  try {
+    const stats = await lstat(filePath);
+    if (stats.isSymbolicLink()) {
+      logger.warn(`Attempted to read symlink: ${filePath}`);
+      return null;
+    }
+    if (stats.size > MAX_FILE_SIZE) {
+      logger.warn(`File size exceeds limit: ${filePath} (${stats.size} bytes)`);
+      return null;
+    }
+  } catch {
+    return null;
+  }
+  return readMDXFile(filePath);
+}
+
 export function formatMDXContent(mdxContent: MDXContent): string {
   const { content, frontmatter } = mdxContent;
 

package/src/utils/paths.ts

@@ -1,6 +1,7 @@
 import { readdir, stat } from "node:fs/promises";
 import { join, extname } from "node:path";
 import { DOCS_PATH, MDX_EXTENSION, MD_EXTENSION } from "../constants.js";
+import { cacheListing } from "./cache.js";
 import { logger } from "./logger.js";
 
 const SIMILARITY_THRESHOLDS = {
@@ -66,6 +67,30 @@ export async function getAvailablePaths(): Promise<string[]> {
   return paths.sort();
 }
 
+export const getAvailableDocFiles = cacheListing(scanDocFiles);
+
+async function scanDocFiles(): Promise<string[]> {
+  const files: string[] = [];
+
+  async function scanDirectory(dir: string, prefix = ""): Promise<void> {
+    const { directories, files: dirFiles } = await listDirContents(dir);
+
+    for (const file of dirFiles) {
+      if (extname(file) !== MDX_EXTENSION) continue;
+      const name = file.replace(MDX_EXTENSION, "");
+      files.push(prefix ? `${prefix}/${name}` : name);
+    }
+
+    for (const subdir of directories) {
+      const newPrefix = prefix ? `${prefix}/${subdir}` : subdir;
+      await scanDirectory(join(dir, subdir), newPrefix);
+    }
+  }
+
+  await scanDirectory(DOCS_PATH);
+  return files.sort();
+}
+
 export function findNearestPaths(
   requestedPath: string,
   availablePaths: string[],