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

package/src/tools/tests/mcp-protocol.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect } from "vitest";
+import { server } from "../../index.js";
+import {
+  InitializeRequestSchema,
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  type InitializeRequest,
+  type ListToolsRequest,
+  type CallToolRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+
+describe("MCP Protocol Integration", () => {
+  // These tests verify the MCP protocol layer handles requests correctly
+  // and that parameter schemas are properly converted to JSON schemas
+  it("should handle Initialize request", async () => {
+    const request: InitializeRequest = {
+      method: "initialize",
+      params: {
+        protocolVersion: "2024-11-05",
+        capabilities: {
+          tools: {},
+        },
+        clientInfo: {
+          name: "test-client",
+          version: "1.0.0",
+        },
+      },
+    };
+
+    // Parse and validate the request
+    const parsed = InitializeRequestSchema.parse(request);
+    expect(parsed).toBeDefined();
+
+    // The server should have an initialize handler set up
+    const handlers = (server as any).server._requestHandlers;
+    expect(handlers).toBeDefined();
+    expect(handlers.get("initialize")).toBeDefined();
+  });
+
+  it("should handle ListTools request", async () => {
+    const request: ListToolsRequest = {
+      method: "tools/list",
+      params: {},
+    };
+
+    // Parse and validate the request
+    const parsed = ListToolsRequestSchema.parse(request);
+    expect(parsed).toBeDefined();
+
+    // The server should have a tools/list handler
+    const handlers = (server as any).server._requestHandlers;
+    expect(handlers.get("tools/list")).toBeDefined();
+
+    // Call the handler
+    const handler = handlers.get("tools/list");
+    const result = await handler(parsed, {});
+
+    expect(result).toBeDefined();
+    expect(result.tools).toBeInstanceOf(Array);
+    expect(result.tools).toHaveLength(2);
+
+    // Check the tools have proper JSON schemas
+    const docsTool = result.tools.find(
+      (t: any) => t.name === "assistantUIDocs",
+    );
+    expect(docsTool).toBeDefined();
+    expect(docsTool.inputSchema).toBeDefined();
+    expect(docsTool.inputSchema.type).toBe("object");
+    expect(docsTool.inputSchema.properties).toBeDefined();
+
+    const examplesTool = result.tools.find(
+      (t: any) => t.name === "assistantUIExamples",
+    );
+    expect(examplesTool).toBeDefined();
+    expect(examplesTool.inputSchema).toBeDefined();
+    expect(examplesTool.inputSchema.type).toBe("object");
+    expect(examplesTool.inputSchema.properties).toBeDefined();
+  });
+
+  it("should handle CallTool request for assistantUIDocs", async () => {
+    const request: CallToolRequest = {
+      method: "tools/call",
+      params: {
+        name: "assistantUIDocs",
+        arguments: {
+          paths: ["/"],
+        },
+      },
+    };
+
+    // Parse and validate the request
+    const parsed = CallToolRequestSchema.parse(request);
+    expect(parsed).toBeDefined();
+
+    // The server should have a tools/call handler
+    const handlers = (server as any).server._requestHandlers;
+    expect(handlers.get("tools/call")).toBeDefined();
+
+    // Call the handler through the MCP protocol layer
+    const handler = handlers.get("tools/call");
+    const result = await handler(parsed, {});
+
+    expect(result).toBeDefined();
+    expect(result.content).toBeDefined();
+    expect(result.content[0].type).toBe("text");
+  });
+
+  it("should handle CallTool request for assistantUIExamples with no arguments", async () => {
+    const request: CallToolRequest = {
+      method: "tools/call",
+      params: {
+        name: "assistantUIExamples",
+        arguments: {},
+      },
+    };
+
+    // Parse and validate the request
+    const parsed = CallToolRequestSchema.parse(request);
+    expect(parsed).toBeDefined();
+
+    // The server should have a tools/call handler
+    const handlers = (server as any).server._requestHandlers;
+    expect(handlers.get("tools/call")).toBeDefined();
+
+    // Call the handler
+    const handler = handlers.get("tools/call");
+    const result = await handler(parsed, {});
+
+    expect(result).toBeDefined();
+    expect(result.content).toBeDefined();
+    expect(result.content[0].type).toBe("text");
+  });
+});

package/src/tools/tests/path-traversal.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from "vitest";
+import { testContext } from "./test-setup.js";
+
+describe("Path Traversal Security", () => {
+  describe("assistantUIDocs tool", () => {
+    const maliciousPaths = [
+      "../../../../etc/passwd",
+      "../../../package.json",
+      "..\\..\\..\\windows\\system32",
+      "/etc/passwd",
+      "docs/../../../sensitive-file",
+      "./../../private/keys",
+    ];
+
+    maliciousPaths.forEach((path) => {
+      it(`should block path traversal attempt: ${path}`, async () => {
+        const result = await testContext.callTool("assistantUIDocs", {
+          paths: [path],
+        });
+
+        expect(result.error).toBeDefined();
+        expect(result.error).toContain("Invalid path");
+        expect(result.content).toBeUndefined();
+      });
+    });
+
+    it("should handle multiple paths with one malicious", async () => {
+      const result = await testContext.callTool("assistantUIDocs", {
+        paths: ["getting-started", "../../../../etc/passwd", "guides"],
+      });
+
+      expect(result.results).toBeDefined();
+      expect(result.results).toHaveLength(3);
+
+      expect(result.results[0].found).toBe(true);
+      expect(result.results[1].error).toContain("Invalid path");
+      expect(result.results[2].found).toBe(true);
+    });
+  });
+
+  describe("assistantUIExamples tool", () => {
+    const maliciousExamples = [
+      "../../../../etc/passwd",
+      "../../../src/index",
+      "..\\..\\..\\config",
+      "/root/.ssh/id_rsa",
+      "examples/../../../private",
+    ];
+
+    maliciousExamples.forEach((example) => {
+      it(`should block path traversal attempt: ${example}`, async () => {
+        const result = await testContext.callTool("assistantUIExamples", {
+          example,
+        });
+
+        expect(result.error).toBeDefined();
+        expect(result.error).toContain("Example not found");
+        expect(result.content).toBeUndefined();
+      });
+    });
+  });
+
+  describe("Valid paths should still work", () => {
+    it("should allow valid documentation paths", async () => {
+      const result = await testContext.callTool("assistantUIDocs", {
+        paths: ["getting-started", "api-reference/primitives/Thread"],
+      });
+
+      expect(result.results).toBeDefined();
+      expect(result.results).toHaveLength(2);
+      expect(result.results.every((r: any) => r.found || r.error)).toBe(true);
+    });
+
+    it("should allow valid example names", async () => {
+      const result = await testContext.callTool("assistantUIExamples", {});
+
+      expect(result.examples).toBeDefined();
+      expect(Array.isArray(result.examples)).toBe(true);
+    });
+  });
+});

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

@@ -0,0 +1,40 @@
+import { beforeAll } from "vitest";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { PACKAGE_DIR } from "../../constants.js";
+import { docsTools } from "../docs.js";
+import { examplesTools } from "../examples.js";
+
+const tools = {
+  assistantUIDocs: docsTools,
+  assistantUIExamples: examplesTools,
+};
+
+export const testContext = {
+  callTool: async (name: string, args: any) => {
+    const tool = tools[name as keyof typeof tools];
+    if (!tool) {
+      throw new Error(`Tool ${name} not found`);
+    }
+    const result = await tool.execute(args);
+
+    const text = result.content?.[0]?.text;
+    if (text === undefined) {
+      throw new Error(`Tool ${name} returned no content`);
+    }
+    try {
+      return JSON.parse(text);
+    } catch (error) {
+      throw new Error(
+        `Tool ${name} returned invalid JSON. Output: ${text}\nParse error: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  },
+};
+
+beforeAll(() => {
+  const docsPath = join(PACKAGE_DIR, ".docs");
+  if (!existsSync(docsPath)) {
+    throw new Error("Documentation not prepared. Run: pnpm build");
+  }
+});

package/src/utils/logger.ts

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

@@ -0,0 +1,12 @@
+export function formatMCPResponse(data: any): {
+  content: Array<{ type: "text"; text: string }>;
+} {
+  return {
+    content: [
+      {
+        type: "text",
+        text: typeof data === "string" ? data : JSON.stringify(data, null, 2),
+      },
+    ],
+  };
+}

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 };