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

package/src/utils/search.ts

@@ -0,0 +1,131 @@
+import { join } from "node:path";
+import { DOCS_PATH, MDX_EXTENSION } from "../constants.js";
+import { getAvailablePaths, pathExists } from "./paths.js";
+import { readMDXFile } from "./mdx.js";
+
+const SCORE_WEIGHTS = {
+  FULL_QUERY: { title: 10, path: 8, description: 5 },
+  TOKEN: { title: 3, path: 2, description: 1, content: 0.5 },
+} as const;
+
+interface IndexEntry {
+  path: string;
+  title: string;
+  description: string;
+  content: string;
+  excerpt: string;
+}
+
+export interface SearchResult {
+  path: string;
+  title: string;
+  snippet: string;
+}
+
+let indexPromise: Promise<IndexEntry[]> | null = null;
+
+function deriveTitle(
+  path: string,
+  frontmatter: Record<string, unknown>,
+): string {
+  const fmTitle = frontmatter["title"];
+  if (typeof fmTitle === "string" && fmTitle.trim()) return fmTitle;
+  return path.split("/").pop() ?? path;
+}
+
+async function buildIndex(): Promise<IndexEntry[]> {
+  const paths = await getAvailablePaths();
+  const entries = await Promise.all(
+    paths.map(async (path): Promise<IndexEntry | null> => {
+      const filePath = join(DOCS_PATH, `${path}${MDX_EXTENSION}`);
+      if (!(await pathExists(filePath))) return null;
+      const mdx = await readMDXFile(filePath);
+      if (!mdx) return null;
+      const description = mdx.frontmatter["description"];
+      return {
+        path,
+        title: deriveTitle(path, mdx.frontmatter),
+        description: typeof description === "string" ? description : "",
+        content: mdx.content,
+        excerpt: mdx.excerpt ?? "",
+      };
+    }),
+  );
+  return entries.filter((entry): entry is IndexEntry => entry !== null);
+}
+
+function getIndex(): Promise<IndexEntry[]> {
+  if (!indexPromise) {
+    indexPromise = buildIndex().catch((error) => {
+      indexPromise = null;
+      throw error;
+    });
+  }
+  return indexPromise;
+}
+
+function makeSnippet(
+  content: string,
+  tokens: string[],
+  excerpt: string,
+): string {
+  const lower = content.toLowerCase();
+  for (const token of tokens) {
+    const idx = lower.indexOf(token);
+    if (idx >= 0) {
+      const start = Math.max(0, idx - 60);
+      const end = Math.min(content.length, idx + token.length + 100);
+      const slice = content.slice(start, end).replace(/\s+/g, " ").trim();
+      return `${start > 0 ? "…" : ""}${slice}${end < content.length ? "…" : ""}`;
+    }
+  }
+  if (excerpt) return excerpt.slice(0, 160);
+  const firstLine = content.split("\n").find((line) => line.trim());
+  return firstLine ? firstLine.replace(/^#+\s*/, "").slice(0, 160) : "";
+}
+
+function scoreEntry(
+  entry: IndexEntry,
+  query: string,
+  tokens: string[],
+): number {
+  const title = entry.title.toLowerCase();
+  const path = entry.path.toLowerCase();
+  const description = entry.description.toLowerCase();
+  const content = entry.content.toLowerCase();
+
+  let score = 0;
+  if (title.includes(query)) score += SCORE_WEIGHTS.FULL_QUERY.title;
+  if (path.includes(query)) score += SCORE_WEIGHTS.FULL_QUERY.path;
+  if (description.includes(query))
+    score += SCORE_WEIGHTS.FULL_QUERY.description;
+
+  for (const token of tokens) {
+    if (title.includes(token)) score += SCORE_WEIGHTS.TOKEN.title;
+    if (path.includes(token)) score += SCORE_WEIGHTS.TOKEN.path;
+    if (description.includes(token)) score += SCORE_WEIGHTS.TOKEN.description;
+    if (content.includes(token)) score += SCORE_WEIGHTS.TOKEN.content;
+  }
+  return score;
+}
+
+export async function searchDocs(
+  query: string,
+  limit = 10,
+): Promise<SearchResult[]> {
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) return [];
+  const tokens = normalized.split(/\s+/).filter(Boolean);
+
+  const index = await getIndex();
+  return index
+    .map((entry) => ({ entry, score: scoreEntry(entry, normalized, tokens) }))
+    .filter((scored) => scored.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map(({ entry }) => ({
+      path: entry.path,
+      title: entry.title,
+      snippet: makeSnippet(entry.content, tokens, entry.excerpt),
+    }));
+}

package/src/utils/tests/cache.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { cacheListing } from "../cache.js";
+
+describe("cacheListing", () => {
+  it("scans once and reuses the result", async () => {
+    let calls = 0;
+    const listing = cacheListing(async () => {
+      calls++;
+      return ["a", "b"];
+    });
+    const first = await listing();
+    const second = await listing();
+    expect(second).toBe(first);
+    expect(calls).toBe(1);
+  });
+
+  it("shares one in-flight scan across concurrent callers", async () => {
+    let calls = 0;
+    const listing = cacheListing(async () => {
+      calls++;
+      return ["a"];
+    });
+    const [first, second] = await Promise.all([listing(), listing()]);
+    expect(second).toBe(first);
+    expect(calls).toBe(1);
+  });
+
+  it("re-scans after a failed scan", async () => {
+    let calls = 0;
+    const listing = cacheListing(async () => {
+      calls++;
+      if (calls === 1) throw new Error("boom");
+      return ["a"];
+    });
+    await expect(listing()).rejects.toThrow("boom");
+    expect(await listing()).toEqual(["a"]);
+    expect(calls).toBe(2);
+  });
+
+  it("does not cache an empty listing", async () => {
+    let calls = 0;
+    const listing = cacheListing(async () => {
+      calls++;
+      return calls === 1 ? [] : ["a"];
+    });
+    expect(await listing()).toEqual([]);
+    expect(await listing()).toEqual(["a"]);
+    expect(await listing()).toEqual(["a"]);
+    expect(calls).toBe(2);
+  });
+});

package/src/utils/tests/mcp-format.test.ts

@@ -0,0 +1,22 @@
+import { describe, it, expect } from "vitest";
+import { formatMCPResponse } from "../mcp-format.js";
+
+describe("formatMCPResponse", () => {
+  it("attaches structuredContent for object data, mirroring the text block", () => {
+    const data = { found: true, path: "getting-started", type: "file" };
+    const res = formatMCPResponse(data);
+    expect(res.content[0]!.text).toBe(JSON.stringify(data, null, 2));
+    expect(res.structuredContent).toEqual(data);
+  });
+
+  it("omits structuredContent for string data", () => {
+    const res = formatMCPResponse("plain text");
+    expect(res.content[0]!.text).toBe("plain text");
+    expect(res.structuredContent).toBeUndefined();
+  });
+
+  it("omits structuredContent for array data", () => {
+    const res = formatMCPResponse([1, 2, 3] as any);
+    expect(res.structuredContent).toBeUndefined();
+  });
+});

package/src/utils/tests/security.test.ts

@@ -85,7 +85,7 @@ describe("sanitizePath", () => {
       },
       { input: "guides/tools", expected: "guides/tools" },
       { input: "docs/index", expected: "docs/index" },
-      { input: "examples/with-ai-sdk-v6", expected: "examples/with-ai-sdk-v6" },
+      { input: "examples/with-ai-sdk-v7", expected: "examples/with-ai-sdk-v7" },
       { input: "./current-dir-file", expected: "current-dir-file" },
       {
         input: "deeply/nested/path/to/file",

package/src/xulux/catalog-client.ts

@@ -0,0 +1,105 @@
+import { logger } from "../utils/logger.js";
+import { FALLBACK_CATALOG, FALLBACK_NOTE } from "./fallback-catalog.js";
+import type { XuluxCatalog, 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;
+
+export function getCatalogUrl(): string {
+  const override = process.env.XULUX_CATALOG_URL?.trim();
+  return override || DEFAULT_CATALOG_URL;
+}
+
+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) {
+    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;
+}
+
+interface CacheEntry {
+  catalog: XuluxCatalog;
+  fetchedAt: number;
+  url: string;
+}
+
+let cache: CacheEntry | null = null;
+
+export function clearCatalogCache(): void {
+  cache = null;
+}
+
+async function fetchCatalog(url: string): Promise<XuluxCatalog> {
+  const res = await fetch(url, {
+    headers: { Accept: "application/json" },
+  });
+  if (!res.ok) {
+    throw new Error(`Catalog fetch failed: HTTP ${res.status}`);
+  }
+  const data: unknown = await res.json();
+  return validateCatalog(data);
+}
+
+/**
+ * Returns the assistant-ui template catalog. Uses an in-memory five-minute cache, and falls
+ * back to a minimal bundled catalog (marked degraded) when the live fetch
+ * fails and no cached copy exists.
+ */
+export async function getXuluxCatalog(): Promise<XuluxCatalogResult> {
+  const url = getCatalogUrl();
+  const now = Date.now();
+
+  if (cache && cache.url === url && now - cache.fetchedAt < CATALOG_TTL_MS) {
+    return { catalog: cache.catalog, degraded: false };
+  }
+
+  try {
+    const catalog = await fetchCatalog(url);
+    cache = { catalog, fetchedAt: now, url };
+    return { catalog, degraded: false };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.warn(
+      `assistant-ui template catalog fetch failed (${url}): ${message}`,
+    );
+
+    // Prefer a stale cached copy over the minimal fallback.
+    if (cache && cache.url === url) {
+      return {
+        catalog: cache.catalog,
+        degraded: true,
+        degradedReason: `Live catalog refresh failed (${message}); using previously fetched catalog.`,
+      };
+    }
+
+    return {
+      catalog: FALLBACK_CATALOG,
+      degraded: true,
+      degradedReason: `${message} ${FALLBACK_NOTE}`,
+    };
+  }
+}

package/src/xulux/fallback-catalog.ts

@@ -0,0 +1,63 @@
+import {
+  XULUX_MCP_CATALOG_VERSION,
+  type XuluxCatalog,
+  type XuluxCatalogTemplate,
+} from "./types.js";
+
+// Minimal bundled fallback catalog for degraded mode. It supports discovery
+// (ids + names) only. Full authoring details and preview/download URLs
+// require the live catalog endpoint. Do NOT grow this into a copy of the
+// full template knowledge base — the docs endpoint owns freshness.
+
+export const FALLBACK_NOTE =
+  "The live assistant-ui template catalog could not be fetched, so this is minimal bundled fallback data. " +
+  "Template details, previews, and downloads require live catalog access. " +
+  "Check network access to the docs site or set XULUX_CATALOG_URL to a reachable catalog endpoint.";
+
+const fallbackTemplate = (
+  overrides: Pick<XuluxCatalogTemplate, "id" | "kind" | "name" | "summary">,
+): XuluxCatalogTemplate => ({
+  templateId: overrides.id,
+  versionId: null,
+  assistantPlacement: "unavailable in fallback mode",
+  features: [],
+  customizable: [],
+  versions: [],
+  ...overrides,
+});
+
+export const FALLBACK_CATALOG: XuluxCatalog = {
+  version: XULUX_MCP_CATALOG_VERSION,
+  generatedAt: "fallback",
+  docsOrigin: "https://www.assistant-ui.com",
+  templates: [
+    fallbackTemplate({
+      id: "base-assistant-ui",
+      kind: "template",
+      name: "Configurable Base Assistant UI",
+      summary:
+        "Hosted configurable assistant-ui Base chat template with threads, composer, suggestions, and no-key demo flows.",
+    }),
+    fallbackTemplate({
+      id: "webpage-assistant",
+      kind: "template",
+      name: "Webpage with Assistant",
+      summary:
+        "Docs/website layout with a sidebar or modal assistant grounded in configurable pages.",
+    }),
+    fallbackTemplate({
+      id: "product-page-assistant",
+      kind: "template",
+      name: "Product Page with Floating Assistant",
+      summary:
+        "Mock product dashboard with a floating modal support assistant and analyze-then-handoff flow.",
+    }),
+    fallbackTemplate({
+      id: "expo-react-native",
+      kind: "example",
+      name: "Expo React Native Assistant",
+      summary:
+        "Mobile AI chat app built with Expo and assistant-ui React Native primitives.",
+    }),
+  ],
+};

package/src/xulux/fetch-sandbox.ts

@@ -0,0 +1,56 @@
+const SANDBOX_FETCH_HEADERS = {
+  Accept: "application/json, application/zip, application/octet-stream, */*",
+  // Blaxel preview hosts intermittently reset Node's default fetch path.
+  "User-Agent": "curl/8.7.1",
+};
+
+const MAX_ATTEMPTS = 3;
+const RETRY_DELAY_MS = 300;
+
+function isRetryableFetchError(error: unknown) {
+  if (!(error instanceof Error)) return false;
+  const cause = error.cause as { code?: string } | undefined;
+  const code = cause?.code ?? error.message;
+  return (
+    code === "ECONNRESET" ||
+    code === "ETIMEDOUT" ||
+    code === "ECONNREFUSED" ||
+    code === "fetch failed"
+  );
+}
+
+function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function mergeHeaders(headers?: HeadersInit): Headers {
+  const merged = new Headers(SANDBOX_FETCH_HEADERS);
+  if (!headers) return merged;
+  new Headers(headers).forEach((value, key) => merged.set(key, value));
+  return merged;
+}
+
+export async function fetchSandboxResource(
+  url: string | URL,
+  init?: RequestInit,
+): Promise<Response> {
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+    try {
+      return await fetch(url, {
+        ...init,
+        cache: "no-store",
+        headers: mergeHeaders(init?.headers),
+      });
+    } catch (error) {
+      lastError = error;
+      if (!isRetryableFetchError(error) || attempt === MAX_ATTEMPTS) {
+        throw error;
+      }
+      await sleep(RETRY_DELAY_MS * attempt);
+    }
+  }
+
+  throw lastError;
+}