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

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

@@ -1,119 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { sanitizePath } from "../security.js";
-
-describe("sanitizePath", () => {
-  describe("should reject directory traversal attempts", () => {
-    const maliciousPaths = [
-      "../../../etc/passwd",
-      "..\\..\\windows\\system32",
-      "/etc/passwd",
-      "/absolute/path",
-      "docs/../../../etc/passwd",
-      "valid/../../../../../../etc/passwd",
-      "../",
-      "..",
-      ".../.../",
-      "foo/../../bar",
-      "./../../etc/passwd",
-      "path/with/../../../traversal",
-      "path/to/\0/null",
-      "path\\to\\..\\..\\file",
-    ];
-
-    if (process.platform === "win32") {
-      maliciousPaths.push("C:\\Windows\\System32", "\\\\server\\share");
-    } else {
-      maliciousPaths.push("C:\\Windows\\System32", "\\\\server\\share");
-    }
-
-    maliciousPaths.forEach((path) => {
-      it(`should reject: ${path}`, () => {
-        expect(() => sanitizePath(path)).toThrow();
-      });
-    });
-  });
-
-  describe("should reject invalid inputs", () => {
-    it("should reject empty string", () => {
-      expect(() => sanitizePath("")).toThrow(
-        "Invalid path: Path must be a non-empty string",
-      );
-    });
-
-    it("should reject null", () => {
-      expect(() => sanitizePath(null as any)).toThrow(
-        "Invalid path: Path must be a non-empty string",
-      );
-    });
-
-    it("should reject undefined", () => {
-      expect(() => sanitizePath(undefined as any)).toThrow(
-        "Invalid path: Path must be a non-empty string",
-      );
-    });
-
-    it("should reject numbers", () => {
-      expect(() => sanitizePath(123 as any)).toThrow(
-        "Invalid path: Path must be a non-empty string",
-      );
-    });
-  });
-
-  describe("should reject hidden files", () => {
-    const hiddenPaths = [
-      ".hidden",
-      ".git/config",
-      "docs/.secret",
-      "path/to/.env",
-    ];
-
-    hiddenPaths.forEach((path) => {
-      it(`should reject: ${path}`, () => {
-        expect(() => sanitizePath(path)).toThrow(
-          "Invalid path: Hidden files are not allowed",
-        );
-      });
-    });
-  });
-
-  describe("should allow valid paths", () => {
-    const validPaths = [
-      { input: "getting-started", expected: "getting-started" },
-      {
-        input: "api-reference/primitives/thread",
-        expected: "api-reference/primitives/thread",
-      },
-      { input: "guides/tools", expected: "guides/tools" },
-      { input: "docs/index", expected: "docs/index" },
-      { 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",
-        expected: "deeply/nested/path/to/file",
-      },
-    ];
-
-    validPaths.forEach(({ input, expected }) => {
-      it(`should allow: ${input} => ${expected}`, () => {
-        expect(sanitizePath(input)).toBe(expected);
-      });
-    });
-  });
-
-  if (process.platform === "win32") {
-    describe("Windows-specific tests", () => {
-      it("should reject Windows drive letters", () => {
-        expect(() => sanitizePath("C:")).toThrow(
-          "Invalid path: Path contains invalid Windows characters",
-        );
-        expect(() => sanitizePath("D:\\file")).toThrow();
-      });
-
-      it("should reject UNC paths", () => {
-        expect(() => sanitizePath("\\\\server\\share")).toThrow(
-          "Invalid path: Absolute paths are not allowed",
-        );
-      });
-    });
-  }
-});

package/src/xulux/catalog-client.ts

@@ -1,150 +0,0 @@
-import { z } from "zod";
-import { logger } from "../utils/logger.js";
-import { FALLBACK_CATALOG, FALLBACK_NOTE } from "./fallback-catalog.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();
-  return override || DEFAULT_CATALOG_URL;
-}
-
-function validateCatalog(data: unknown): XuluxCatalog {
-  // 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(version)}. Expected ${XULUX_MCP_CATALOG_VERSION}.`,
-    );
-  }
-  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;
-}
-
-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

@@ -1,63 +0,0 @@
-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

@@ -1,56 +0,0 @@
-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;
-}