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

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-v6", expected: "examples/with-ai-sdk-v6" },
+      { 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/.docs/raw/docs/index.mdx

@@ -1,7 +0,0 @@
----
-title: "Documentation"
----
-
-import { redirect } from "next/navigation";
-
-<>{redirect("/docs/getting-started")}</>

package/.docs/raw/docs/ui/AssistantModal.mdx

@@ -1,45 +0,0 @@
----
-title: AssistantModal
----
-
-import { Steps, Step } from "fumadocs-ui/components/steps";
-import { InstallCommand } from "@/components/docs/install-command";
-import { AssistantModalSample } from "@/components/samples/assistant-modal-sample";
-
-## Overview
-
-A chat bubble shown in the bottom right corner of the screen. Useful for support or Q&A use cases.
-
-<AssistantModalSample />
-
-
-## Getting Started
-
-<Steps>
-  <Step>
-
-### Add `assistant-modal`
-
-<InstallCommand shadcn={["assistant-modal"]} />
-
-This adds `/components/assistant-ui/assistant-modal.tsx` to your project, which you can adjust as needed.
-
-  </Step>
-  <Step>
-
-### Use in your application
-
-```tsx title="/app/page.tsx" {1,6}
-import { AssistantModal } from "@/components/assistant-ui/assistant-modal";
-
-export default function Home() {
-  return (
-    <div className="h-full">
-      <AssistantModal />
-    </div>
-  );
-}
-```
-
-  </Step>
-</Steps>

package/.docs/raw/docs/ui/AssistantSidebar.mdx

@@ -1,41 +0,0 @@
----
-title: AssistantSidebar
----
-
-import { Steps, Step } from "fumadocs-ui/components/steps";
-import { InstallCommand } from "@/components/docs/install-command";
-
-## Overview
-
-A chat sidebar show on the right side of the screen. Useful for co-pilot use cases.
-
-## Getting Started
-
-<Steps> 
-  <Step>
-
-### Add `assistant-sidebar`
-
-<InstallCommand shadcn={["assistant-sidebar"]} />
-
-This adds `/components/assistant-ui/assistant-sidebar.tsx` to your project, which you can adjust as needed.
-
-  </Step>
-  <Step>
-
-### Use in your application
-
-```tsx title="/app/page.tsx" {1,6}
-import { AssistantSidebar } from "@/components/assistant-ui/assistant-sidebar";
-
-export default function Home() {
-  return (
-    <div className="h-full">
-      <AssistantSidebar>{/* your app */}</AssistantSidebar>
-    </div>
-  );
-}
-```
-
-  </Step>
-</Steps>

package/.docs/raw/docs/ui/Attachment.mdx

@@ -1,84 +0,0 @@
----
-title: Attachment
----
-
-import { Steps, Step } from "fumadocs-ui/components/steps";
-import { AttachmentSample } from "@/components/samples/attachment-sample";
-import { Callout } from "fumadocs-ui/components/callout";
-import { InstallCommand } from "@/components/docs/install-command";
-
-## Overview
-
-The Attachment components let the user attach files and view the attachments.
-
-<AttachmentSample />
-
-<Callout type="info">
-  **Note:** These components provide the UI for attachments, but you also need
-  to configure attachment adapters in your runtime to handle file uploads and
-  processing. See the [Attachments Guide](/docs/guides/Attachments) for complete
-  setup instructions.
-</Callout>
-
-## Getting Started
-
-<Steps>
-  <Step>
-
-### Add `attachment`
-
-<InstallCommand shadcn={["attachment"]} />
-
-This adds a `/components/assistant-ui/attachment.tsx` file to your project, which you can adjust as needed.
-
-  </Step>
-  <Step>
-
-### Use in your application
-
-```tsx title="/components/assistant-ui/thread.tsx" {1-4,9-10}
-import {
-  ComposerAttachments,
-  ComposerAddAttachment,
-} from "@/components/assistant-ui/attachment";
-
-const Composer: FC = () => {
-  return (
-    <ComposerPrimitive.Root className="...">
-      <ComposerAttachments />
-      <ComposerAddAttachment />
-
-      <ComposerPrimitive.Input
-        autoFocus
-        placeholder="Write a message..."
-        rows={1}
-        className="..."
-      />
-      <ComposerAction />
-    </ComposerPrimitive.Root>
-  );
-};
-```
-
-```tsx title="/components/assistant-ui/thread.tsx" {1,8}
-import { UserMessageAttachments } from "@/components/assistant-ui/attachment";
-
-const UserMessage: FC = () => {
-  return (
-    <MessagePrimitive.Root className="...">
-      <UserActionBar />
-
-      <UserMessageAttachments />
-
-      <div className="...">
-        <MessagePrimitive.Parts />
-      </div>
-
-      <BranchPicker className="..." />
-    </MessagePrimitive.Root>
-  );
-};
-```
-
-  </Step>
-</Steps>

package/.docs/raw/docs/ui/Reasoning.mdx

@@ -1,152 +0,0 @@
----
-title: Reasoning
----
-
-import { Steps, Step } from "fumadocs-ui/components/steps";
-import { InstallCommand } from "@/components/docs/install-command";
-
-## Overview
-
-The Reasoning component displays AI reasoning or thinking messages in a collapsible UI. Consecutive reasoning message parts are automatically grouped together with smooth animations and a shimmer effect while streaming.
-
-## Getting Started
-
-<Steps>
-  <Step>
-
-### Add `reasoning`
-
-<InstallCommand shadcn={["reasoning"]} />
-
-This adds a `/components/assistant-ui/reasoning.tsx` file to your project, which you can adjust as needed.
-
-  </Step>
-  <Step>
-
-### Use in your application
-
-Pass the `Reasoning` and `ReasoningGroup` components to the `MessagePrimitive.Parts` component:
-
-```tsx title="/app/components/assistant-ui/thread.tsx" {2,10-11}
-import { MessagePrimitive } from "@assistant-ui/react";
-import { Reasoning, ReasoningGroup } from "@/components/assistant-ui/reasoning";
-
-const AssistantMessage: FC = () => {
-  return (
-    <MessagePrimitive.Root className="...">
-      <div className="...">
-        <MessagePrimitive.Parts 
-          components={{ 
-            Reasoning: Reasoning,
-            ReasoningGroup: ReasoningGroup
-          }} 
-        />
-      </div>
-      <AssistantActionBar />
-
-      <BranchPicker className="..." />
-    </MessagePrimitive.Root>
-  );
-};
-```
-
-  </Step>
-</Steps>
-
-## How It Works
-
-The component consists of two parts:
-
-1. **Reasoning**: Renders individual reasoning message part content
-2. **ReasoningGroup**: Wraps consecutive reasoning parts in a collapsible container
-
-Consecutive reasoning parts are automatically grouped together by the `ReasoningGroup` component, similar to how `ToolGroup` handles tool calls.
-
-### Reasoning
-
-The Reasoning component doesn't accept additional props—it renders the reasoning text content with markdown support.
-
-## Examples
-
-### Basic Usage
-
-```tsx title="/app/components/assistant-ui/thread.tsx"
-<MessagePrimitive.Parts 
-  components={{ 
-    Reasoning,
-    ReasoningGroup 
-  }} 
-/>
-```
-
-### Custom Styling
-
-Since the component is copied to your project, you can customize it directly by modifying the `reasoning.tsx` file. The internal components (`ReasoningRoot`, `ReasoningTrigger`, `ReasoningContent`, `ReasoningText`) accept `className` props for styling:
-
-```tsx title="/components/assistant-ui/reasoning.tsx"
-const ReasoningGroupImpl: ReasoningGroupComponent = ({
-  // ... existing code ...
-  return (
-    <ReasoningRoot className="rounded-lg border bg-muted/50 p-4">
-      <ReasoningTrigger 
-        active={isReasoningStreaming} 
-        className="font-semibold text-foreground"
-      />
-      <ReasoningContent 
-        aria-busy={isReasoningStreaming}
-        className="mt-2"
-      >
-        <ReasoningText className="text-base">{children}</ReasoningText>
-      </ReasoningContent>
-    </ReasoningRoot>
-  );
-};
-```
-
-You can also customize the individual internal components:
-
-```tsx title="/components/assistant-ui/reasoning.tsx"
-const ReasoningRoot: FC<PropsWithChildren<{ className?: string }>> = ({ 
-  // ... existing code ...
-  return (
-    <Collapsible
-      // ...
-      className={cn("aui-reasoning-root mb-4 w-full rounded-lg border bg-muted/50 p-4", className)}
-      // ...
-    >
-      {children}
-    </Collapsible>
-  );
-};
-
-const ReasoningTrigger: FC<{ active: boolean; className?: string }> = ({
-  // ... existing code ...
-  <CollapsibleTrigger
-    className={cn(
-      "aui-reasoning-trigger group/trigger -mb-2 flex max-w-[75%] items-center gap-2 py-2 text-sm font-semibold text-foreground transition-colors hover:text-foreground",
-      className,
-    )}
-  >
-    {/* ... existing content ... */}
-  </CollapsibleTrigger>
-);
-```
-
-## Technical Details
-
-### Scroll Lock
-
-The component uses the `useScrollLock` hook (exported from `@assistant-ui/react`) to prevent page jumps when collapsing the reasoning section. This maintains the scroll position during the collapse animation.
-
-### Animation Timing
-
-The component uses CSS custom properties for animation timing:
-- `--animation-duration`: Controls expand/collapse animation (default: 200ms)
-- `--shimmer-duration`: Controls the shimmer effect speed (default: 1000ms)
-
-These can be customized by modifying the CSS variables in your component.
-
-## Related Components
-
-- [ToolGroup](/docs/ui/ToolGroup) - Similar grouping pattern for tool calls
-- [PartGrouping](/docs/ui/PartGrouping) - Experimental API for grouping message parts