@mhalder/qdrant-mcp-server 1.1.1 → 1.2.0

package/src/qdrant/client.ts

@@ -1,11 +1,12 @@
-import { QdrantClient } from '@qdrant/js-client-rest';
-import { createHash } from 'crypto';
+import { createHash } from "node:crypto";
+import { QdrantClient } from "@qdrant/js-client-rest";
 
 export interface CollectionInfo {
   name: string;
   vectorSize: number;
   pointsCount: number;
-  distance: 'Cosine' | 'Euclid' | 'Dot';
+  distance: "Cosine" | "Euclid" | "Dot";
+  hybridEnabled?: boolean;
 }
 
 export interface SearchResult {
@@ -14,10 +15,15 @@ export interface SearchResult {
   payload?: Record<string, any>;
 }
 
+export interface SparseVector {
+  indices: number[];
+  values: number[];
+}
+
 export class QdrantManager {
   private client: QdrantClient;
 
-  constructor(url: string = 'http://localhost:6333') {
+  constructor(url: string = "http://localhost:6333") {
     this.client = new QdrantClient({ url });
   }
 
@@ -26,7 +32,7 @@ export class QdrantManager {
    * Qdrant requires string IDs to be in UUID format.
    */
   private normalizeId(id: string | number): string | number {
-    if (typeof id === 'number') {
+    if (typeof id === "number") {
       return id;
     }
 
@@ -37,21 +43,40 @@ export class QdrantManager {
     }
 
     // Convert arbitrary string to deterministic UUID v5-like format
-    const hash = createHash('sha256').update(id).digest('hex');
+    const hash = createHash("sha256").update(id).digest("hex");
     return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-${hash.slice(12, 16)}-${hash.slice(16, 20)}-${hash.slice(20, 32)}`;
   }
 
   async createCollection(
     name: string,
     vectorSize: number,
-    distance: 'Cosine' | 'Euclid' | 'Dot' = 'Cosine'
+    distance: "Cosine" | "Euclid" | "Dot" = "Cosine",
+    enableSparse: boolean = false
   ): Promise<void> {
-    await this.client.createCollection(name, {
-      vectors: {
+    const config: any = {};
+
+    // When hybrid search is enabled, use named vectors
+    if (enableSparse) {
+      config.vectors = {
+        dense: {
+          size: vectorSize,
+          distance,
+        },
+      };
+      config.sparse_vectors = {
+        text: {
+          modifier: "idf",
+        },
+      };
+    } else {
+      // Standard unnamed vector configuration
+      config.vectors = {
         size: vectorSize,
         distance,
-      },
-    });
+      };
+    }
+
+    await this.client.createCollection(name, config);
   }
 
   async collectionExists(name: string): Promise<boolean> {
@@ -74,11 +99,25 @@ export class QdrantManager {
 
     // Handle both named and unnamed vector configurations
     let size = 0;
-    let distance: 'Cosine' | 'Euclid' | 'Dot' = 'Cosine';
+    let distance: "Cosine" | "Euclid" | "Dot" = "Cosine";
+    let hybridEnabled = false;
 
-    if (typeof vectorConfig === 'object' && vectorConfig !== null && 'size' in vectorConfig) {
-      size = typeof vectorConfig.size === 'number' ? vectorConfig.size : 0;
-      distance = vectorConfig.distance as 'Cosine' | 'Euclid' | 'Dot';
+    // Check if sparse vectors are configured
+    if (info.config.params.sparse_vectors) {
+      hybridEnabled = true;
+    }
+
+    if (typeof vectorConfig === "object" && vectorConfig !== null) {
+      // Check for unnamed vector config (has 'size' directly)
+      if ("size" in vectorConfig) {
+        size = typeof vectorConfig.size === "number" ? vectorConfig.size : 0;
+        distance = vectorConfig.distance as "Cosine" | "Euclid" | "Dot";
+      } else if ("dense" in vectorConfig) {
+        // Named vector config for hybrid search
+        const denseConfig = vectorConfig.dense as any;
+        size = typeof denseConfig.size === "number" ? denseConfig.size : 0;
+        distance = denseConfig.distance as "Cosine" | "Euclid" | "Dot";
+      }
     }
 
     return {
@@ -86,6 +125,7 @@ export class QdrantManager {
       vectorSize: size,
       pointsCount: info.points_count || 0,
       distance,
+      hybridEnabled,
     };
   }
 
@@ -103,7 +143,7 @@ export class QdrantManager {
   ): Promise<void> {
     try {
       // Normalize all IDs to ensure string IDs are in UUID format
-      const normalizedPoints = points.map(point => ({
+      const normalizedPoints = points.map((point) => ({
         ...point,
         id: this.normalizeId(point.id),
       }));
@@ -144,8 +184,11 @@ export class QdrantManager {
       }
     }
 
+    // Check if collection uses named vectors (hybrid mode)
+    const collectionInfo = await this.getCollectionInfo(collectionName);
+
     const results = await this.client.search(collectionName, {
-      vector,
+      vector: collectionInfo.hybridEnabled ? { name: "dense", vector } : vector,
       limit,
       filter: qdrantFilter,
     });
@@ -180,16 +223,113 @@ export class QdrantManager {
     }
   }
 
-  async deletePoints(
-    collectionName: string,
-    ids: (string | number)[]
-  ): Promise<void> {
+  async deletePoints(collectionName: string, ids: (string | number)[]): Promise<void> {
     // Normalize IDs to ensure string IDs are in UUID format
-    const normalizedIds = ids.map(id => this.normalizeId(id));
+    const normalizedIds = ids.map((id) => this.normalizeId(id));
 
     await this.client.delete(collectionName, {
       wait: true,
       points: normalizedIds,
     });
   }
+
+  /**
+   * Performs hybrid search combining semantic vector search with sparse vector (keyword) search
+   * using Reciprocal Rank Fusion (RRF) to combine results
+   */
+  async hybridSearch(
+    collectionName: string,
+    denseVector: number[],
+    sparseVector: SparseVector,
+    limit: number = 5,
+    filter?: Record<string, any>,
+    _semanticWeight: number = 0.7
+  ): Promise<SearchResult[]> {
+    // Convert simple key-value filter to Qdrant filter format
+    let qdrantFilter;
+    if (filter && Object.keys(filter).length > 0) {
+      if (filter.must || filter.should || filter.must_not) {
+        qdrantFilter = filter;
+      } else {
+        qdrantFilter = {
+          must: Object.entries(filter).map(([key, value]) => ({
+            key,
+            match: { value },
+          })),
+        };
+      }
+    }
+
+    // Calculate prefetch limits based on weights
+    // We fetch more results than needed to ensure good fusion results
+    const prefetchLimit = Math.max(20, limit * 4);
+
+    try {
+      const results = await this.client.query(collectionName, {
+        prefetch: [
+          {
+            query: denseVector,
+            using: "dense",
+            limit: prefetchLimit,
+            filter: qdrantFilter,
+          },
+          {
+            query: sparseVector,
+            using: "text",
+            limit: prefetchLimit,
+            filter: qdrantFilter,
+          },
+        ],
+        query: {
+          fusion: "rrf",
+        },
+        limit: limit,
+        with_payload: true,
+      });
+
+      return results.points.map((result: any) => ({
+        id: result.id,
+        score: result.score,
+        payload: result.payload || undefined,
+      }));
+    } catch (error: any) {
+      const errorMessage = error?.data?.status?.error || error?.message || String(error);
+      throw new Error(`Hybrid search failed on collection "${collectionName}": ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Adds points with both dense and sparse vectors for hybrid search
+   */
+  async addPointsWithSparse(
+    collectionName: string,
+    points: Array<{
+      id: string | number;
+      vector: number[];
+      sparseVector: SparseVector;
+      payload?: Record<string, any>;
+    }>
+  ): Promise<void> {
+    try {
+      // Normalize all IDs to ensure string IDs are in UUID format
+      const normalizedPoints = points.map((point) => ({
+        id: this.normalizeId(point.id),
+        vector: {
+          dense: point.vector,
+          text: point.sparseVector,
+        },
+        payload: point.payload,
+      }));
+
+      await this.client.upsert(collectionName, {
+        wait: true,
+        points: normalizedPoints,
+      });
+    } catch (error: any) {
+      const errorMessage = error?.data?.status?.error || error?.message || String(error);
+      throw new Error(
+        `Failed to add points with sparse vectors to collection "${collectionName}": ${errorMessage}`
+      );
+    }
+  }
 }

package/vitest.config.ts

@@ -14,10 +14,10 @@ export default defineConfig({
         "**/*.test.ts",
         "**/*.spec.ts",
         "vitest.config.ts",
-        "src/index.ts", // MCP server SDK integration - tested via integration
-        "scripts/**", // Exclude utility scripts from coverage
+        "commitlint.config.js",
+        "src/index.ts",
+        "scripts/**",
       ],
-      // Set thresholds for core business logic modules
       thresholds: {
         "src/qdrant/client.ts": {
           lines: 90,