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

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

@@ -1,147 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { testContext } from "./test-setup.js";
-import * as fs from "node:fs/promises";
-
-vi.mock("fs/promises", async () => {
-  const { readdir, readFile, stat, lstat } = await import("node:fs/promises");
-  return {
-    readdir,
-    readFile,
-    stat,
-    lstat: vi.fn(lstat),
-  };
-});
-
-describe("assistantUIDocs", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-  it("should list root directory contents", async () => {
-    const result = await testContext.callTool("assistantUIDocs", {
-      paths: ["/"],
-    });
-
-    expect(result.path).toBe("/");
-    expect(result.found).toBe(true);
-    expect(result.type).toBe("directory");
-    expect(result.directories).toContain("(getting-started)");
-    expect(result.directories).toContain("(reference)");
-    expect(result.directories).toContain("ui");
-  });
-
-  it("should retrieve specific documentation file", async () => {
-    const result = await testContext.callTool("assistantUIDocs", {
-      paths: ["(getting-started)/index"],
-    });
-
-    expect(result.path).toBe("(getting-started)/index");
-    expect(result.found).toBe(true);
-    expect(result.type).toBe("file");
-    expect(result.content).toBeDefined();
-    expect(result.content).toContain("title: Documentation");
-  });
-
-  it("should handle non-existent paths", async () => {
-    const result = await testContext.callTool("assistantUIDocs", {
-      paths: ["non-existent-path"],
-    });
-
-    expect(result.error).toBeDefined();
-    expect(result.error).toContain("Documentation not found");
-    expect(result.suggestions).toBeDefined();
-  });
-
-  it("should support multiple path requests", async () => {
-    const result = await testContext.callTool("assistantUIDocs", {
-      paths: [
-        "(getting-started)/index",
-        "(reference)/api-reference/primitives/thread",
-      ],
-    });
-
-    expect(result.results).toBeDefined();
-    expect(result.results).toHaveLength(2);
-    expect(result.results[0].path).toBe("(getting-started)/index");
-    expect(result.results[1].path).toBe(
-      "(reference)/api-reference/primitives/thread",
-    );
-  });
-
-  it("should list directory contents with files", async () => {
-    const result = await testContext.callTool("assistantUIDocs", {
-      paths: ["(reference)/api-reference/primitives"],
-    });
-
-    expect(result.path).toBe("(reference)/api-reference/primitives");
-    expect(result.found).toBe(true);
-    expect(result.type).toBe("directory");
-    expect(result.files).toContain("thread");
-    expect(result.files).toContain("message");
-    expect(result.files).toContain("composer");
-  });
-
-  it("should parse MDX files with frontmatter", async () => {
-    const result = await testContext.callTool("assistantUIDocs", {
-      paths: ["(getting-started)/index"],
-    });
-
-    expect(result.content).toBeDefined();
-    expect(result.content).toContain("title:");
-    expect(result.content).toContain("description:");
-  });
-
-  it("includes title and excerpt on a file response", async () => {
-    const result = await testContext.callTool("assistantUIDocs", {
-      paths: ["(getting-started)/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);
-
-    mockedLstat.mockResolvedValueOnce({
-      isSymbolicLink: () => true,
-      isFile: () => false,
-      isDirectory: () => false,
-    } as any);
-
-    const symlinkResult = await testContext.callTool("assistantUIDocs", {
-      paths: ["symlink-test"],
-    });
-    expect(symlinkResult.error).toBe(
-      "Symlinks are not allowed for security reasons",
-    );
-
-    mockedLstat.mockRejectedValueOnce(new Error("ENOENT"));
-    mockedLstat.mockResolvedValueOnce({
-      isSymbolicLink: () => false,
-      isFile: () => true,
-      size: 11 * 1024 * 1024,
-    } as any);
-
-    const largeFileResult = await testContext.callTool("assistantUIDocs", {
-      paths: ["large-file"],
-    });
-    expect(largeFileResult.error).toContain(
-      "File size exceeds maximum allowed size",
-    );
-  });
-});

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

@@ -1,94 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { testContext } from "./test-setup.js";
-import * as fs from "node:fs/promises";
-
-vi.mock("fs/promises", async () => {
-  const { readdir, readFile, lstat } = await import("node:fs/promises");
-  return {
-    readdir,
-    readFile,
-    lstat: vi.fn(lstat),
-  };
-});
-
-describe("assistantUIExamples", () => {
-  it("should list all available examples", async () => {
-    const result = await testContext.callTool("assistantUIExamples", {});
-
-    expect(result.type).toBe("list");
-    expect(result.examples).toBeDefined();
-    expect(Array.isArray(result.examples)).toBe(true);
-    expect(result.examples.length).toBeGreaterThan(0);
-    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-v7",
-    });
-
-    expect(result.type).toBe("example");
-    expect(result.name).toBe("with-ai-sdk-v7");
-    expect(result.content).toBeDefined();
-    expect(result.content).toContain("# Example: with-ai-sdk-v7");
-    expect(result.content).toContain("app/api/chat/route.ts");
-    expect(result.content).toContain("streamText");
-  });
-
-  it("should handle non-existent examples", async () => {
-    const result = await testContext.callTool("assistantUIExamples", {
-      example: "non-existent-example",
-    });
-
-    expect(result.error).toBeDefined();
-    expect(result.error).toContain("Example not found");
-    expect(result.availableExamples).toBeDefined();
-    expect(Array.isArray(result.availableExamples)).toBe(true);
-  });
-
-  it("should include all files in example", async () => {
-    const result = await testContext.callTool("assistantUIExamples", {
-      example: "with-ai-sdk-v7",
-    });
-
-    expect(result.content).toContain("package.json");
-    expect(result.content).toContain("app/page.tsx");
-  });
-
-  it("should handle empty example parameter", async () => {
-    const result = await testContext.callTool("assistantUIExamples", {
-      example: undefined,
-    });
-
-    expect(result.type).toBe("list");
-    expect(result.hint).toBeDefined();
-  });
-
-  it("should skip symlinks and large files", async () => {
-    const mockedLstat = vi.mocked(fs.lstat);
-
-    mockedLstat.mockResolvedValueOnce({
-      isSymbolicLink: () => true,
-      isFile: () => false,
-      size: 0,
-    } as any);
-
-    const symlinkResult = await testContext.callTool("assistantUIExamples", {
-      example: "symlink-example",
-    });
-    expect(symlinkResult.error).toContain("Example not found");
-
-    mockedLstat.mockResolvedValueOnce({
-      isSymbolicLink: () => false,
-      isFile: () => true,
-      size: 11 * 1024 * 1024, // 11MB - exceeds MAX_FILE_SIZE
-    } as any);
-
-    const largeFileResult = await testContext.callTool("assistantUIExamples", {
-      example: "large-example",
-    });
-    expect(largeFileResult.error).toContain("Example not found");
-  });
-});

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

@@ -1,45 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { server } from "../../index.js";
-import { McpServer } from "@modelcontextprotocol/server";
-import { docsTools } from "../docs.js";
-import { examplesTools } from "../examples.js";
-
-describe("MCP Server Integration", () => {
-  it("should be an instance of McpServer", () => {
-    expect(server).toBeInstanceOf(McpServer);
-  });
-
-  it("should have tools with correct properties", () => {
-    expect(docsTools.name).toBe("assistantUIDocs");
-    expect(docsTools.description).toContain(
-      "Retrieve assistant-ui documentation",
-    );
-    expect(docsTools.parameters).toBeDefined();
-    expect(docsTools.execute).toBeInstanceOf(Function);
-
-    expect(examplesTools.name).toBe("assistantUIExamples");
-    expect(examplesTools.description).toContain("List available examples");
-    expect(examplesTools.parameters).toBeDefined();
-    expect(examplesTools.execute).toBeInstanceOf(Function);
-  });
-
-  it("should have valid input schemas", () => {
-    expect(docsTools.parameters).toBeDefined();
-    expect(docsTools.parameters.shape.paths).toBeDefined();
-
-    expect(examplesTools.parameters).toBeDefined();
-    expect(examplesTools.parameters.shape.example).toBeDefined();
-  });
-
-  it("should execute tools successfully", async () => {
-    const docsResult = await docsTools.execute({ paths: ["/"] });
-    expect(docsResult).toBeDefined();
-    expect(docsResult.content).toBeDefined();
-    expect(docsResult.content[0]!.type).toBe("text");
-
-    const examplesResult = await examplesTools.execute({});
-    expect(examplesResult).toBeDefined();
-    expect(examplesResult.content).toBeDefined();
-    expect(examplesResult.content[0]!.type).toBe("text");
-  });
-});

package/src/tools/tests/json-parsing.test.ts

@@ -1,23 +0,0 @@
-import { describe, it, expect, vi, afterEach } from "vitest";
-import { testContext } from "./test-setup.js";
-import { docsTools } from "../docs.js";
-
-describe("JSON parsing error handling", () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it("should provide helpful error message for invalid JSON", async () => {
-    vi.spyOn(docsTools, "execute").mockResolvedValue({
-      content: [{ type: "text" as const, text: "invalid json {not valid}" }],
-    });
-
-    await expect(
-      testContext.callTool("assistantUIDocs", { paths: ["/"] }),
-    ).rejects.toThrow(/Tool assistantUIDocs returned invalid JSON/);
-
-    await expect(
-      testContext.callTool("assistantUIDocs", { paths: ["/"] }),
-    ).rejects.toThrow(/invalid json \{not valid\}/);
-  });
-});

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

@@ -1,19 +0,0 @@
-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

@@ -1,216 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import {
-  CallToolRequestSchema,
-  GetPromptRequestSchema,
-  InitializeRequestSchema,
-  ListPromptsRequestSchema,
-  ListToolsRequestSchema,
-} from "@modelcontextprotocol/core";
-import { server } from "../../index.js";
-import { createMcpTestClient, type McpTestClient } from "./mcp-test-client.js";
-
-type Tool = {
-  name: string;
-  title?: string;
-  annotations?: {
-    readOnlyHint?: boolean;
-    openWorldHint?: boolean;
-  };
-  inputSchema: {
-    type?: string;
-    properties?: Record<string, { description?: string }>;
-    required?: string[];
-  };
-};
-
-type ToolListResult = {
-  tools: Tool[];
-};
-
-type ToolCallResult = {
-  content: Array<{
-    type: string;
-  }>;
-};
-
-type PromptListResult = {
-  prompts: Array<{
-    name: string;
-    title?: string;
-  }>;
-};
-
-type PromptGetResult = {
-  messages: Array<{
-    content: {
-      type: string;
-      text?: string;
-    };
-  }>;
-};
-
-type InitializeResult = {
-  protocolVersion: string;
-  serverInfo: {
-    name: string;
-  };
-};
-
-function requireTool(tools: Tool[], name: string): Tool {
-  const tool = tools.find((candidate) => candidate.name === name);
-  expect(tool).toBeDefined();
-  if (!tool) throw new Error(`Missing tool: ${name}`);
-  return tool;
-}
-
-describe("MCP Protocol Integration", () => {
-  let client: McpTestClient;
-  let initializeResult: Promise<InitializeResult>;
-
-  beforeEach(async () => {
-    client = await createMcpTestClient(server);
-    initializeResult = client.initialize() as Promise<InitializeResult>;
-    await initializeResult;
-  });
-
-  afterEach(async () => {
-    await client?.close();
-  });
-
-  it("handles Initialize requests", async () => {
-    const request = {
-      method: "initialize",
-      params: {
-        protocolVersion: "2025-11-25",
-        capabilities: {},
-        clientInfo: {
-          name: "mcp-docs-server-tests",
-          version: "1.0.0",
-        },
-      },
-    };
-
-    expect(InitializeRequestSchema.parse(request)).toBeDefined();
-    await expect(initializeResult).resolves.toMatchObject({
-      protocolVersion: "2025-11-25",
-      serverInfo: { name: "assistant-ui-docs" },
-    });
-  });
-
-  it("lists tool metadata and JSON schemas", async () => {
-    const request = ListToolsRequestSchema.parse({
-      method: "tools/list",
-      params: {},
-    });
-    const result = await client.request<ToolListResult>(request);
-
-    expect(result.tools).toHaveLength(6);
-
-    for (const expected of [
-      {
-        name: "assistantUIDocs",
-        title: "assistant-ui Documentation",
-        annotations: { readOnlyHint: true, openWorldHint: false },
-      },
-      {
-        name: "assistantUIExamples",
-        title: "assistant-ui Examples",
-        annotations: { readOnlyHint: true, openWorldHint: false },
-      },
-      {
-        name: "assistantUISearch",
-        title: "Search assistant-ui Documentation",
-        annotations: { readOnlyHint: true, openWorldHint: false },
-      },
-      {
-        name: "assistantUITemplates",
-        title: "assistant-ui Templates",
-        annotations: { readOnlyHint: true, openWorldHint: true },
-      },
-      {
-        name: "assistantUITemplateDetails",
-        title: "assistant-ui Template Details",
-        annotations: { readOnlyHint: true, openWorldHint: true },
-      },
-      {
-        name: "assistantUITemplatePreview",
-        title: "assistant-ui Template Preview URLs",
-        annotations: { readOnlyHint: false, openWorldHint: true },
-      },
-    ]) {
-      const tool = requireTool(result.tools, expected.name);
-
-      expect(tool).toMatchObject({
-        title: expected.title,
-        annotations: expected.annotations,
-      });
-      expect(tool.inputSchema.type).toBe("object");
-      expect(tool.inputSchema.properties).toBeDefined();
-    }
-
-    const search = requireTool(result.tools, "assistantUISearch");
-    expect(search.inputSchema.required ?? []).not.toContain("limit");
-    expect(search.inputSchema.properties?.["query"]?.description).toBeDefined();
-  });
-
-  it("calls assistantUIDocs", async () => {
-    const request = CallToolRequestSchema.parse({
-      method: "tools/call",
-      params: {
-        name: "assistantUIDocs",
-        arguments: {
-          paths: ["/"],
-        },
-      },
-    });
-    const result = await client.request<ToolCallResult>(request);
-
-    expect(result.content[0]?.type).toBe("text");
-  });
-
-  it("calls assistantUIExamples without arguments", async () => {
-    const request = CallToolRequestSchema.parse({
-      method: "tools/call",
-      params: {
-        name: "assistantUIExamples",
-        arguments: {},
-      },
-    });
-    const result = await client.request<ToolCallResult>(request);
-
-    expect(result.content[0]?.type).toBe("text");
-  });
-
-  it("lists prompts", async () => {
-    const request = ListPromptsRequestSchema.parse({
-      method: "prompts/list",
-      params: {},
-    });
-    const result = await client.request<PromptListResult>(request);
-    const prompt = result.prompts.find(
-      (candidate) => candidate.name === "assistant-ui-template-workflow",
-    );
-
-    expect(prompt).toMatchObject({
-      title: "assistant-ui Template Workflow",
-    });
-  });
-
-  it("gets the assistant-ui-template-workflow prompt", async () => {
-    const request = GetPromptRequestSchema.parse({
-      method: "prompts/get",
-      params: {
-        name: "assistant-ui-template-workflow",
-        arguments: {},
-      },
-    });
-    const result = await client.request<PromptGetResult>(request);
-    const text = result.messages[0]?.content.text;
-
-    expect(result.messages).toHaveLength(1);
-    expect(result.messages[0]?.content.type).toBe("text");
-    expect(text).toContain("assistantUITemplates");
-    expect(text).toContain("assistantUITemplateDetails");
-    expect(text).toContain("assistantUITemplatePreview");
-  });
-});

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

@@ -1,111 +0,0 @@
-import {
-  InMemoryTransport,
-  type McpServer,
-} from "@modelcontextprotocol/server";
-
-type RawMcpRequest = {
-  method: string;
-  params?: unknown;
-};
-
-type JsonRpcResponse = {
-  id: number;
-  result?: unknown;
-  error?: {
-    code: number;
-    message: string;
-  };
-};
-
-type PendingRequest = {
-  resolve: (result: unknown) => void;
-  reject: (error: Error) => void;
-};
-
-export type McpTestClient = {
-  initialize: () => Promise<unknown>;
-  request: <Result>(request: RawMcpRequest) => Promise<Result>;
-  close: () => Promise<void>;
-};
-
-function isJsonRpcResponse(message: unknown): message is JsonRpcResponse {
-  return (
-    typeof message === "object" &&
-    message !== null &&
-    "id" in message &&
-    typeof message.id === "number" &&
-    ("result" in message || "error" in message)
-  );
-}
-
-export async function createMcpTestClient(
-  server: McpServer,
-): Promise<McpTestClient> {
-  const [clientTransport, serverTransport] =
-    InMemoryTransport.createLinkedPair();
-  const pendingRequests = new Map<number, PendingRequest>();
-  let nextRequestId = 1;
-
-  clientTransport.onmessage = (message) => {
-    if (!isJsonRpcResponse(message)) return;
-
-    const pendingRequest = pendingRequests.get(message.id);
-    if (!pendingRequest) return;
-
-    pendingRequests.delete(message.id);
-    if (message.error) {
-      pendingRequest.reject(
-        new Error(
-          `MCP request failed (${message.error.code}): ${message.error.message}`,
-        ),
-      );
-      return;
-    }
-
-    pendingRequest.resolve(message.result);
-  };
-
-  await clientTransport.start();
-  await server.connect(serverTransport);
-
-  const request = <Result>(rawRequest: RawMcpRequest): Promise<Result> => {
-    const id = nextRequestId++;
-
-    return new Promise((resolve, reject) => {
-      pendingRequests.set(id, { resolve, reject });
-      void clientTransport
-        .send({ jsonrpc: "2.0", id, ...rawRequest })
-        .catch((error: unknown) => {
-          pendingRequests.delete(id);
-          reject(error instanceof Error ? error : new Error(String(error)));
-        });
-    }) as Promise<Result>;
-  };
-
-  return {
-    initialize: async () => {
-      const result = await request({
-        method: "initialize",
-        params: {
-          protocolVersion: "2025-11-25",
-          capabilities: {},
-          clientInfo: {
-            name: "mcp-docs-server-tests",
-            version: "1.0.0",
-          },
-        },
-      });
-
-      await clientTransport.send({
-        jsonrpc: "2.0",
-        method: "notifications/initialized",
-      });
-
-      return result;
-    },
-    request,
-    close: async () => {
-      await clientTransport.close();
-    },
-  };
-}