@assistant-ui/mcp-docs-server 0.1.38 → 0.2.0

package/src/tools/docs.ts

@@ -1,4 +1,4 @@
-import { z } from "zod/v3";
+import { z } from "zod";
 import { stat, lstat } from "node:fs/promises";
 import { join, extname } from "node:path";
 import {
@@ -34,6 +34,9 @@ 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;
@@ -85,6 +88,11 @@ 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) {
@@ -105,8 +113,16 @@ async function readDocumentation(docPath: string): Promise<DocResult> {
           }
           const mdxContent = await readMDXFile(join(fullPath, file));
           if (mdxContent) {
-            contents[file.replace(MDX_EXTENSION, "")] =
-              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,
+              }),
+            });
           }
         }
 
@@ -120,9 +136,10 @@ 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; request individual files by path to retrieve their content.`,
+            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.`,
           }),
         };
       }
@@ -158,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,
+          }),
         };
       }
     }
@@ -191,7 +213,7 @@ 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,
+  parameters: docsInputSchema,
   execute: async ({ paths }: z.infer<typeof docsInputSchema>) => {
     logger.info(`Retrieving documentation for paths: ${paths.join(", ")}`);
 

package/src/tools/examples.ts

@@ -1,7 +1,8 @@
-import { z } from "zod/v3";
+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";
@@ -11,21 +12,25 @@ 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.',
     ),
 });
 
-export 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();
 }
 
 export async function readCodeExample(
@@ -58,7 +63,7 @@ export const examplesTools = {
   name: "assistantUIExamples",
   description:
     "List available examples or retrieve complete code for a specific example",
-  parameters: examplesInputSchema.shape,
+  parameters: examplesInputSchema,
   execute: async ({ example }: z.infer<typeof examplesInputSchema>) => {
     try {
       if (!example) {

package/src/tools/resources.ts

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

package/src/tools/search.ts

@@ -1,4 +1,4 @@
-import { z } from "zod/v3";
+import { z } from "zod";
 import { logger } from "../utils/logger.js";
 import { formatMCPResponse } from "../utils/mcp-format.js";
 import { searchDocs } from "../utils/search.js";
@@ -21,7 +21,7 @@ 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,
+  parameters: searchInputSchema,
   execute: async ({ query, limit }: z.infer<typeof searchInputSchema>) => {
     logger.info(`Searching documentation for: ${query}`);
     try {

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

@@ -1,46 +1,60 @@
-import { describe, it, expect } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { server } from "../../index.js";
+import { createMcpTestClient, type McpTestClient } from "./mcp-test-client.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;
-}
+type CompletionResult = {
+  completion: {
+    values: string[];
+  };
+};
 
-async function complete(uri: string, name: string, value: string) {
-  return handler("completion/complete")(
-    {
+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 } },
-    },
-    {},
-  );
-}
+      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);
+    const result = await complete("aui-docs:///{+path}", "path", "api");
+
+    expect(result.completion.values.length).toBeGreaterThan(0);
     expect(
-      res.completion.values.every((v: string) =>
-        v.toLowerCase().includes("api"),
+      result.completion.values.every((value) =>
+        value.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);
+    const result = await complete("aui-example:///{+name}", "name", "with");
+
+    expect(result.completion.values.length).toBeGreaterThan(0);
     expect(
-      res.completion.values.every((v: string) =>
-        v.toLowerCase().includes("with"),
+      result.completion.values.every((value) =>
+        value.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);
+    const result = await complete("aui-docs:///{+path}", "path", "zzzqqxnope");
+
+    expect(result.completion.values).toHaveLength(0);
   });
 });

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/integration.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from "vitest";
 import { server } from "../../index.js";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
 import { docsTools } from "../docs.js";
 import { examplesTools } from "../examples.js";
 
@@ -24,12 +24,11 @@ describe("MCP Server Integration", () => {
   });
 
   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(docsTools.parameters.shape.paths).toBeDefined();
 
     expect(examplesTools.parameters).toBeDefined();
-    expect(Object.keys(examplesTools.parameters)).toContain("example");
+    expect(examplesTools.parameters.shape.example).toBeDefined();
   });
 
   it("should execute tools successfully", async () => {

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