@assistant-ui/mcp-docs-server 0.2.3 → 0.3.0

package/src/prepare-docs/prepare.ts

@@ -1,24 +0,0 @@
-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/prompts/xulux-playground.ts

@@ -1,36 +0,0 @@
-// Skill-style MCP prompt teaching agents the assistant-ui template workflow.
-// Adapted for MCP clients: tools return URLs and data only; there is no
-// browser canvas UI here.
-
-export const XULUX_PLAYGROUND_PROMPT_NAME = "assistant-ui-template-workflow";
-
-export const XULUX_PLAYGROUND_PROMPT_DESCRIPTION =
-  "How to use the assistant-ui template tools to discover hosted templates, inspect their customization contracts, and retrieve preview/download URLs.";
-
-export const XULUX_PLAYGROUND_PROMPT = `You have access to assistant-ui template tools for hosted app templates.
-
-<workflow>
-Follow this template-first workflow for any assistant-ui app-building request:
-
-1. Call **assistantUITemplates** FIRST. Never decide on a template or claim one exists without listing.
-2. Call **assistantUITemplateDetails** on any candidate template before deciding whether it fits.
-   - Review the whole template shape: features, assistantPlacement, configRoots schemas, rules, built-in tools, renderers, and exampleConfig.
-   - If \`customizable\` is empty, the entry is a fixed demo. Use it as-is; never pass a config for it.
-3. Decide one of three paths:
-   - The template fits as-is: call **assistantUITemplatePreview** with templateId and optional versionId.
-   - The template fits with supported customization: author a config using the configRoots schemas and rules from assistantUITemplateDetails, then call **assistantUITemplatePreview** with that config.
-   - No template fits: do NOT call assistantUITemplatePreview. Do not force the request into a template or fake domain content with mock config. Instead, ground yourself in the assistant-ui docs (assistantUIDocs, assistantUISearch, assistantUIExamples) and produce an honest, docs-grounded build guide or prompt for the user.
-</workflow>
-
-<important_constraints>
-- Only use URLs copied exactly from tool results. Never guess, fabricate, or use placeholder URLs.
-- If assistantUITemplatePreview returns validationWarnings or an error, call assistantUITemplateDetails again and correct the config against configRoots. Pass only the documented top-level config roots.
-- Customization is for supported adaptation within a template's shape, not for turning it into a completely different kind of product.
-- Responses may include \`catalogDegraded: true\` when the live template catalog is unreachable. In that mode, template details and preview URLs may be unavailable; tell the user rather than improvising.
-</important_constraints>`;
-
-export const xuluxPlaygroundPrompt = {
-  name: XULUX_PLAYGROUND_PROMPT_NAME,
-  description: XULUX_PLAYGROUND_PROMPT_DESCRIPTION,
-  text: XULUX_PLAYGROUND_PROMPT,
-};

package/src/tools/docs.ts

@@ -1,255 +0,0 @@
-import { z } from "zod";
-import { stat, lstat } from "node:fs/promises";
-import { join, extname } from "node:path";
-import {
-  DOCS_PATH,
-  MDX_EXTENSION,
-  MAX_FILE_SIZE,
-  MAX_DIRECTORY_CONTENT_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[];
-  summaries?: Array<{ name: string; title?: string; excerpt?: string }>;
-  title?: string;
-  excerpt?: string;
-  suggestions?: string[];
-  hint?: 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> = {};
-        const summaries: Array<{
-          name: string;
-          title?: string;
-          excerpt?: string;
-        }> = [];
-        let aggregateSize = 0;
-        let truncated = false;
-        for (const file of files) {
-          let fileSize: number;
-          try {
-            fileSize = (await stat(join(fullPath, file))).size;
-          } catch (error) {
-            logger.warn(
-              `Failed to stat MDX file: ${join(fullPath, file)}`,
-              error,
-            );
-            continue;
-          }
-          aggregateSize += fileSize;
-          if (aggregateSize > MAX_DIRECTORY_CONTENT_SIZE) {
-            truncated = true;
-            break;
-          }
-          const mdxContent = await readMDXFile(join(fullPath, file));
-          if (mdxContent) {
-            const name = file.replace(MDX_EXTENSION, "");
-            contents[name] = formatMDXContent(mdxContent);
-            const title = mdxContent.frontmatter["title"];
-            summaries.push({
-              name,
-              ...(typeof title === "string" && { title }),
-              ...(mdxContent.excerpt !== undefined && {
-                excerpt: mdxContent.excerpt,
-              }),
-            });
-          }
-        }
-
-        const content =
-          !truncated && 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, "")),
-          ...(summaries.length > 0 && { summaries }),
-          ...(content !== undefined && { content }),
-          ...(truncated && {
-            hint: `Directory content exceeds ${MAX_DIRECTORY_CONTENT_SIZE} bytes and was omitted; summaries cover only the files read before the limit. Request individual files by path to retrieve their 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) {
-        const title = mdxContent.frontmatter["title"];
-        return {
-          path: docPath,
-          found: true,
-          type: "file",
-          content: formatMDXContent(mdxContent),
-          ...(typeof title === "string" && { title }),
-          ...(mdxContent.excerpt !== undefined && {
-            excerpt: mdxContent.excerpt,
-          }),
-        };
-      }
-    }
-
-    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,
-  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

@@ -1,114 +0,0 @@
-import { z } from "zod";
-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 { cacheListing } from "../utils/cache.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-v7"). Leave empty to list all examples.',
-    ),
-});
-
-const loadCodeExamples = cacheListing(scanCodeExamples);
-
-export function listCodeExamples(): Promise<string[]> {
-  return loadCodeExamples().catch((error) => {
-    logger.error("Failed to list code examples", error);
-    return [];
-  });
-}
-
-async function scanCodeExamples(): Promise<string[]> {
-  const files = await readdir(CODE_EXAMPLES_PATH);
-  return files
-    .filter((file) => extname(file) === ".md")
-    .map((file) => file.replace(".md", ""))
-    .sort();
-}
-
-export 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,
-  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/resources.ts

@@ -1,111 +0,0 @@
-import { type McpServer, ResourceTemplate } from "@modelcontextprotocol/server";
-import { join } from "node:path";
-import { DOCS_PATH, MDX_EXTENSION } from "../constants.js";
-import { getAvailableDocFiles } from "../utils/paths.js";
-import { readMDXFileSafe, formatMDXContent } from "../utils/mdx.js";
-import { sanitizePath } from "../utils/security.js";
-import { listCodeExamples, readCodeExample } from "./examples.js";
-import { logger } from "../utils/logger.js";
-
-const MARKDOWN_MIME_TYPE = "text/markdown";
-const DOCS_SCHEME = "aui-docs";
-const EXAMPLE_SCHEME = "aui-example";
-
-function templateVarToPath(value: string | string[] | undefined): string {
-  if (Array.isArray(value)) return value.join("/");
-  return value ?? "";
-}
-
-interface MarkdownResourceConfig {
-  name: string;
-  scheme: string;
-  variable: string;
-  title: string;
-  description: string;
-  notFoundLabel: string;
-  list: () => Promise<string[]>;
-  read: (key: string) => Promise<string | null>;
-}
-
-function registerMarkdownResource(
-  server: McpServer,
-  config: MarkdownResourceConfig,
-): void {
-  const {
-    name,
-    scheme,
-    variable,
-    title,
-    description,
-    notFoundLabel,
-    list,
-    read,
-  } = config;
-  server.registerResource(
-    name,
-    new ResourceTemplate(`${scheme}:///{+${variable}}`, {
-      list: async () => ({
-        resources: (await list()).map((key) => ({
-          uri: `${scheme}:///${key}`,
-          name: key,
-          mimeType: MARKDOWN_MIME_TYPE,
-        })),
-      }),
-      complete: {
-        [variable]: async (value) => {
-          const needle = value.toLowerCase();
-          return (await list()).filter((key) =>
-            key.toLowerCase().includes(needle),
-          );
-        },
-      },
-    }),
-    { title, description, mimeType: MARKDOWN_MIME_TYPE },
-    async (uri, variables) => {
-      const key = templateVarToPath(variables[variable]);
-      const text = await read(key);
-      if (text === null) {
-        throw new Error(`${notFoundLabel} not found: ${key}`);
-      }
-      return {
-        contents: [{ uri: uri.href, mimeType: MARKDOWN_MIME_TYPE, text }],
-      };
-    },
-  );
-}
-
-async function readDocResource(path: string): Promise<string | null> {
-  const sanitized = sanitizePath(path);
-  const mdx = await readMDXFileSafe(
-    join(DOCS_PATH, `${sanitized}${MDX_EXTENSION}`),
-  );
-  return mdx ? formatMDXContent(mdx) : null;
-}
-
-export function registerResources(server: McpServer): void {
-  registerMarkdownResource(server, {
-    name: "assistant-ui-docs",
-    scheme: DOCS_SCHEME,
-    variable: "path",
-    title: "assistant-ui Documentation",
-    description:
-      "Individual assistant-ui documentation pages, readable as markdown by path.",
-    notFoundLabel: "Documentation",
-    list: getAvailableDocFiles,
-    read: readDocResource,
-  });
-
-  registerMarkdownResource(server, {
-    name: "assistant-ui-examples",
-    scheme: EXAMPLE_SCHEME,
-    variable: "name",
-    title: "assistant-ui Examples",
-    description:
-      "Complete assistant-ui example projects, readable as markdown.",
-    notFoundLabel: "Example",
-    list: listCodeExamples,
-    read: readCodeExample,
-  });
-
-  logger.debug("Registered docs and examples resources");
-}

package/src/tools/search.ts

@@ -1,46 +0,0 @@
-import { z } from "zod";
-import { logger } from "../utils/logger.js";
-import { formatMCPResponse } from "../utils/mcp-format.js";
-import { searchDocs } from "../utils/search.js";
-
-const searchInputSchema = z.object({
-  query: z
-    .string()
-    .min(1)
-    .describe("Keyword(s) to search assistant-ui documentation for."),
-  limit: z
-    .number()
-    .int()
-    .min(1)
-    .max(25)
-    .default(10)
-    .describe("Maximum number of results to return (default 10)."),
-});
-
-export const searchTools = {
-  name: "assistantUISearch",
-  description:
-    "Search assistant-ui documentation by keyword. Returns ranked matches with their doc path, title, and a snippet. Fetch full content with assistantUIDocs using a returned path.",
-  parameters: searchInputSchema,
-  execute: async ({ query, limit }: z.infer<typeof searchInputSchema>) => {
-    logger.info(`Searching documentation for: ${query}`);
-    try {
-      const results = await searchDocs(query, limit);
-      if (results.length === 0) {
-        return formatMCPResponse({
-          query,
-          results: [],
-          total: 0,
-          hint: 'No matches. Use assistantUIDocs with "/" to list all sections.',
-        });
-      }
-      return formatMCPResponse({ query, results, total: results.length });
-    } catch (error) {
-      logger.error("Failed to search documentation", error);
-      return formatMCPResponse({
-        error: "Failed to search documentation",
-        message: error instanceof Error ? error.message : String(error),
-      });
-    }
-  },
-};

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

@@ -1,60 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { server } from "../../index.js";
-import { createMcpTestClient, type McpTestClient } from "./mcp-test-client.js";
-
-type CompletionResult = {
-  completion: {
-    values: string[];
-  };
-};
-
-describe("resource argument completions", () => {
-  let client: McpTestClient;
-
-  beforeEach(async () => {
-    client = await createMcpTestClient(server);
-    await client.initialize();
-  });
-
-  afterEach(async () => {
-    await client?.close();
-  });
-
-  async function complete(uri: string, name: string, value: string) {
-    return client.request<CompletionResult>({
-      method: "completion/complete",
-      params: {
-        ref: { type: "ref/resource", uri },
-        argument: { name, value },
-      },
-    });
-  }
-
-  it("suggests doc paths matching the partial value", async () => {
-    const result = await complete("aui-docs:///{+path}", "path", "api");
-
-    expect(result.completion.values.length).toBeGreaterThan(0);
-    expect(
-      result.completion.values.every((value) =>
-        value.toLowerCase().includes("api"),
-      ),
-    ).toBe(true);
-  });
-
-  it("suggests example names matching the partial value", async () => {
-    const result = await complete("aui-example:///{+name}", "name", "with");
-
-    expect(result.completion.values.length).toBeGreaterThan(0);
-    expect(
-      result.completion.values.every((value) =>
-        value.toLowerCase().includes("with"),
-      ),
-    ).toBe(true);
-  });
-
-  it("returns no values for a nonsense partial", async () => {
-    const result = await complete("aui-docs:///{+path}", "path", "zzzqqxnope");
-
-    expect(result.completion.values).toHaveLength(0);
-  });
-});

package/src/tools/tests/directory-size-cap.test.ts

@@ -1,50 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-
-vi.mock("../../utils/paths.js", async (importOriginal) => ({
-  ...(await importOriginal<typeof import("../../utils/paths.js")>()),
-  listDirContents: vi.fn(async () => ({
-    directories: [],
-    files: ["first.mdx", "second.mdx"],
-  })),
-}));
-
-vi.mock("node:fs/promises", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("node:fs/promises")>();
-  return {
-    ...actual,
-    stat: vi.fn(async (path: string) => ({
-      isFile: () => path.endsWith(".mdx"),
-      isDirectory: () => !path.endsWith(".mdx"),
-      size: 600 * 1024,
-    })),
-  };
-});
-
-vi.mock("../../utils/mdx.js", async (importOriginal) => ({
-  ...(await importOriginal<typeof import("../../utils/mdx.js")>()),
-  readMDXFile: vi.fn(async () => ({
-    content: "x".repeat(600 * 1024),
-    frontmatter: {},
-  })),
-  formatMDXContent: (mdx: { content: string }) => mdx.content,
-}));
-
-import { docsTools } from "../docs.js";
-
-function parse(result: { content: Array<{ text: string }> }) {
-  return JSON.parse(result.content[0]!.text);
-}
-
-describe("assistantUIDocs directory aggregate size cap", () => {
-  it("omits inlined content and returns a hint when a directory exceeds the cap", async () => {
-    const result = await docsTools.execute({
-      paths: ["(reference)/api-reference/primitives"],
-    });
-    const parsed = parse(result);
-
-    expect(parsed.type).toBe("directory");
-    expect(parsed.files).toEqual(["first", "second"]);
-    expect(parsed.content).toBeUndefined();
-    expect(parsed.hint).toContain("exceeds");
-  });
-});