fix(search): remove exactMatch flag from MCP API, improve internal handling

- remove exactMatch flag from the MCP server interface to prevent confusion for LLM/API users
- keep exactMatch logic for CLI/internal use, now robustly throws VersionNotFoundError with available versions if used without a version
- add and update unit tests for all exactMatch scenarios

resolves #24

Author: arabold

src/mcp/index.ts

@@ -135,7 +135,6 @@ export async function startServer() {
       "Search indexed documentation. Examples:\n" +
         '- {library: "react", query: "how do hooks work"} -> matches latest version of React\n' +
         '- {library: "react", version: "18.0.0", query: "how do hooks work"} -> matches React 18.0.0 or earlier\n' +
-        '- {library: "react", version: "18.0.0", query: "how do hooks work", exactMatch: true} -> only React 18.0.0\n' +
         '- {library: "typescript", version: "5.x", query: "ReturnType example"} -> any TypeScript 5.x.x version\n' +
         '- {library: "typescript", version: "5.2.x", query: "ReturnType example"} -> any TypeScript 5.2.x version',
       {
@@ -148,20 +147,15 @@ export async function startServer() {
           ),
         query: z.string().describe("Search query"),
         limit: z.number().optional().default(5).describe("Maximum number of results"),
-        exactMatch: z
-          .boolean()
-          .optional()
-          .default(false)
-          .describe("Only use exact version match"),
       },
-      async ({ library, version, query, limit, exactMatch }) => {
+      async ({ library, version, query, limit }) => {
         try {
           const result = await tools.search.execute({
             library,
             version,
             query,
             limit,
-            exactMatch,
+            exactMatch: false, // Always false for MCP interface
           });
 
           const formattedResults = result.results.map(

src/tools/SearchTool.test.ts

@@ -20,6 +20,7 @@ describe("SearchTool", () => {
       validateLibraryExists: vi.fn(),
       findBestVersion: vi.fn(),
       searchStore: vi.fn(),
+      listVersions: vi.fn(),
     };
 
     searchTool = new SearchTool(mockDocService as DocumentManagementService);
@@ -58,6 +59,37 @@ describe("SearchTool", () => {
     expect(result.error).toBeUndefined();
   });
 
+  it("should throw VersionNotFoundError when exactMatch is true but no version is specified", async () => {
+    const options: SearchToolOptions = {
+      ...baseOptions,
+      exactMatch: true,
+    };
+    const availableVersions = [{ version: "1.0.0", indexed: true }];
+    (mockDocService.validateLibraryExists as Mock).mockResolvedValue(undefined);
+    (mockDocService.listVersions as Mock).mockResolvedValue(availableVersions);
+
+    await expect(searchTool.execute(options)).rejects.toThrow(VersionNotFoundError);
+    expect(mockDocService.validateLibraryExists).toHaveBeenCalledWith("test-lib");
+    expect(mockDocService.listVersions).toHaveBeenCalledWith("test-lib");
+    expect(mockDocService.searchStore).not.toHaveBeenCalled();
+  });
+
+  it("should throw VersionNotFoundError when exactMatch is true with 'latest' version", async () => {
+    const options: SearchToolOptions = {
+      ...baseOptions,
+      version: "latest",
+      exactMatch: true,
+    };
+    const availableVersions = [{ version: "1.0.0", indexed: true }];
+    (mockDocService.validateLibraryExists as Mock).mockResolvedValue(undefined);
+    (mockDocService.listVersions as Mock).mockResolvedValue(availableVersions);
+
+    await expect(searchTool.execute(options)).rejects.toThrow(VersionNotFoundError);
+    expect(mockDocService.validateLibraryExists).toHaveBeenCalledWith("test-lib");
+    expect(mockDocService.listVersions).toHaveBeenCalledWith("test-lib");
+    expect(mockDocService.searchStore).not.toHaveBeenCalled();
+  });
+
   it("should find best version and search when exactMatch is false (default)", async () => {
     const options: SearchToolOptions = { ...baseOptions, version: "1.x" };
     const findVersionResult = { bestMatch: "1.2.0", hasUnversioned: false };
@@ -105,7 +137,8 @@ describe("SearchTool", () => {
 
     await searchTool.execute(options);
 
-    expect(mockDocService.findBestVersion).toHaveBeenCalledWith("test-lib", "latest"); // Default version
+    // The implementation passes undefined, which is defaulted to "latest" in the method
+    expect(mockDocService.findBestVersion).toHaveBeenCalledWith("test-lib", undefined);
     expect(mockDocService.searchStore).toHaveBeenCalledWith(
       "test-lib",
       "1.2.0",

src/tools/SearchTool.ts

@@ -35,18 +35,33 @@ export class SearchTool {
   }
 
   async execute(options: SearchToolOptions): Promise<SearchToolResult> {
-    const { library, version = "latest", query, limit = 5, exactMatch = false } = options;
+    const { library, version, query, limit = 5, exactMatch = false } = options;
+
+    // When exactMatch is true, version must be specified and not 'latest'
+    if (exactMatch && (!version || version === "latest")) {
+      // Get available versions for error message
+      await this.docService.validateLibraryExists(library);
+      const versions = await this.docService.listVersions(library);
+      throw new VersionNotFoundError(
+        library,
+        "latest",
+        versions, // versions already has the correct { version: string, indexed: boolean } format
+      );
+    }
+
+    // Default to 'latest' only when exactMatch is false
+    const resolvedVersion = version || "latest";
 
     logger.info(
-      `🔍 Searching ${library}@${version} for: ${query}${exactMatch ? " (exact match)" : ""}`,
+      `🔍 Searching ${library}@${resolvedVersion} for: ${query}${exactMatch ? " (exact match)" : ""}`,
     );
 
     try {
       // 1. Validate library exists first
       await this.docService.validateLibraryExists(library);
 
       // 2. Proceed with version finding and searching
-      let versionToSearch: string | null | undefined = version;
+      let versionToSearch: string | null | undefined = resolvedVersion;
 
       if (!exactMatch) {
         // If not exact match, find the best version (which might be null)