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

package/dist/utils/search.js

@@ -0,0 +1,97 @@
+import { DOCS_PATH, MDX_EXTENSION } from "../constants.js";
+import { getAvailablePaths, pathExists } from "./paths.js";
+import { readMDXFile } from "./mdx.js";
+import { join } from "node:path";
+//#region src/utils/search.ts
+const SCORE_WEIGHTS = {
+	FULL_QUERY: {
+		title: 10,
+		path: 8,
+		description: 5
+	},
+	TOKEN: {
+		title: 3,
+		path: 2,
+		description: 1,
+		content: .5
+	}
+};
+let indexPromise = null;
+function deriveTitle(path, frontmatter) {
+	const fmTitle = frontmatter["title"];
+	if (typeof fmTitle === "string" && fmTitle.trim()) return fmTitle;
+	return path.split("/").pop() ?? path;
+}
+async function buildIndex() {
+	const paths = await getAvailablePaths();
+	return (await Promise.all(paths.map(async (path) => {
+		const filePath = join(DOCS_PATH, `${path}${MDX_EXTENSION}`);
+		if (!await pathExists(filePath)) return null;
+		const mdx = await readMDXFile(filePath);
+		if (!mdx) return null;
+		const description = mdx.frontmatter["description"];
+		return {
+			path,
+			title: deriveTitle(path, mdx.frontmatter),
+			description: typeof description === "string" ? description : "",
+			content: mdx.content,
+			excerpt: mdx.excerpt ?? ""
+		};
+	}))).filter((entry) => entry !== null);
+}
+function getIndex() {
+	if (!indexPromise) indexPromise = buildIndex().catch((error) => {
+		indexPromise = null;
+		throw error;
+	});
+	return indexPromise;
+}
+function makeSnippet(content, tokens, excerpt) {
+	const lower = content.toLowerCase();
+	for (const token of tokens) {
+		const idx = lower.indexOf(token);
+		if (idx >= 0) {
+			const start = Math.max(0, idx - 60);
+			const end = Math.min(content.length, idx + token.length + 100);
+			const slice = content.slice(start, end).replace(/\s+/g, " ").trim();
+			return `${start > 0 ? "…" : ""}${slice}${end < content.length ? "…" : ""}`;
+		}
+	}
+	if (excerpt) return excerpt.slice(0, 160);
+	const firstLine = content.split("\n").find((line) => line.trim());
+	return firstLine ? firstLine.replace(/^#+\s*/, "").slice(0, 160) : "";
+}
+function scoreEntry(entry, query, tokens) {
+	const title = entry.title.toLowerCase();
+	const path = entry.path.toLowerCase();
+	const description = entry.description.toLowerCase();
+	const content = entry.content.toLowerCase();
+	let score = 0;
+	if (title.includes(query)) score += SCORE_WEIGHTS.FULL_QUERY.title;
+	if (path.includes(query)) score += SCORE_WEIGHTS.FULL_QUERY.path;
+	if (description.includes(query)) score += SCORE_WEIGHTS.FULL_QUERY.description;
+	for (const token of tokens) {
+		if (title.includes(token)) score += SCORE_WEIGHTS.TOKEN.title;
+		if (path.includes(token)) score += SCORE_WEIGHTS.TOKEN.path;
+		if (description.includes(token)) score += SCORE_WEIGHTS.TOKEN.description;
+		if (content.includes(token)) score += SCORE_WEIGHTS.TOKEN.content;
+	}
+	return score;
+}
+async function searchDocs(query, limit = 10) {
+	const normalized = query.trim().toLowerCase();
+	if (!normalized) return [];
+	const tokens = normalized.split(/\s+/).filter(Boolean);
+	return (await getIndex()).map((entry) => ({
+		entry,
+		score: scoreEntry(entry, normalized, tokens)
+	})).filter((scored) => scored.score > 0).sort((a, b) => b.score - a.score).slice(0, limit).map(({ entry }) => ({
+		path: entry.path,
+		title: entry.title,
+		snippet: makeSnippet(entry.content, tokens, entry.excerpt)
+	}));
+}
+//#endregion
+export { searchDocs };
+
+//# sourceMappingURL=search.js.map

package/dist/utils/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","names":[],"sources":["../../src/utils/search.ts"],"sourcesContent":["import { join } from \"node:path\";\nimport { DOCS_PATH, MDX_EXTENSION } from \"../constants.js\";\nimport { getAvailablePaths, pathExists } from \"./paths.js\";\nimport { readMDXFile } from \"./mdx.js\";\n\nconst SCORE_WEIGHTS = {\n  FULL_QUERY: { title: 10, path: 8, description: 5 },\n  TOKEN: { title: 3, path: 2, description: 1, content: 0.5 },\n} as const;\n\ninterface IndexEntry {\n  path: string;\n  title: string;\n  description: string;\n  content: string;\n  excerpt: string;\n}\n\nexport interface SearchResult {\n  path: string;\n  title: string;\n  snippet: string;\n}\n\nlet indexPromise: Promise<IndexEntry[]> | null = null;\n\nfunction deriveTitle(\n  path: string,\n  frontmatter: Record<string, unknown>,\n): string {\n  const fmTitle = frontmatter[\"title\"];\n  if (typeof fmTitle === \"string\" && fmTitle.trim()) return fmTitle;\n  return path.split(\"/\").pop() ?? path;\n}\n\nasync function buildIndex(): Promise<IndexEntry[]> {\n  const paths = await getAvailablePaths();\n  const entries = await Promise.all(\n    paths.map(async (path): Promise<IndexEntry | null> => {\n      const filePath = join(DOCS_PATH, `${path}${MDX_EXTENSION}`);\n      if (!(await pathExists(filePath))) return null;\n      const mdx = await readMDXFile(filePath);\n      if (!mdx) return null;\n      const description = mdx.frontmatter[\"description\"];\n      return {\n        path,\n        title: deriveTitle(path, mdx.frontmatter),\n        description: typeof description === \"string\" ? description : \"\",\n        content: mdx.content,\n        excerpt: mdx.excerpt ?? \"\",\n      };\n    }),\n  );\n  return entries.filter((entry): entry is IndexEntry => entry !== null);\n}\n\nfunction getIndex(): Promise<IndexEntry[]> {\n  if (!indexPromise) {\n    indexPromise = buildIndex().catch((error) => {\n      indexPromise = null;\n      throw error;\n    });\n  }\n  return indexPromise;\n}\n\nfunction makeSnippet(\n  content: string,\n  tokens: string[],\n  excerpt: string,\n): string {\n  const lower = content.toLowerCase();\n  for (const token of tokens) {\n    const idx = lower.indexOf(token);\n    if (idx >= 0) {\n      const start = Math.max(0, idx - 60);\n      const end = Math.min(content.length, idx + token.length + 100);\n      const slice = content.slice(start, end).replace(/\\s+/g, \" \").trim();\n      return `${start > 0 ? \"…\" : \"\"}${slice}${end < content.length ? \"…\" : \"\"}`;\n    }\n  }\n  if (excerpt) return excerpt.slice(0, 160);\n  const firstLine = content.split(\"\\n\").find((line) => line.trim());\n  return firstLine ? firstLine.replace(/^#+\\s*/, \"\").slice(0, 160) : \"\";\n}\n\nfunction scoreEntry(\n  entry: IndexEntry,\n  query: string,\n  tokens: string[],\n): number {\n  const title = entry.title.toLowerCase();\n  const path = entry.path.toLowerCase();\n  const description = entry.description.toLowerCase();\n  const content = entry.content.toLowerCase();\n\n  let score = 0;\n  if (title.includes(query)) score += SCORE_WEIGHTS.FULL_QUERY.title;\n  if (path.includes(query)) score += SCORE_WEIGHTS.FULL_QUERY.path;\n  if (description.includes(query))\n    score += SCORE_WEIGHTS.FULL_QUERY.description;\n\n  for (const token of tokens) {\n    if (title.includes(token)) score += SCORE_WEIGHTS.TOKEN.title;\n    if (path.includes(token)) score += SCORE_WEIGHTS.TOKEN.path;\n    if (description.includes(token)) score += SCORE_WEIGHTS.TOKEN.description;\n    if (content.includes(token)) score += SCORE_WEIGHTS.TOKEN.content;\n  }\n  return score;\n}\n\nexport async function searchDocs(\n  query: string,\n  limit = 10,\n): Promise<SearchResult[]> {\n  const normalized = query.trim().toLowerCase();\n  if (!normalized) return [];\n  const tokens = normalized.split(/\\s+/).filter(Boolean);\n\n  const index = await getIndex();\n  return index\n    .map((entry) => ({ entry, score: scoreEntry(entry, normalized, tokens) }))\n    .filter((scored) => scored.score > 0)\n    .sort((a, b) => b.score - a.score)\n    .slice(0, limit)\n    .map(({ entry }) => ({\n      path: entry.path,\n      title: entry.title,\n      snippet: makeSnippet(entry.content, tokens, entry.excerpt),\n    }));\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/mcp-docs-server",
-  "version": "0.1.35",
+  "version": "0.1.38",
   "description": "MCP server for assistant-ui documentation and examples",
   "keywords": [
     "mcp",
@@ -37,10 +37,10 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.0.0",
     "tsx": "^4.22.4",
-    "vitest": "^4.1.8",
-    "@assistant-ui/x-buildutils": "0.0.14"
+    "vitest": "^4.1.9",
+    "@assistant-ui/x-buildutils": "0.0.17"
   },
   "publishConfig": {
     "access": "public",

package/src/constants.ts

@@ -17,6 +17,8 @@ export const MD_EXTENSION = ".md";
 
 export const MAX_FILE_SIZE = 10 * 1024 * 1024;
 
+export const MAX_DIRECTORY_CONTENT_SIZE = 1024 * 1024;
+
 export const IS_PREPARE_MODE = process.argv[1]?.includes(
   "prepare-docs/prepare",
 );

package/src/index.ts

@@ -2,6 +2,8 @@ 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 { searchTools } from "./tools/search.js";
+import { registerResources } from "./tools/resources.js";
 import { logger } from "./utils/logger.js";
 import { PACKAGE_DIR } from "./constants.js";
 
@@ -17,18 +19,38 @@ export const server = new McpServer({
   version: packageJson.version,
 });
 
-server.tool(
+server.registerTool(
   docsTools.name,
-  docsTools.description,
-  docsTools.parameters,
+  {
+    title: "assistant-ui Documentation",
+    description: docsTools.description,
+    inputSchema: docsTools.parameters,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
   docsTools.execute,
 );
-server.tool(
+server.registerTool(
   examplesTools.name,
-  examplesTools.description,
-  examplesTools.parameters,
+  {
+    title: "assistant-ui Examples",
+    description: examplesTools.description,
+    inputSchema: examplesTools.parameters,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
   examplesTools.execute,
 );
+server.registerTool(
+  searchTools.name,
+  {
+    title: "Search assistant-ui Documentation",
+    description: searchTools.description,
+    inputSchema: searchTools.parameters,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  searchTools.execute,
+);
+
+registerResources(server);
 
 export async function runServer() {
   try {

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

@@ -4,7 +4,6 @@ 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> {
@@ -43,10 +42,6 @@ export async function copyRaw(): Promise<void> {
     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);

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,
@@ -30,6 +35,7 @@ interface DocResult {
   files?: string[];
   directories?: string[];
   suggestions?: string[];
+  hint?: string;
   error?: string;
 }
 
@@ -79,16 +85,33 @@ async function readDocumentation(docPath: string): Promise<DocResult> {
         const { directories, files } = await listDirContents(fullPath);
 
         const contents: Record<string, 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);
+            contents[file.replace(MDX_EXTENSION, "")] =
+              formatMDXContent(mdxContent);
           }
         }
 
         const content =
-          Object.keys(contents).length > 0
+          !truncated && Object.keys(contents).length > 0
             ? JSON.stringify(contents, null, 2)
             : undefined;
         return {
@@ -98,6 +121,9 @@ async function readDocumentation(docPath: string): Promise<DocResult> {
           directories,
           files: files.map((f) => f.replace(MDX_EXTENSION, "")),
           ...(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.`,
+          }),
         };
       }
     }

package/src/tools/examples.ts

@@ -15,7 +15,7 @@ const examplesInputSchema = z.object({
     ),
 });
 
-async function listCodeExamples(): Promise<string[]> {
+export async function listCodeExamples(): Promise<string[]> {
   try {
     const files = await readdir(CODE_EXAMPLES_PATH);
     return files
@@ -28,7 +28,9 @@ async function listCodeExamples(): Promise<string[]> {
   }
 }
 
-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/mcp-protocol.test.ts

@@ -55,7 +55,7 @@ describe("MCP Protocol Integration", () => {
 
     expect(result).toBeDefined();
     expect(result.tools).toBeInstanceOf(Array);
-    expect(result.tools).toHaveLength(2);
+    expect(result.tools).toHaveLength(3);
 
     // Check the tools have proper JSON schemas
     const docsTool = result.tools.find(
@@ -73,6 +73,26 @@ describe("MCP Protocol Integration", () => {
     expect(examplesTool.inputSchema).toBeDefined();
     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");
+    expect(docsTool.annotations?.readOnlyHint).toBe(true);
+    expect(docsTool.annotations?.openWorldHint).toBe(false);
+    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);
   });
 
   it("should handle CallTool request for assistantUIDocs", async () => {