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

package/src/stdio.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runServer } from "./index.js";
+
+void runServer().catch((error) => {
+  console.error("Failed to start server:", error);
+  process.exit(1);
+});

package/src/tools/docs.ts

@@ -0,0 +1,207 @@
+import { z } from "zod/v3";
+import { stat, lstat } from "node:fs/promises";
+import { join, extname } from "node:path";
+import { DOCS_PATH, MDX_EXTENSION, MAX_FILE_SIZE } from "../constants.js";
+import { logger } from "../utils/logger.js";
+import {
+  listDirContents,
+  getAvailablePaths,
+  findNearestPaths,
+  pathExists,
+} from "../utils/paths.js";
+import { readMDXFile, formatMDXContent } from "../utils/mdx.js";
+import { formatMCPResponse } from "../utils/mcp-format.js";
+import { sanitizePath } from "../utils/security.js";
+
+const docsInputSchema = z.object({
+  paths: z
+    .array(z.string())
+    .min(1)
+    .describe(
+      'Documentation paths to retrieve (e.g., ["getting-started", "api-reference/primitives/Thread"])',
+    ),
+});
+
+interface DocResult {
+  path: string;
+  found: boolean;
+  type?: "file" | "directory";
+  content?: string;
+  files?: string[];
+  directories?: string[];
+  suggestions?: string[];
+  error?: string;
+}
+
+async function readDocumentation(docPath: string): Promise<DocResult> {
+  logger.debug(`Reading documentation for path: ${docPath}`);
+
+  if (docPath === "/" || docPath === "") {
+    const { directories, files } = await listDirContents(DOCS_PATH);
+    return {
+      path: "/",
+      found: true,
+      type: "directory",
+      directories,
+      files: files.map((f) => f.replace(MDX_EXTENSION, "")),
+    };
+  }
+
+  try {
+    const sanitized = sanitizePath(docPath);
+    const fullPath = join(DOCS_PATH, sanitized);
+
+    try {
+      const lstats = await lstat(fullPath);
+      if (lstats.isSymbolicLink()) {
+        logger.warn(`Symlink detected at path: ${fullPath}`);
+        return {
+          path: docPath,
+          found: false,
+          error: "Symlinks are not allowed for security reasons",
+        };
+      }
+    } catch {}
+
+    if (await pathExists(fullPath)) {
+      const stats = await stat(fullPath);
+
+      if (stats.isFile() && stats.size > MAX_FILE_SIZE) {
+        logger.warn(`File too large: ${fullPath} (${stats.size} bytes)`);
+        return {
+          path: docPath,
+          found: false,
+          error: `File size exceeds maximum allowed size of ${MAX_FILE_SIZE} bytes`,
+        };
+      }
+
+      if (stats.isDirectory()) {
+        const { directories, files } = await listDirContents(fullPath);
+
+        const contents: Record<string, string> = {};
+        for (const file of files) {
+          const mdxContent = await readMDXFile(join(fullPath, file));
+          if (mdxContent) {
+            const fileName = file.replace(MDX_EXTENSION, "");
+            contents[fileName] = formatMDXContent(mdxContent);
+          }
+        }
+
+        const content =
+          Object.keys(contents).length > 0
+            ? JSON.stringify(contents, null, 2)
+            : undefined;
+        return {
+          path: docPath,
+          found: true,
+          type: "directory",
+          directories,
+          files: files.map((f) => f.replace(MDX_EXTENSION, "")),
+          ...(content !== undefined && { content }),
+        };
+      }
+    }
+
+    const mdxPath =
+      extname(fullPath) === MDX_EXTENSION
+        ? fullPath
+        : `${fullPath}${MDX_EXTENSION}`;
+
+    try {
+      const mdxLstats = await lstat(mdxPath);
+      if (mdxLstats.isSymbolicLink()) {
+        logger.warn(`Symlink detected at MDX path: ${mdxPath}`);
+        return {
+          path: docPath,
+          found: false,
+          error: "Symlinks are not allowed for security reasons",
+        };
+      }
+
+      if (mdxLstats.size > MAX_FILE_SIZE) {
+        logger.warn(`MDX file too large: ${mdxPath} (${mdxLstats.size} bytes)`);
+        return {
+          path: docPath,
+          found: false,
+          error: `File size exceeds maximum allowed size of ${MAX_FILE_SIZE} bytes`,
+        };
+      }
+    } catch {}
+
+    if (await pathExists(mdxPath)) {
+      const mdxContent = await readMDXFile(mdxPath);
+
+      if (mdxContent) {
+        return {
+          path: docPath,
+          found: true,
+          type: "file",
+          content: formatMDXContent(mdxContent),
+        };
+      }
+    }
+
+    const availablePaths = await getAvailablePaths();
+    const suggestions = findNearestPaths(docPath, availablePaths);
+
+    return {
+      path: docPath,
+      found: false,
+      suggestions,
+    };
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("Invalid path")) {
+      return {
+        path: docPath,
+        found: false,
+        error: error.message,
+      };
+    }
+    throw error;
+  }
+}
+
+export const docsTools = {
+  name: "assistantUIDocs",
+  description:
+    'Retrieve assistant-ui documentation by path. Use "/" to list all sections. Supports multiple paths in a single request.',
+  parameters: docsInputSchema.shape,
+  execute: async ({ paths }: z.infer<typeof docsInputSchema>) => {
+    logger.info(`Retrieving documentation for paths: ${paths.join(", ")}`);
+
+    try {
+      const results = await Promise.all(
+        paths.map((path) => readDocumentation(path)),
+      );
+
+      if (results.length === 1) {
+        const result = results[0]!;
+        if (result.error) {
+          return formatMCPResponse({
+            error: result.error,
+            path: result.path,
+          });
+        }
+        if (!result.found) {
+          return formatMCPResponse({
+            error: `Documentation not found for path: ${result.path}`,
+            suggestions: result.suggestions,
+            hint: 'Use "/" to list all available documentation sections',
+          });
+        }
+        return formatMCPResponse(result);
+      }
+
+      return formatMCPResponse({
+        results,
+        summary: `Retrieved ${results.filter((r) => r.found).length} of ${results.length} requested paths`,
+      });
+    } catch (error) {
+      logger.error("Failed to retrieve documentation", error);
+      return formatMCPResponse({
+        error: "Failed to retrieve documentation",
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  },
+};

package/src/tools/examples.ts

@@ -0,0 +1,107 @@
+import { z } from "zod/v3";
+import { readFile, readdir, lstat } from "node:fs/promises";
+import { join, extname } from "node:path";
+import { CODE_EXAMPLES_PATH, MAX_FILE_SIZE } from "../constants.js";
+import { logger } from "../utils/logger.js";
+import { formatMCPResponse } from "../utils/mcp-format.js";
+import { sanitizePath } from "../utils/security.js";
+
+const examplesInputSchema = z.object({
+  example: z
+    .string()
+    .optional()
+    .describe(
+      'Example name (e.g., "with-ai-sdk"). Leave empty to list all examples.',
+    ),
+});
+
+async function listCodeExamples(): Promise<string[]> {
+  try {
+    const files = await readdir(CODE_EXAMPLES_PATH);
+    return files
+      .filter((file) => extname(file) === ".md")
+      .map((file) => file.replace(".md", ""))
+      .sort();
+  } catch (error) {
+    logger.error("Failed to list code examples", error);
+    return [];
+  }
+}
+
+async function readCodeExample(exampleName: string): Promise<string | null> {
+  try {
+    const sanitized = sanitizePath(exampleName);
+    const filePath = join(CODE_EXAMPLES_PATH, `${sanitized}.md`);
+
+    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;
+    }
+
+    const content = await readFile(filePath, "utf-8");
+    return content;
+  } catch (error) {
+    logger.error(`Failed to read example: ${exampleName}`, error);
+    return null;
+  }
+}
+
+export const examplesTools = {
+  name: "assistantUIExamples",
+  description:
+    "List available examples or retrieve complete code for a specific example",
+  parameters: examplesInputSchema.shape,
+  execute: async ({ example }: z.infer<typeof examplesInputSchema>) => {
+    try {
+      if (!example) {
+        logger.info("Listing all available examples");
+        const examples = await listCodeExamples();
+
+        if (examples.length === 0) {
+          return formatMCPResponse({
+            error:
+              "No examples found. Please run documentation preparation first.",
+            hint: "Run: pnpm prepare-docs",
+          });
+        }
+
+        return formatMCPResponse({
+          type: "list",
+          examples,
+          total: examples.length,
+          hint: "Use example parameter to get complete code for any example",
+        });
+      }
+
+      logger.info(`Retrieving example: ${example}`);
+      const content = await readCodeExample(example);
+
+      if (!content) {
+        const availableExamples = await listCodeExamples();
+        return formatMCPResponse({
+          error: `Example not found: ${example}`,
+          availableExamples,
+          hint: "Use without example parameter to list all available examples",
+        });
+      }
+
+      return formatMCPResponse({
+        type: "example",
+        name: example,
+        content,
+      });
+    } catch (error) {
+      logger.error("Failed to retrieve examples", error);
+      return formatMCPResponse({
+        error: "Failed to retrieve examples",
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  },
+};

package/src/tools/tests/docs.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { testContext } from "./test-setup.js";
+import * as fs from "node:fs/promises";
+
+vi.mock("fs/promises", async () => {
+  const { readdir, readFile, stat, lstat } = await import("node:fs/promises");
+  return {
+    readdir,
+    readFile,
+    stat,
+    lstat: vi.fn(lstat),
+  };
+});
+
+describe("assistantUIDocs", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+  it("should list root directory contents", async () => {
+    const result = await testContext.callTool("assistantUIDocs", {
+      paths: ["/"],
+    });
+
+    expect(result.path).toBe("/");
+    expect(result.found).toBe(true);
+    expect(result.type).toBe("directory");
+    expect(result.directories).toContain("api-reference");
+    expect(result.directories).toContain("guides");
+    expect(result.files).toContain("getting-started");
+  });
+
+  it("should retrieve specific documentation file", async () => {
+    const result = await testContext.callTool("assistantUIDocs", {
+      paths: ["getting-started"],
+    });
+
+    expect(result.path).toBe("getting-started");
+    expect(result.found).toBe(true);
+    expect(result.type).toBe("file");
+    expect(result.content).toBeDefined();
+    expect(result.content).toContain("Getting Started");
+  });
+
+  it("should handle non-existent paths", async () => {
+    const result = await testContext.callTool("assistantUIDocs", {
+      paths: ["non-existent-path"],
+    });
+
+    expect(result.error).toBeDefined();
+    expect(result.error).toContain("Documentation not found");
+    expect(result.suggestions).toBeDefined();
+  });
+
+  it("should support multiple path requests", 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[0].path).toBe("getting-started");
+    expect(result.results[1].path).toBe("api-reference/primitives/Thread");
+  });
+
+  it("should list directory contents with files", async () => {
+    const result = await testContext.callTool("assistantUIDocs", {
+      paths: ["api-reference/primitives"],
+    });
+
+    expect(result.path).toBe("api-reference/primitives");
+    expect(result.found).toBe(true);
+    expect(result.type).toBe("directory");
+    expect(result.files).toContain("Thread");
+    expect(result.files).toContain("Message");
+    expect(result.files).toContain("Composer");
+  });
+
+  it("should parse MDX files with frontmatter", async () => {
+    const result = await testContext.callTool("assistantUIDocs", {
+      paths: ["getting-started"],
+    });
+
+    expect(result.content).toBeDefined();
+    expect(result.content).toContain("title:");
+    expect(result.content).toContain("Getting Started");
+  });
+
+  it("should skip symlinks and large files", async () => {
+    const mockedLstat = vi.mocked(fs.lstat);
+
+    mockedLstat.mockResolvedValueOnce({
+      isSymbolicLink: () => true,
+      isFile: () => false,
+      isDirectory: () => false,
+    } as any);
+
+    const symlinkResult = await testContext.callTool("assistantUIDocs", {
+      paths: ["symlink-test"],
+    });
+    expect(symlinkResult.error).toBe(
+      "Symlinks are not allowed for security reasons",
+    );
+
+    mockedLstat.mockRejectedValueOnce(new Error("ENOENT"));
+    mockedLstat.mockResolvedValueOnce({
+      isSymbolicLink: () => false,
+      isFile: () => true,
+      size: 11 * 1024 * 1024,
+    } as any);
+
+    const largeFileResult = await testContext.callTool("assistantUIDocs", {
+      paths: ["large-file"],
+    });
+    expect(largeFileResult.error).toContain(
+      "File size exceeds maximum allowed size",
+    );
+  });
+});

package/src/tools/tests/examples.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, vi } from "vitest";
+import { testContext } from "./test-setup.js";
+import * as fs from "node:fs/promises";
+
+vi.mock("fs/promises", async () => {
+  const { readdir, readFile, lstat } = await import("node:fs/promises");
+  return {
+    readdir,
+    readFile,
+    lstat: vi.fn(lstat),
+  };
+});
+
+describe("assistantUIExamples", () => {
+  it("should list all available examples", async () => {
+    const result = await testContext.callTool("assistantUIExamples", {});
+
+    expect(result.type).toBe("list");
+    expect(result.examples).toBeDefined();
+    expect(Array.isArray(result.examples)).toBe(true);
+    expect(result.examples.length).toBeGreaterThan(0);
+    expect(result.examples).toContain("with-ai-sdk-v5");
+    expect(result.examples).toContain("with-langgraph");
+    expect(result.total).toBe(result.examples.length);
+  });
+
+  it("should retrieve specific example code", async () => {
+    const result = await testContext.callTool("assistantUIExamples", {
+      example: "with-ai-sdk-v5",
+    });
+
+    expect(result.type).toBe("example");
+    expect(result.name).toBe("with-ai-sdk-v5");
+    expect(result.content).toBeDefined();
+    expect(result.content).toContain("# Example: with-ai-sdk-v5");
+    expect(result.content).toContain("app/api/chat/route.ts");
+    expect(result.content).toContain("streamText");
+  });
+
+  it("should handle non-existent examples", async () => {
+    const result = await testContext.callTool("assistantUIExamples", {
+      example: "non-existent-example",
+    });
+
+    expect(result.error).toBeDefined();
+    expect(result.error).toContain("Example not found");
+    expect(result.availableExamples).toBeDefined();
+    expect(Array.isArray(result.availableExamples)).toBe(true);
+  });
+
+  it("should include all files in example", async () => {
+    const result = await testContext.callTool("assistantUIExamples", {
+      example: "with-ai-sdk-v5",
+    });
+
+    expect(result.content).toContain("package.json");
+    expect(result.content).toContain("components/assistant-ui/thread.tsx");
+  });
+
+  it("should handle empty example parameter", async () => {
+    const result = await testContext.callTool("assistantUIExamples", {
+      example: undefined,
+    });
+
+    expect(result.type).toBe("list");
+    expect(result.hint).toBeDefined();
+  });
+
+  it("should skip symlinks and large files", async () => {
+    const mockedLstat = vi.mocked(fs.lstat);
+
+    mockedLstat.mockResolvedValueOnce({
+      isSymbolicLink: () => true,
+      isFile: () => false,
+      size: 0,
+    } as any);
+
+    const symlinkResult = await testContext.callTool("assistantUIExamples", {
+      example: "symlink-example",
+    });
+    expect(symlinkResult.error).toContain("Example not found");
+
+    mockedLstat.mockResolvedValueOnce({
+      isSymbolicLink: () => false,
+      isFile: () => true,
+      size: 11 * 1024 * 1024, // 11MB - exceeds MAX_FILE_SIZE
+    } as any);
+
+    const largeFileResult = await testContext.callTool("assistantUIExamples", {
+      example: "large-example",
+    });
+    expect(largeFileResult.error).toContain("Example not found");
+  });
+});

package/src/tools/tests/integration.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+import { server } from "../../index.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { docsTools } from "../docs.js";
+import { examplesTools } from "../examples.js";
+
+describe("MCP Server Integration", () => {
+  it("should be an instance of McpServer", () => {
+    expect(server).toBeInstanceOf(McpServer);
+  });
+
+  it("should have tools with correct properties", () => {
+    expect(docsTools.name).toBe("assistantUIDocs");
+    expect(docsTools.description).toContain(
+      "Retrieve assistant-ui documentation",
+    );
+    expect(docsTools.parameters).toBeDefined();
+    expect(docsTools.execute).toBeInstanceOf(Function);
+
+    expect(examplesTools.name).toBe("assistantUIExamples");
+    expect(examplesTools.description).toContain("List available examples");
+    expect(examplesTools.parameters).toBeDefined();
+    expect(examplesTools.execute).toBeInstanceOf(Function);
+  });
+
+  it("should have valid input schemas", () => {
+    // docsTools.parameters is the Zod schema shape
+    expect(docsTools.parameters).toBeDefined();
+    expect(Object.keys(docsTools.parameters)).toContain("paths");
+
+    expect(examplesTools.parameters).toBeDefined();
+    expect(Object.keys(examplesTools.parameters)).toContain("example");
+  });
+
+  it("should execute tools successfully", async () => {
+    const docsResult = await docsTools.execute({ paths: ["/"] });
+    expect(docsResult).toBeDefined();
+    expect(docsResult.content).toBeDefined();
+    expect(docsResult.content[0].type).toBe("text");
+
+    const examplesResult = await examplesTools.execute({});
+    expect(examplesResult).toBeDefined();
+    expect(examplesResult.content).toBeDefined();
+    expect(examplesResult.content[0].type).toBe("text");
+  });
+});

package/src/tools/tests/json-parsing.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { testContext } from "./test-setup.js";
+import { docsTools } from "../docs.js";
+
+describe("JSON parsing error handling", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should provide helpful error message for invalid JSON", async () => {
+    vi.spyOn(docsTools, "execute").mockResolvedValue({
+      content: [{ text: "invalid json {not valid}" }],
+    });
+
+    await expect(
+      testContext.callTool("assistantUIDocs", { paths: ["/"] }),
+    ).rejects.toThrow(/Tool assistantUIDocs returned invalid JSON/);
+
+    await expect(
+      testContext.callTool("assistantUIDocs", { paths: ["/"] }),
+    ).rejects.toThrow(/invalid json \{not valid\}/);
+  });
+});