@mhalder/qdrant-mcp-server 1.1.0 → 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,

package/docs/test_report.md

@@ -1,259 +0,0 @@
-# Test Report - Qdrant MCP Server
-
-**Generated:** 2025-10-09
-**Version:** 1.1.0 (Ollama as Default Provider)
-**Test Framework:** Vitest 2.1.9
-
-## Summary
-
-✅ **All tests passing**
-
-| Metric                           | Value    |
-| -------------------------------- | -------- |
-| **Latest MCP Integration Tests** | 6        |
-| **Test Operations**              | 6        |
-| **Passed**                       | 6 (100%) |
-| **Failed**                       | 0        |
-| **Duration**                     | ~30s     |
-
-## Latest Test Results (2025-10-09)
-
-### MCP Integration Test - Full Workflow Validation
-
-**Date:** 2025-10-09
-**Environment:** Production MCP server with Ollama embeddings (default provider)
-**Purpose:** Validate complete MCP functionality with real embeddings
-
-#### Test Setup
-
-- ✅ Qdrant running via Docker (localhost:6333)
-- ✅ MCP server connected to Claude Code
-- ✅ Ollama configured as default provider
-- ✅ Model: nomic-embed-text (768 dimensions)
-- ✅ No API keys required
-
-### Test Operations
-
-#### Test 1: List Existing Collections
-
-```
-Operation: List all collections
-Result: ✅ SUCCESS
-Collections Found: ["final_test"]
-```
-
-#### Test 2: Create Test Collection
-
-```
-Operation: Create collection "mcp_test_collection"
-Distance Metric: Cosine
-Result: ✅ SUCCESS
-Details: Collection created with 768 dimensions (Ollama default)
-```
-
-**Validation:**
-
-- ✅ Correct dimensions for Ollama provider (768)
-- ✅ Cosine distance metric configured
-- ✅ Collection created successfully
-
-#### Test 3: Add Documents with Metadata
-
-```
-Operation: Add 5 documents with real Ollama embeddings
-Result: ✅ SUCCESS
-
-Documents Added:
-1. "Python is a high-level programming language..." (category: programming)
-2. "JavaScript is the programming language of the web..." (category: programming)
-3. "Machine learning is a subset of artificial intelligence..." (category: AI)
-4. "Qdrant is a vector database designed for storing..." (category: database)
-5. "Neural networks are computing systems inspired by..." (category: AI)
-```
-
-**Validation:**
-
-- ✅ All 5 documents embedded using Ollama
-- ✅ Metadata correctly attached
-- ✅ Batch processing successful
-
-#### Test 4: Semantic Search - Vector Database Query
-
-```
-Query: "What is a vector database?"
-Limit: 3
-Result: ✅ SUCCESS
-
-Top Results:
-1. Score: 0.687 - "Qdrant is a vector database designed for storing..."
-2. Score: 0.481 - "Python is a high-level programming language..."
-3. Score: 0.477 - "Neural networks are computing systems inspired by..."
-```
-
-**Analysis:**
-
-- ✅ Excellent semantic matching - correctly identified Qdrant as most relevant
-- ✅ High relevance score (0.687) for vector database content
-- ✅ Query understanding working correctly
-
-#### Test 5: Semantic Search - AI and Deep Learning Query
-
-```
-Query: "artificial intelligence and deep learning"
-Limit: 3
-Result: ✅ SUCCESS
-
-Top Results:
-1. Score: 0.784 - "Neural networks are computing systems..."
-2. Score: 0.771 - "Machine learning is a subset of AI..."
-3. Score: 0.578 - "Python is a high-level programming language..."
-```
-
-**Analysis:**
-
-- ✅ Very high relevance scores (0.78+) for AI content
-- ✅ Correctly prioritized neural networks and machine learning
-- ✅ Semantic understanding of query intent
-
-#### Test 6: Get Collection Information
-
-```
-Operation: Get collection info for "mcp_test_collection"
-Result: ✅ SUCCESS
-
-Collection Details:
-- Name: mcp_test_collection
-- Vector Size: 768 (Ollama default)
-- Points Count: 5
-- Distance: Cosine
-```
-
-**Validation:**
-
-- ✅ Correct vector dimensions for Ollama
-- ✅ Accurate point count
-- ✅ Distance metric confirmed
-
-#### Test 7: Cleanup - Delete Collection
-
-```
-Operation: Delete collection "mcp_test_collection"
-Result: ✅ SUCCESS
-Final State: Test collection removed successfully
-```
-
-## Test Results Summary
-
-| Test | Operation         | Status  | Notes                      |
-| ---- | ----------------- | ------- | -------------------------- |
-| 1    | List Collections  | ✅ PASS | Found existing collections |
-| 2    | Create Collection | ✅ PASS | 768 dimensions (Ollama)    |
-| 3    | Add Documents     | ✅ PASS | 5 documents with metadata  |
-| 4    | Search: Vector DB | ✅ PASS | High relevance (0.687)     |
-| 5    | Search: AI/ML     | ✅ PASS | Excellent scores (0.78+)   |
-| 6    | Collection Info   | ✅ PASS | Metadata accurate          |
-| 7    | Delete Collection | ✅ PASS | Cleanup successful         |
-
-**Total Tests:** 7
-**Passed:** 7 ✅
-**Failed:** 0 ❌
-**Success Rate:** 100%
-
-## Key Validations
-
-✅ **Ollama as Default Provider** - Works seamlessly without API keys
-✅ **Collection Management** - Create, info, delete all functional
-✅ **Document Operations** - Batch add with metadata working correctly
-✅ **Semantic Search Quality** - High relevance scores (0.68-0.78)
-✅ **Embeddings Generation** - Real Ollama embeddings (768 dimensions)
-✅ **Metadata Handling** - Categories correctly stored and retrievable
-✅ **MCP Protocol Compliance** - All tools responding correctly
-✅ **Error Handling** - No failures or exceptions
-✅ **Cleanup** - Test artifacts removed successfully
-
-## Search Quality Assessment
-
-### Query 1: "What is a vector database?"
-
-- **Top Match:** Qdrant vector database description
-- **Relevance Score:** 0.687
-- **Quality:** ✅ EXCELLENT - Perfect match for query intent
-
-### Query 2: "artificial intelligence and deep learning"
-
-- **Top Matches:** Neural networks (0.784), Machine learning (0.771)
-- **Quality:** ✅ EXCELLENT - Both query concepts matched accurately
-
-### Search Accuracy
-
-- Semantic understanding: ✅ EXCELLENT
-- Relevance ranking: ✅ ACCURATE
-- Query interpretation: ✅ PRECISE
-
-## Ollama Integration Performance
-
-- **Provider:** Ollama (default)
-- **Model:** nomic-embed-text
-- **Dimensions:** 768
-- **API Key:** Not required ✓
-- **Documents Processed:** 5
-- **Embedding Calls:** 2 (batch operations)
-- **Errors:** 0
-- **Privacy:** All data processed locally ✓
-
-## MCP Tool Validation
-
-All 7 MCP tools tested and working:
-
-| Tool                  | Status                    | Notes                           |
-| --------------------- | ------------------------- | ------------------------------- |
-| `list_collections`    | ✅ PASS                   | Lists all collections           |
-| `create_collection`   | ✅ PASS                   | Creates with correct dimensions |
-| `add_documents`       | ✅ PASS                   | Batch add with metadata         |
-| `semantic_search`     | ✅ PASS                   | High-quality results            |
-| `get_collection_info` | ✅ PASS                   | Accurate metadata               |
-| `delete_collection`   | ✅ PASS                   | Clean removal                   |
-| `delete_documents`    | ⚪ Not tested in this run | -                               |
-
-## Production Readiness Checklist
-
-- ✅ Ollama as default provider - no setup required
-- ✅ Collections create with correct dimensions
-- ✅ Documents add successfully with embeddings
-- ✅ Semantic search returns relevant results
-- ✅ Collection info shows accurate metadata
-- ✅ Collections delete cleanly
-- ✅ No API keys required for basic usage
-- ✅ Privacy-first local embeddings
-- ✅ Zero configuration needed
-- ✅ All MCP tools functional
-
-## Conclusion
-
-The Qdrant MCP Server with **Ollama as the default provider** is **production-ready** and performs excellently in real-world scenarios. All operations completed successfully with:
-
-- ✅ Real Ollama embeddings (5 documents)
-- ✅ No configuration required (zero setup)
-- ✅ High semantic search accuracy (0.68-0.78 relevance)
-- ✅ Local processing (privacy-first)
-- ✅ No API keys needed
-- ✅ Clean error-free execution
-
-### Key Strengths
-
-1. **Privacy-First:** All embeddings processed locally via Ollama
-2. **Zero Setup:** Works immediately with Docker Compose
-3. **No API Keys:** Default provider requires no configuration
-4. **High Quality:** Excellent semantic search results
-5. **MCP Compliance:** All tools working correctly
-6. **Clean Architecture:** Proper error handling and cleanup
-7. **Production Ready:** Validated with real-world workflows
-
-**Test Status:** ✅ **EXCELLENT**
-
----
-
-**Report Generated:** 2025-10-09
-**Platform:** Linux
-**Docker:** Qdrant running on localhost:6333
-**Status:** All 7 MCP integration tests passing ✅