@mhalder/qdrant-mcp-server 1.1.0

package/scripts/verify-providers.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+/**
+ * Provider Verification Script
+ *
+ * This script verifies that all embedding providers can be instantiated
+ * correctly and that the factory pattern works as expected.
+ */
+
+import { EmbeddingProviderFactory } from "../build/embeddings/factory.js";
+
+console.log("=".repeat(60));
+console.log("QDRANT MCP SERVER - PROVIDER VERIFICATION");
+console.log("=".repeat(60));
+console.log();
+
+const results = {
+  passed: 0,
+  failed: 0,
+  tests: [],
+};
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`✅ PASS: ${name}`);
+    results.passed++;
+    results.tests.push({ name, status: "PASS" });
+  } catch (error) {
+    console.log(`❌ FAIL: ${name}`);
+    console.log(`   Error: ${error.message}`);
+    results.failed++;
+    results.tests.push({ name, status: "FAIL", error: error.message });
+  }
+}
+
+console.log("Testing Provider Factory...\n");
+
+// Test 1: Factory should reject unknown providers
+test("Factory rejects unknown provider", () => {
+  try {
+    EmbeddingProviderFactory.create({
+      provider: "unknown-provider",
+      apiKey: "test-key",
+    });
+    throw new Error("Should have thrown error for unknown provider");
+  } catch (error) {
+    if (!error.message.includes("Unknown embedding provider")) {
+      throw error;
+    }
+  }
+});
+
+// Test 2: OpenAI provider requires API key
+test("OpenAI provider requires API key", () => {
+  try {
+    EmbeddingProviderFactory.create({
+      provider: "openai",
+    });
+    throw new Error("Should have thrown error for missing API key");
+  } catch (error) {
+    if (!error.message.includes("API key is required")) {
+      throw error;
+    }
+  }
+});
+
+// Test 3: Cohere provider requires API key
+test("Cohere provider requires API key", () => {
+  try {
+    EmbeddingProviderFactory.create({
+      provider: "cohere",
+    });
+    throw new Error("Should have thrown error for missing API key");
+  } catch (error) {
+    if (!error.message.includes("API key is required")) {
+      throw error;
+    }
+  }
+});
+
+// Test 4: Voyage AI provider requires API key
+test("Voyage AI provider requires API key", () => {
+  try {
+    EmbeddingProviderFactory.create({
+      provider: "voyage",
+    });
+    throw new Error("Should have thrown error for missing API key");
+  } catch (error) {
+    if (!error.message.includes("API key is required")) {
+      throw error;
+    }
+  }
+});
+
+// Test 5: Ollama provider does NOT require API key
+test("Ollama provider does not require API key", () => {
+  const provider = EmbeddingProviderFactory.create({
+    provider: "ollama",
+  });
+  if (!provider) {
+    throw new Error("Failed to create Ollama provider");
+  }
+  if (provider.getModel() !== "nomic-embed-text") {
+    throw new Error(
+      `Expected default model 'nomic-embed-text', got '${provider.getModel()}'`,
+    );
+  }
+  if (provider.getDimensions() !== 768) {
+    throw new Error(
+      `Expected default dimensions 768, got ${provider.getDimensions()}`,
+    );
+  }
+});
+
+// Test 6: OpenAI provider with valid config
+test("OpenAI provider instantiates with API key", () => {
+  const provider = EmbeddingProviderFactory.create({
+    provider: "openai",
+    apiKey: "test-key-123",
+  });
+  if (!provider) {
+    throw new Error("Failed to create OpenAI provider");
+  }
+  if (provider.getModel() !== "text-embedding-3-small") {
+    throw new Error(
+      `Expected default model 'text-embedding-3-small', got '${provider.getModel()}'`,
+    );
+  }
+  if (provider.getDimensions() !== 1536) {
+    throw new Error(
+      `Expected default dimensions 1536, got ${provider.getDimensions()}`,
+    );
+  }
+});
+
+// Test 7: Cohere provider with valid config
+test("Cohere provider instantiates with API key", () => {
+  const provider = EmbeddingProviderFactory.create({
+    provider: "cohere",
+    apiKey: "test-key-123",
+  });
+  if (!provider) {
+    throw new Error("Failed to create Cohere provider");
+  }
+  if (provider.getModel() !== "embed-english-v3.0") {
+    throw new Error(
+      `Expected default model 'embed-english-v3.0', got '${provider.getModel()}'`,
+    );
+  }
+  if (provider.getDimensions() !== 1024) {
+    throw new Error(
+      `Expected default dimensions 1024, got ${provider.getDimensions()}`,
+    );
+  }
+});
+
+// Test 8: Voyage AI provider with valid config
+test("Voyage AI provider instantiates with API key", () => {
+  const provider = EmbeddingProviderFactory.create({
+    provider: "voyage",
+    apiKey: "test-key-123",
+  });
+  if (!provider) {
+    throw new Error("Failed to create Voyage AI provider");
+  }
+  if (provider.getModel() !== "voyage-2") {
+    throw new Error(
+      `Expected default model 'voyage-2', got '${provider.getModel()}'`,
+    );
+  }
+  if (provider.getDimensions() !== 1024) {
+    throw new Error(
+      `Expected default dimensions 1024, got ${provider.getDimensions()}`,
+    );
+  }
+});
+
+// Test 9: Custom model configuration
+test("Custom model configuration works", () => {
+  const provider = EmbeddingProviderFactory.create({
+    provider: "openai",
+    apiKey: "test-key-123",
+    model: "text-embedding-3-large",
+  });
+  if (provider.getModel() !== "text-embedding-3-large") {
+    throw new Error(
+      `Expected model 'text-embedding-3-large', got '${provider.getModel()}'`,
+    );
+  }
+  if (provider.getDimensions() !== 3072) {
+    throw new Error(
+      `Expected dimensions 3072 for large model, got ${provider.getDimensions()}`,
+    );
+  }
+});
+
+// Test 10: Custom dimensions override
+test("Custom dimensions override works", () => {
+  const provider = EmbeddingProviderFactory.create({
+    provider: "openai",
+    apiKey: "test-key-123",
+    dimensions: 512,
+  });
+  if (provider.getDimensions() !== 512) {
+    throw new Error(
+      `Expected custom dimensions 512, got ${provider.getDimensions()}`,
+    );
+  }
+});
+
+console.log();
+console.log("=".repeat(60));
+console.log("RESULTS");
+console.log("=".repeat(60));
+console.log(`Total Tests: ${results.passed + results.failed}`);
+console.log(`Passed: ${results.passed} ✅`);
+console.log(`Failed: ${results.failed} ${results.failed > 0 ? "❌" : ""}`);
+console.log(
+  `Success Rate: ${Math.round((results.passed / (results.passed + results.failed)) * 100)}%`,
+);
+console.log("=".repeat(60));
+
+if (results.failed > 0) {
+  console.log();
+  console.log("Failed Tests:");
+  results.tests
+    .filter((t) => t.status === "FAIL")
+    .forEach((t) => {
+      console.log(`  - ${t.name}: ${t.error}`);
+    });
+  process.exit(1);
+} else {
+  console.log();
+  console.log("✅ All provider instantiation tests passed!");
+  console.log("Multi-provider architecture is working correctly.");
+  process.exit(0);
+}

package/src/embeddings/base.ts

@@ -0,0 +1,25 @@
+export interface EmbeddingResult {
+  embedding: number[];
+  dimensions: number;
+}
+
+export interface RateLimitConfig {
+  maxRequestsPerMinute?: number;
+  retryAttempts?: number;
+  retryDelayMs?: number;
+}
+
+export interface EmbeddingProvider {
+  embed(text: string): Promise<EmbeddingResult>;
+  embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
+  getDimensions(): number;
+  getModel(): string;
+}
+
+export interface ProviderConfig {
+  model?: string;
+  dimensions?: number;
+  rateLimitConfig?: RateLimitConfig;
+  apiKey?: string;
+  baseUrl?: string;
+}

package/src/embeddings/cohere.test.ts

@@ -0,0 +1,408 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { CohereEmbeddings } from "./cohere.js";
+import { CohereClient } from "cohere-ai";
+
+vi.mock("cohere-ai", () => ({
+  CohereClient: vi.fn(),
+}));
+
+describe("CohereEmbeddings", () => {
+  let embeddings: CohereEmbeddings;
+  let mockClient: any;
+
+  beforeEach(() => {
+    mockClient = {
+      embed: vi.fn(),
+    };
+
+    vi.mocked(CohereClient).mockImplementation(() => mockClient as any);
+
+    embeddings = new CohereEmbeddings("test-api-key");
+  });
+
+  describe("constructor", () => {
+    it("should use default model and dimensions", () => {
+      expect(embeddings.getModel()).toBe("embed-english-v3.0");
+      expect(embeddings.getDimensions()).toBe(1024);
+    });
+
+    it("should use custom model", () => {
+      const customEmbeddings = new CohereEmbeddings(
+        "test-api-key",
+        "embed-multilingual-v3.0",
+      );
+      expect(customEmbeddings.getModel()).toBe("embed-multilingual-v3.0");
+      expect(customEmbeddings.getDimensions()).toBe(1024);
+    });
+
+    it("should use custom dimensions", () => {
+      const customEmbeddings = new CohereEmbeddings(
+        "test-api-key",
+        "embed-english-v3.0",
+        512,
+      );
+      expect(customEmbeddings.getDimensions()).toBe(512);
+    });
+
+    it("should use default dimensions for light models", () => {
+      const lightEmbeddings = new CohereEmbeddings(
+        "test-api-key",
+        "embed-english-light-v3.0",
+      );
+      expect(lightEmbeddings.getDimensions()).toBe(384);
+    });
+
+    it("should default to 1024 for unknown models", () => {
+      const unknownEmbeddings = new CohereEmbeddings(
+        "test-api-key",
+        "custom-model",
+      );
+      expect(unknownEmbeddings.getDimensions()).toBe(1024);
+    });
+
+    it("should accept custom input type", () => {
+      const searchQueryEmbeddings = new CohereEmbeddings(
+        "test-api-key",
+        "embed-english-v3.0",
+        undefined,
+        undefined,
+        "search_query",
+      );
+      expect(searchQueryEmbeddings).toBeInstanceOf(CohereEmbeddings);
+    });
+  });
+
+  describe("embed", () => {
+    it("should generate embedding for single text", async () => {
+      const mockEmbedding = Array(1024)
+        .fill(0)
+        .map((_, i) => i * 0.001);
+      mockClient.embed.mockResolvedValue({
+        embeddings: [mockEmbedding],
+      });
+
+      const result = await embeddings.embed("test text");
+
+      expect(result).toEqual({
+        embedding: mockEmbedding,
+        dimensions: 1024,
+      });
+      expect(mockClient.embed).toHaveBeenCalledWith({
+        texts: ["test text"],
+        model: "embed-english-v3.0",
+        inputType: "search_document",
+        embeddingTypes: ["float"],
+      });
+    });
+
+    it("should handle long text", async () => {
+      const longText = "word ".repeat(1000);
+      const mockEmbedding = Array(1024).fill(0.5);
+      mockClient.embed.mockResolvedValue({
+        embeddings: [mockEmbedding],
+      });
+
+      const result = await embeddings.embed(longText);
+
+      expect(result.embedding).toEqual(mockEmbedding);
+      expect(mockClient.embed).toHaveBeenCalledWith({
+        texts: [longText],
+        model: "embed-english-v3.0",
+        inputType: "search_document",
+        embeddingTypes: ["float"],
+      });
+    });
+
+    it("should use custom model configuration", async () => {
+      const customEmbeddings = new CohereEmbeddings(
+        "test-api-key",
+        "embed-multilingual-v3.0",
+        1024,
+      );
+      const mockEmbedding = Array(1024).fill(0.1);
+      mockClient.embed.mockResolvedValue({
+        embeddings: [mockEmbedding],
+      });
+
+      await customEmbeddings.embed("test");
+
+      expect(mockClient.embed).toHaveBeenCalledWith({
+        texts: ["test"],
+        model: "embed-multilingual-v3.0",
+        inputType: "search_document",
+        embeddingTypes: ["float"],
+      });
+    });
+
+    it("should throw error if no embedding returned", async () => {
+      mockClient.embed.mockResolvedValue({
+        embeddings: [],
+      });
+
+      await expect(embeddings.embed("test")).rejects.toThrow(
+        "No embedding returned from Cohere API",
+      );
+    });
+
+    it("should propagate errors", async () => {
+      mockClient.embed.mockRejectedValue(new Error("API Error"));
+
+      await expect(embeddings.embed("test")).rejects.toThrow("API Error");
+    });
+  });
+
+  describe("embedBatch", () => {
+    it("should generate embeddings for multiple texts", async () => {
+      const mockEmbeddings = [
+        Array(1024).fill(0.1),
+        Array(1024).fill(0.2),
+        Array(1024).fill(0.3),
+      ];
+      mockClient.embed.mockResolvedValue({
+        embeddings: mockEmbeddings,
+      });
+
+      const texts = ["text1", "text2", "text3"];
+      const results = await embeddings.embedBatch(texts);
+
+      expect(results).toEqual([
+        { embedding: mockEmbeddings[0], dimensions: 1024 },
+        { embedding: mockEmbeddings[1], dimensions: 1024 },
+        { embedding: mockEmbeddings[2], dimensions: 1024 },
+      ]);
+      expect(mockClient.embed).toHaveBeenCalledWith({
+        texts,
+        model: "embed-english-v3.0",
+        inputType: "search_document",
+        embeddingTypes: ["float"],
+      });
+    });
+
+    it("should handle empty batch", async () => {
+      mockClient.embed.mockResolvedValue({
+        embeddings: [],
+      });
+
+      const results = await embeddings.embedBatch([]);
+
+      expect(results).toEqual([]);
+    });
+
+    it("should handle single item in batch", async () => {
+      const mockEmbedding = Array(1024).fill(0.5);
+      mockClient.embed.mockResolvedValue({
+        embeddings: [mockEmbedding],
+      });
+
+      const results = await embeddings.embedBatch(["single text"]);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].embedding).toEqual(mockEmbedding);
+    });
+
+    it("should handle large batches", async () => {
+      const batchSize = 100;
+      const mockEmbeddings = Array(batchSize)
+        .fill(null)
+        .map(() => Array(1024).fill(Math.random()));
+
+      mockClient.embed.mockResolvedValue({
+        embeddings: mockEmbeddings,
+      });
+
+      const texts = Array(batchSize)
+        .fill(null)
+        .map((_, i) => `text ${i}`);
+      const results = await embeddings.embedBatch(texts);
+
+      expect(results).toHaveLength(batchSize);
+    });
+
+    it("should throw error if no embeddings returned", async () => {
+      mockClient.embed.mockResolvedValue({});
+
+      await expect(embeddings.embedBatch(["text1"])).rejects.toThrow(
+        "No embeddings returned from Cohere API",
+      );
+    });
+
+    it("should propagate errors in batch", async () => {
+      mockClient.embed.mockRejectedValue(new Error("Batch API Error"));
+
+      await expect(embeddings.embedBatch(["text1", "text2"])).rejects.toThrow(
+        "Batch API Error",
+      );
+    });
+  });
+
+  describe("getDimensions", () => {
+    it("should return configured dimensions", () => {
+      expect(embeddings.getDimensions()).toBe(1024);
+    });
+
+    it("should return custom dimensions", () => {
+      const customEmbeddings = new CohereEmbeddings(
+        "test-api-key",
+        "embed-english-v3.0",
+        512,
+      );
+      expect(customEmbeddings.getDimensions()).toBe(512);
+    });
+  });
+
+  describe("getModel", () => {
+    it("should return configured model", () => {
+      expect(embeddings.getModel()).toBe("embed-english-v3.0");
+    });
+
+    it("should return custom model", () => {
+      const customEmbeddings = new CohereEmbeddings(
+        "test-api-key",
+        "embed-multilingual-v3.0",
+      );
+      expect(customEmbeddings.getModel()).toBe("embed-multilingual-v3.0");
+    });
+  });
+
+  describe("rate limiting", () => {
+    it("should retry on rate limit error (status 429)", async () => {
+      const mockEmbedding = Array(1024).fill(0.5);
+
+      mockClient.embed
+        .mockRejectedValueOnce({ status: 429, message: "Rate limit exceeded" })
+        .mockRejectedValueOnce({ status: 429, message: "Rate limit exceeded" })
+        .mockResolvedValue({ embeddings: [mockEmbedding] });
+
+      const result = await embeddings.embed("test text");
+
+      expect(result.embedding).toEqual(mockEmbedding);
+      expect(mockClient.embed).toHaveBeenCalledTimes(3);
+    });
+
+    it("should retry on rate limit error (statusCode 429)", async () => {
+      const mockEmbedding = Array(1024).fill(0.5);
+
+      mockClient.embed
+        .mockRejectedValueOnce({
+          statusCode: 429,
+          message: "Rate limit exceeded",
+        })
+        .mockResolvedValue({ embeddings: [mockEmbedding] });
+
+      const result = await embeddings.embed("test text");
+
+      expect(result.embedding).toEqual(mockEmbedding);
+      expect(mockClient.embed).toHaveBeenCalledTimes(2);
+    });
+
+    it("should retry on rate limit message", async () => {
+      const mockEmbedding = Array(1024).fill(0.5);
+
+      mockClient.embed
+        .mockRejectedValueOnce({
+          message: "You have exceeded the rate limit",
+        })
+        .mockResolvedValue({ embeddings: [mockEmbedding] });
+
+      const result = await embeddings.embed("test text");
+
+      expect(result.embedding).toEqual(mockEmbedding);
+      expect(mockClient.embed).toHaveBeenCalledTimes(2);
+    });
+
+    it("should use exponential backoff", async () => {
+      const rateLimitEmbeddings = new CohereEmbeddings(
+        "test-api-key",
+        "embed-english-v3.0",
+        undefined,
+        {
+          retryAttempts: 3,
+          retryDelayMs: 100,
+        },
+      );
+
+      const mockEmbedding = Array(1024).fill(0.5);
+      const rateLimitError = {
+        status: 429,
+        message: "Rate limit exceeded",
+      };
+
+      mockClient.embed
+        .mockRejectedValueOnce(rateLimitError)
+        .mockRejectedValueOnce(rateLimitError)
+        .mockResolvedValue({ embeddings: [mockEmbedding] });
+
+      const startTime = Date.now();
+      await rateLimitEmbeddings.embed("test text");
+      const duration = Date.now() - startTime;
+
+      // Should wait: 100ms (first retry) + 200ms (second retry) = 300ms
+      expect(duration).toBeGreaterThanOrEqual(250);
+    });
+
+    it("should throw error after max retries exceeded", async () => {
+      const rateLimitEmbeddings = new CohereEmbeddings(
+        "test-api-key",
+        "embed-english-v3.0",
+        undefined,
+        {
+          retryAttempts: 2,
+          retryDelayMs: 100,
+        },
+      );
+
+      const rateLimitError = {
+        status: 429,
+        message: "Rate limit exceeded",
+      };
+
+      mockClient.embed.mockRejectedValue(rateLimitError);
+
+      await expect(rateLimitEmbeddings.embed("test text")).rejects.toThrow(
+        "Cohere API rate limit exceeded after 2 retry attempts",
+      );
+
+      expect(mockClient.embed).toHaveBeenCalledTimes(3);
+    });
+
+    it("should handle rate limit errors in batch operations", async () => {
+      const mockEmbeddings = [Array(1024).fill(0.1), Array(1024).fill(0.2)];
+
+      mockClient.embed
+        .mockRejectedValueOnce({ status: 429, message: "Rate limit exceeded" })
+        .mockResolvedValue({
+          embeddings: mockEmbeddings,
+        });
+
+      const results = await embeddings.embedBatch(["text1", "text2"]);
+
+      expect(results).toHaveLength(2);
+      expect(mockClient.embed).toHaveBeenCalledTimes(2);
+    });
+
+    it("should not retry on non-rate-limit errors", async () => {
+      const apiError = new Error("Invalid API key");
+      mockClient.embed.mockRejectedValue(apiError);
+
+      await expect(embeddings.embed("test text")).rejects.toThrow(
+        "Invalid API key",
+      );
+      expect(mockClient.embed).toHaveBeenCalledTimes(1);
+    });
+
+    it("should accept custom rate limit configuration", () => {
+      const customEmbeddings = new CohereEmbeddings(
+        "test-api-key",
+        "embed-english-v3.0",
+        undefined,
+        {
+          maxRequestsPerMinute: 200,
+          retryAttempts: 5,
+          retryDelayMs: 2000,
+        },
+      );
+
+      expect(customEmbeddings).toBeDefined();
+    });
+  });
+});