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

package/src/tools/xulux-templates.ts

@@ -1,141 +0,0 @@
-import { z } from "zod";
-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,
-  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,
-  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,
-  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

@@ -1,20 +0,0 @@
-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/logger.ts

@@ -1,20 +0,0 @@
-import { IS_PREPARE_MODE } from "../constants.js";
-
-export const logger = {
-  debug: (message: string, ...args: any[]) => {
-    if (process.env.DEBUG) {
-      console.debug(`[DEBUG] ${message}`, ...args);
-    }
-  },
-  info: (message: string, ...args: any[]) => {
-    if (IS_PREPARE_MODE) {
-      console.log(`[INFO] ${message}`, ...args);
-    }
-  },
-  error: (message: string, ...args: any[]) => {
-    console.error(`[ERROR] ${message}`, ...args);
-  },
-  warn: (message: string, ...args: any[]) => {
-    console.warn(`[WARN] ${message}`, ...args);
-  },
-};

package/src/utils/mcp-format.ts

@@ -1,14 +0,0 @@
-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 }],
-    ...(isStructured && {
-      structuredContent: data as Record<string, unknown>,
-    }),
-  };
-}

package/src/utils/mdx.ts

@@ -1,59 +0,0 @@
-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 {
-  content: string;
-  frontmatter: Record<string, any>;
-  excerpt?: string;
-}
-
-export async function readMDXFile(
-  filePath: string,
-): Promise<MDXContent | null> {
-  try {
-    const fileContent = await readFile(filePath, "utf-8");
-    const { content, data } = matter(fileContent);
-
-    const excerptMatch = content.match(/^(.+?)(?:\n\n|$)/);
-    const excerpt =
-      excerptMatch?.[1] !== undefined
-        ? excerptMatch[1].replace(/^#+ /, "")
-        : undefined;
-
-    return {
-      content,
-      frontmatter: data,
-      ...(excerpt !== undefined && { excerpt }),
-    };
-  } catch (error) {
-    logger.error(`Failed to read MDX file: ${filePath}`, error);
-    return null;
-  }
-}
-
-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;
-
-  return matter.stringify(content, frontmatter);
-}

package/src/utils/paths.ts

@@ -1,139 +0,0 @@
-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 = {
-  EXACT_MATCH: 1,
-  CONTAINS_MATCH: 0.8,
-  PARTIAL_MATCH: 0.5,
-  MIN_SUGGESTION: 0.3,
-} as const;
-
-export async function listDirContents(dirPath: string): Promise<{
-  directories: string[];
-  files: string[];
-}> {
-  try {
-    const items = await readdir(dirPath, { withFileTypes: true });
-
-    const directories = items
-      .filter((item) => item.isDirectory())
-      .map((item) => item.name)
-      .filter((name) => !name.startsWith("."))
-      .sort();
-
-    const files = items
-      .filter(
-        (item) =>
-          item.isFile() &&
-          (extname(item.name) === MDX_EXTENSION ||
-            extname(item.name) === MD_EXTENSION),
-      )
-      .map((item) => item.name)
-      .sort();
-
-    return { directories, files };
-  } catch (error) {
-    logger.error(`Failed to list directory contents: ${dirPath}`, error);
-    return { directories: [], files: [] };
-  }
-}
-
-export async function getAvailablePaths(): Promise<string[]> {
-  const paths: string[] = [];
-
-  async function scanDirectory(
-    dir: string,
-    prefix: string = "",
-  ): Promise<void> {
-    const { directories, files } = await listDirContents(dir);
-
-    for (const file of files) {
-      const name = file.replace(MDX_EXTENSION, "").replace(MD_EXTENSION, "");
-      paths.push(prefix ? `${prefix}/${name}` : name);
-    }
-
-    for (const subdir of directories) {
-      const subdirPath = join(dir, subdir);
-      const newPrefix = prefix ? `${prefix}/${subdir}` : subdir;
-      paths.push(newPrefix);
-      await scanDirectory(subdirPath, newPrefix);
-    }
-  }
-
-  await scanDirectory(DOCS_PATH);
-  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[],
-): string[] {
-  const normalizedRequest = requestedPath
-    .toLowerCase()
-    .replace(/[^a-z0-9]/g, "");
-
-  const scored = availablePaths.map((path) => {
-    const normalizedPath = path.toLowerCase().replace(/[^a-z0-9]/g, "");
-
-    if (normalizedPath.includes(normalizedRequest)) {
-      return { path, score: SIMILARITY_THRESHOLDS.EXACT_MATCH };
-    }
-
-    if (normalizedRequest.includes(normalizedPath)) {
-      return { path, score: SIMILARITY_THRESHOLDS.CONTAINS_MATCH };
-    }
-
-    const overlap = [...normalizedRequest].filter((char) =>
-      normalizedPath.includes(char),
-    ).length;
-
-    return {
-      path,
-      score:
-        (overlap / normalizedRequest.length) *
-        SIMILARITY_THRESHOLDS.PARTIAL_MATCH,
-    };
-  });
-
-  return scored
-    .filter((item) => item.score > SIMILARITY_THRESHOLDS.MIN_SUGGESTION)
-    .sort((a, b) => b.score - a.score)
-    .slice(0, 3)
-    .map((item) => item.path);
-}
-
-export async function pathExists(path: string): Promise<boolean> {
-  try {
-    await stat(path);
-    return true;
-  } catch {
-    return false;
-  }
-}

package/src/utils/search.ts

@@ -1,131 +0,0 @@
-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/security.ts

@@ -1,52 +0,0 @@
-import path from "node:path";
-
-export function sanitizePath(userPath: string): string {
-  if (!userPath || typeof userPath !== "string") {
-    throw new Error("Invalid path: Path must be a non-empty string");
-  }
-
-  // Check for traversal patterns before normalization - defense in depth
-  if (userPath.includes("../") || userPath.includes("..\\")) {
-    throw new Error("Invalid path: Directory traversal attempt detected");
-  }
-
-  const normalized = path.normalize(userPath);
-
-  if (path.isAbsolute(normalized)) {
-    throw new Error("Invalid path: Absolute paths are not allowed");
-  }
-
-  const relativePath = path.relative("", normalized);
-
-  if (relativePath.startsWith("..")) {
-    throw new Error("Invalid path: Directory traversal attempt detected");
-  }
-
-  if (relativePath.includes("..")) {
-    throw new Error("Invalid path: Path contains invalid traversal sequences");
-  }
-
-  if (relativePath.includes("\0")) {
-    throw new Error("Invalid path: Path contains null bytes");
-  }
-
-  if (process.platform !== "win32") {
-    if (normalized.includes("\\")) {
-      throw new Error("Invalid path: Backslashes not allowed");
-    }
-  } else {
-    if (normalized.includes(":") || normalized.startsWith("\\\\")) {
-      throw new Error("Invalid path: Path contains invalid Windows characters");
-    }
-  }
-
-  const segments = relativePath.split(path.sep);
-  for (const segment of segments) {
-    if (segment.startsWith(".") && segment !== ".") {
-      throw new Error("Invalid path: Hidden files are not allowed");
-    }
-  }
-
-  // Always return Unix-style paths for consistency across platforms
-  return relativePath.replace(/\\/g, "/");
-}

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

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

@@ -1,22 +0,0 @@
-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();
-  });
-});