@assistant-ui/mcp-docs-server 0.1.36 → 0.1.39

package/src/tools/docs.ts

@@ -1,7 +1,12 @@
 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 {
+  DOCS_PATH,
+  MDX_EXTENSION,
+  MAX_FILE_SIZE,
+  MAX_DIRECTORY_CONTENT_SIZE,
+} from "../constants.js";
 import { logger } from "../utils/logger.js";
 import {
   listDirContents,
@@ -29,7 +34,11 @@ interface DocResult {
   content?: string;
   files?: string[];
   directories?: string[];
+  summaries?: Array<{ name: string; title?: string; excerpt?: string }>;
+  title?: string;
+  excerpt?: string;
   suggestions?: string[];
+  hint?: string;
   error?: string;
 }
 
@@ -79,16 +88,46 @@ async function readDocumentation(docPath: string): Promise<DocResult> {
         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 fileName = file.replace(MDX_EXTENSION, "");
-            contents[fileName] = formatMDXContent(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 =
-          Object.keys(contents).length > 0
+          !truncated && Object.keys(contents).length > 0
             ? JSON.stringify(contents, null, 2)
             : undefined;
         return {
@@ -97,7 +136,11 @@ async function readDocumentation(docPath: string): Promise<DocResult> {
           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.`,
+          }),
         };
       }
     }
@@ -132,11 +175,16 @@ async function readDocumentation(docPath: string): Promise<DocResult> {
       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,
+          }),
         };
       }
     }

package/src/tools/examples.ts

@@ -2,6 +2,7 @@ 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 { cacheListing } from "../utils/cache.js";
 import { logger } from "../utils/logger.js";
 import { formatMCPResponse } from "../utils/mcp-format.js";
 import { sanitizePath } from "../utils/security.js";
@@ -11,24 +12,30 @@ const examplesInputSchema = z.object({
     .string()
     .optional()
     .describe(
-      'Example name (e.g., "with-ai-sdk-v6"). Leave empty to list all examples.',
+      'Example name (e.g., "with-ai-sdk-v7"). 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) {
+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();
 }
 
-async function readCodeExample(exampleName: string): Promise<string | null> {
+export async function readCodeExample(
+  exampleName: string,
+): Promise<string | null> {
   try {
     const sanitized = sanitizePath(exampleName);
     const filePath = join(CODE_EXAMPLES_PATH, `${sanitized}.md`);

package/src/tools/resources.ts

@@ -0,0 +1,114 @@
+import {
+  McpServer,
+  ResourceTemplate,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+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

@@ -0,0 +1,46 @@
+import { z } from "zod/v3";
+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.shape,
+  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

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+import { server } from "../../index.js";
+
+function handler(method: string) {
+  const handlers = (server as any).server._requestHandlers;
+  const h = handlers.get(method);
+  if (!h) throw new Error(`No handler for ${method}`);
+  return h;
+}
+
+async function complete(uri: string, name: string, value: string) {
+  return handler("completion/complete")(
+    {
+      method: "completion/complete",
+      params: { ref: { type: "ref/resource", uri }, argument: { name, value } },
+    },
+    {},
+  );
+}
+
+describe("resource argument completions", () => {
+  it("suggests doc paths matching the partial value", async () => {
+    const res = await complete("aui-docs:///{+path}", "path", "api");
+    expect(res.completion.values.length).toBeGreaterThan(0);
+    expect(
+      res.completion.values.every((v: string) =>
+        v.toLowerCase().includes("api"),
+      ),
+    ).toBe(true);
+  });
+
+  it("suggests example names matching the partial value", async () => {
+    const res = await complete("aui-example:///{+name}", "name", "with");
+    expect(res.completion.values.length).toBeGreaterThan(0);
+    expect(
+      res.completion.values.every((v: string) =>
+        v.toLowerCase().includes("with"),
+      ),
+    ).toBe(true);
+  });
+
+  it("returns no values for a nonsense partial", async () => {
+    const res = await complete("aui-docs:///{+path}", "path", "zzzqqxnope");
+    expect(res.completion.values).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,50 @@
+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");
+  });
+});

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

@@ -91,6 +91,26 @@ describe("assistantUIDocs", () => {
     expect(result.content).toContain("assistant-ui");
   });
 
+  it("includes title and excerpt on a file response", async () => {
+    const result = await testContext.callTool("assistantUIDocs", {
+      paths: ["(docs)/index"],
+    });
+    expect(result.type).toBe("file");
+    expect(result.title ?? result.excerpt).toBeDefined();
+  });
+
+  it("includes per-file summaries on a directory listing", async () => {
+    const result = await testContext.callTool("assistantUIDocs", {
+      paths: ["(reference)/api-reference/primitives"],
+    });
+    expect(result.type).toBe("directory");
+    expect(Array.isArray(result.summaries)).toBe(true);
+    expect(result.summaries.length).toBeGreaterThan(0);
+    const summary = result.summaries[0];
+    expect(summary.name).toBeDefined();
+    expect(summary.title ?? summary.excerpt).toBeDefined();
+  });
+
   it("should skip symlinks and large files", async () => {
     const mockedLstat = vi.mocked(fs.lstat);
 

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

@@ -19,20 +19,20 @@ describe("assistantUIExamples", () => {
     expect(result.examples).toBeDefined();
     expect(Array.isArray(result.examples)).toBe(true);
     expect(result.examples.length).toBeGreaterThan(0);
-    expect(result.examples).toContain("with-ai-sdk-v6");
+    expect(result.examples).toContain("with-ai-sdk-v7");
     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-v6",
+      example: "with-ai-sdk-v7",
     });
 
     expect(result.type).toBe("example");
-    expect(result.name).toBe("with-ai-sdk-v6");
+    expect(result.name).toBe("with-ai-sdk-v7");
     expect(result.content).toBeDefined();
-    expect(result.content).toContain("# Example: with-ai-sdk-v6");
+    expect(result.content).toContain("# Example: with-ai-sdk-v7");
     expect(result.content).toContain("app/api/chat/route.ts");
     expect(result.content).toContain("streamText");
   });
@@ -50,7 +50,7 @@ describe("assistantUIExamples", () => {
 
   it("should include all files in example", async () => {
     const result = await testContext.callTool("assistantUIExamples", {
-      example: "with-ai-sdk-v6",
+      example: "with-ai-sdk-v7",
     });
 
     expect(result.content).toContain("package.json");

package/src/tools/tests/listings-cache.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from "vitest";
+import { getAvailableDocFiles } from "../../utils/paths.js";
+import { listCodeExamples } from "../examples.js";
+
+describe("listing caches", () => {
+  it("caches the doc file listing (same instance on repeat calls)", async () => {
+    const first = await getAvailableDocFiles();
+    const second = await getAvailableDocFiles();
+    expect(second).toBe(first);
+    expect(first.length).toBeGreaterThan(0);
+  });
+
+  it("caches the example listing (same instance on repeat calls)", async () => {
+    const first = await listCodeExamples();
+    const second = await listCodeExamples();
+    expect(second).toBe(first);
+    expect(first.length).toBeGreaterThan(0);
+  });
+});

package/src/tools/tests/mcp-protocol.test.ts

@@ -4,9 +4,13 @@ import {
   InitializeRequestSchema,
   ListToolsRequestSchema,
   CallToolRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
   type InitializeRequest,
   type ListToolsRequest,
   type CallToolRequest,
+  type ListPromptsRequest,
+  type GetPromptRequest,
 } from "@modelcontextprotocol/sdk/types.js";
 
 describe("MCP Protocol Integration", () => {
@@ -55,7 +59,7 @@ describe("MCP Protocol Integration", () => {
 
     expect(result).toBeDefined();
     expect(result.tools).toBeInstanceOf(Array);
-    expect(result.tools).toHaveLength(2);
+    expect(result.tools).toHaveLength(6);
 
     // Check the tools have proper JSON schemas
     const docsTool = result.tools.find(
@@ -74,6 +78,14 @@ describe("MCP Protocol Integration", () => {
     expect(examplesTool.inputSchema.type).toBe("object");
     expect(examplesTool.inputSchema.properties).toBeDefined();
 
+    const searchTool = result.tools.find(
+      (t: any) => t.name === "assistantUISearch",
+    );
+    expect(searchTool).toBeDefined();
+    expect(searchTool.inputSchema).toBeDefined();
+    expect(searchTool.inputSchema.type).toBe("object");
+    expect(searchTool.inputSchema.properties).toBeDefined();
+
     // registerTool metadata is surfaced on tools/list: `title` is a
     // top-level field, `annotations` carries only the hint flags.
     expect(docsTool.title).toBe("assistant-ui Documentation");
@@ -82,6 +94,33 @@ describe("MCP Protocol Integration", () => {
     expect(examplesTool.title).toBe("assistant-ui Examples");
     expect(examplesTool.annotations?.readOnlyHint).toBe(true);
     expect(examplesTool.annotations?.openWorldHint).toBe(false);
+    expect(searchTool.title).toBe("Search assistant-ui Documentation");
+    expect(searchTool.annotations?.readOnlyHint).toBe(true);
+    expect(searchTool.annotations?.openWorldHint).toBe(false);
+
+    const xuluxListTool = result.tools.find(
+      (t: any) => t.name === "assistantUITemplates",
+    );
+    expect(xuluxListTool).toBeDefined();
+    expect(xuluxListTool.title).toBe("assistant-ui Templates");
+    expect(xuluxListTool.annotations?.readOnlyHint).toBe(true);
+    expect(xuluxListTool.annotations?.openWorldHint).toBe(true);
+
+    const xuluxDetailsTool = result.tools.find(
+      (t: any) => t.name === "assistantUITemplateDetails",
+    );
+    expect(xuluxDetailsTool).toBeDefined();
+    expect(xuluxDetailsTool.title).toBe("assistant-ui Template Details");
+    expect(xuluxDetailsTool.annotations?.readOnlyHint).toBe(true);
+    expect(xuluxDetailsTool.annotations?.openWorldHint).toBe(true);
+
+    const xuluxPreviewTool = result.tools.find(
+      (t: any) => t.name === "assistantUITemplatePreview",
+    );
+    expect(xuluxPreviewTool).toBeDefined();
+    expect(xuluxPreviewTool.title).toBe("assistant-ui Template Preview URLs");
+    expect(xuluxPreviewTool.annotations?.readOnlyHint).toBe(false);
+    expect(xuluxPreviewTool.annotations?.openWorldHint).toBe(true);
   });
 
   it("should handle CallTool request for assistantUIDocs", async () => {
@@ -137,4 +176,56 @@ describe("MCP Protocol Integration", () => {
     expect(result.content).toBeDefined();
     expect(result.content[0].type).toBe("text");
   });
+
+  it("should handle ListPrompts request", async () => {
+    const request: ListPromptsRequest = {
+      method: "prompts/list",
+      params: {},
+    };
+
+    const parsed = ListPromptsRequestSchema.parse(request);
+    expect(parsed).toBeDefined();
+
+    const handlers = (server as any).server._requestHandlers;
+    expect(handlers.get("prompts/list")).toBeDefined();
+
+    const handler = handlers.get("prompts/list");
+    const result = await handler(parsed, {});
+
+    expect(result.prompts).toBeInstanceOf(Array);
+    const prompt = result.prompts.find(
+      (p: any) => p.name === "assistant-ui-template-workflow",
+    );
+    expect(prompt).toBeDefined();
+    expect(prompt.title).toBe("assistant-ui Template Workflow");
+  });
+
+  it("should handle GetPrompt request for assistant-ui-template-workflow", async () => {
+    const request: GetPromptRequest = {
+      method: "prompts/get",
+      params: {
+        name: "assistant-ui-template-workflow",
+        arguments: {},
+      },
+    };
+
+    const parsed = GetPromptRequestSchema.parse(request);
+    expect(parsed).toBeDefined();
+
+    const handlers = (server as any).server._requestHandlers;
+    expect(handlers.get("prompts/get")).toBeDefined();
+
+    const handler = handlers.get("prompts/get");
+    const result = await handler(parsed, {});
+
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].content.type).toBe("text");
+    expect(result.messages[0].content.text).toContain("assistantUITemplates");
+    expect(result.messages[0].content.text).toContain(
+      "assistantUITemplateDetails",
+    );
+    expect(result.messages[0].content.text).toContain(
+      "assistantUITemplatePreview",
+    );
+  });
 });