@assistant-ui/mcp-docs-server 0.1.16 → 0.1.18

package/src/utils/mdx.ts

@@ -0,0 +1,39 @@
+import { readFile } from "node:fs/promises";
+import matter from "gray-matter";
+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 function formatMDXContent(mdxContent: MDXContent): string {
+  const { content, frontmatter } = mdxContent;
+
+  return matter.stringify(content, frontmatter);
+}

package/src/utils/paths.ts

@@ -0,0 +1,114 @@
+import { readdir, stat } from "node:fs/promises";
+import { join, extname } from "node:path";
+import { DOCS_PATH, MDX_EXTENSION, MD_EXTENSION } from "../constants.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 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/security.ts

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

@@ -0,0 +1,119 @@
+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", expected: "examples/with-ai-sdk" },
+      { 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/dist/chunk-M2RKUM66.js

@@ -1,38 +0,0 @@
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-
-// src/constants.ts
-var __dirname$1 = dirname(fileURLToPath(import.meta.url));
-var ROOT_DIR = join(__dirname$1, "../../../");
-var PACKAGE_DIR = join(__dirname$1, "../");
-var EXAMPLES_PATH = join(ROOT_DIR, "examples");
-var DOCS_BASE = join(PACKAGE_DIR, ".docs");
-var DOCS_PATH = join(DOCS_BASE, "raw/docs");
-join(DOCS_BASE, "raw/blog");
-var CODE_EXAMPLES_PATH = join(DOCS_BASE, "organized/code-examples");
-var MDX_EXTENSION = ".mdx";
-var MD_EXTENSION = ".md";
-var MAX_FILE_SIZE = 10 * 1024 * 1024;
-var IS_PREPARE_MODE = process.env.PREPARE === "true";
-
-// src/utils/logger.ts
-var logger = {
-  debug: (message, ...args) => {
-    if (process.env.DEBUG) {
-      console.debug(`[DEBUG] ${message}`, ...args);
-    }
-  },
-  info: (message, ...args) => {
-    if (process.env.PREPARE === "true") {
-      console.log(`[INFO] ${message}`, ...args);
-    }
-  },
-  error: (message, ...args) => {
-    console.error(`[ERROR] ${message}`, ...args);
-  },
-  warn: (message, ...args) => {
-    console.warn(`[WARN] ${message}`, ...args);
-  }
-};
-
-export { CODE_EXAMPLES_PATH, DOCS_PATH, EXAMPLES_PATH, IS_PREPARE_MODE, MAX_FILE_SIZE, MDX_EXTENSION, MD_EXTENSION, ROOT_DIR, logger };