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

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

@@ -1,102 +1,160 @@
-import { describe, it, expect } from "vitest";
-import { server } from "../../index.js";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import {
+  CallToolRequestSchema,
+  GetPromptRequestSchema,
   InitializeRequestSchema,
+  ListPromptsRequestSchema,
   ListToolsRequestSchema,
-  CallToolRequestSchema,
-  type InitializeRequest,
-  type ListToolsRequest,
-  type CallToolRequest,
-} from "@modelcontextprotocol/sdk/types.js";
+} 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", () => {
-  // These tests verify the MCP protocol layer handles requests correctly
-  // and that parameter schemas are properly converted to JSON schemas
-  it("should handle Initialize request", async () => {
-    const request: InitializeRequest = {
+  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: "2024-11-05",
+        protocolVersion: "2025-11-25",
         capabilities: {},
         clientInfo: {
-          name: "test-client",
+          name: "mcp-docs-server-tests",
           version: "1.0.0",
         },
       },
     };
 
-    // Parse and validate the request
-    const parsed = InitializeRequestSchema.parse(request);
-    expect(parsed).toBeDefined();
-
-    // The server should have an initialize handler set up
-    const handlers = (server as any).server._requestHandlers;
-    expect(handlers).toBeDefined();
-    expect(handlers.get("initialize")).toBeDefined();
+    expect(InitializeRequestSchema.parse(request)).toBeDefined();
+    await expect(initializeResult).resolves.toMatchObject({
+      protocolVersion: "2025-11-25",
+      serverInfo: { name: "assistant-ui-docs" },
+    });
   });
 
-  it("should handle ListTools request", async () => {
-    const request: ListToolsRequest = {
+  it("lists tool metadata and JSON schemas", async () => {
+    const request = ListToolsRequestSchema.parse({
       method: "tools/list",
       params: {},
-    };
-
-    // Parse and validate the request
-    const parsed = ListToolsRequestSchema.parse(request);
-    expect(parsed).toBeDefined();
-
-    // The server should have a tools/list handler
-    const handlers = (server as any).server._requestHandlers;
-    expect(handlers.get("tools/list")).toBeDefined();
-
-    // Call the handler
-    const handler = handlers.get("tools/list");
-    const result = await handler(parsed, {});
+    });
+    const result = await client.request<ToolListResult>(request);
 
-    expect(result).toBeDefined();
-    expect(result.tools).toBeInstanceOf(Array);
-    expect(result.tools).toHaveLength(3);
+    expect(result.tools).toHaveLength(6);
 
-    // Check the tools have proper JSON schemas
-    const docsTool = result.tools.find(
-      (t: any) => t.name === "assistantUIDocs",
-    );
-    expect(docsTool).toBeDefined();
-    expect(docsTool.inputSchema).toBeDefined();
-    expect(docsTool.inputSchema.type).toBe("object");
-    expect(docsTool.inputSchema.properties).toBeDefined();
-
-    const examplesTool = result.tools.find(
-      (t: any) => t.name === "assistantUIExamples",
-    );
-    expect(examplesTool).toBeDefined();
-    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);
+    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("should handle CallTool request for assistantUIDocs", async () => {
-    const request: CallToolRequest = {
+  it("calls assistantUIDocs", async () => {
+    const request = CallToolRequestSchema.parse({
       method: "tools/call",
       params: {
         name: "assistantUIDocs",
@@ -104,48 +162,55 @@ describe("MCP Protocol Integration", () => {
           paths: ["/"],
         },
       },
-    };
-
-    // Parse and validate the request
-    const parsed = CallToolRequestSchema.parse(request);
-    expect(parsed).toBeDefined();
+    });
+    const result = await client.request<ToolCallResult>(request);
 
-    // The server should have a tools/call handler
-    const handlers = (server as any).server._requestHandlers;
-    expect(handlers.get("tools/call")).toBeDefined();
-
-    // Call the handler through the MCP protocol layer
-    const handler = handlers.get("tools/call");
-    const result = await handler(parsed, {});
-
-    expect(result).toBeDefined();
-    expect(result.content).toBeDefined();
-    expect(result.content[0].type).toBe("text");
+    expect(result.content[0]?.type).toBe("text");
   });
 
-  it("should handle CallTool request for assistantUIExamples with no arguments", async () => {
-    const request: CallToolRequest = {
+  it("calls assistantUIExamples without arguments", async () => {
+    const request = CallToolRequestSchema.parse({
       method: "tools/call",
       params: {
         name: "assistantUIExamples",
         arguments: {},
       },
-    };
+    });
+    const result = await client.request<ToolCallResult>(request);
 
-    // Parse and validate the request
-    const parsed = CallToolRequestSchema.parse(request);
-    expect(parsed).toBeDefined();
+    expect(result.content[0]?.type).toBe("text");
+  });
 
-    // The server should have a tools/call handler
-    const handlers = (server as any).server._requestHandlers;
-    expect(handlers.get("tools/call")).toBeDefined();
+  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",
+    );
 
-    // Call the handler
-    const handler = handlers.get("tools/call");
-    const result = await handler(parsed, {});
+    expect(prompt).toMatchObject({
+      title: "assistant-ui Template Workflow",
+    });
+  });
 
-    expect(result).toBeDefined();
-    expect(result.content).toBeDefined();
-    expect(result.content[0].type).toBe("text");
+  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

@@ -0,0 +1,111 @@
+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();
+    },
+  };
+}

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

@@ -1,102 +1,133 @@
-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 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 handler("resources/list")(
-      { method: "resources/list", params: {} },
-      {},
-    );
+    const result = await client.request<ResourceListResult>({
+      method: "resources/list",
+      params: {},
+    });
+
     expect(result.resources.length).toBeGreaterThan(0);
     expect(
-      result.resources.some((r: any) => r.uri.startsWith("aui-docs:///")),
+      result.resources.some((resource) =>
+        resource.uri.startsWith("aui-docs:///"),
+      ),
     ).toBe(true);
     expect(
-      result.resources.some((r: any) => r.uri.startsWith("aui-example:///")),
+      result.resources.some((resource) =>
+        resource.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);
+    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 handler("resources/list")(
-      { method: "resources/list", params: {} },
-      {},
-    );
+    const list = await client.request<ResourceListResult>({
+      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("/"),
+      (resource) =>
+        resource.uri.startsWith(prefix) &&
+        resource.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);
+    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(
-      handler("resources/read")(
-        {
-          method: "resources/read",
-          params: { uri: "aui-docs:///definitely-not-a-real-doc" },
-        },
-        {},
-      ),
+      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 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);
+    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(
-      handler("resources/read")(
-        {
-          method: "resources/read",
-          params: { uri: "aui-example:///definitely-not-a-real-example" },
-        },
-        {},
-      ),
+      client.request({
+        method: "resources/read",
+        params: { uri: "aui-example:///definitely-not-a-real-example" },
+      }),
     ).rejects.toThrow();
   });
 });

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

@@ -5,11 +5,19 @@ 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 = {