@assistant-ui/mcp-docs-server 0.1.1

package/dist/chunk-CZCDQ3YH.js

@@ -0,0 +1,420 @@
+import { logger, IS_PREPARE_MODE, MDX_EXTENSION, DOCS_PATH, MAX_FILE_SIZE, CODE_EXAMPLES_PATH, MD_EXTENSION } from './chunk-C7O7EFKU.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { lstat, stat, readdir, readFile } from 'fs/promises';
+import path, { dirname, join, extname, normalize, relative } from 'path';
+import matter from 'gray-matter';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+
+var SIMILARITY_THRESHOLDS = {
+  EXACT_MATCH: 1,
+  CONTAINS_MATCH: 0.8,
+  PARTIAL_MATCH: 0.5,
+  MIN_SUGGESTION: 0.3
+};
+async function listDirContents(dirPath) {
+  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: [] };
+  }
+}
+async function getAvailablePaths() {
+  const paths = [];
+  async function scanDirectory(dir, prefix = "") {
+    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();
+}
+function findNearestPaths(requestedPath, availablePaths) {
+  const normalizedRequest = requestedPath.toLowerCase().replace(/[^a-z0-9]/g, "");
+  const scored = availablePaths.map((path2) => {
+    const normalizedPath = path2.toLowerCase().replace(/[^a-z0-9]/g, "");
+    if (normalizedPath.includes(normalizedRequest)) {
+      return { path: path2, score: SIMILARITY_THRESHOLDS.EXACT_MATCH };
+    }
+    if (normalizedRequest.includes(normalizedPath)) {
+      return { path: path2, score: SIMILARITY_THRESHOLDS.CONTAINS_MATCH };
+    }
+    const overlap = [...normalizedRequest].filter(
+      (char) => normalizedPath.includes(char)
+    ).length;
+    return {
+      path: path2,
+      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);
+}
+async function pathExists(path2) {
+  try {
+    await stat(path2);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readMDXFile(filePath) {
+  try {
+    const fileContent = await readFile(filePath, "utf-8");
+    const { content, data } = matter(fileContent);
+    const excerptMatch = content.match(/^(.+?)(?:\n\n|$)/);
+    const excerpt = excerptMatch ? excerptMatch[1].replace(/^#+ /, "") : void 0;
+    return {
+      content,
+      frontmatter: data,
+      excerpt
+    };
+  } catch (error) {
+    logger.error(`Failed to read MDX file: ${filePath}`, error);
+    return null;
+  }
+}
+function formatMDXContent(mdxContent) {
+  const { content, frontmatter } = mdxContent;
+  return matter.stringify(content, frontmatter);
+}
+
+// src/utils/mcp-format.ts
+function formatMCPResponse(data) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: typeof data === "string" ? data : JSON.stringify(data, null, 2)
+      }
+    ]
+  };
+}
+function sanitizePath(userPath) {
+  if (!userPath || typeof userPath !== "string") {
+    throw new Error("Invalid path: Path must be a non-empty string");
+  }
+  const normalized = normalize(userPath);
+  if (path.isAbsolute(normalized)) {
+    throw new Error("Invalid path: Absolute paths are not allowed");
+  }
+  const relativePath = 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");
+    }
+  }
+  return relativePath;
+}
+
+// src/tools/docs.ts
+var docsInputSchema = z.object({
+  paths: z.array(z.string()).min(1).describe(
+    'Documentation paths to retrieve (e.g., ["getting-started", "api-reference/primitives/Thread"])'
+  )
+});
+async function readDocumentation(docPath) {
+  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 = {};
+        for (const file of files) {
+          const mdxContent = await readMDXFile(join(fullPath, file));
+          if (mdxContent) {
+            const fileName = file.replace(MDX_EXTENSION, "");
+            contents[fileName] = formatMDXContent(mdxContent);
+          }
+        }
+        return {
+          path: docPath,
+          found: true,
+          type: "directory",
+          directories,
+          files: files.map((f) => f.replace(MDX_EXTENSION, "")),
+          content: Object.keys(contents).length > 0 ? JSON.stringify(contents, null, 2) : void 0
+        };
+      }
+    }
+    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;
+  }
+}
+var 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 }) => {
+    logger.info(`Retrieving documentation for paths: ${paths.join(", ")}`);
+    try {
+      const results = await Promise.all(
+        paths.map((path2) => readDocumentation(path2))
+      );
+      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)
+      });
+    }
+  }
+};
+var examplesInputSchema = z.object({
+  example: z.string().optional().describe(
+    'Example name (e.g., "with-ai-sdk"). Leave empty to list all examples.'
+  )
+});
+async function listCodeExamples() {
+  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) {
+  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;
+  }
+}
+var examplesTools = {
+  name: "assistantUIExamples",
+  description: "List available examples or retrieve complete code for a specific example",
+  parameters: examplesInputSchema.shape,
+  execute: async ({ example }) => {
+    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)
+      });
+    }
+  }
+};
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var packageJson = JSON.parse(
+  readFileSync(join(__dirname, "../package.json"), "utf-8")
+);
+var 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
+);
+async function runServer() {
+  try {
+    if (IS_PREPARE_MODE) {
+      logger.info("Running in preparation mode...");
+      process.exit(0);
+    }
+    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);
+  });
+}
+
+export { runServer, server };

package/dist/index.js

@@ -0,0 +1 @@
+export { runServer, server } from './chunk-CZCDQ3YH.js';

package/dist/prepare-docs/prepare.js

@@ -0,0 +1,199 @@
+import { ROOT_DIR, logger, EXAMPLES_PATH } from '../chunk-C7O7EFKU.js';
+import { rm, mkdir, readdir, readFile, writeFile, copyFile } from 'fs/promises';
+import { join, extname, relative } from 'path';
+
+var DOCS_SOURCE = join(ROOT_DIR, "apps/docs/content/docs");
+var BLOG_SOURCE = join(ROOT_DIR, "apps/docs/content/blog");
+var DOCS_DEST = join(ROOT_DIR, "packages/mcp-docs-server/.docs/raw");
+async function copyDir(src, dest) {
+  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;
+  }
+}
+async function copyRaw() {
+  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;
+  }
+}
+var OUTPUT_DIR = join(
+  ROOT_DIR,
+  "packages/mcp-docs-server/.docs/organized/code-examples"
+);
+var MAX_LINES = 1e4;
+async function scanDirectory(dir, baseDir) {
+  const files = [];
+  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) {
+  const ext = extname(filename).toLowerCase();
+  const extMap = {
+    ".ts": "typescript",
+    ".tsx": "tsx",
+    ".js": "javascript",
+    ".jsx": "jsx",
+    ".json": "json",
+    ".css": "css",
+    ".md": "markdown",
+    ".mdx": "mdx"
+  };
+  return extMap[ext] || "text";
+}
+async function prepareCodeExamples() {
+  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) {
+          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}
+
+`;
+        if (description) {
+          markdown += `${description}
+
+`;
+        }
+        let totalLines = 0;
+        for (const file of files) {
+          const lines = file.content.split("\n").length;
+          if (totalLines + lines > MAX_LINES) {
+            markdown += `
+_Note: Additional files truncated due to size limits_
+`;
+            break;
+          }
+          markdown += `## ${file.path}
+
+`;
+          markdown += `\`\`\`${getFileType(file.path)}
+`;
+          markdown += file.content;
+          markdown += `
+\`\`\`
+
+`;
+          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;
+  }
+}
+
+// src/prepare-docs/prepare.ts
+async function prepare() {
+  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 (process.env.PREPARE === "true") {
+  prepare().catch((error) => {
+    logger.error("Preparation failed", error);
+    process.exit(1);
+  });
+}
+
+export { prepare };

package/dist/stdio.js

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

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@assistant-ui/mcp-docs-server",
+  "version": "0.1.1",
+  "description": "MCP server for assistant-ui documentation and examples",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "assistant-ui-mcp": "./dist/stdio.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.25.57",
+    "gray-matter": "^4.0.3",
+    "cross-env": "^7.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsup": "^8.5.0",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.3",
+    "eslint": "^9.28.0"
+  },
+  "files": [
+    "dist",
+    ".docs",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf dist .docs",
+    "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",
+    "dev": "tsx src/stdio.ts",
+    "pretest": "pnpm build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint ."
+  }
+}