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

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

@@ -0,0 +1,102 @@
+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;
+}
+
+describe("MCP resources", () => {
+  it("lists docs and example resources", async () => {
+    const result = await handler("resources/list")(
+      { method: "resources/list", params: {} },
+      {},
+    );
+    expect(result.resources.length).toBeGreaterThan(0);
+    expect(
+      result.resources.some((r: any) => r.uri.startsWith("aui-docs:///")),
+    ).toBe(true);
+    expect(
+      result.resources.some((r: any) => r.uri.startsWith("aui-example:///")),
+    ).toBe(true);
+  });
+
+  it("reads a documentation resource as markdown", async () => {
+    const list = await handler("resources/list")(
+      { method: "resources/list", params: {} },
+      {},
+    );
+    const doc = list.resources.find((r: any) =>
+      r.uri.startsWith("aui-docs:///"),
+    );
+    const read = await handler("resources/read")(
+      { method: "resources/read", params: { uri: doc.uri } },
+      {},
+    );
+    expect(read.contents[0].mimeType).toBe("text/markdown");
+    expect(typeof read.contents[0].text).toBe("string");
+    expect(read.contents[0].text.length).toBeGreaterThan(0);
+  });
+
+  it("reads a slash-containing documentation resource", async () => {
+    const list = await handler("resources/list")(
+      { method: "resources/list", params: {} },
+      {},
+    );
+    const prefix = "aui-docs:///";
+    const nested = list.resources.find(
+      (r: any) =>
+        r.uri.startsWith(prefix) && r.uri.slice(prefix.length).includes("/"),
+    );
+    expect(nested).toBeDefined();
+    const read = await handler("resources/read")(
+      { method: "resources/read", params: { uri: nested.uri } },
+      {},
+    );
+    expect(read.contents[0].mimeType).toBe("text/markdown");
+    expect(read.contents[0].text.length).toBeGreaterThan(0);
+  });
+
+  it("errors on an unknown documentation resource", async () => {
+    await expect(
+      handler("resources/read")(
+        {
+          method: "resources/read",
+          params: { uri: "aui-docs:///definitely-not-a-real-doc" },
+        },
+        {},
+      ),
+    ).rejects.toThrow();
+  });
+
+  it("reads an example resource as markdown", async () => {
+    const list = await handler("resources/list")(
+      { method: "resources/list", params: {} },
+      {},
+    );
+    const example = list.resources.find((r: any) =>
+      r.uri.startsWith("aui-example:///"),
+    );
+    const read = await handler("resources/read")(
+      { method: "resources/read", params: { uri: example.uri } },
+      {},
+    );
+    expect(read.contents[0].mimeType).toBe("text/markdown");
+    expect(typeof read.contents[0].text).toBe("string");
+    expect(read.contents[0].text.length).toBeGreaterThan(0);
+  });
+
+  it("errors on an unknown example resource", async () => {
+    await expect(
+      handler("resources/read")(
+        {
+          method: "resources/read",
+          params: { uri: "aui-example:///definitely-not-a-real-example" },
+        },
+        {},
+      ),
+    ).rejects.toThrow();
+  });
+});

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

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { testContext } from "./test-setup.js";
+
+describe("assistantUISearch", () => {
+  it("returns ranked matches for a known term", async () => {
+    const result = await testContext.callTool("assistantUISearch", {
+      query: "thread",
+    });
+    expect(result.total).toBeGreaterThan(0);
+    expect(result.results[0].path).toBeDefined();
+    expect(result.results[0].title).toBeDefined();
+    expect(result.results[0].snippet).toBeDefined();
+  });
+
+  it("returns no matches for a nonsense query", async () => {
+    const result = await testContext.callTool("assistantUISearch", {
+      query: "zzzqqxnotarealdocterm",
+    });
+    expect(result.total).toBe(0);
+    expect(result.results).toHaveLength(0);
+  });
+
+  it("respects the limit", async () => {
+    const result = await testContext.callTool("assistantUISearch", {
+      query: "ui",
+      limit: 3,
+    });
+    expect(result.results.length).toBeLessThanOrEqual(3);
+  });
+
+  it("defaults to at most 10 results when no limit is given", async () => {
+    const result = await testContext.callTool("assistantUISearch", {
+      query: "ui",
+    });
+    expect(result.results.length).toBeLessThanOrEqual(10);
+  });
+});

package/src/tools/tests/test-setup.ts

@@ -4,10 +4,12 @@ import { join } from "node:path";
 import { PACKAGE_DIR } from "../../constants.js";
 import { docsTools } from "../docs.js";
 import { examplesTools } from "../examples.js";
+import { searchTools } from "../search.js";
 
 const tools = {
   assistantUIDocs: docsTools,
   assistantUIExamples: examplesTools,
+  assistantUISearch: searchTools,
 };
 
 export const testContext = {

package/src/utils/mdx.ts

@@ -1,5 +1,6 @@
-import { readFile } from "node:fs/promises";
+import { readFile, lstat } from "node:fs/promises";
 import matter from "gray-matter";
+import { MAX_FILE_SIZE } from "../constants.js";
 import { logger } from "./logger.js";
 
 interface MDXContent {
@@ -32,6 +33,25 @@ export async function readMDXFile(
   }
 }
 
+export async function readMDXFileSafe(
+  filePath: string,
+): Promise<MDXContent | null> {
+  try {
+    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;
+    }
+  } catch {
+    return null;
+  }
+  return readMDXFile(filePath);
+}
+
 export function formatMDXContent(mdxContent: MDXContent): string {
   const { content, frontmatter } = mdxContent;
 

package/src/utils/paths.ts

@@ -66,6 +66,28 @@ export async function getAvailablePaths(): Promise<string[]> {
   return paths.sort();
 }
 
+export async function getAvailableDocFiles(): Promise<string[]> {
+  const files: string[] = [];
+
+  async function scanDirectory(dir: string, prefix = ""): Promise<void> {
+    const { directories, files: dirFiles } = await listDirContents(dir);
+
+    for (const file of dirFiles) {
+      if (extname(file) !== MDX_EXTENSION) continue;
+      const name = file.replace(MDX_EXTENSION, "");
+      files.push(prefix ? `${prefix}/${name}` : name);
+    }
+
+    for (const subdir of directories) {
+      const newPrefix = prefix ? `${prefix}/${subdir}` : subdir;
+      await scanDirectory(join(dir, subdir), newPrefix);
+    }
+  }
+
+  await scanDirectory(DOCS_PATH);
+  return files.sort();
+}
+
 export function findNearestPaths(
   requestedPath: string,
   availablePaths: string[],

package/src/utils/search.ts

@@ -0,0 +1,131 @@
+import { join } from "node:path";
+import { DOCS_PATH, MDX_EXTENSION } from "../constants.js";
+import { getAvailablePaths, pathExists } from "./paths.js";
+import { readMDXFile } from "./mdx.js";
+
+const SCORE_WEIGHTS = {
+  FULL_QUERY: { title: 10, path: 8, description: 5 },
+  TOKEN: { title: 3, path: 2, description: 1, content: 0.5 },
+} as const;
+
+interface IndexEntry {
+  path: string;
+  title: string;
+  description: string;
+  content: string;
+  excerpt: string;
+}
+
+export interface SearchResult {
+  path: string;
+  title: string;
+  snippet: string;
+}
+
+let indexPromise: Promise<IndexEntry[]> | null = null;
+
+function deriveTitle(
+  path: string,
+  frontmatter: Record<string, unknown>,
+): string {
+  const fmTitle = frontmatter["title"];
+  if (typeof fmTitle === "string" && fmTitle.trim()) return fmTitle;
+  return path.split("/").pop() ?? path;
+}
+
+async function buildIndex(): Promise<IndexEntry[]> {
+  const paths = await getAvailablePaths();
+  const entries = await Promise.all(
+    paths.map(async (path): Promise<IndexEntry | null> => {
+      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 ?? "",
+      };
+    }),
+  );
+  return entries.filter((entry): entry is IndexEntry => entry !== null);
+}
+
+function getIndex(): Promise<IndexEntry[]> {
+  if (!indexPromise) {
+    indexPromise = buildIndex().catch((error) => {
+      indexPromise = null;
+      throw error;
+    });
+  }
+  return indexPromise;
+}
+
+function makeSnippet(
+  content: string,
+  tokens: string[],
+  excerpt: string,
+): string {
+  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: IndexEntry,
+  query: string,
+  tokens: string[],
+): number {
+  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;
+}
+
+export async function searchDocs(
+  query: string,
+  limit = 10,
+): Promise<SearchResult[]> {
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) return [];
+  const tokens = normalized.split(/\s+/).filter(Boolean);
+
+  const index = await getIndex();
+  return index
+    .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),
+    }));
+}

package/.docs/raw/blog/2024-07-29-hello/index.mdx

@@ -1,64 +0,0 @@
----
-title: Hello, assistant-ui
-description: assistant-ui is an open-source AI chat component for React.
-author: Simon Farshid
-date: 2024-07-29T12:00:00
----
-
-import Image from "next/image";
-import { TestimonialContainer } from "@/components/home/testimonials/testimonials";
-import { BLOG_TESTIMONIALS } from "@/components/home/testimonials/data";
-import npmDownloads from "./npm-downloads.png";
-import assistantUi from "./assistant-ui-screenshot.png";
-
-After spending the last two years building Gen-AI prototypes and products, I realized that all software will soon have a natural language interface. OpenAI's ChatGPT sets the quality bar high and I wanted to have a similar UX in my own apps. No solution on the market came anywhere close, so I built assistant-ui.
-
-assistant-ui is an open-source, embeddable, customizable AI chat component for React web apps. You can use it to build GPT wrappers, in-app copilots, or agentic systems. It supports rich content (markdown, code highlighting, charts, tables), generative UI, message editing, ..., across all the major model providers.
-
-<Image
-  src={assistantUi}
-  alt="screenshot of assistant-ui"
-  width={398}
-  height={498}
-  className="mx-auto rounded-xl border drop-shadow"
-/>
-
-Earlier last month, I released the project to the world. The feedback from early adopters has been overwhelmingly positive:
-
-<div className="not-prose mx-auto max-w-md">
-  <TestimonialContainer testimonials={BLOG_TESTIMONIALS} />
-</div>
-
-It didn't take long for developers to start building with assistant-ui. Here are some of my favorite products from the community:
-
-- [Helicone](https://helicone.ai/) - open-source LLM observability platform
-- [screenpipe](https://screenpi.pe/) - AI to remember everything you see, say or hear
-- [myresume.guru](http://myresume.guru) - AI resume optimizer to land your dream job
-
-With 250+ stars on [GitHub](https://github.com/assistant-ui/assistant-ui) and over 1k [npm](https://www.npmjs.com/package/@assistant-ui/react) weekly downloads, we got a vibrant growing community of developers who care about the user experience.
-
-<Image
-  src={npmDownloads}
-  alt="graph showing 1355 weekly npm downloads"
-  width={381}
-  height={94}
-  className="mx-auto dark:hue-rotate-180 dark:invert"
-/>
-
-I want to thank the following contributors who got the project to where it is today:
-
-- [@m13v](https://github.com/m13v) for contributing two examples and several how-to videos
-- [@okisdev](https://github.com/okisdev) for multiple bugfixes
-- [@Rajaniraiyn](https://github.com/Rajaniraiyn) for improving streaming support for REST APIs
-- @ccbkai for integrating Chrome's `window.ai` with assistant-ui
-- [@stingfeng](https://github.com/stingfeng/dify-extensions) for building a [Dify](https://dify.ai) integration
-- [@Ephibbs](https://github.com/Ephibbs/flowtoken) for building a Perplexity-style text streaming library ([Demo](https://assistant-ui-flowtoken-demo.vercel.app/))
-- … and so many others
-
-assistant-ui builds on top of [Radix UI](https://www.radix-ui.com/), [Tailwind](https://tailwindcss.com/), [shadcn/ui](https://ui.shadcn.com/), [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction) and other amazing open-source projects.
-
-Over the coming month, I'll be rolling out multimodal support, so you can use your voice and upload images. There's so much more in the pipeline that I can't wait to unveil!
-
-Today, several companies like [Helicone (YC W23)](https://x.com/justinstorre/status/1816849882612904156) are using assistant-ui to power a core part of their product. If your company wants to do the same, please [get in touch](https://cal.com/simon-farshid/assistant-ui).
-
-If you're building conversational AI, join us on [Discord](https://discord.gg/S9dwgCNEFs). If you're technical and want to shape how we interact with AIs of the future, [send me an email](mailto:simon@assistant-ui.com).

package/.docs/raw/blog/2024-09-11/index.mdx

@@ -1,10 +0,0 @@
----
-title: Build conversational AI agents with LangGraph and assistant-ui
-description: Announcing our collaboration with LangChain
-author: Harrison Chase
-date: 2024-09-11T12:00:00
----
-
-import { Redirect } from "./redirect";
-
-<Redirect />

package/.docs/raw/blog/2024-12-15/index.mdx

@@ -1,10 +0,0 @@
----
-title: Announcing github-assistant
-description: github-assistant answers questions about your GitHub repositories.
-author: Amir Zohrenejad
-date: 2024-12-15T12:00:00
----
-
-import { Redirect } from "./redirect";
-
-<Redirect />

package/.docs/raw/blog/2025-01-31-changelog/index.mdx

@@ -1,127 +0,0 @@
----
-title: January 2025 Changelog
-description: shadcn/ui, Thread Management, Improvements to AI SDK and LangGraph support
-author: Simon Farshid
-date: 2025-01-31T12:00:00
----
-
-<Callout emoji="🎉">
-  This is the first edition of our changelog. We post these updates on a monthly
-  basis. If you want more frequent updates about our new features, join our
-  Discord where we have a `#changelog` channel that is updated on a daily basis.
-</Callout>
-
-## Summary
-
-In January, we shipped 36 new versions of our package `@assistant-ui/react`. We also crossed 10k weekly downloads on npm for the first time. 🎉
-
-## shadcn/ui CLI support
-
-You can now install all components using the shadcn CLI, e.g.
-
-```sh
-npx shadcn@latest add "https://r.assistant-ui.com/thread"
-```
-
-We began a migration towards distributing our components as unstyled primitives and using the shadcn CLI to drop styles in your project.
-
-## Styled components moved to @assistant-ui/react-ui
-
-All styled components (Thread, ThreadList, AssistantModal, makeMarkdownText, etc.) have been moved to a new package, `@assistant-ui/ui`.
-
-To ease the migration, we added a migration codemod:
-
-```sh
-npx assistant-ui upgrade
-```
-
-This will update your codebase to use the new package. This new package remains supported, however, based on the learnings from existing users, we recommend all new projects to use our shadcn/ui CLI instead.
-
-## Customizing the max-width of the Thread
-
-You can now customize the max-width of the thread via `--aui-thread-max-width` CSS variable.
-
-## Thread Management
-
-One of our main focus areas in this month was on the new Thread Management API. The new ThreadList API is available under `runtime.threads`. It allows you to create, switch to, rename, archive, and delete threads.
-
-We shipped a `<ThreadList />` component which gives the user the UI to manage their threads.
-
-We also shipped a few hooks `useThreadListItem()`, `useThreadListItemRuntime()`, `useRemoteThreadListRuntime()` and `useCloudThreadListRuntime()`.
-
-## Assistant Cloud
-
-We rolled out the new Assistant Cloud service to early users. This is a managed service for persistence, chat history, and thread management.
-Our runtimes are being upgraded to support Assistant Cloud natively by letting you pass a `cloud` object to the runtime hook.
-
-Keep an eye out for the public announcement of Assistant Cloud in a few days.
-
-## Improvements to our LangGraph Integration
-
-- We now have full support for LangGraph's `interrupt()`/`Command` API. You can check out the new example repository [here](https://github.com/assistant-ui/assistant-ui-langgraph-interrupt).
-- We now also support starting LangGraph runs without a user message (based on button input or other events).
-- Cancellation of runs is now supported via an `abortSignal` being passed to the LangGraph runtime adapter.
-
-## Improvements to our AI SDK Integration
-
-We now give you access to annotations and data packets in the assistant message:
-
-```tsx
-type AssistantMessage = {
-  metadata: {
-    unstable_annotations: [...],
-    unstable_data: [...],
-  }
-}
-```
-
-## AI SDK recommended for new projects
-
-For new projects, we recommend using the AI SDK integration. Previously, we recommended our custom SDK called `useEdgeRuntime`.  
-With our improved AI SDK integration, we believe it is time to recommend AI SDK for new projects, giving you access to the AI SDK ecosystem.
-
-The edge runtime remains maintained and supported for existing projects.
-
-## Misc
-
-- **Refactors & API Enhancements**:
-
-  - Renamed `ModelConfig` to `ModelContext`.
-  - Moved `switchToThread / switchToNewThread` under `runtime.threads`.
-  - Deprecated `UIContentPart`.
-  - `ToolCallContentPart.args` is now a `JSONObject`.
-  - `MessagePrimitive.tools.Override` introduced.
-  - Added `AppendMessage.sourceId` to provide better tracking.
-  - Reverse order of threads in `useRemoteThreadListRuntime` for better visibility.
-  - Added `threads.getById` and `threads.main` APIs.
-  - Introduced `AssistantCloudThreadHistoryAdapter` to handle cloud-based thread history.
-  - Auto-injection of history adapter in the local runtime.
-  - Tool call `id` + `args` are now optional in `ThreadMessageLike`.
-  - Added `ThreadListPrimitive.Root`.
-  - `ComposerRuntime.clearAttachments` API added.
-  - Improved input support for IME keyboards (e.g., Chinese, Japanese, Korean).
-  - Moved repository to a new GitHub organization (`assistant-ui/assistant-ui`).
-
-- **External Store & Data Handling**:
-
-  - Enhanced `ExternalStoreAdapter` to support metadata and attachments.
-  - Renamed `getExternalStoreMessage` to `getExternalStoreMessages`.
-  - Tool call `args` streaming support in our Python SDK.
-
-- **User Interface & Styling**:
-
-  - Styled UI assistant message footer.
-  - Improved attachment filename handling to prevent overflow.
-  - Renamed CSS class to `aui-thread-welcome-suggestions`.
-
-- **Performance Optimizations**:
-
-  - Memoized `MessageRepository.getMessages()` for better efficiency.
-  - Marked `ChatAdapter` types as readonly.
-
-- **Bug Fixes**:
-
-  - Fixed event subscription issues in thread lists.
-  - Fixed import errors in React server environments.
-  - Prevented excessive classes being included via TailwindCSS.
-  - Fixed AI SDK annotation packet errors.