@mhalder/qdrant-mcp-server 1.1.1 → 1.3.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/src/transport.test.ts

@@ -0,0 +1,202 @@
+import type { Server as HttpServer } from "node:http";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+describe("Transport Configuration", () => {
+  let originalEnv: NodeJS.ProcessEnv;
+
+  beforeEach(() => {
+    originalEnv = { ...process.env };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  describe("HTTP Port Validation", () => {
+    it("should accept valid port numbers", () => {
+      const validPorts = ["1", "80", "443", "3000", "8080", "65535"];
+
+      validPorts.forEach((port) => {
+        const parsed = parseInt(port, 10);
+        expect(parsed).toBeGreaterThanOrEqual(1);
+        expect(parsed).toBeLessThanOrEqual(65535);
+        expect(Number.isNaN(parsed)).toBe(false);
+      });
+    });
+
+    it("should reject invalid port numbers", () => {
+      const invalidCases = [
+        { port: "0", reason: "port 0 is reserved" },
+        { port: "-1", reason: "negative ports are invalid" },
+        { port: "65536", reason: "exceeds maximum port" },
+        { port: "99999", reason: "exceeds maximum port" },
+        { port: "abc", reason: "non-numeric input" },
+        { port: "", reason: "empty string" },
+      ];
+
+      invalidCases.forEach(({ port, reason }) => {
+        const parsed = parseInt(port, 10);
+        const isValid = !Number.isNaN(parsed) && parsed >= 1 && parsed <= 65535;
+        expect(isValid, `Failed for ${port}: ${reason}`).toBe(false);
+      });
+    });
+
+    it("should use default port 3000 when HTTP_PORT is not set", () => {
+      const port = parseInt(process.env.HTTP_PORT || "3000", 10);
+      expect(port).toBe(3000);
+    });
+
+    it("should parse HTTP_PORT from environment", () => {
+      process.env.HTTP_PORT = "8080";
+      const port = parseInt(process.env.HTTP_PORT || "3000", 10);
+      expect(port).toBe(8080);
+    });
+  });
+
+  describe("Transport Mode Validation", () => {
+    it("should accept valid transport modes", () => {
+      const validModes = ["stdio", "http", "STDIO", "HTTP"];
+
+      validModes.forEach((mode) => {
+        const normalized = mode.toLowerCase();
+        expect(["stdio", "http"]).toContain(normalized);
+      });
+    });
+
+    it("should reject invalid transport modes", () => {
+      const invalidModes = ["tcp", "websocket", "grpc", ""];
+
+      invalidModes.forEach((mode) => {
+        const normalized = mode.toLowerCase();
+        expect(["stdio", "http"]).not.toContain(normalized);
+      });
+    });
+
+    it("should default to stdio when TRANSPORT_MODE is not set", () => {
+      const mode = (process.env.TRANSPORT_MODE || "stdio").toLowerCase();
+      expect(mode).toBe("stdio");
+    });
+  });
+
+  describe("Request Size Limits", () => {
+    it("should define request size limit for HTTP transport", () => {
+      const limit = "10mb";
+      expect(limit).toMatch(/^\d+mb$/);
+    });
+
+    it("should parse size limit correctly", () => {
+      const limit = "10mb";
+      const sizeInBytes = parseInt(limit, 10) * 1024 * 1024;
+      expect(sizeInBytes).toBe(10485760);
+    });
+  });
+});
+
+describe("HTTP Server Configuration", () => {
+  describe("Graceful Shutdown", () => {
+    it("should handle shutdown signals", async () => {
+      const mockServer = {
+        close: vi.fn((callback) => {
+          if (callback) callback();
+        }),
+      } as unknown as HttpServer;
+
+      const shutdown = () => {
+        mockServer.close(() => {
+          // Shutdown callback
+        });
+      };
+
+      shutdown();
+      expect(mockServer.close).toHaveBeenCalled();
+    });
+
+    it("should support timeout for forced shutdown", () => {
+      vi.useFakeTimers();
+
+      let forcedShutdown = false;
+      const timeout = setTimeout(() => {
+        forcedShutdown = true;
+      }, 10000);
+
+      vi.advanceTimersByTime(9999);
+      expect(forcedShutdown).toBe(false);
+
+      vi.advanceTimersByTime(1);
+      expect(forcedShutdown).toBe(true);
+
+      clearTimeout(timeout);
+      vi.useRealTimers();
+    });
+  });
+
+  describe("Error Handling", () => {
+    it("should return JSON-RPC 2.0 error format", () => {
+      const error = {
+        jsonrpc: "2.0",
+        error: {
+          code: -32603,
+          message: "Internal server error",
+        },
+        id: null,
+      };
+
+      expect(error.jsonrpc).toBe("2.0");
+      expect(error.error.code).toBe(-32603);
+      expect(error.error.message).toBeTruthy();
+      expect(error.id).toBeNull();
+    });
+
+    it("should use standard JSON-RPC error codes", () => {
+      const errorCodes = {
+        parseError: -32700,
+        invalidRequest: -32600,
+        methodNotFound: -32601,
+        invalidParams: -32602,
+        internalError: -32603,
+      };
+
+      expect(errorCodes.parseError).toBe(-32700);
+      expect(errorCodes.invalidRequest).toBe(-32600);
+      expect(errorCodes.methodNotFound).toBe(-32601);
+      expect(errorCodes.invalidParams).toBe(-32602);
+      expect(errorCodes.internalError).toBe(-32603);
+    });
+  });
+});
+
+describe("Transport Lifecycle", () => {
+  it("should close transport on response close", () => {
+    const mockTransport = {
+      close: vi.fn(),
+    };
+
+    const mockResponse = {
+      on: vi.fn((event, callback) => {
+        if (event === "close") {
+          callback();
+        }
+      }),
+    };
+
+    mockResponse.on("close", () => {
+      mockTransport.close();
+    });
+
+    expect(mockTransport.close).toHaveBeenCalled();
+  });
+
+  it("should handle transport connection", async () => {
+    const mockServer = {
+      connect: vi.fn().mockResolvedValue(undefined),
+    };
+
+    const mockTransport = {
+      handleRequest: vi.fn().mockResolvedValue(undefined),
+      close: vi.fn(),
+    };
+
+    await mockServer.connect(mockTransport);
+    expect(mockServer.connect).toHaveBeenCalledWith(mockTransport);
+  });
+});

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,