feat: Add remove documents functionality

Adds a new tool and CLI command to remove indexed documentation for a specific library version.

- **MCP Tool:** `remove_docs`
  - Implemented in `src/tools/RemoveTool.ts`.
  - Registered in `src/mcp/index.ts`.
  - Uses existing `DocumentManagementService.removeAllDocuments`.
- **CLI Command:** `remove <library>`
  - Added to `src/cli.ts`.
  - Uses existing `DocumentManagementService.removeAllDocuments`.
  - Takes library name as positional argument and optional `--version` flag.
- **Testing:** Added unit tests in `src/tools/RemoveTool.test.ts`.

Author: arabold

README.md

@@ -15,6 +15,7 @@ The server exposes MCP tools for:
 - Searching documentation (`search_docs`).
 - Listing indexed libraries (`list_libraries`).
 - Finding appropriate versions (`find_version`).
+- Removing indexed documents (`remove_docs`).
 
 A companion CLI (`docs-mcp`) is also included for local management and interaction (note: the CLI `scrape` command waits for completion).
 
@@ -112,6 +113,7 @@ docs-mcp --help
 docs-mcp scrape --help
 docs-mcp search --help
 docs-mcp find-version --help
+docs-mcp remove --help
 ```
 
 ### Scraping Documentation (`scrape`)
@@ -218,6 +220,28 @@ Lists all libraries currently indexed in the store.
 docs-mcp list-libraries
 ```
 
+### Removing Documentation (`remove`)
+
+Removes indexed documents for a specific library and version.
+
+```bash
+docs-mcp remove <library> [options]
+```
+
+**Options:**
+
+- `-v, --version <string>`: The specific version to remove. If omitted, removes **unversioned** documents for the library.
+
+**Examples:**
+
+```bash
+# Remove React 18.2.0 docs
+docs-mcp remove react --version 18.2.0
+
+# Remove unversioned React docs
+docs-mcp remove react
+```
+
 ### Version Handling Summary
 
 - **Scraping:** Requires a specific, valid version (`X.Y.Z`, `X.Y.Z-pre`, `X.Y`, `X`) or no version (for unversioned docs). Ranges (`X.x`) are invalid for scraping.

src/cli.ts

@@ -104,7 +104,7 @@ async function main() {
       });
 
     program
-      .command("list-libraries")
+      .command("list")
       .description("List all available libraries and their versions")
       .action(async () => {
         const result = await tools.listLibraries.execute();
@@ -132,6 +132,34 @@ async function main() {
         console.log(versionInfo); // Log the descriptive string from the tool
       });
 
+    program
+      .command("remove <library>") // Library as positional argument
+      .description("Remove documents for a specific library and version")
+      .option(
+        "-v, --version <string>",
+        "Version to remove (optional, removes unversioned if omitted)",
+      )
+      .action(async (library, options) => {
+        // library is now the first arg
+        if (!docService) {
+          throw new Error("Document service not initialized.");
+        }
+        const { version } = options; // Get version from options
+        try {
+          await docService.removeAllDocuments(library, version);
+          console.log(
+            `✅ Successfully removed documents for ${library}${version ? `@${version}` : " (unversioned)"}.`,
+          );
+        } catch (error) {
+          console.error(
+            `❌ Failed to remove documents for ${library}${version ? `@${version}` : " (unversioned)"}:`,
+            error instanceof Error ? error.message : String(error),
+          );
+          // Re-throw to trigger the main catch block for shutdown
+          throw error;
+        }
+      });
+
     await program.parseAsync();
   } catch (error) {
     console.error("Error:", error instanceof Error ? error.message : String(error));

src/mcp/index.ts

@@ -12,6 +12,7 @@ import {
   GetJobInfoTool,
   ListJobsTool,
   ListLibrariesTool,
+  RemoveTool,
   ScrapeTool,
   SearchTool,
   VersionNotFoundError,
@@ -48,6 +49,7 @@ export async function startServer() {
       listJobs: new ListJobsTool(pipelineManager),
       getJobInfo: new GetJobInfoTool(pipelineManager),
       cancelJob: new CancelJobTool(pipelineManager),
+      remove: new RemoveTool(docService), // Instantiate RemoveTool
     };
 
     const server = new McpServer(
@@ -64,7 +66,7 @@ export async function startServer() {
       },
     );
 
-    // --- Existing Tool Definitions ---
+    // --- Tool Definitions ---
 
     // Scrape docs tool (Keep as is for now, but likely needs ScrapeTool refactor)
     server.tool(
@@ -333,6 +335,34 @@ ${formattedResults.join("")}`,
       },
     );
 
+    // Remove docs tool
+    server.tool(
+      "remove_docs",
+      "Remove indexed documentation for a library version.",
+      {
+        library: z.string().describe("Name of the library"),
+        version: z
+          .string()
+          .optional()
+          .describe("Version of the library (optional, removes unversioned if omitted)"),
+      },
+      async ({ library, version }) => {
+        try {
+          // Execute the remove tool logic
+          const result = await tools.remove.execute({ library, version });
+          // Use the message from the tool's successful execution
+          return createResponse(result.message);
+        } catch (error) {
+          // Catch errors thrown by the RemoveTool's execute method
+          return createError(
+            `Failed to remove documents: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          );
+        }
+      },
+    );
+
     server.prompt(
       "docs",
       "Search indexed documentation",

src/tools/RemoveTool.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { MockedObject } from "vitest"; // Import MockedObject
+import type { DocumentManagementService } from "../store";
+import { RemoveTool, type RemoveToolArgs } from "./RemoveTool";
+import { ToolError } from "./errors";
+
+// Create a properly typed mock using MockedObject
+const mockDocService = {
+  removeAllDocuments: vi.fn(),
+  // Add other methods used by DocumentManagementService if needed, mocking them with vi.fn()
+} as MockedObject<DocumentManagementService>;
+
+describe("RemoveTool", () => {
+  let removeTool: RemoveTool;
+
+  beforeEach(() => {
+    // Reset mocks before each test
+    vi.resetAllMocks(); // Resets all mocks, including those on mockDocService
+    removeTool = new RemoveTool(mockDocService); // Pass the typed mock
+  });
+
+  it("should call removeAllDocuments with library and version", async () => {
+    const args: RemoveToolArgs = { library: "react", version: "18.2.0" };
+    // Now TypeScript knows mockDocService.removeAllDocuments is a mock function
+    mockDocService.removeAllDocuments.mockResolvedValue(undefined);
+
+    const result = await removeTool.execute(args);
+
+    expect(mockDocService.removeAllDocuments).toHaveBeenCalledTimes(1);
+    expect(mockDocService.removeAllDocuments).toHaveBeenCalledWith("react", "18.2.0");
+    expect(result).toEqual({
+      message: "Successfully removed documents for react@18.2.0.",
+    });
+  });
+
+  it("should call removeAllDocuments with library and undefined version for unversioned", async () => {
+    const args: RemoveToolArgs = { library: "lodash" };
+    mockDocService.removeAllDocuments.mockResolvedValue(undefined);
+
+    const result = await removeTool.execute(args);
+
+    expect(mockDocService.removeAllDocuments).toHaveBeenCalledTimes(1);
+    expect(mockDocService.removeAllDocuments).toHaveBeenCalledWith("lodash", undefined);
+    expect(result).toEqual({
+      message: "Successfully removed documents for lodash (unversioned).",
+    });
+  });
+
+  it("should handle empty string version as unversioned", async () => {
+    const args: RemoveToolArgs = { library: "moment", version: "" };
+    mockDocService.removeAllDocuments.mockResolvedValue(undefined);
+
+    const result = await removeTool.execute(args);
+
+    expect(mockDocService.removeAllDocuments).toHaveBeenCalledTimes(1);
+    expect(mockDocService.removeAllDocuments).toHaveBeenCalledWith("moment", "");
+    expect(result).toEqual({
+      message: "Successfully removed documents for moment (unversioned).",
+    });
+  });
+
+  it("should throw ToolError if removeAllDocuments fails", async () => {
+    const args: RemoveToolArgs = { library: "vue", version: "3.0.0" };
+    const testError = new Error("Database connection failed");
+    mockDocService.removeAllDocuments.mockRejectedValue(testError);
+
+    // Use try-catch to ensure the mock call check happens even after rejection
+    try {
+      await removeTool.execute(args);
+    } catch (e) {
+      expect(e).toBeInstanceOf(ToolError);
+      expect((e as ToolError).message).toContain(
+        "Failed to remove documents for vue@3.0.0: Database connection failed",
+      );
+    }
+    // Verify the call happened
+    expect(mockDocService.removeAllDocuments).toHaveBeenCalledWith("vue", "3.0.0");
+  });
+
+  it("should throw ToolError with correct message for unversioned failure", async () => {
+    const args: RemoveToolArgs = { library: "angular" };
+    const testError = new Error("Filesystem error");
+    mockDocService.removeAllDocuments.mockRejectedValue(testError);
+
+    // Use try-catch to ensure the mock call check happens even after rejection
+    try {
+      await removeTool.execute(args);
+    } catch (e) {
+      expect(e).toBeInstanceOf(ToolError);
+      expect((e as ToolError).message).toContain(
+        "Failed to remove documents for angular (unversioned): Filesystem error",
+      );
+    }
+    // Verify the call happened
+    expect(mockDocService.removeAllDocuments).toHaveBeenCalledWith("angular", undefined);
+  });
+});

src/tools/RemoveTool.ts

@@ -0,0 +1,72 @@
+import type { JSONSchema7 } from "json-schema";
+import type { DocumentManagementService } from "../store";
+import { logger } from "../utils/logger";
+import { ToolError } from "./errors"; // Keep ToolError for potential internal errors
+
+/**
+ * Input schema for the remove_docs tool.
+ */
+export const RemoveToolInputSchema: JSONSchema7 = {
+  type: "object",
+  properties: {
+    library: {
+      type: "string",
+      description: "Name of the library",
+    },
+    version: {
+      type: "string",
+      description: "Version of the library (optional, removes unversioned if omitted)",
+    },
+  },
+  required: ["library"],
+  additionalProperties: false,
+};
+
+/**
+ * Represents the arguments for the remove_docs tool.
+ * The MCP server should validate the input against RemoveToolInputSchema before calling execute.
+ */
+export interface RemoveToolArgs {
+  library: string;
+  version?: string;
+}
+
+/**
+ * Tool to remove indexed documentation for a specific library version.
+ * This class provides the core logic, intended to be called by the McpServer.
+ */
+export class RemoveTool {
+  readonly name = "remove_docs";
+  readonly description = "Remove indexed documentation for a library version.";
+  readonly inputSchema = RemoveToolInputSchema;
+
+  constructor(private readonly documentManagementService: DocumentManagementService) {}
+
+  /**
+   * Executes the tool to remove the specified library version documents.
+   * Assumes args have been validated by the caller (McpServer) against inputSchema.
+   * Returns a simple success message or throws an error.
+   */
+  async execute(args: RemoveToolArgs): Promise<{ message: string }> {
+    const { library, version } = args;
+
+    logger.info(
+      `Executing ${this.name} for library: ${library}${version ? `, version: ${version}` : " (unversioned)"}`,
+    );
+
+    try {
+      // Core logic: Call the document management service
+      await this.documentManagementService.removeAllDocuments(library, version);
+
+      const message = `Successfully removed documents for ${library}${version ? `@${version}` : " (unversioned)"}.`;
+      logger.info(message);
+      // Return a simple success object, the McpServer will format the final response
+      return { message };
+    } catch (error) {
+      const errorMessage = `Failed to remove documents for ${library}${version ? `@${version}` : " (unversioned)"}: ${error instanceof Error ? error.message : String(error)}`;
+      logger.error(`Error executing ${this.name}: ${errorMessage}`);
+      // Re-throw the error for the McpServer to handle and format
+      throw new ToolError(errorMessage, this.name);
+    }
+  }
+}

src/tools/index.ts

@@ -5,4 +5,5 @@ export * from "./ScrapeTool";
 export * from "./ListJobsTool";
 export * from "./GetJobInfoTool";
 export * from "./CancelJobTool";
+export * from "./RemoveTool";
 export * from "./errors";