@mhalder/qdrant-mcp-server 1.1.1 → 1.3.0

package/build/transport.test.js

@@ -0,0 +1,168 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+describe("Transport Configuration", () => {
+    let originalEnv;
+    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();
+                }),
+            };
+            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);
+    });
+});
+//# sourceMappingURL=transport.test.js.map

package/build/transport.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.test.js","sourceRoot":"","sources":["../src/transport.test.ts"],"names":[],"mappings":"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"}

package/examples/README.md

@@ -31,6 +31,21 @@ Configure MCP server as described in [main README](../README.md).
 
 ---
 
+### 🔀 [Hybrid Search](./hybrid-search/)
+
+Combine semantic and keyword search for better results
+
+- Understanding hybrid search benefits
+- Creating hybrid-enabled collections
+- Comparing semantic vs hybrid search
+- Best practices for technical content
+
+**Use cases:** Technical docs, product search, legal documents, code search
+
+**Time:** 15-20 minutes | **Difficulty:** Intermediate
+
+---
+
 ### ⚡ [Rate Limiting](./rate-limiting/)
 
 Automatic rate limit handling for batch operations
@@ -77,7 +92,7 @@ Complex search filters with boolean logic
 ## Learning Path
 
 ```
-Basic → Rate Limiting → Knowledge Base → Advanced Filtering
+Basic → Hybrid Search → Rate Limiting → Knowledge Base → Advanced Filtering
 ```
 
 ## Common Patterns

package/examples/basic/README.md

@@ -52,6 +52,7 @@ Delete collection "my-first-collection"
 
 Continue learning with these examples:
 
+- **[Hybrid Search](../hybrid-search/)** - Combine semantic and keyword search
 - **[Knowledge Base](../knowledge-base/)** - Metadata and content organization
 - **[Advanced Filtering](../filters/)** - Complex search queries
 - **[Rate Limiting](../rate-limiting/)** - Batch processing patterns

package/examples/hybrid-search/README.md

@@ -0,0 +1,236 @@
+# Hybrid Search
+
+Combine semantic vector search with keyword (BM25) search for more accurate and comprehensive results.
+
+**Time:** 15-20 minutes | **Difficulty:** Intermediate
+
+## What is Hybrid Search?
+
+Hybrid search combines two search approaches:
+
+1. **Semantic Search**: Understands meaning and context using vector embeddings
+2. **Keyword Search**: Exact term matching using BM25 sparse vectors
+
+The results are merged using **Reciprocal Rank Fusion (RRF)**, which combines rankings from both methods to produce the best overall results.
+
+## When to Use Hybrid Search
+
+Hybrid search is ideal for:
+
+- **Technical documentation**: Users search for exact function names + concepts
+- **Product search**: Match SKUs/model numbers + descriptions
+- **Legal documents**: Exact citations + semantic context
+- **Code search**: Function names + natural language descriptions
+- **Mixed queries**: "authentication JWT" (semantic + exact keyword)
+
+## Benefits
+
+- **Best of both worlds**: Precision (keyword) + recall (semantic)
+- **Better results for ambiguous queries**
+- **Handles typos** (semantic) and **exact matches** (keyword)
+- **More control** over result relevance
+
+## Workflow
+
+### 1. Create a Collection with Hybrid Search Enabled
+
+```
+Create a collection named "technical_docs" with Cosine distance and enableHybrid set to true
+```
+
+**Important**: Set `enableHybrid: true` to enable hybrid search capabilities.
+
+### 2. Add Documents
+
+Documents are automatically indexed for both semantic and keyword search:
+
+```
+Add these documents to technical_docs:
+- id: 1, text: "The authenticateUser function validates JWT tokens for user sessions",
+  metadata: {"category": "authentication", "type": "function"}
+- id: 2, text: "JWT (JSON Web Token) is a compact URL-safe means of representing claims",
+  metadata: {"category": "authentication", "type": "definition"}
+- id: 3, text: "OAuth2 provides authorization framework for third-party applications",
+  metadata: {"category": "authentication", "type": "protocol"}
+- id: 4, text: "The login endpoint requires username and password credentials",
+  metadata: {"category": "authentication", "type": "endpoint"}
+```
+
+### 3. Perform Hybrid Search
+
+Search using both semantic understanding and keyword matching:
+
+```
+Search technical_docs for "JWT authentication function" with limit 3 using hybrid_search
+```
+
+**Result**: Documents are ranked by combining:
+
+- Semantic similarity to "authentication function"
+- Exact keyword matches for "JWT"
+
+### 4. Hybrid Search with Filters
+
+Combine hybrid search with metadata filtering:
+
+```
+Search technical_docs for "JWT token validation" with limit 2 and filter {"type": "function"} using hybrid_search
+```
+
+## Comparison: Semantic vs Hybrid Search
+
+### Semantic Search Only
+
+```
+Search technical_docs for "JWT authentication" with limit 3 using semantic_search
+```
+
+**Result**: May miss documents with exact "JWT" match if they're not semantically similar.
+
+### Hybrid Search
+
+```
+Search technical_docs for "JWT authentication" with limit 3 using hybrid_search
+```
+
+**Result**: Finds both:
+
+- Documents semantically related to authentication
+- Documents with exact "JWT" keyword match
+- Best combination ranked by RRF
+
+## Example Scenarios
+
+### Scenario 1: Exact Term + Context
+
+**Query**: "authenticateUser JWT"
+
+**Hybrid Search finds**:
+
+1. Documents with `authenticateUser` function name (keyword match)
+2. Documents about JWT authentication (semantic match)
+3. Best combination of both
+
+**Pure semantic search might miss**: Exact function name if using different terminology.
+
+### Scenario 2: Acronym + Description
+
+**Query**: "API rate limiting"
+
+**Hybrid Search finds**:
+
+1. Documents with "API" acronym (keyword match)
+2. Documents about rate limiting concepts (semantic match)
+3. Documents mentioning "API rate limiting" get highest score
+
+### Scenario 3: Typos + Exact Terms
+
+**Query**: "OAuth2 authentification"
+
+**Hybrid Search finds**:
+
+1. "OAuth2" exact matches (keyword - ignores typo in other term)
+2. Authentication concepts (semantic - understands "authentification" ≈ "authentication")
+
+## Technical Details
+
+### How It Works
+
+1. **Dense Vector Generation**: Your query is embedded using the configured embedding provider (Ollama, OpenAI, etc.)
+2. **Sparse Vector Generation**: Query is tokenized and BM25 scores are calculated
+3. **Parallel Search**: Both vectors are searched simultaneously
+4. **Result Fusion**: RRF combines rankings from both searches
+5. **Final Ranking**: Merged results with combined relevance scores
+
+### BM25 Sparse Vectors
+
+The server uses a lightweight BM25 implementation for sparse vectors:
+
+- Tokenization: Lowercase + whitespace splitting
+- IDF scoring: Inverse document frequency
+- Configurable parameters: k1=1.2, b=0.75
+
+### Reciprocal Rank Fusion (RRF)
+
+RRF formula: `score = Σ(1 / (k + rank))` where k=60 (default)
+
+Benefits:
+
+- No score normalization needed
+- Robust to differences in score scales
+- Works well for combining different ranking methods
+
+## Best Practices
+
+1. **Enable hybrid for technical content**: Use when exact terms matter
+2. **Use semantic for general content**: Natural language queries without technical terms
+3. **Combine with filters**: Narrow down results by category or type
+4. **Test both approaches**: Compare semantic vs hybrid for your use case
+5. **Monitor performance**: Hybrid search requires more computation
+
+## Performance Considerations
+
+- **Storage**: Hybrid collections require more space (dense + sparse vectors)
+- **Indexing**: Document indexing is slightly slower
+- **Query time**: Hybrid search performs two searches and fusion
+- **Scalability**: Qdrant optimizes both vector types efficiently
+
+## Try It
+
+Practice hybrid search with your own example:
+
+```
+Create a collection named "my-hybrid-docs" with Cosine distance and enableHybrid set to true
+
+Add these documents to my-hybrid-docs:
+- id: "doc1", text: "The calculateTax function computes sales tax based on location and product type", metadata: {"category": "finance", "type": "function"}
+- id: "doc2", text: "Tax calculation involves applying regional rates and exemptions", metadata: {"category": "finance", "type": "concept"}
+- id: "doc3", text: "The generateInvoice method creates PDF invoices with itemized charges", metadata: {"category": "billing", "type": "function"}
+- id: "doc4", text: "Invoice generation includes customer details, line items, and payment terms", metadata: {"category": "billing", "type": "concept"}
+
+Search my-hybrid-docs for "calculateTax invoice" with limit 3 using hybrid_search
+
+Search my-hybrid-docs for "tax calculation" with limit 2 using semantic_search
+
+# Compare the results - notice how hybrid search finds both exact function names and concepts
+
+Delete collection "my-hybrid-docs"
+```
+
+## Troubleshooting
+
+### "Collection does not have hybrid search enabled"
+
+**Solution**: Create a new collection with `enableHybrid: true`. Existing collections cannot be converted.
+
+### Poor results with hybrid search
+
+**Try**:
+
+1. Adjust query phrasing to include key terms
+2. Use metadata filters to narrow scope
+3. Increase `limit` to see more results
+4. Compare with pure semantic search
+
+### Slow query performance
+
+**Solutions**:
+
+1. Reduce prefetch limit (contact support for tuning)
+2. Add filters to narrow search space
+3. Use fewer documents or partition data
+
+## Cleanup
+
+```
+Delete collection "technical_docs"
+```
+
+## Next Steps
+
+Continue learning with these examples:
+
+- **[Knowledge Base](../knowledge-base/)** - Searchable documentation with metadata
+- **[Advanced Filtering](../filters/)** - Complex search queries
+- **[Rate Limiting](../rate-limiting/)** - Batch processing patterns
+- **[Basic Usage](../basic/)** - Fundamental operations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhalder/qdrant-mcp-server",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "MCP server for semantic search using local Qdrant and Ollama (default) with support for OpenAI, Cohere, and Voyage AI",
   "type": "module",
   "bin": {
@@ -37,6 +37,7 @@
     "@qdrant/js-client-rest": "^1.12.0",
     "bottleneck": "^2.19.5",
     "cohere-ai": "^7.19.0",
+    "express": "^5.1.0",
     "openai": "^4.77.3",
     "zod": "^3.24.1"
   },
@@ -47,6 +48,7 @@
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^11.0.6",
     "@semantic-release/npm": "^12.0.2",
+    "@types/express": "^5.0.3",
     "@types/node": "^22.10.5",
     "@vitest/coverage-v8": "^2.1.8",
     "@vitest/ui": "^2.1.8",

package/src/embeddings/sparse.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { BM25SparseVectorGenerator } from "./sparse.js";
+
+describe("BM25SparseVectorGenerator", () => {
+  it("should generate sparse vectors for simple text", () => {
+    const generator = new BM25SparseVectorGenerator();
+    const result = generator.generate("hello world");
+
+    expect(result.indices).toBeDefined();
+    expect(result.values).toBeDefined();
+    expect(result.indices.length).toBeGreaterThan(0);
+    expect(result.values.length).toBe(result.indices.length);
+  });
+
+  it("should generate different vectors for different texts", () => {
+    const generator = new BM25SparseVectorGenerator();
+    const result1 = generator.generate("hello world");
+    const result2 = generator.generate("goodbye world");
+
+    // Different texts should have different sparse representations
+    expect(result1.indices).not.toEqual(result2.indices);
+  });
+
+  it("should generate consistent vectors for the same text", () => {
+    const generator = new BM25SparseVectorGenerator();
+    const result1 = generator.generate("hello world");
+    const result2 = generator.generate("hello world");
+
+    expect(result1.indices).toEqual(result2.indices);
+    expect(result1.values).toEqual(result2.values);
+  });
+
+  it("should handle empty strings", () => {
+    const generator = new BM25SparseVectorGenerator();
+    const result = generator.generate("");
+
+    expect(result.indices).toHaveLength(0);
+    expect(result.values).toHaveLength(0);
+  });
+
+  it("should handle special characters and punctuation", () => {
+    const generator = new BM25SparseVectorGenerator();
+    const result = generator.generate("hello, world! how are you?");
+
+    expect(result.indices).toBeDefined();
+    expect(result.values).toBeDefined();
+    expect(result.indices.length).toBeGreaterThan(0);
+  });
+
+  it("should train on corpus and generate IDF scores", () => {
+    const generator = new BM25SparseVectorGenerator();
+    const corpus = ["the quick brown fox", "jumps over the lazy dog", "the fox is quick"];
+
+    generator.train(corpus);
+    const result = generator.generate("quick fox");
+
+    expect(result.indices).toBeDefined();
+    expect(result.values).toBeDefined();
+    expect(result.indices.length).toBeGreaterThan(0);
+  });
+
+  it("should use static generateSimple method", () => {
+    const result = BM25SparseVectorGenerator.generateSimple("hello world");
+
+    expect(result.indices).toBeDefined();
+    expect(result.values).toBeDefined();
+    expect(result.indices.length).toBeGreaterThan(0);
+  });
+
+  it("should lowercase and tokenize text properly", () => {
+    const generator = new BM25SparseVectorGenerator();
+    const result1 = generator.generate("HELLO WORLD");
+    const result2 = generator.generate("hello world");
+
+    // Should produce same results due to lowercasing
+    expect(result1.indices).toEqual(result2.indices);
+  });
+
+  it("should generate positive values", () => {
+    const generator = new BM25SparseVectorGenerator();
+    const result = generator.generate("hello world");
+
+    result.values.forEach((value) => {
+      expect(value).toBeGreaterThan(0);
+    });
+  });
+});