@mhalder/qdrant-mcp-server 3.2.0 → 3.3.0

package/src/tools/git-history.ts

@@ -3,9 +3,13 @@
  */
 
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import logger from "../logger.js";
 import type { GitHistoryIndexer } from "../git/indexer.js";
+import { withToolLogging } from "./logging.js";
 import * as schemas from "./schemas.js";
 
+const log = logger.child({ component: "tools" });
+
 export interface GitHistoryToolDependencies {
   gitHistoryIndexer: GitHistoryIndexer;
 }
@@ -25,30 +29,51 @@ export function registerGitHistoryTools(
         "Index a repository's git commit history for semantic search. Extracts commit messages, metadata, and optionally diffs to enable finding relevant past commits. Useful for finding similar fixes, understanding change patterns, or learning from past work.",
       inputSchema: schemas.IndexGitHistorySchema,
     },
-    async ({ path, forceReindex, sinceDate, maxCommits }) => {
-      const stats = await gitHistoryIndexer.indexHistory(
-        path,
-        { forceReindex, sinceDate, maxCommits },
-        (progress) => {
-          console.error(
-            `[${progress.phase}] ${progress.percentage}% - ${progress.message}`,
-          );
-        },
-      );
+    withToolLogging(
+      "index_git_history",
+      async ({ path, forceReindex, sinceDate, maxCommits }, extra) => {
+        log.info(
+          { tool: "index_git_history", path, forceReindex },
+          "Tool called",
+        );
+        const progressToken = extra._meta?.progressToken;
 
-      let statusMessage = `Indexed ${stats.commitsIndexed}/${stats.commitsScanned} commits (${stats.chunksCreated} chunks) in ${(stats.durationMs / 1000).toFixed(1)}s`;
+        const stats = await gitHistoryIndexer.indexHistory(
+          path,
+          { forceReindex, sinceDate, maxCommits },
+          (progress) => {
+            log.debug(
+              { phase: progress.phase, percentage: progress.percentage },
+              progress.message,
+            );
+            if (progressToken !== undefined) {
+              extra.sendNotification({
+                method: "notifications/progress",
+                params: {
+                  progressToken,
+                  progress: progress.percentage,
+                  total: 100,
+                  message: `[${progress.phase}] ${progress.message}`,
+                },
+              });
+            }
+          },
+        );
 
-      if (stats.status === "partial") {
-        statusMessage += `\n\nWarnings:\n${stats.errors?.join("\n")}`;
-      } else if (stats.status === "failed") {
-        statusMessage = `Indexing failed:\n${stats.errors?.join("\n")}`;
-      }
+        let statusMessage = `Indexed ${stats.commitsIndexed}/${stats.commitsScanned} commits (${stats.chunksCreated} chunks) in ${(stats.durationMs / 1000).toFixed(1)}s`;
 
-      return {
-        content: [{ type: "text", text: statusMessage }],
-        isError: stats.status === "failed",
-      };
-    },
+        if (stats.status === "partial") {
+          statusMessage += `\n\nWarnings:\n${stats.errors?.join("\n")}`;
+        } else if (stats.status === "failed") {
+          statusMessage = `Indexing failed:\n${stats.errors?.join("\n")}`;
+        }
+
+        return {
+          content: [{ type: "text", text: statusMessage }],
+          isError: stats.status === "failed",
+        };
+      },
+    ),
   );
 
   // search_git_history
@@ -60,47 +85,62 @@ export function registerGitHistoryTools(
         "Search indexed git history using natural language queries. Returns semantically relevant commits with metadata. Useful for finding past fixes, similar changes, or understanding how problems were solved before.",
       inputSchema: schemas.SearchGitHistorySchema,
     },
-    async ({ path, query, limit, commitTypes, authors, dateFrom, dateTo }) => {
-      const results = await gitHistoryIndexer.searchHistory(path, query, {
+    withToolLogging(
+      "search_git_history",
+      async ({
+        path,
+        query,
         limit,
         commitTypes,
         authors,
         dateFrom,
         dateTo,
-      });
+      }) => {
+        log.info(
+          { tool: "search_git_history", path, query: query.substring(0, 80) },
+          "Tool called",
+        );
+        const results = await gitHistoryIndexer.searchHistory(path, query, {
+          limit,
+          commitTypes,
+          authors,
+          dateFrom,
+          dateTo,
+        });
+
+        if (results.length === 0) {
+          return {
+            content: [
+              { type: "text", text: `No results found for query: "${query}"` },
+            ],
+          };
+        }
+
+        // Format results
+        const formattedResults = results
+          .map(
+            (r, idx) =>
+              `\n--- Result ${idx + 1} (score: ${r.score.toFixed(3)}) ---\n` +
+              `Commit: ${r.shortHash}\n` +
+              `Type: ${r.commitType}\n` +
+              `Author: ${r.author}\n` +
+              `Date: ${r.date.split("T")[0]}\n` +
+              `Subject: ${r.subject}\n` +
+              `Files: ${r.files.slice(0, 5).join(", ")}${r.files.length > 5 ? ` (+${r.files.length - 5} more)` : ""}\n\n` +
+              `${r.content.substring(0, 500)}${r.content.length > 500 ? "..." : ""}\n`,
+          )
+          .join("\n");
 
-      if (results.length === 0) {
         return {
           content: [
-            { type: "text", text: `No results found for query: "${query}"` },
+            {
+              type: "text",
+              text: `Found ${results.length} result(s):\n${formattedResults}`,
+            },
           ],
         };
-      }
-
-      // Format results
-      const formattedResults = results
-        .map(
-          (r, idx) =>
-            `\n--- Result ${idx + 1} (score: ${r.score.toFixed(3)}) ---\n` +
-            `Commit: ${r.shortHash}\n` +
-            `Type: ${r.commitType}\n` +
-            `Author: ${r.author}\n` +
-            `Date: ${r.date.split("T")[0]}\n` +
-            `Subject: ${r.subject}\n` +
-            `Files: ${r.files.slice(0, 5).join(", ")}${r.files.length > 5 ? ` (+${r.files.length - 5} more)` : ""}\n\n` +
-            `${r.content.substring(0, 500)}${r.content.length > 500 ? "..." : ""}\n`,
-        )
-        .join("\n");
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Found ${results.length} result(s):\n${formattedResults}`,
-          },
-        ],
-      };
-    },
+      },
+    ),
   );
 
   // index_new_commits
@@ -112,13 +152,28 @@ export function registerGitHistoryTools(
         "Incrementally index only new commits since the last indexing. Much faster than full re-indexing when keeping the index up to date with recent changes.",
       inputSchema: schemas.IndexNewCommitsSchema,
     },
-    async ({ path }) => {
+    withToolLogging("index_new_commits", async ({ path }, extra) => {
+      log.info({ tool: "index_new_commits", path }, "Tool called");
+      const progressToken = extra._meta?.progressToken;
+
       const stats = await gitHistoryIndexer.indexNewCommits(
         path,
         (progress) => {
-          console.error(
-            `[${progress.phase}] ${progress.percentage}% - ${progress.message}`,
+          log.debug(
+            { phase: progress.phase, percentage: progress.percentage },
+            progress.message,
           );
+          if (progressToken !== undefined) {
+            extra.sendNotification({
+              method: "notifications/progress",
+              params: {
+                progressToken,
+                progress: progress.percentage,
+                total: 100,
+                message: `[${progress.phase}] ${progress.message}`,
+              },
+            });
+          }
         },
       );
 
@@ -134,7 +189,7 @@ export function registerGitHistoryTools(
       return {
         content: [{ type: "text", text: message }],
       };
-    },
+    }),
   );
 
   // get_git_index_status
@@ -146,7 +201,8 @@ export function registerGitHistoryTools(
         "Get the indexing status and statistics for a repository's git history index.",
       inputSchema: schemas.GetGitIndexStatusSchema,
     },
-    async ({ path }) => {
+    withToolLogging("get_git_index_status", async ({ path }) => {
+      log.info({ tool: "get_git_index_status", path }, "Tool called");
       const status = await gitHistoryIndexer.getIndexStatus(path);
 
       if (status.status === "not_indexed") {
@@ -184,7 +240,7 @@ export function registerGitHistoryTools(
       return {
         content: [{ type: "text", text: JSON.stringify(statusInfo, null, 2) }],
       };
-    },
+    }),
   );
 
   // clear_git_index
@@ -196,13 +252,14 @@ export function registerGitHistoryTools(
         "Delete all indexed git history data for a repository. This is irreversible and will remove the entire git history index.",
       inputSchema: schemas.ClearGitIndexSchema,
     },
-    async ({ path }) => {
+    withToolLogging("clear_git_index", async ({ path }) => {
+      log.info({ tool: "clear_git_index", path }, "Tool called");
       await gitHistoryIndexer.clearIndex(path);
       return {
         content: [
           { type: "text", text: `Git history index cleared for "${path}".` },
         ],
       };
-    },
+    }),
   );
 }

package/src/tools/logging.test.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { withToolLogging } from "./logging.js";
+
+vi.mock("../logger.js", () => ({
+  default: {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+    fatal: vi.fn(),
+    trace: vi.fn(),
+    child: vi.fn().mockReturnValue({
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    }),
+  },
+}));
+
+import logger from "../logger.js";
+
+const mockLog = logger.child({ component: "tools" }) as unknown as {
+  info: ReturnType<typeof vi.fn>;
+  warn: ReturnType<typeof vi.fn>;
+  error: ReturnType<typeof vi.fn>;
+};
+
+describe("withToolLogging", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should log completion with durationMs on success", async () => {
+    const handler = vi.fn().mockResolvedValue({
+      content: [{ type: "text", text: "Success" }],
+    });
+
+    const wrapped = withToolLogging("create_collection", handler);
+    const result = await wrapped({ name: "test" });
+
+    expect(result.content[0]).toEqual({ type: "text", text: "Success" });
+    expect(mockLog.info).toHaveBeenCalledWith(
+      expect.objectContaining({
+        tool: "create_collection",
+        durationMs: expect.any(Number),
+      }),
+      "Tool completed",
+    );
+  });
+
+  it("should log error when result has isError: true", async () => {
+    const handler = vi.fn().mockResolvedValue({
+      content: [{ type: "text", text: "Error: Collection not found" }],
+      isError: true,
+    });
+
+    const wrapped = withToolLogging("add_documents", handler);
+    const result = await wrapped({ collection: "test" });
+
+    expect(result.isError).toBe(true);
+    expect(mockLog.error).toHaveBeenCalledWith(
+      expect.objectContaining({
+        tool: "add_documents",
+        durationMs: expect.any(Number),
+        error: "Error: Collection not found",
+      }),
+      "Tool failed",
+    );
+    expect(mockLog.info).not.toHaveBeenCalled();
+  });
+
+  it("should log error and re-throw when handler throws", async () => {
+    const testError = new Error("Connection refused");
+    const handler = vi.fn().mockRejectedValue(testError);
+
+    const wrapped = withToolLogging("list_collections", handler);
+
+    await expect(wrapped()).rejects.toThrow("Connection refused");
+    expect(mockLog.error).toHaveBeenCalledWith(
+      expect.objectContaining({
+        tool: "list_collections",
+        durationMs: expect.any(Number),
+        err: testError,
+      }),
+      "Tool threw an error",
+    );
+  });
+
+  it('should log warn for search tool with "No results found" response', async () => {
+    const handler = vi.fn().mockResolvedValue({
+      content: [{ type: "text", text: 'No results found for query: "test"' }],
+    });
+
+    const wrapped = withToolLogging("semantic_search", handler);
+    await wrapped({ collection: "test", query: "test" });
+
+    expect(mockLog.warn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        tool: "semantic_search",
+        durationMs: expect.any(Number),
+      }),
+      "Tool completed with no results",
+    );
+    expect(mockLog.info).not.toHaveBeenCalled();
+  });
+
+  it("should log warn for search tool with empty JSON array response", async () => {
+    const handler = vi.fn().mockResolvedValue({
+      content: [{ type: "text", text: "[]" }],
+    });
+
+    const wrapped = withToolLogging("hybrid_search", handler);
+    await wrapped({ collection: "test", query: "test" });
+
+    expect(mockLog.warn).toHaveBeenCalledWith(
+      expect.objectContaining({ tool: "hybrid_search" }),
+      "Tool completed with no results",
+    );
+  });
+
+  it("should log warn for search tool with Found 0 result(s) response", async () => {
+    const handler = vi.fn().mockResolvedValue({
+      content: [{ type: "text", text: "Found 0 result(s):\n" }],
+    });
+
+    const wrapped = withToolLogging("search_code", handler);
+    await wrapped({ path: "/test", query: "test" });
+
+    expect(mockLog.warn).toHaveBeenCalledWith(
+      expect.objectContaining({ tool: "search_code" }),
+      "Tool completed with no results",
+    );
+  });
+
+  it("should NOT log warn for non-search tool with empty-looking response", async () => {
+    const handler = vi.fn().mockResolvedValue({
+      content: [{ type: "text", text: "No results found for query: test" }],
+    });
+
+    const wrapped = withToolLogging("get_index_status", handler);
+    await wrapped({ path: "/test" });
+
+    // Should log info, not warn, because get_index_status is not a search tool
+    expect(mockLog.info).toHaveBeenCalledWith(
+      expect.objectContaining({ tool: "get_index_status" }),
+      "Tool completed",
+    );
+    expect(mockLog.warn).not.toHaveBeenCalled();
+  });
+
+  it("should log info for search tool with actual results", async () => {
+    const handler = vi.fn().mockResolvedValue({
+      content: [{ type: "text", text: "Found 5 result(s):\n..." }],
+    });
+
+    const wrapped = withToolLogging("search_code", handler);
+    await wrapped({ path: "/test", query: "test" });
+
+    expect(mockLog.info).toHaveBeenCalledWith(
+      expect.objectContaining({ tool: "search_code" }),
+      "Tool completed",
+    );
+    expect(mockLog.warn).not.toHaveBeenCalled();
+  });
+
+  it("should preserve handler return value exactly", async () => {
+    const expected = {
+      content: [{ type: "text" as const, text: "data" }],
+      isError: false,
+    };
+    const handler = vi.fn().mockResolvedValue(expected);
+
+    const wrapped = withToolLogging("list_collections", handler);
+    const result = await wrapped();
+
+    expect(result).toBe(expected);
+  });
+
+  it("should pass all arguments through to the handler", async () => {
+    const handler = vi.fn().mockResolvedValue({
+      content: [{ type: "text", text: "ok" }],
+    });
+
+    const wrapped = withToolLogging("index_codebase", handler);
+    const args = { path: "/test" };
+    const extra = { _meta: {} };
+    await wrapped(args, extra);
+
+    expect(handler).toHaveBeenCalledWith(args, extra);
+  });
+
+  it("should handle empty content array", async () => {
+    const handler = vi.fn().mockResolvedValue({
+      content: [],
+    });
+
+    const wrapped = withToolLogging("search_git_history", handler);
+    await wrapped({ path: "/test", query: "test" });
+
+    expect(mockLog.warn).toHaveBeenCalledWith(
+      expect.objectContaining({ tool: "search_git_history" }),
+      "Tool completed with no results",
+    );
+  });
+});

package/src/tools/logging.ts

@@ -0,0 +1,85 @@
+/**
+ * Tool handler logging wrapper
+ *
+ * Provides standardized completion, error, and warning logging
+ * for all MCP tool handlers.
+ */
+
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import logger from "../logger.js";
+
+const log = logger.child({ component: "tools" });
+
+/** Tools that are search operations (empty results trigger a warning) */
+const SEARCH_TOOLS = new Set([
+  "semantic_search",
+  "hybrid_search",
+  "search_code",
+  "search_git_history",
+  "contextual_search",
+  "federated_search",
+]);
+
+/**
+ * Check whether a tool result indicates an empty search (zero results).
+ */
+function isEmptySearchResult(result: CallToolResult): boolean {
+  if (!result.content || result.content.length === 0) return true;
+  const first = result.content[0];
+  if (first.type === "text") {
+    const text = (first as { type: "text"; text: string }).text;
+    return (
+      text.startsWith("No results found") ||
+      text === "[]" ||
+      text.includes("Found 0 result(s)")
+    );
+  }
+  return false;
+}
+
+/**
+ * Wraps a tool handler with standardized logging:
+ * - Logs "Tool completed" at info level with durationMs on success
+ * - Logs "Tool failed" at error level when result has isError: true
+ * - Logs "Tool completed with no results" at warn level for search tools
+ * - Logs "Tool threw an error" at error level when handler throws (re-throws)
+ */
+export function withToolLogging<
+  T extends (...args: any[]) => Promise<CallToolResult>,
+>(toolName: string, handler: T): T {
+  const wrapped = async (...args: Parameters<T>): Promise<CallToolResult> => {
+    const startTime = Date.now();
+    try {
+      const result = await handler(...args);
+      const durationMs = Date.now() - startTime;
+
+      if (result.isError) {
+        const errorText =
+          result.content?.[0]?.type === "text"
+            ? (result.content[0] as { type: "text"; text: string }).text
+            : "Unknown error";
+        log.error(
+          { tool: toolName, durationMs, error: errorText },
+          "Tool failed",
+        );
+      } else if (SEARCH_TOOLS.has(toolName) && isEmptySearchResult(result)) {
+        log.warn(
+          { tool: toolName, durationMs },
+          "Tool completed with no results",
+        );
+      } else {
+        log.info({ tool: toolName, durationMs }, "Tool completed");
+      }
+
+      return result;
+    } catch (error) {
+      const durationMs = Date.now() - startTime;
+      log.error(
+        { tool: toolName, durationMs, err: error },
+        "Tool threw an error",
+      );
+      throw error;
+    }
+  };
+  return wrapped as T;
+}

package/src/tools/schemas.ts

@@ -41,7 +41,7 @@ export const AddDocumentsSchema = {
           .describe("Unique identifier for the document"),
         text: z.string().describe("Text content to embed and store"),
         metadata: z
-          .record(z.any())
+          .record(z.string(), z.any())
           .optional()
           .describe("Optional metadata to store with the document"),
       }),
@@ -64,7 +64,10 @@ export const SemanticSearchSchema = {
     .number()
     .optional()
     .describe("Maximum number of results (default: 5)"),
-  filter: z.record(z.any()).optional().describe("Optional metadata filter"),
+  filter: z
+    .record(z.string(), z.any())
+    .optional()
+    .describe("Optional metadata filter"),
 };
 
 export const HybridSearchSchema = {
@@ -74,7 +77,10 @@ export const HybridSearchSchema = {
     .number()
     .optional()
     .describe("Maximum number of results (default: 5)"),
-  filter: z.record(z.any()).optional().describe("Optional metadata filter"),
+  filter: z
+    .record(z.string(), z.any())
+    .optional()
+    .describe("Optional metadata filter"),
 };
 
 // Code indexing schemas