@mhalder/qdrant-mcp-server 1.1.0

package/src/qdrant/client.test.ts

@@ -0,0 +1,456 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { QdrantManager } from "./client.js";
+import { QdrantClient } from "@qdrant/js-client-rest";
+
+vi.mock("@qdrant/js-client-rest", () => ({
+  QdrantClient: vi.fn(),
+}));
+
+describe("QdrantManager", () => {
+  let manager: QdrantManager;
+  let mockClient: any;
+
+  beforeEach(() => {
+    mockClient = {
+      createCollection: vi.fn(),
+      getCollection: vi.fn(),
+      getCollections: vi.fn(),
+      deleteCollection: vi.fn(),
+      upsert: vi.fn(),
+      search: vi.fn(),
+      retrieve: vi.fn(),
+      delete: vi.fn(),
+    };
+
+    vi.mocked(QdrantClient).mockImplementation(() => mockClient as any);
+
+    manager = new QdrantManager("http://localhost:6333");
+  });
+
+  describe("createCollection", () => {
+    it("should create a collection with default distance metric", async () => {
+      await manager.createCollection("test-collection", 1536);
+
+      expect(mockClient.createCollection).toHaveBeenCalledWith(
+        "test-collection",
+        {
+          vectors: {
+            size: 1536,
+            distance: "Cosine",
+          },
+        },
+      );
+    });
+
+    it("should create a collection with custom distance metric", async () => {
+      await manager.createCollection("test-collection", 1536, "Euclid");
+
+      expect(mockClient.createCollection).toHaveBeenCalledWith(
+        "test-collection",
+        {
+          vectors: {
+            size: 1536,
+            distance: "Euclid",
+          },
+        },
+      );
+    });
+  });
+
+  describe("collectionExists", () => {
+    it("should return true if collection exists", async () => {
+      mockClient.getCollection.mockResolvedValue({ collection_name: "test" });
+
+      const exists = await manager.collectionExists("test");
+
+      expect(exists).toBe(true);
+      expect(mockClient.getCollection).toHaveBeenCalledWith("test");
+    });
+
+    it("should return false if collection does not exist", async () => {
+      mockClient.getCollection.mockRejectedValue(new Error("Not found"));
+
+      const exists = await manager.collectionExists("test");
+
+      expect(exists).toBe(false);
+    });
+  });
+
+  describe("listCollections", () => {
+    it("should return list of collection names", async () => {
+      mockClient.getCollections.mockResolvedValue({
+        collections: [
+          { name: "collection1" },
+          { name: "collection2" },
+          { name: "collection3" },
+        ],
+      });
+
+      const collections = await manager.listCollections();
+
+      expect(collections).toEqual([
+        "collection1",
+        "collection2",
+        "collection3",
+      ]);
+    });
+
+    it("should return empty array when no collections exist", async () => {
+      mockClient.getCollections.mockResolvedValue({
+        collections: [],
+      });
+
+      const collections = await manager.listCollections();
+
+      expect(collections).toEqual([]);
+    });
+  });
+
+  describe("getCollectionInfo", () => {
+    it("should return collection info with vector configuration", async () => {
+      mockClient.getCollection.mockResolvedValue({
+        collection_name: "test-collection",
+        points_count: 100,
+        config: {
+          params: {
+            vectors: {
+              size: 1536,
+              distance: "Cosine",
+            },
+          },
+        },
+      });
+
+      const info = await manager.getCollectionInfo("test-collection");
+
+      expect(info).toEqual({
+        name: "test-collection",
+        vectorSize: 1536,
+        pointsCount: 100,
+        distance: "Cosine",
+      });
+    });
+
+    it("should handle missing points_count", async () => {
+      mockClient.getCollection.mockResolvedValue({
+        collection_name: "test-collection",
+        config: {
+          params: {
+            vectors: {
+              size: 1536,
+              distance: "Dot",
+            },
+          },
+        },
+      });
+
+      const info = await manager.getCollectionInfo("test-collection");
+
+      expect(info.pointsCount).toBe(0);
+    });
+  });
+
+  describe("deleteCollection", () => {
+    it("should delete a collection", async () => {
+      await manager.deleteCollection("test-collection");
+
+      expect(mockClient.deleteCollection).toHaveBeenCalledWith(
+        "test-collection",
+      );
+    });
+  });
+
+  describe("addPoints", () => {
+    it("should add points to a collection", async () => {
+      const points = [
+        { id: 1, vector: [0.1, 0.2, 0.3], payload: { text: "test" } },
+        { id: 2, vector: [0.4, 0.5, 0.6], payload: { text: "test2" } },
+      ];
+
+      await manager.addPoints("test-collection", points);
+
+      expect(mockClient.upsert).toHaveBeenCalledWith("test-collection", {
+        wait: true,
+        points,
+      });
+    });
+
+    it("should add points without payload", async () => {
+      const points = [{ id: 1, vector: [0.1, 0.2, 0.3] }];
+
+      await manager.addPoints("test-collection", points);
+
+      expect(mockClient.upsert).toHaveBeenCalledWith("test-collection", {
+        wait: true,
+        points,
+      });
+    });
+
+    it("should normalize string IDs to UUID format", async () => {
+      const points = [
+        {
+          id: "my-custom-id",
+          vector: [0.1, 0.2, 0.3],
+          payload: { text: "test" },
+        },
+      ];
+
+      await manager.addPoints("test-collection", points);
+
+      // Verify the ID was normalized to UUID format
+      const calls = mockClient.upsert.mock.calls;
+      expect(calls).toHaveLength(1);
+      expect(calls[0][0]).toBe("test-collection");
+
+      const normalizedId = calls[0][1].points[0].id;
+      // Check that it's a valid UUID format
+      expect(normalizedId).toMatch(
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+      );
+      // Ensure it's not the original ID
+      expect(normalizedId).not.toBe("my-custom-id");
+    });
+
+    it("should preserve UUID format IDs without modification", async () => {
+      const uuidId = "123e4567-e89b-12d3-a456-426614174000";
+      const points = [
+        { id: uuidId, vector: [0.1, 0.2, 0.3], payload: { text: "test" } },
+      ];
+
+      await manager.addPoints("test-collection", points);
+
+      // UUID should remain unchanged
+      expect(mockClient.upsert).toHaveBeenCalledWith("test-collection", {
+        wait: true,
+        points: [
+          {
+            id: uuidId,
+            vector: [0.1, 0.2, 0.3],
+            payload: { text: "test" },
+          },
+        ],
+      });
+    });
+
+    it("should throw error with error.data.status.error message", async () => {
+      const points = [{ id: 1, vector: [0.1, 0.2, 0.3] }];
+
+      mockClient.upsert.mockRejectedValue({
+        data: {
+          status: {
+            error: "Vector dimension mismatch",
+          },
+        },
+      });
+
+      await expect(
+        manager.addPoints("test-collection", points),
+      ).rejects.toThrow(
+        'Failed to add points to collection "test-collection": Vector dimension mismatch',
+      );
+    });
+
+    it("should throw error with error.message fallback", async () => {
+      const points = [{ id: 1, vector: [0.1, 0.2, 0.3] }];
+
+      mockClient.upsert.mockRejectedValue(new Error("Network error"));
+
+      await expect(
+        manager.addPoints("test-collection", points),
+      ).rejects.toThrow(
+        'Failed to add points to collection "test-collection": Network error',
+      );
+    });
+
+    it("should throw error with String(error) fallback", async () => {
+      const points = [{ id: 1, vector: [0.1, 0.2, 0.3] }];
+
+      mockClient.upsert.mockRejectedValue("Unknown error");
+
+      await expect(
+        manager.addPoints("test-collection", points),
+      ).rejects.toThrow(
+        'Failed to add points to collection "test-collection": Unknown error',
+      );
+    });
+  });
+
+  describe("search", () => {
+    it("should search for similar vectors", async () => {
+      mockClient.search.mockResolvedValue([
+        { id: 1, score: 0.95, payload: { text: "result1" } },
+        { id: 2, score: 0.85, payload: { text: "result2" } },
+      ]);
+
+      const results = await manager.search(
+        "test-collection",
+        [0.1, 0.2, 0.3],
+        5,
+      );
+
+      expect(results).toEqual([
+        { id: 1, score: 0.95, payload: { text: "result1" } },
+        { id: 2, score: 0.85, payload: { text: "result2" } },
+      ]);
+      expect(mockClient.search).toHaveBeenCalledWith("test-collection", {
+        vector: [0.1, 0.2, 0.3],
+        limit: 5,
+        filter: undefined,
+      });
+    });
+
+    it("should search with custom limit", async () => {
+      mockClient.search.mockResolvedValue([]);
+
+      await manager.search("test-collection", [0.1, 0.2, 0.3], 10);
+
+      expect(mockClient.search).toHaveBeenCalledWith("test-collection", {
+        vector: [0.1, 0.2, 0.3],
+        limit: 10,
+        filter: undefined,
+      });
+    });
+
+    it("should search with Qdrant format filter (must)", async () => {
+      mockClient.search.mockResolvedValue([]);
+
+      const filter = { must: [{ key: "category", match: { value: "test" } }] };
+      await manager.search("test-collection", [0.1, 0.2, 0.3], 5, filter);
+
+      expect(mockClient.search).toHaveBeenCalledWith("test-collection", {
+        vector: [0.1, 0.2, 0.3],
+        limit: 5,
+        filter,
+      });
+    });
+
+    it("should convert simple key-value filter to Qdrant format", async () => {
+      mockClient.search.mockResolvedValue([]);
+
+      const simpleFilter = { category: "database", type: "document" };
+      await manager.search("test-collection", [0.1, 0.2, 0.3], 5, simpleFilter);
+
+      expect(mockClient.search).toHaveBeenCalledWith("test-collection", {
+        vector: [0.1, 0.2, 0.3],
+        limit: 5,
+        filter: {
+          must: [
+            { key: "category", match: { value: "database" } },
+            { key: "type", match: { value: "document" } },
+          ],
+        },
+      });
+    });
+
+    it("should handle empty filter object", async () => {
+      mockClient.search.mockResolvedValue([]);
+
+      await manager.search("test-collection", [0.1, 0.2, 0.3], 5, {});
+
+      expect(mockClient.search).toHaveBeenCalledWith("test-collection", {
+        vector: [0.1, 0.2, 0.3],
+        limit: 5,
+        filter: undefined,
+      });
+    });
+
+    it("should search with Qdrant format filter (should)", async () => {
+      mockClient.search.mockResolvedValue([]);
+
+      const filter = {
+        should: [{ key: "tag", match: { value: "important" } }],
+      };
+      await manager.search("test-collection", [0.1, 0.2, 0.3], 5, filter);
+
+      expect(mockClient.search).toHaveBeenCalledWith("test-collection", {
+        vector: [0.1, 0.2, 0.3],
+        limit: 5,
+        filter,
+      });
+    });
+
+    it("should search with Qdrant format filter (must_not)", async () => {
+      mockClient.search.mockResolvedValue([]);
+
+      const filter = {
+        must_not: [{ key: "status", match: { value: "deleted" } }],
+      };
+      await manager.search("test-collection", [0.1, 0.2, 0.3], 5, filter);
+
+      expect(mockClient.search).toHaveBeenCalledWith("test-collection", {
+        vector: [0.1, 0.2, 0.3],
+        limit: 5,
+        filter,
+      });
+    });
+
+    it("should handle null payload in results", async () => {
+      mockClient.search.mockResolvedValue([
+        { id: 1, score: 0.95, payload: null },
+      ]);
+
+      const results = await manager.search("test-collection", [0.1, 0.2, 0.3]);
+
+      expect(results).toEqual([{ id: 1, score: 0.95, payload: undefined }]);
+    });
+  });
+
+  describe("getPoint", () => {
+    it("should retrieve a point by id", async () => {
+      mockClient.retrieve.mockResolvedValue([
+        { id: 1, payload: { text: "test" } },
+      ]);
+
+      const point = await manager.getPoint("test-collection", 1);
+
+      expect(point).toEqual({ id: 1, payload: { text: "test" } });
+      expect(mockClient.retrieve).toHaveBeenCalledWith("test-collection", {
+        ids: [1],
+      });
+    });
+
+    it("should return null if point not found", async () => {
+      mockClient.retrieve.mockResolvedValue([]);
+
+      const point = await manager.getPoint("test-collection", 1);
+
+      expect(point).toBeNull();
+    });
+
+    it("should handle errors gracefully", async () => {
+      mockClient.retrieve.mockRejectedValue(new Error("Not found"));
+
+      const point = await manager.getPoint("test-collection", 1);
+
+      expect(point).toBeNull();
+    });
+
+    it("should handle null payload", async () => {
+      mockClient.retrieve.mockResolvedValue([{ id: 1, payload: null }]);
+
+      const point = await manager.getPoint("test-collection", 1);
+
+      expect(point).toEqual({ id: 1, payload: undefined });
+    });
+  });
+
+  describe("deletePoints", () => {
+    it("should delete points by ids", async () => {
+      await manager.deletePoints("test-collection", [1, 2, 3]);
+
+      expect(mockClient.delete).toHaveBeenCalledWith("test-collection", {
+        wait: true,
+        points: [1, 2, 3],
+      });
+    });
+
+    it("should delete single point", async () => {
+      await manager.deletePoints("test-collection", ["doc-1"]);
+
+      expect(mockClient.delete).toHaveBeenCalledWith("test-collection", {
+        wait: true,
+        points: ["bb0e4f49-4437-94d9-01e8-969ff11bd112"], // Normalized UUID from 'doc-1'
+      });
+    });
+  });
+});

package/src/qdrant/client.ts

@@ -0,0 +1,195 @@
+import { QdrantClient } from '@qdrant/js-client-rest';
+import { createHash } from 'crypto';
+
+export interface CollectionInfo {
+  name: string;
+  vectorSize: number;
+  pointsCount: number;
+  distance: 'Cosine' | 'Euclid' | 'Dot';
+}
+
+export interface SearchResult {
+  id: string | number;
+  score: number;
+  payload?: Record<string, any>;
+}
+
+export class QdrantManager {
+  private client: QdrantClient;
+
+  constructor(url: string = 'http://localhost:6333') {
+    this.client = new QdrantClient({ url });
+  }
+
+  /**
+   * Converts a string ID to UUID format if it's not already a UUID.
+   * Qdrant requires string IDs to be in UUID format.
+   */
+  private normalizeId(id: string | number): string | number {
+    if (typeof id === 'number') {
+      return id;
+    }
+
+    // Check if already a valid UUID (8-4-4-4-12 format)
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    if (uuidRegex.test(id)) {
+      return id;
+    }
+
+    // Convert arbitrary string to deterministic UUID v5-like format
+    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'
+  ): Promise<void> {
+    await this.client.createCollection(name, {
+      vectors: {
+        size: vectorSize,
+        distance,
+      },
+    });
+  }
+
+  async collectionExists(name: string): Promise<boolean> {
+    try {
+      await this.client.getCollection(name);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async listCollections(): Promise<string[]> {
+    const response = await this.client.getCollections();
+    return response.collections.map((c) => c.name);
+  }
+
+  async getCollectionInfo(name: string): Promise<CollectionInfo> {
+    const info = await this.client.getCollection(name);
+    const vectorConfig = info.config.params.vectors;
+
+    // Handle both named and unnamed vector configurations
+    let size = 0;
+    let distance: 'Cosine' | 'Euclid' | 'Dot' = 'Cosine';
+
+    if (typeof vectorConfig === 'object' && vectorConfig !== null && 'size' in vectorConfig) {
+      size = typeof vectorConfig.size === 'number' ? vectorConfig.size : 0;
+      distance = vectorConfig.distance as 'Cosine' | 'Euclid' | 'Dot';
+    }
+
+    return {
+      name,
+      vectorSize: size,
+      pointsCount: info.points_count || 0,
+      distance,
+    };
+  }
+
+  async deleteCollection(name: string): Promise<void> {
+    await this.client.deleteCollection(name);
+  }
+
+  async addPoints(
+    collectionName: string,
+    points: Array<{
+      id: string | number;
+      vector: number[];
+      payload?: Record<string, any>;
+    }>
+  ): Promise<void> {
+    try {
+      // Normalize all IDs to ensure string IDs are in UUID format
+      const normalizedPoints = points.map(point => ({
+        ...point,
+        id: this.normalizeId(point.id),
+      }));
+
+      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 to collection "${collectionName}": ${errorMessage}`);
+    }
+  }
+
+  async search(
+    collectionName: string,
+    vector: number[],
+    limit: number = 5,
+    filter?: Record<string, any>
+  ): Promise<SearchResult[]> {
+    // Convert simple key-value filter to Qdrant filter format
+    // Accepts either:
+    // 1. Simple format: {"category": "database"}
+    // 2. Qdrant format: {must: [{key: "category", match: {value: "database"}}]}
+    let qdrantFilter;
+    if (filter && Object.keys(filter).length > 0) {
+      // Check if already in Qdrant format (has must/should/must_not keys)
+      if (filter.must || filter.should || filter.must_not) {
+        qdrantFilter = filter;
+      } else {
+        // Convert simple key-value format to Qdrant format
+        qdrantFilter = {
+          must: Object.entries(filter).map(([key, value]) => ({
+            key,
+            match: { value },
+          })),
+        };
+      }
+    }
+
+    const results = await this.client.search(collectionName, {
+      vector,
+      limit,
+      filter: qdrantFilter,
+    });
+
+    return results.map((result) => ({
+      id: result.id,
+      score: result.score,
+      payload: result.payload || undefined,
+    }));
+  }
+
+  async getPoint(
+    collectionName: string,
+    id: string | number
+  ): Promise<{ id: string | number; payload?: Record<string, any> } | null> {
+    try {
+      const normalizedId = this.normalizeId(id);
+      const points = await this.client.retrieve(collectionName, {
+        ids: [normalizedId],
+      });
+
+      if (points.length === 0) {
+        return null;
+      }
+
+      return {
+        id: points[0].id,
+        payload: points[0].payload || undefined,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  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));
+
+    await this.client.delete(collectionName, {
+      wait: true,
+      points: normalizedIds,
+    });
+  }
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./build",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "build"]
+}

package/vitest.config.ts

@@ -0,0 +1,37 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+      exclude: [
+        "node_modules/",
+        "build/",
+        "dist/",
+        "**/*.test.ts",
+        "**/*.spec.ts",
+        "vitest.config.ts",
+        "src/index.ts", // MCP server SDK integration - tested via integration
+        "scripts/**", // Exclude utility scripts from coverage
+      ],
+      // Set thresholds for core business logic modules
+      thresholds: {
+        "src/qdrant/client.ts": {
+          lines: 90,
+          functions: 100,
+          branches: 80,
+          statements: 90,
+        },
+        "src/embeddings/openai.ts": {
+          lines: 100,
+          functions: 100,
+          branches: 90,
+          statements: 100,
+        },
+      },
+    },
+  },
+});