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

package/src/tools/tests/path-traversal.test.ts

@@ -1,84 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { testContext } from "./test-setup.js";
-
-describe("Path Traversal Security", () => {
-  describe("assistantUIDocs tool", () => {
-    const maliciousPaths = [
-      "../../../../etc/passwd",
-      "../../../package.json",
-      "..\\..\\..\\windows\\system32",
-      "/etc/passwd",
-      "docs/../../../sensitive-file",
-      "./../../private/keys",
-    ];
-
-    maliciousPaths.forEach((path) => {
-      it(`should block path traversal attempt: ${path}`, async () => {
-        const result = await testContext.callTool("assistantUIDocs", {
-          paths: [path],
-        });
-
-        expect(result.error).toBeDefined();
-        expect(result.error).toContain("Invalid path");
-        expect(result.content).toBeUndefined();
-      });
-    });
-
-    it("should handle multiple paths with one malicious", async () => {
-      const result = await testContext.callTool("assistantUIDocs", {
-        paths: ["(getting-started)/index", "../../../../etc/passwd", "guides"],
-      });
-
-      expect(result.results).toBeDefined();
-      expect(result.results).toHaveLength(3);
-
-      expect(result.results[0].found).toBe(true);
-      expect(result.results[1].error).toContain("Invalid path");
-      expect(result.results[2].found).toBe(true);
-    });
-  });
-
-  describe("assistantUIExamples tool", () => {
-    const maliciousExamples = [
-      "../../../../etc/passwd",
-      "../../../src/index",
-      "..\\..\\..\\config",
-      "/root/.ssh/id_rsa",
-      "examples/../../../private",
-    ];
-
-    maliciousExamples.forEach((example) => {
-      it(`should block path traversal attempt: ${example}`, async () => {
-        const result = await testContext.callTool("assistantUIExamples", {
-          example,
-        });
-
-        expect(result.error).toBeDefined();
-        expect(result.error).toContain("Example not found");
-        expect(result.content).toBeUndefined();
-      });
-    });
-  });
-
-  describe("Valid paths should still work", () => {
-    it("should allow valid documentation paths", 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.every((r: any) => r.found)).toBe(true);
-    });
-
-    it("should allow valid example names", async () => {
-      const result = await testContext.callTool("assistantUIExamples", {});
-
-      expect(result.examples).toBeDefined();
-      expect(Array.isArray(result.examples)).toBe(true);
-    });
-  });
-});

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

@@ -1,133 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { server } from "../../index.js";
-import { createMcpTestClient, type McpTestClient } from "./mcp-test-client.js";
-
-type Resource = {
-  uri: string;
-};
-
-type ResourceListResult = {
-  resources: Resource[];
-};
-
-type ResourceReadResult = {
-  contents: Array<{
-    mimeType?: string;
-    text?: string;
-  }>;
-};
-
-function requireResource(resources: Resource[], prefix: string): Resource {
-  const resource = resources.find((candidate) =>
-    candidate.uri.startsWith(prefix),
-  );
-  expect(resource).toBeDefined();
-  if (!resource) throw new Error(`Missing resource with URI prefix: ${prefix}`);
-  return resource;
-}
-
-describe("MCP resources", () => {
-  let client: McpTestClient;
-
-  beforeEach(async () => {
-    client = await createMcpTestClient(server);
-    await client.initialize();
-  });
-
-  afterEach(async () => {
-    await client?.close();
-  });
-
-  it("lists docs and example resources", async () => {
-    const result = await client.request<ResourceListResult>({
-      method: "resources/list",
-      params: {},
-    });
-
-    expect(result.resources.length).toBeGreaterThan(0);
-    expect(
-      result.resources.some((resource) =>
-        resource.uri.startsWith("aui-docs:///"),
-      ),
-    ).toBe(true);
-    expect(
-      result.resources.some((resource) =>
-        resource.uri.startsWith("aui-example:///"),
-      ),
-    ).toBe(true);
-  });
-
-  it("reads a documentation resource as markdown", async () => {
-    const list = await client.request<ResourceListResult>({
-      method: "resources/list",
-      params: {},
-    });
-    const doc = requireResource(list.resources, "aui-docs:///");
-    const read = await client.request<ResourceReadResult>({
-      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 client.request<ResourceListResult>({
-      method: "resources/list",
-      params: {},
-    });
-    const prefix = "aui-docs:///";
-    const nested = list.resources.find(
-      (resource) =>
-        resource.uri.startsWith(prefix) &&
-        resource.uri.slice(prefix.length).includes("/"),
-    );
-
-    expect(nested).toBeDefined();
-    if (!nested) throw new Error("Missing nested documentation resource");
-
-    const read = await client.request<ResourceReadResult>({
-      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(
-      client.request({
-        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 client.request<ResourceListResult>({
-      method: "resources/list",
-      params: {},
-    });
-    const example = requireResource(list.resources, "aui-example:///");
-    const read = await client.request<ResourceReadResult>({
-      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(
-      client.request({
-        method: "resources/read",
-        params: { uri: "aui-example:///definitely-not-a-real-example" },
-      }),
-    ).rejects.toThrow();
-  });
-});

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

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

@@ -1,50 +0,0 @@
-import { beforeAll } from "vitest";
-import { existsSync } from "node:fs";
-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";
-import {
-  xuluxTemplatesListTool,
-  xuluxTemplateDetailsTool,
-  xuluxTemplatePreviewTool,
-} from "../xulux-templates.js";
-
-const tools = {
-  assistantUIDocs: docsTools,
-  assistantUIExamples: examplesTools,
-  assistantUISearch: searchTools,
-  assistantUITemplates: xuluxTemplatesListTool,
-  assistantUITemplateDetails: xuluxTemplateDetailsTool,
-  assistantUITemplatePreview: xuluxTemplatePreviewTool,
-};
-
-export const testContext = {
-  callTool: async (name: string, args: any) => {
-    const tool = tools[name as keyof typeof tools];
-    if (!tool) {
-      throw new Error(`Tool ${name} not found`);
-    }
-    const result = await tool.execute(args);
-
-    const text = result.content?.[0]?.text;
-    if (text === undefined) {
-      throw new Error(`Tool ${name} returned no content`);
-    }
-    try {
-      return JSON.parse(text);
-    } catch (error) {
-      throw new Error(
-        `Tool ${name} returned invalid JSON. Output: ${text}\nParse error: ${error instanceof Error ? error.message : String(error)}`,
-      );
-    }
-  },
-};
-
-beforeAll(() => {
-  const docsPath = join(PACKAGE_DIR, ".docs");
-  if (!existsSync(docsPath)) {
-    throw new Error("Documentation not prepared. Run: pnpm build");
-  }
-});

package/src/tools/tests/xulux-templates.test.ts

@@ -1,325 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { clearCatalogCache } from "../../xulux/catalog-client.js";
-import {
-  xuluxTemplatesListTool,
-  xuluxTemplateDetailsTool,
-  xuluxTemplatePreviewTool,
-} from "../xulux-templates.js";
-
-const LIVE_CATALOG = {
-  version: 1,
-  generatedAt: "2026-07-10T00:00:00.000Z",
-  docsOrigin: "https://www.assistant-ui.com",
-  templates: [
-    {
-      id: "base-assistant-ui",
-      templateId: "base-assistant-ui",
-      versionId: "default",
-      kind: "template",
-      name: "Configurable Base Assistant UI",
-      summary: "Base chat template",
-      assistantPlacement: "full-page chat shell",
-      features: ["threads", "composer"],
-      customizable: ["assistant", "brandTheme"],
-      versions: [
-        {
-          id: "default",
-          entryId: "base-assistant-ui-default",
-          name: "Default",
-          description: "Default base chat",
-          previewUrl: "https://base.example.com",
-          downloadUrl: "https://base.example.com/api/download",
-        },
-      ],
-      previewUrl: "https://base.example.com",
-      downloadUrl: "https://base.example.com/api/download",
-      sandboxBaseUrl: "https://base.example.com",
-      configRoots: {
-        assistant: { description: "Assistant config" },
-      },
-      rules: {
-        required: ["Only pass documented top-level config roots."],
-      },
-      tools: {
-        builtIn: [{ id: "getWeather" }],
-        customToolSupported: true,
-        renderers: [{ type: "generic" }],
-      },
-    },
-    {
-      id: "base",
-      templateId: "base",
-      versionId: null,
-      kind: "example",
-      name: "Base Demo",
-      summary: "Fixed base demo",
-      assistantPlacement: "full-page demo route",
-      features: ["fixed demo"],
-      customizable: [],
-      versions: [],
-      previewUrl: "https://www.assistant-ui.com/demos/base",
-      downloadUrl:
-        "https://www.assistant-ui.com/api/xulux/demo-download?slug=base",
-      rules: {
-        required: [
-          "This entry is a fixed demo and is not schema-customizable.",
-        ],
-      },
-    },
-  ],
-};
-
-function jsonResponse(body: unknown, init?: ResponseInit) {
-  return new Response(JSON.stringify(body), {
-    status: 200,
-    headers: { "Content-Type": "application/json" },
-    ...init,
-  });
-}
-
-async function callTool(
-  tool:
-    | typeof xuluxTemplatesListTool
-    | typeof xuluxTemplateDetailsTool
-    | typeof xuluxTemplatePreviewTool,
-  args: unknown,
-) {
-  const result = await tool.execute(args as never);
-  const text = result.content?.[0]?.text;
-  if (!text) throw new Error(`Tool ${tool.name} returned no text content`);
-  return JSON.parse(text);
-}
-
-describe("assistant-ui template MCP tools", () => {
-  beforeEach(() => {
-    clearCatalogCache();
-    vi.stubEnv("XULUX_CATALOG_URL", "https://catalog.example.com/mcp-catalog");
-  });
-
-  afterEach(() => {
-    vi.unstubAllEnvs();
-    vi.unstubAllGlobals();
-    clearCatalogCache();
-  });
-
-  it("lists templates from the live catalog", async () => {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async () => jsonResponse(LIVE_CATALOG)),
-    );
-
-    const result = await callTool(xuluxTemplatesListTool, {});
-    expect(result.catalogDegraded).toBeUndefined();
-    expect(result.templates).toHaveLength(2);
-    expect(result.templates[0]).toMatchObject({
-      id: "base-assistant-ui",
-      kind: "template",
-      name: "Configurable Base Assistant UI",
-    });
-  });
-
-  it("uses the minimal fallback catalog when the live catalog is unavailable", async () => {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async () => {
-        throw new Error("network unavailable");
-      }),
-    );
-
-    const result = await callTool(xuluxTemplatesListTool, {});
-    expect(result.catalogDegraded).toBe(true);
-    expect(result.catalogDegradedReason).toContain("network unavailable");
-    expect(result.templates.map((t: any) => t.id)).toContain(
-      "base-assistant-ui",
-    );
-  });
-
-  it("uses the fallback catalog when a live template entry is malformed", async () => {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async () =>
-        jsonResponse({
-          ...LIVE_CATALOG,
-          templates: [
-            {
-              id: "broken",
-              templateId: "broken",
-              kind: "template",
-            },
-          ],
-        }),
-      ),
-    );
-
-    const result = await callTool(xuluxTemplatesListTool, {});
-    expect(result.catalogDegraded).toBe(true);
-    expect(result.catalogDegradedReason).toContain(
-      "Catalog response is malformed",
-    );
-    expect(result.templates.map((t: { id: string }) => t.id)).toContain(
-      "base-assistant-ui",
-    );
-  });
-
-  it("names the version when the live catalog is a newer revision", async () => {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async () => jsonResponse({ ...LIVE_CATALOG, version: 2 })),
-    );
-
-    const result = await callTool(xuluxTemplatesListTool, {});
-    expect(result.catalogDegraded).toBe(true);
-    expect(result.catalogDegradedReason).toContain(
-      "Unsupported catalog version: 2. Expected 1.",
-    );
-  });
-
-  it("uses the fallback catalog when a live template URL is malformed", async () => {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async () =>
-        jsonResponse({
-          ...LIVE_CATALOG,
-          templates: [
-            {
-              ...LIVE_CATALOG.templates[0],
-              sandboxBaseUrl: "not a URL",
-            },
-          ],
-        }),
-      ),
-    );
-
-    const result = await callTool(xuluxTemplatesListTool, {});
-    expect(result.catalogDegraded).toBe(true);
-    expect(result.catalogDegradedReason).toContain(
-      "Catalog response is malformed",
-    );
-  });
-
-  it("returns details and fetches exampleConfig from the selected sandbox contract", async () => {
-    const fetchMock = vi.fn(async (url: string | URL) => {
-      const href = String(url);
-      if (href === "https://catalog.example.com/mcp-catalog") {
-        return jsonResponse(LIVE_CATALOG);
-      }
-      if (href === "https://base.example.com/api/template/contract?v=default") {
-        return jsonResponse({
-          exampleCompleteConfig: {
-            assistant: { appName: "Example" },
-          },
-        });
-      }
-      throw new Error(`Unexpected fetch: ${href}`);
-    });
-    vi.stubGlobal("fetch", fetchMock);
-
-    const result = await callTool(xuluxTemplateDetailsTool, {
-      templateId: "base-assistant-ui",
-      versionId: "default",
-    });
-    expect(result.selectedVersionId).toBe("default");
-    expect(result.configRoots.assistant).toBeDefined();
-    expect(result.exampleConfig).toEqual({
-      assistant: { appName: "Example" },
-    });
-    expect(fetchMock).toHaveBeenCalledWith(
-      "https://base.example.com/api/template/contract?v=default",
-      expect.objectContaining({
-        cache: "no-store",
-        headers: expect.any(Headers),
-      }),
-    );
-    const sandboxCall = fetchMock.mock.calls.find((call) =>
-      String(call[0]).includes("/api/template/contract"),
-    ) as [string | URL, RequestInit] | undefined;
-    expect(sandboxCall?.[1].headers).toBeInstanceOf(Headers);
-    expect((sandboxCall?.[1].headers as Headers).get("User-Agent")).toBe(
-      "curl/8.7.1",
-    );
-  });
-
-  it("returns fixed demo preview URLs and rejects config for fixed demos", async () => {
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async () => jsonResponse(LIVE_CATALOG)),
-    );
-
-    const ok = await callTool(xuluxTemplatePreviewTool, {
-      templateId: "base",
-    });
-    expect(ok).toMatchObject({
-      success: true,
-      templateId: "base",
-      previewUrl: "https://www.assistant-ui.com/demos/base",
-      customized: false,
-    });
-
-    const rejected = await callTool(xuluxTemplatePreviewTool, {
-      templateId: "base",
-      config: { assistant: { appName: "Nope" } },
-    });
-    expect(rejected.success).toBe(false);
-    expect(rejected.error).toContain("fixed demo");
-  });
-
-  it("creates configured hosted previews through the sandbox session endpoint", async () => {
-    const fetchMock = vi.fn(async (url: string | URL, init?: RequestInit) => {
-      const href = String(url);
-      if (href === "https://catalog.example.com/mcp-catalog") {
-        return jsonResponse(LIVE_CATALOG);
-      }
-      if (href === "https://base.example.com/api/preview/session?v=default") {
-        expect(init?.method).toBe("POST");
-        expect(init?.body).toBe(
-          JSON.stringify({ assistant: { appName: "Custom" } }),
-        );
-        return jsonResponse({
-          previewUrl: "/preview/session-1",
-          downloadUrl: "/api/download?session=1",
-          validationWarnings: [],
-        });
-      }
-      throw new Error(`Unexpected fetch: ${href}`);
-    });
-    vi.stubGlobal("fetch", fetchMock);
-
-    const result = await callTool(xuluxTemplatePreviewTool, {
-      templateId: "base-assistant-ui-default",
-      config: { assistant: { appName: "Custom" } },
-    });
-    expect(result).toMatchObject({
-      success: true,
-      templateId: "base-assistant-ui",
-      versionId: "default",
-      previewUrl: "https://base.example.com/preview/session-1?v=default",
-      downloadUrl: "https://base.example.com/api/download?session=1&v=default",
-      customized: true,
-    });
-  });
-
-  it("matches the web tool shape for configured preview network failures", async () => {
-    const fetchMock = vi.fn(async (url: string | URL) => {
-      const href = String(url);
-      if (href === "https://catalog.example.com/mcp-catalog") {
-        return jsonResponse(LIVE_CATALOG);
-      }
-      if (href === "https://base.example.com/api/preview/session?v=default") {
-        throw new Error("fetch failed");
-      }
-      throw new Error(`Unexpected fetch: ${href}`);
-    });
-    vi.stubGlobal("fetch", fetchMock);
-
-    const result = await callTool(xuluxTemplatePreviewTool, {
-      templateId: "base-assistant-ui",
-      config: { assistant: { appName: "Custom" } },
-    });
-    expect(result).toEqual({
-      success: false,
-      templateId: "base-assistant-ui",
-      versionId: "default",
-      error: "fetch failed",
-    });
-  });
-});