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

package/package.json

@@ -1,46 +1,64 @@
 {
   "name": "@assistant-ui/mcp-docs-server",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "MCP server for assistant-ui documentation and examples",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "assistant-ui",
+    "documentation",
+    "ai",
+    "claude"
+  ],
+  "author": "AgentbaseAI Inc.",
+  "license": "MIT",
   "type": "module",
-  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "aui-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "bin": {
     "assistant-ui-mcp": "./dist/stdio.js"
   },
+  "files": [
+    "dist",
+    "src",
+    ".docs",
+    "README.md"
+  ],
+  "sideEffects": false,
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.24.3",
-    "zod": "^4.1.13",
+    "@modelcontextprotocol/sdk": "^1.25.3",
     "gray-matter": "^4.0.3",
-    "cross-env": "^10.1.0"
+    "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@types/node": "^25.0.0",
-    "tsup": "^8.5.1",
+    "@types/node": "^25.0.9",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.15"
+    "vitest": "^4.0.17",
+    "@assistant-ui/x-buildutils": "0.0.1"
   },
-  "files": [
-    "dist",
-    ".docs",
-    "README.md"
-  ],
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
+  "homepage": "https://www.assistant-ui.com/",
   "repository": {
     "type": "git",
-    "url": "https://github.com/assistant-ui/assistant-ui/tree/main/packages/mcp-docs-server"
+    "url": "git+https://github.com/assistant-ui/assistant-ui.git",
+    "directory": "packages/mcp-docs-server"
   },
   "bugs": {
     "url": "https://github.com/assistant-ui/assistant-ui/issues"
   },
   "scripts": {
-    "clean": "tsx scripts/clean.mts",
-    "prepare-docs": "cross-env PREPARE=true node ./dist/prepare-docs/prepare.js",
-    "build:cli": "tsup src/stdio.ts src/prepare-docs/prepare.ts src/index.ts --format esm --treeshake=smallest --splitting",
-    "build": "pnpm clean && pnpm build:cli && pnpm prepare-docs",
+    "prepare-docs": "node ./dist/prepare-docs/prepare.js",
+    "build": "aui-build && pnpm prepare-docs",
     "dev": "tsx src/stdio.ts",
     "pretest": "pnpm build",
     "test": "vitest run",

package/src/constants.ts

@@ -0,0 +1,22 @@
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export const ROOT_DIR = join(__dirname, "../../../");
+export const PACKAGE_DIR = join(__dirname, "../");
+
+export const EXAMPLES_PATH = join(ROOT_DIR, "examples");
+
+const DOCS_BASE = join(PACKAGE_DIR, ".docs");
+export const DOCS_PATH = join(DOCS_BASE, "raw/docs");
+export const CODE_EXAMPLES_PATH = join(DOCS_BASE, "organized/code-examples");
+
+export const MDX_EXTENSION = ".mdx";
+export const MD_EXTENSION = ".md";
+
+export const MAX_FILE_SIZE = 10 * 1024 * 1024;
+
+export const IS_PREPARE_MODE = process.argv[1]?.includes(
+  "prepare-docs/prepare",
+);

package/src/index.ts

@@ -0,0 +1,51 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { docsTools } from "./tools/docs.js";
+import { examplesTools } from "./tools/examples.js";
+import { logger } from "./utils/logger.js";
+import { PACKAGE_DIR } from "./constants.js";
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const packageJson = JSON.parse(
+  readFileSync(join(PACKAGE_DIR, "package.json"), "utf-8"),
+);
+
+export const server = new McpServer({
+  name: "assistant-ui-docs",
+  version: packageJson.version,
+});
+
+server.tool(
+  docsTools.name,
+  docsTools.description,
+  docsTools.parameters,
+  docsTools.execute,
+);
+server.tool(
+  examplesTools.name,
+  examplesTools.description,
+  examplesTools.parameters,
+  examplesTools.execute,
+);
+
+export async function runServer() {
+  try {
+    logger.info(
+      `Starting assistant-ui MCP docs server v${packageJson.version}`,
+    );
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+  } catch (error) {
+    logger.error("Failed to start MCP server", error);
+    process.exit(1);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  void runServer().catch((error) => {
+    console.error("Failed to start server:", error);
+    process.exit(1);
+  });
+}

package/src/prepare-docs/code-examples.ts

@@ -0,0 +1,158 @@
+import { rm, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join, relative, extname } from "node:path";
+import { logger } from "../utils/logger.js";
+import { ROOT_DIR, EXAMPLES_PATH } from "../constants.js";
+
+const OUTPUT_DIR = join(
+  ROOT_DIR,
+  "packages/mcp-docs-server/.docs/organized/code-examples",
+);
+const MAX_LINES = 10000;
+
+interface FileContent {
+  path: string;
+  content: string;
+}
+
+async function scanDirectory(
+  dir: string,
+  baseDir: string,
+): Promise<FileContent[]> {
+  const files: FileContent[] = [];
+
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        const skipDirs = [
+          "node_modules",
+          "dist",
+          "build",
+          ".next",
+          ".git",
+          ".turbo",
+        ];
+        if (!skipDirs.includes(entry.name)) {
+          const subFiles = await scanDirectory(fullPath, baseDir);
+          files.push(...subFiles);
+        }
+      } else if (entry.isFile()) {
+        const includeExts = [
+          ".ts",
+          ".tsx",
+          ".js",
+          ".jsx",
+          ".json",
+          ".css",
+          ".md",
+          ".mdx",
+        ];
+        const ext = extname(entry.name).toLowerCase();
+
+        if (
+          includeExts.includes(ext) ||
+          entry.name === "package.json" ||
+          entry.name === "tsconfig.json"
+        ) {
+          try {
+            const content = await readFile(fullPath, "utf-8");
+            const relativePath = relative(baseDir, fullPath);
+            files.push({ path: relativePath, content });
+          } catch (error) {
+            logger.warn(`Failed to read file: ${fullPath}`, error);
+          }
+        }
+      }
+    }
+  } catch (error) {
+    logger.error(`Failed to scan directory: ${dir}`, error);
+  }
+
+  return files;
+}
+
+function getFileType(filename: string): string {
+  const ext = extname(filename).toLowerCase();
+  const extMap: Record<string, string> = {
+    ".ts": "typescript",
+    ".tsx": "tsx",
+    ".js": "javascript",
+    ".jsx": "jsx",
+    ".json": "json",
+    ".css": "css",
+    ".md": "markdown",
+    ".mdx": "mdx",
+  };
+  return extMap[ext] || "text";
+}
+
+export async function prepareCodeExamples(): Promise<void> {
+  logger.info("Preparing code examples...");
+
+  try {
+    await rm(OUTPUT_DIR, { recursive: true, force: true });
+    await mkdir(OUTPUT_DIR, { recursive: true });
+
+    const exampleDirs = await readdir(EXAMPLES_PATH, { withFileTypes: true });
+
+    for (const dir of exampleDirs) {
+      if (dir.isDirectory() && !dir.name.startsWith(".")) {
+        const examplePath = join(EXAMPLES_PATH, dir.name);
+        logger.info(`Processing example: ${dir.name}`);
+
+        let description = "";
+        try {
+          const packageJsonPath = join(examplePath, "package.json");
+          const packageJson = JSON.parse(
+            await readFile(packageJsonPath, "utf-8"),
+          );
+          description = packageJson.description || "";
+        } catch (error: any) {
+          if (error?.code !== "ENOENT") {
+            logger.warn(`Failed to read package.json for ${dir.name}:`, error);
+          } else {
+            logger.debug(`No package.json found for example: ${dir.name}`);
+          }
+        }
+
+        const files = await scanDirectory(examplePath, examplePath);
+
+        files.sort((a, b) => a.path.localeCompare(b.path));
+
+        let markdown = `# Example: ${dir.name}\n\n`;
+        if (description) {
+          markdown += `${description}\n\n`;
+        }
+
+        let totalLines = 0;
+        for (const file of files) {
+          const lines = file.content.split("\n").length;
+          if (totalLines + lines > MAX_LINES) {
+            markdown += `\n_Note: Additional files truncated due to size limits_\n`;
+            break;
+          }
+
+          // Normalize Windows backslashes to forward slashes for consistent markdown output
+          markdown += `## ${file.path.replace(/\\/g, "/")}\n\n`;
+          markdown += `\`\`\`${getFileType(file.path)}\n`;
+          markdown += file.content;
+          markdown += `\n\`\`\`\n\n`;
+
+          totalLines += lines;
+        }
+
+        const outputPath = join(OUTPUT_DIR, `${dir.name}.md`);
+        await writeFile(outputPath, markdown, "utf-8");
+        logger.debug(`Created example: ${outputPath}`);
+      }
+    }
+
+    logger.info("Code examples preparation complete");
+  } catch (error) {
+    logger.error("Failed to prepare code examples", error);
+    throw error;
+  }
+}

package/src/prepare-docs/copy-raw.ts

@@ -0,0 +1,55 @@
+import { rm, mkdir, readdir, copyFile } from "node:fs/promises";
+import { join, extname } from "node:path";
+import { logger } from "../utils/logger.js";
+import { ROOT_DIR } from "../constants.js";
+
+const DOCS_SOURCE = join(ROOT_DIR, "apps/docs/content/docs");
+const BLOG_SOURCE = join(ROOT_DIR, "apps/docs/content/blog");
+const DOCS_DEST = join(ROOT_DIR, "packages/mcp-docs-server/.docs/raw");
+
+async function copyDir(src: string, dest: string): Promise<void> {
+  try {
+    await mkdir(dest, { recursive: true });
+    const entries = await readdir(src, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const srcPath = join(src, entry.name);
+      const destPath = join(dest, entry.name);
+
+      if (entry.isDirectory()) {
+        await copyDir(srcPath, destPath);
+      } else if (entry.isFile()) {
+        const ext = extname(entry.name).toLowerCase();
+        if (ext === ".mdx" || ext === ".md") {
+          await copyFile(srcPath, destPath);
+          logger.debug(`Copied: ${srcPath} -> ${destPath}`);
+        }
+      }
+    }
+  } catch (error) {
+    logger.error(`Failed to copy directory: ${src}`, error);
+    throw error;
+  }
+}
+
+export async function copyRaw(): Promise<void> {
+  logger.info("Copying raw documentation files...");
+
+  try {
+    await rm(DOCS_DEST, { recursive: true, force: true });
+    await mkdir(DOCS_DEST, { recursive: true });
+
+    const docsPath = join(DOCS_DEST, "docs");
+    await copyDir(DOCS_SOURCE, docsPath);
+    logger.info(`Copied documentation to ${docsPath}`);
+
+    const blogPath = join(DOCS_DEST, "blog");
+    await copyDir(BLOG_SOURCE, blogPath);
+    logger.info(`Copied blog posts to ${blogPath}`);
+
+    logger.info("Raw documentation copy complete");
+  } catch (error) {
+    logger.error("Failed to copy raw documentation", error);
+    throw error;
+  }
+}

package/src/prepare-docs/prepare.ts

@@ -0,0 +1,24 @@
+import { logger } from "../utils/logger.js";
+import { copyRaw } from "./copy-raw.js";
+import { prepareCodeExamples } from "./code-examples.js";
+
+async function prepare(): Promise<void> {
+  logger.info("Starting documentation preparation...");
+
+  try {
+    await copyRaw();
+    await prepareCodeExamples();
+
+    logger.info("Documentation preparation complete");
+  } catch (error) {
+    logger.error("Documentation preparation failed", error);
+    throw error;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  prepare().catch((error) => {
+    logger.error("Preparation failed", error);
+    process.exit(1);
+  });
+}

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),
+      });
+    }
+  },
+};