test(igniteui-mcp): add MCP cli and runtime unit tests

packages/igniteui-mcp/igniteui-doc-mcp/src/index.ts

@@ -6,12 +6,13 @@ import { appendFileSync, mkdirSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import dotenv from "dotenv";
-import { TOOL_DESCRIPTIONS, SETUP_DOCS, SETUP_MD, BLAZOR_DOTNET_GUIDE, USAGE_GUIDE } from "./tools/constants.js";
+import { TOOL_DESCRIPTIONS, USAGE_GUIDE } from "./tools/constants.js";
 import type { DocsProvider } from "./providers/DocsProvider.js";
 import { RemoteDocsProvider } from "./providers/RemoteDocsProvider.js";
 import { LocalDocsProvider } from "./providers/LocalDocsProvider.js";
 import { getApiReferenceSchema, searchApiSchema } from "./tools/schemas.js";
 import { createGetApiReferenceHandler, createSearchApiHandler } from "./tools/handlers.js";
+import { buildProjectSetupGuide, sanitizeSearchDocsQuery } from "./tools/doc-tools.js";
 import { ApiDocLoader } from "./lib/api-doc-loader.js";
 import { getPlatforms } from "./config/platforms.js";
 
@@ -170,30 +171,7 @@ function registerDocTools(server: McpServer, docsProvider: DocsProvider) {
         return { content: [{ type: "text" as const, text: "Empty query." }] };
       }
 
-      // Sanitize user input for FTS4 MATCH syntax.
-      // Strip characters that are FTS4 operators or cause syntax errors:
-      //   " (phrase delimiter), ( ) (grouping), : (column filter), @ (internal)
-      // Preserve hyphens — the porter tokenizer handles them consistently
-      // at both index and query time (e.g. "grid-editing" stays as one phrase).
-      // Preserve trailing * — FTS4 prefix queries (e.g. grid*) rely on it,
-      // and the DB is built with prefix="2,3" indexes to support this.
-      const sanitized = queryText
-        .replace(/["(){}[\]:@]/g, " ")
-        .split(/\s+/)
-        .filter(Boolean)
-        .map((term) => {
-          // Terms ending with * are prefix queries — don't quote them
-          // because FTS4 treats "grid*" as a literal match for the
-          // asterisk character, while unquoted grid* does prefix expansion.
-          // Drop terms that are only asterisks (e.g. *, **) — they have
-          // no actual prefix and would cause an FTS4 syntax error.
-          if (term.endsWith("*")) {
-            return /[^*]/.test(term) ? term : null;
-          }
-          return `"${term}"`;
-        })
-        .filter(Boolean)
-        .join(" OR ");
+      const sanitized = sanitizeSearchDocsQuery(queryText);
 
       if (!sanitized) {
         log("search_docs", { query: queryText, framework }, "Empty query after sanitization.", 0);
@@ -223,27 +201,7 @@ function registerDocTools(server: McpServer, docsProvider: DocsProvider) {
     async ({ framework }) => {
       const start = performance.now();
 
-      if (!framework) {
-        const msg = "Which framework are you using? Please specify one of: angular, react, blazor, or webcomponents.";
-        log("get_project_setup_guide", {}, msg, 0);
-        return { content: [{ type: "text" as const, text: msg }] };
-      }
-
-      let result: string;
-
-      if (framework === "blazor") {
-        const docNames = SETUP_DOCS["blazor"] || [];
-        const sections: string[] = [BLAZOR_DOTNET_GUIDE];
-        for (const name of docNames) {
-          const { text, found } = await docsProvider.getDoc(framework, name);
-          if (found) {
-            sections.push(text);
-          }
-        }
-        result = sections.join("\n\n---\n\n");
-      } else {
-        result = SETUP_MD[framework] ?? `No setup guide available for framework: ${framework}`;
-      }
+      const result = await buildProjectSetupGuide(docsProvider, framework);
 
       log("get_project_setup_guide", { framework }, result, Math.round(performance.now() - start));
       return { content: [{ type: "text" as const, text: result }] };

packages/igniteui-mcp/igniteui-doc-mcp/src/tools/doc-tools.ts

@@ -0,0 +1,69 @@
+import type { DocsProvider } from '../providers/DocsProvider.js';
+import { BLAZOR_DOTNET_GUIDE, SETUP_DOCS, SETUP_MD } from './constants.js';
+
+export const MISSING_FRAMEWORK_MESSAGE =
+  'Which framework are you using? Please specify one of: angular, react, blazor, or webcomponents.';
+
+// Sanitize user input for FTS4 MATCH syntax.
+// Strip characters that are FTS4 operators or commonly cause syntax issues:
+//   " (phrase delimiter), ( ) (grouping), { } [ ] (extra grouping/bracketing),
+//   : (column filter), @ (internal)
+// Preserve hyphens — the porter tokenizer handles them consistently
+// at both index and query time (e.g. "grid-editing" stays as one phrase).
+// Preserve trailing * — FTS4 prefix queries (e.g. grid*) rely on it,
+// and the DB is built with prefix="2,3" indexes to support this.
+export function sanitizeSearchDocsQuery(queryText: string): string | null {
+  const sanitized = queryText
+    .replace(/["(){}[\]:@]/g, ' ')
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((term) => {
+      // Terms ending with * are prefix queries — don't quote them
+      // because FTS4 treats "grid*" as a literal match for the
+      // asterisk character, while unquoted grid* does prefix expansion.
+      // Drop terms that are only asterisks (e.g. *, **) — they have
+      // no actual prefix and would cause an FTS4 syntax error.
+      if (term.endsWith('*')) {
+        return /[^*]/.test(term) ? term : null;
+      }
+
+      return `"${term}"`;
+    })
+    .filter((term): term is string => Boolean(term))
+    .join(' OR ');
+
+  return sanitized || null;
+}
+
+// Build the setup-guide response for the requested framework.
+// For Blazor, combine the base .NET guide with any MCP-fetched docs
+// that are available for the configured setup document names.
+// For other frameworks, return the static setup markdown when present,
+// otherwise fall back to a simple "not available" message.
+export async function buildProjectSetupGuide(
+  docsProvider: DocsProvider,
+  framework?: string,
+): Promise<string> {
+  if (!framework) {
+    return MISSING_FRAMEWORK_MESSAGE;
+  }
+
+  if (framework === 'blazor') {
+    const docNames = SETUP_DOCS.blazor || [];
+    const sections: string[] = [BLAZOR_DOTNET_GUIDE];
+
+    for (const name of docNames) {
+      const { text, found } = await docsProvider.getDoc(framework, name);
+      if (found) {
+        sections.push(text);
+      }
+    }
+
+    return sections.join('\n\n---\n\n');
+  }
+
+  return (
+    SETUP_MD[framework] ??
+    `No setup guide available for framework: ${framework}`
+  );
+}

spec/unit/mcp-cli-spec.ts

@@ -0,0 +1,193 @@
+import child_process from "child_process";
+import { EventEmitter } from "events";
+import fs = require("fs");
+import * as path from "path";
+import yargs from "yargs";
+import mcp from "../../packages/cli/lib/commands/mcp";
+
+function createFakeChildProcess(): EventEmitter {
+	return new EventEmitter();
+}
+
+describe("Unit - MCP CLI command", () => {
+	const mcpPackageJson = path.join(process.cwd(), "node_modules", "@igniteui", "mcp-server", "package.json");
+	const mcpEntry = path.resolve(path.dirname(mcpPackageJson), "dist", "index.js");
+
+	let stderrWriteSpy: jasmine.Spy;
+	let spawnSpy: jasmine.Spy;
+
+	beforeEach(() => {
+		process.exitCode = undefined;
+		stderrWriteSpy = spyOn(process.stderr, "write").and.returnValue(true);
+		spawnSpy = spyOn(child_process, "spawn");
+	});
+
+	afterEach(() => {
+		process.exitCode = undefined;
+	});
+
+	function mockMcpPackageResolution(resolvedPath?: string, shouldThrow = false): void {
+		const moduleApi = require("module");
+		const originalResolveFilename = moduleApi._resolveFilename;
+
+		spyOn(moduleApi, "_resolveFilename").and.callFake((request: string, ...args: any[]) => {
+			if (request === "@igniteui/mcp-server/package.json") {
+				if (shouldThrow) {
+					throw new Error("Cannot find module");
+				}
+				return resolvedPath;
+			}
+
+			return originalResolveFilename.call(moduleApi, request, ...args);
+		});
+	}
+
+	function mockInstalledMcp(entryExists: boolean, child?: EventEmitter): EventEmitter {
+		const spawnedChild = child ?? createFakeChildProcess();
+		mockMcpPackageResolution(mcpPackageJson);
+		spyOn(fs, "existsSync").and.returnValue(entryExists);
+		spawnSpy.and.returnValue(spawnedChild as any);
+		return spawnedChild;
+	}
+
+	describe("metadata", () => {
+		it("registers the MCP command with the expected description", () => {
+			expect(mcp.command).toBe("mcp");
+			expect(mcp.describe).toBe("Starts the Ignite UI MCP server for AI assistant integration");
+		});
+
+		it("configures the debug and remote options", () => {
+			const buildParser = mcp.builder as any;
+			const parser = buildParser(yargs([]));
+			const argv = parser.parseSync(["--remote", "https://docs.example.test", "--debug"]);
+			const defaults = buildParser(yargs([])).parseSync([]);
+
+			expect(argv.remote).toBe("https://docs.example.test");
+			expect(argv.debug).toBeTrue();
+			expect(defaults.debug).toBeFalse();
+		});
+	});
+
+	describe("preflight checks", () => {
+		it("shows an install message when the MCP server package cannot be resolved", async () => {
+			const existsSyncSpy = spyOn(fs, "existsSync");
+			mockMcpPackageResolution(undefined, true);
+
+			await mcp.handler({ _: ["mcp"], $0: "ig" } as any);
+
+			expect(process.exitCode).toBe(1);
+			expect(existsSyncSpy).not.toHaveBeenCalled();
+			expect(spawnSpy).not.toHaveBeenCalled();
+
+			expect(stderrWriteSpy).toHaveBeenCalled();
+			const message = stderrWriteSpy.calls.allArgs().map(args => args[0]).join("");
+			expect(message).toContain("MCP server package not found");
+			expect(message).toContain("yarn install");
+		});
+
+		it("shows a build message when the MCP server entry does not exist", async () => {
+			mockMcpPackageResolution(mcpPackageJson);
+			spyOn(fs, "existsSync").and.returnValue(false);
+
+			await mcp.handler({ _: ["mcp"], $0: "ig" } as any);
+
+			expect(fs.existsSync).toHaveBeenCalledWith(mcpEntry);
+			expect(process.exitCode).toBe(1);
+			expect(spawnSpy).not.toHaveBeenCalled();
+
+			expect(stderrWriteSpy).toHaveBeenCalled();
+			const message = stderrWriteSpy.calls.allArgs().map(args => args[0]).join("");
+			expect(message).toContain("MCP server not built");
+			expect(message).toContain("build:mcp");
+		});
+	});
+
+	describe("runtime behavior", () => {
+		it("starts the installed MCP server with stdio inheritance", async () => {
+			const child = mockInstalledMcp(true);
+			const result = mcp.handler({ _: ["mcp"], $0: "ig" } as any) as Promise<void>;
+
+			expect(spawnSpy).toHaveBeenCalledWith(
+				process.execPath,
+				[mcpEntry],
+				{ stdio: "inherit" }
+			);
+
+			child.emit("exit", 0);
+			await result;
+		});
+
+		it("forwards remote and debug flags to the installed MCP server", async () => {
+			const remoteUrl = "https://docs.example.test";
+			const child = mockInstalledMcp(true);
+			const result = mcp.handler({
+				remote: remoteUrl,
+				debug: true,
+				_: ["mcp"],
+				$0: "ig"
+			} as any) as Promise<void>;
+
+			expect(spawnSpy).toHaveBeenCalledWith(
+				process.execPath,
+				[mcpEntry, "--remote", remoteUrl, "--debug"],
+				{ stdio: "inherit" }
+			);
+
+			child.emit("exit", 0);
+			await result;
+		});
+
+		it("forwards only the debug flag when remote mode is not used", async () => {
+			const child = mockInstalledMcp(true);
+			const result = mcp.handler({
+				debug: true,
+				_: ["mcp"],
+				$0: "ig"
+			} as any) as Promise<void>;
+
+			expect(spawnSpy).toHaveBeenCalledWith(
+				process.execPath,
+				[mcpEntry, "--debug"],
+				{ stdio: "inherit" }
+			);
+
+			child.emit("exit", 0);
+			await result;
+		});
+
+		it("propagates the child process exit code", async () => {
+			const child = mockInstalledMcp(true);
+			const result = mcp.handler({ _: ["mcp"], $0: "ig" } as any) as Promise<void>;
+
+			child.emit("exit", 7);
+			await result;
+
+			expect(process.exitCode).toBe(7);
+		});
+
+		it("defaults the process exit code to 0 when the child exits without one", async () => {
+			const child = mockInstalledMcp(true);
+			const result = mcp.handler({ _: ["mcp"], $0: "ig" } as any) as Promise<void>;
+
+			child.emit("exit", null);
+			await result;
+
+			expect(process.exitCode).toBe(0);
+		});
+
+		it("reports child process startup errors", async () => {
+			const child = mockInstalledMcp(true);
+			const error = new Error("boom");
+			const result = mcp.handler({ _: ["mcp"], $0: "ig" } as any) as Promise<void>;
+
+			child.emit("error", error);
+
+			await expectAsync(result).toBeRejectedWith(error);
+
+			expect(stderrWriteSpy).toHaveBeenCalled();
+			const message = stderrWriteSpy.calls.allArgs().map(args => args[0]).join("");
+			expect(message).toContain("Failed to start MCP server");
+			expect(message).toContain("boom");
+		});
+	});
+});