@mhalder/qdrant-mcp-server 1.1.0 → 1.2.0

package/examples/knowledge-base/README.md

@@ -1,33 +1,24 @@
-# Knowledge Base Example
+# Knowledge Base
 
-This example shows how to build a searchable documentation system with rich metadata for organization and filtering.
+Build a searchable documentation system with rich metadata for filtering and organization.
+
+**Time:** 15-20 minutes | **Difficulty:** Intermediate
 
 ## Use Case
 
-You're building a company knowledge base with:
+Company knowledge base with:
 
 - Documentation from multiple teams
-- Articles with different topics and difficulty levels
-- Content that needs to be searchable and filterable
-
-## What You'll Learn
-
-- Organizing documents with metadata
-- Using metadata for categorization
-- Filtering searches by metadata fields
-- Building a scalable knowledge base structure
+- Content with varying topics and difficulty levels
+- Searchable and filterable articles
 
 ## Setup
 
-### 1. Create the Collection
-
 ```
+# Create collection
 Create a collection named "company-kb"
-```
-
-### 2. Add Structured Documents
 
-```
+# Add structured documents
 Add these documents to company-kb:
 - id: "eng-001", text: "Our API uses REST principles with JSON payloads. Authentication is handled via JWT tokens in the Authorization header.", metadata: {"team": "engineering", "topic": "api", "difficulty": "intermediate", "category": "technical"}
 - id: "eng-002", text: "To deploy to production, merge your PR to main. The CI/CD pipeline automatically runs tests and deploys if all checks pass.", metadata: {"team": "engineering", "topic": "deployment", "difficulty": "beginner", "category": "process"}
@@ -39,51 +30,26 @@ Add these documents to company-kb:
 
 ## Search Examples
 
-### Basic Search (No Filters)
-
 ```
+# Basic search
 Search company-kb for "how do I deploy code"
-```
-
-Expected: Returns deployment-related docs (eng-002 likely ranks highest)
-
-### Filter by Team
 
-```
+# Filter by team
 Search company-kb for "process documentation" with filter {"must": [{"key": "team", "match": {"value": "engineering"}}]}
-```
-
-Returns only engineering team documents.
 
-### Filter by Difficulty
-
-```
+# Filter by difficulty
 Search company-kb for "getting started" with filter {"must": [{"key": "difficulty", "match": {"value": "beginner"}}]}
-```
 
-Returns beginner-friendly documentation.
-
-### Multiple Filters (AND)
-
-```
+# Multiple filters (AND)
 Search company-kb for "company procedures" with filter {"must": [{"key": "category", "match": {"value": "process"}}, {"key": "difficulty", "match": {"value": "beginner"}}]}
-```
-
-Returns beginner process documents only.
 
-### Filter by Topic
-
-```
+# Filter by topic
 Search company-kb for "pricing information" with filter {"must": [{"key": "team", "match": {"value": "sales"}}]}
 ```
 
-Restricts search to sales team content.
-
-## Metadata Design Best Practices
+## Metadata Design
 
-### 1. Consistent Schema
-
-Use the same metadata fields across all documents:
+### Schema Pattern
 
 ```json
 {
@@ -94,9 +60,9 @@ Use the same metadata fields across all documents:
 }
 ```
 
-### 2. Hierarchical Organization
+### Advanced Patterns
 
-Consider nesting metadata for complex taxonomies:
+**Hierarchical:**
 
 ```json
 {
@@ -107,9 +73,7 @@ Consider nesting metadata for complex taxonomies:
 }
 ```
 
-### 3. Multiple Tags
-
-Use arrays for multi-category documents:
+**Multi-category:**
 
 ```json
 {
@@ -118,9 +82,7 @@ Use arrays for multi-category documents:
 }
 ```
 
-### 4. Timestamps and Versioning
-
-Track freshness and versions:
+**Versioned:**
 
 ```json
 {
@@ -131,18 +93,7 @@ Track freshness and versions:
 }
 ```
 
-## Scaling Your Knowledge Base
-
-### Add More Content Types
-
-- Code examples with language tags
-- Video transcripts with duration metadata
-- Meeting notes with attendees and dates
-- Product specs with version numbers
-
-### Implement Access Control
-
-Use metadata for permissions:
+**Access Control:**
 
 ```json
 {
@@ -151,51 +102,38 @@ Use metadata for permissions:
 }
 ```
 
-Then filter searches based on user permissions.
+## Scaling
 
-### Track Usage
+### Content Types
 
-Add metadata for analytics:
-
-```json
-{
-  "views": 0,
-  "last_accessed": null,
-  "author": "user@company.com"
-}
-```
-
-## Maintenance
+- Code examples with language tags
+- Video transcripts with duration
+- Meeting notes with attendees/dates
+- Product specs with versions
 
-### Update Documents
+### Maintenance
 
-To update content, delete and re-add:
+**Update documents:**
 
 ```
 Delete documents ["eng-001"] from company-kb
-
 Add these documents to company-kb:
-- id: "eng-001", text: "Updated API documentation...", metadata: {...}
+- id: "eng-001", text: "Updated content...", metadata: {...}
 ```
 
-### Archive Old Content
-
-Use status metadata to hide outdated docs:
+**Archive old content:**
 
 ```json
-{
-  "status": "archived",
-  "archived_date": "2024-12-01"
-}
+{ "status": "archived", "archived_date": "2024-12-01" }
 ```
 
-Then filter searches to exclude archived content:
+Then filter searches:
 
 ```
 Search company-kb for "deployment" with filter {"must_not": [{"key": "status", "match": {"value": "archived"}}]}
 ```
 
-## Clean Up
+## Cleanup
 
 ```
 Delete collection "company-kb"
@@ -203,5 +141,5 @@ Delete collection "company-kb"
 
 ## Next Steps
 
-- [Advanced Filtering Examples](../filters/) - Learn complex filter patterns
-- See the main README for information on batch document operations
+- Explore [Advanced Filtering](../filters/) for complex filter patterns
+- Review [main README](../../README.md) for batch operations and advanced features

package/examples/rate-limiting/README.md

@@ -1,124 +1,81 @@
-# Rate Limiting Example
+# Rate Limiting
 
-Learn how the Qdrant MCP Server handles embedding provider API rate limits automatically with intelligent throttling and retry mechanisms.
+Learn how the server handles embedding provider API rate limits automatically with intelligent throttling and retry mechanisms.
 
-## Overview
+**Time:** 10-15 minutes | **Difficulty:** Beginner to Intermediate
 
-This example demonstrates:
+## Why It Matters
 
-- How rate limiting prevents API failures (for cloud providers)
-- Configuring rate limits for your embedding provider
-- Batch operations with automatic throttling
-- Exponential backoff retry behavior
-- Monitoring rate limit events
-- Why Ollama doesn't need rate limiting (local processing)
+| Provider             | Rate Limits     | Notes                           |
+| -------------------- | --------------- | ------------------------------- |
+| **Ollama** (default) | None            | Local processing, no limits!    |
+| **OpenAI**           | 500-10,000+/min | Based on tier (Free/Tier 1/2/3) |
+| **Cohere**           | ~100/min        | Varies by plan                  |
+| **Voyage AI**        | ~300/min        | Varies by plan                  |
 
-**Time:** 10-15 minutes
-**Difficulty:** Beginner to Intermediate
-
-## Why Rate Limiting Matters
-
-**Ollama (Default):** Since Ollama runs locally, there are no API rate limits! You can process as many embeddings as your system can handle.
-
-**Cloud Embedding Providers** (OpenAI, Cohere, Voyage AI) enforce rate limits based on your account tier:
-
-**OpenAI:**
-| Tier | Requests/Minute |
-| ------- | --------------- |
-| Free | 500 |
-| Tier 1 | 3,500 |
-| Tier 2 | 5,000 |
-| Tier 3+ | 10,000+ |
-
-**Other Cloud Providers:**
-
-- **Cohere**: ~100 requests/minute (varies by plan)
-- **Voyage AI**: ~300 requests/minute (varies by plan)
-
-Without rate limiting, batch operations with cloud providers can exceed these limits and fail. This is one reason why **Ollama is the default** - no rate limits to worry about!
+Without rate limiting, batch operations with cloud providers can fail. **This is why Ollama is the default** - no rate limits to worry about!
 
 ## How It Works
 
 The server automatically:
 
-1. **Throttles Requests**: Queues API calls to stay within limits
-2. **Retries on Failure**: Uses exponential backoff (1s, 2s, 4s, 8s...)
-3. **Respects Retry-After**: Follows provider retry guidance (when available)
-4. **Provides Feedback**: Shows retry progress in console
+1. **Throttles** - Queues API calls within limits
+2. **Retries** - Exponential backoff (1s, 2s, 4s, 8s...)
+3. **Respects Headers** - Follows provider retry guidance
+4. **Provides Feedback** - Console shows retry progress
 
 ## Configuration
 
-### Ollama Settings (Default - No Rate Limiting Needed)
+### Provider Defaults
+
+| Provider  | Default Limit     | Retry Attempts | Retry Delay |
+| --------- | ----------------- | -------------- | ----------- |
+| Ollama    | 1000/min          | 3              | 500ms       |
+| OpenAI    | 3500/min (Tier 1) | 3              | 1000ms      |
+| Cohere    | 100/min           | 3              | 1000ms      |
+| Voyage AI | 300/min           | 3              | 1000ms      |
+
+### Custom Settings
 
 ```bash
-EMBEDDING_PROVIDER=ollama  # or omit (ollama is default)
-EMBEDDING_BASE_URL=http://localhost:11434
-EMBEDDING_MODEL=nomic-embed-text
-# No rate limit configuration needed - runs locally!
+# Adjust for your provider tier
+EMBEDDING_MAX_REQUESTS_PER_MINUTE=500    # Free tier
+EMBEDDING_RETRY_ATTEMPTS=5                # More resilient
+EMBEDDING_RETRY_DELAY=2000                # Longer initial delay
 ```
 
-### OpenAI Settings
+### Provider Examples
 
-**Default (Tier 1 Paid):**
+**Ollama (Default):**
 
 ```bash
-EMBEDDING_PROVIDER=openai
-EMBEDDING_MAX_REQUESTS_PER_MINUTE=3500
-EMBEDDING_RETRY_ATTEMPTS=3
-EMBEDDING_RETRY_DELAY=1000
+EMBEDDING_PROVIDER=ollama
+EMBEDDING_BASE_URL=http://localhost:11434
+# No rate limit config needed!
 ```
 
-**Free Tier:**
+**OpenAI Free Tier:**
 
 ```bash
 EMBEDDING_PROVIDER=openai
 EMBEDDING_MAX_REQUESTS_PER_MINUTE=500
 EMBEDDING_RETRY_ATTEMPTS=5
-EMBEDDING_RETRY_DELAY=2000
-```
-
-### Cohere Settings
-
-```bash
-EMBEDDING_PROVIDER=cohere
-EMBEDDING_MAX_REQUESTS_PER_MINUTE=100
-EMBEDDING_RETRY_ATTEMPTS=3
-EMBEDDING_RETRY_DELAY=1000
 ```
 
-### Voyage AI Settings
+**OpenAI Paid Tier:**
 
 ```bash
-EMBEDDING_PROVIDER=voyage
-EMBEDDING_MAX_REQUESTS_PER_MINUTE=300
-EMBEDDING_RETRY_ATTEMPTS=3
-EMBEDDING_RETRY_DELAY=1000
+EMBEDDING_PROVIDER=openai
+EMBEDDING_MAX_REQUESTS_PER_MINUTE=3500  # Tier 1
 ```
 
-### Ollama Settings (Local)
-
-```bash
-EMBEDDING_PROVIDER=ollama
-EMBEDDING_MAX_REQUESTS_PER_MINUTE=1000
-EMBEDDING_RETRY_ATTEMPTS=3
-EMBEDDING_RETRY_DELAY=500
-```
-
-## Example: Batch Document Processing
-
-Let's test rate limiting by adding many documents at once.
-
-### Step 1: Create Collection
+## Example: Batch Processing
 
 ```
+# Create collection
 Create a collection named "rate-limit-test"
-```
-
-### Step 2: Add Batch of Documents
 
-Try adding multiple documents in a single operation:
-
-```
+# Add batch of documents (tests rate limiting)
 Add these documents to "rate-limit-test":
 - id: 1, text: "Introduction to machine learning algorithms", metadata: {"topic": "ml"}
 - id: 2, text: "Deep learning neural networks explained", metadata: {"topic": "dl"}
@@ -130,125 +87,23 @@ Add these documents to "rate-limit-test":
 - id: 8, text: "Hyperparameter optimization methods", metadata: {"topic": "tuning"}
 - id: 9, text: "Transfer learning and fine-tuning", metadata: {"topic": "transfer"}
 - id: 10, text: "Ensemble methods and boosting", metadata: {"topic": "ensemble"}
-```
 
-**What happens:**
-
-- The server generates embeddings for all 10 documents
-- Requests are automatically queued and throttled
-- If rate limits are hit, automatic retry with backoff occurs
-- Console shows retry messages with wait times
-
-### Step 3: Test Search
-
-```
+# Search
 Search "rate-limit-test" for "neural networks and deep learning"
-```
-
-### Step 4: Monitor Console Output
-
-Watch for rate limiting messages:
-
-```
-Rate limit reached. Retrying in 1.0s (attempt 1/3)...
-Rate limit reached. Retrying in 2.0s (attempt 2/3)...
-```
-
-These messages indicate:
-
-- Rate limit was detected (429 error)
-- Automatic retry is in progress
-- Current attempt number and delay
-
-## Simulating Rate Limit Scenarios
-
-### Scenario 1: Free Tier User
-
-**Configuration:**
-
-```bash
-OPENAI_MAX_REQUESTS_PER_MINUTE=500
-```
-
-**Test:** Add 50 documents in batches of 10
-
-- Server automatically spaces requests
-- No manual rate limit handling needed
-- Operations complete successfully
-
-### Scenario 2: High-Volume Batch
-
-**Test:** Add 100+ documents
-
-- Create collection: `batch-test-collection`
-- Add documents in chunks
-- Server queues requests automatically
-- Monitor console for throttling behavior
-
-### Scenario 3: Concurrent Operations
-
-**Test:** Multiple searches simultaneously
-
-- Perform several searches in quick succession
-- Rate limiter queues them appropriately
-- All complete without errors
-
-## Best Practices
-
-### 1. Configure for Your Provider
-
-Always set `EMBEDDING_MAX_REQUESTS_PER_MINUTE` to match your provider's limits:
 
-**OpenAI:**
+# Watch console for rate limit messages:
+# "Rate limit reached. Retrying in 1.0s (attempt 1/3)..."
+# "Rate limit reached. Retrying in 2.0s (attempt 2/3)..."
 
-```bash
-# Check your tier at: https://platform.openai.com/account/limits
-EMBEDDING_MAX_REQUESTS_PER_MINUTE=<your-limit>
-```
-
-**Other Providers:**
-
-- Check your provider's dashboard for rate limits
-- Start conservative and increase if needed
-
-### 2. Adjust Retry Settings for Reliability
-
-For critical operations, increase retry attempts:
-
-```bash
-EMBEDDING_RETRY_ATTEMPTS=5  # More resilient
-```
-
-For development/testing, reduce retries:
-
-```bash
-EMBEDDING_RETRY_ATTEMPTS=1  # Fail faster
+# Cleanup
+Delete collection "rate-limit-test"
 ```
 
-### 3. Batch Operations Wisely
-
-Most embedding providers support batch operations:
-
-- **OpenAI**: Up to 2048 texts per request
-- **Cohere**: Batch support available
-- **Voyage AI**: Batch support available
-- **Ollama**: Sequential processing (one at a time)
-
-The server automatically uses batch APIs when available for efficiency.
-
-### 4. Monitor Your Usage
-
-Watch console output during operations:
-
-- No messages = smooth operation
-- Retry messages = hitting limits (consider reducing rate)
-- Error after max retries = need to reduce request volume
+## Retry Behavior
 
-## Understanding Retry Behavior
+### Exponential Backoff
 
-### Exponential Backoff Example
-
-With `OPENAI_RETRY_DELAY=1000`:
+With `EMBEDDING_RETRY_DELAY=1000`:
 
 | Attempt | Delay | Total Wait |
 | ------- | ----- | ---------- |
@@ -259,118 +114,54 @@ With `OPENAI_RETRY_DELAY=1000`:
 
 ### Retry-After Header
 
-If the provider provides a `Retry-After` header (OpenAI, some others):
+If provider sends `Retry-After` header (OpenAI):
 
-- Server uses that exact delay
+- Server uses exact delay
 - Ignores exponential backoff
 - Ensures optimal recovery
 
-## Error Messages
-
-### Success Messages
-
-```
-Successfully added 10 document(s) to collection "rate-limit-test".
-```
-
-### Retry Messages (Normal)
-
-```
-Rate limit reached. Retrying in 2.0s (attempt 1/3)...
-```
-
-**Action:** None needed, automatic retry in progress
-
-### Max Retries Exceeded (Rare)
-
-```
-Error: [Provider] API rate limit exceeded after 3 retry attempts.
-Please try again later or reduce request frequency.
-```
-
-**Action:**
+## Best Practices
 
-- Wait a few minutes
-- Reduce `EMBEDDING_MAX_REQUESTS_PER_MINUTE`
-- Check your provider's dashboard for current usage
+1. **Match Your Tier** - Set `EMBEDDING_MAX_REQUESTS_PER_MINUTE` to your provider's limit
+2. **Check Dashboards** - Verify limits at provider's dashboard
+3. **Start Conservative** - Lower limits, increase if needed
+4. **Monitor Console** - Watch for retry messages
+5. **Use Ollama** - For unlimited local processing
 
-## Integration with Claude Code
+### Batch Operation Tips
 
-The rate limiting works seamlessly with Claude Code.
+- **OpenAI**: Up to 2048 texts per request
+- **Cohere**: Batch support available
+- **Voyage AI**: Batch support available
+- **Ollama**: Sequential processing (one at a time)
 
-**Example with Ollama (Default - No Rate Limits):**
+Server automatically uses batch APIs when available.
 
-```json
-{
-  "mcpServers": {
-    "qdrant": {
-      "command": "node",
-      "args": ["/path/to/qdrant-mcp-server/build/index.js"],
-      "env": {
-        "QDRANT_URL": "http://localhost:6333",
-        "EMBEDDING_BASE_URL": "http://localhost:11434"
-      }
-    }
-  }
-}
-```
+## Error Messages
 
-**Example with OpenAI (Alternative):**
-
-```json
-{
-  "mcpServers": {
-    "qdrant": {
-      "command": "node",
-      "args": ["/path/to/qdrant-mcp-server/build/index.js"],
-      "env": {
-        "EMBEDDING_PROVIDER": "openai",
-        "OPENAI_API_KEY": "sk-your-key",
-        "QDRANT_URL": "http://localhost:6333",
-        "EMBEDDING_MAX_REQUESTS_PER_MINUTE": "3500",
-        "EMBEDDING_RETRY_ATTEMPTS": "3",
-        "EMBEDDING_RETRY_DELAY": "1000"
-      }
-    }
-  }
-}
 ```
+# Success
+Successfully added 10 document(s) to collection "rate-limit-test".
 
-## Cleanup
+# Retry (Normal)
+Rate limit reached. Retrying in 2.0s (attempt 1/3)...
+# Action: None needed, automatic retry
 
-```
-Delete collection "rate-limit-test"
+# Max Retries Exceeded (Rare)
+Error: API rate limit exceeded after 3 retry attempts.
+# Action: Wait, reduce EMBEDDING_MAX_REQUESTS_PER_MINUTE, check dashboard
 ```
 
-## Key Takeaways
+## Troubleshooting
 
-1. ✅ **Ollama Default**: No rate limits with local processing
-2. ✅ **Automatic**: Rate limiting works out-of-the-box for cloud providers
-3. ✅ **Configurable**: Adjust for your cloud provider tier
-4. ✅ **Resilient**: Exponential backoff handles temporary issues
-5. ✅ **Transparent**: Console feedback shows what's happening
-6. ✅ **Efficient**: Batch operations optimize API usage
+| Issue                  | Solution                                           |
+| ---------------------- | -------------------------------------------------- |
+| Persistent rate limits | Reduce `EMBEDDING_MAX_REQUESTS_PER_MINUTE` by 20%  |
+| Slow performance       | Expected with rate limiting - better than failures |
+| Need faster processing | Upgrade provider tier or use Ollama                |
 
 ## Next Steps
 
-- Explore [Knowledge Base example](../knowledge-base/) for real-world usage
+- Explore [Knowledge Base](../knowledge-base/) for real-world usage patterns
 - Learn [Advanced Filtering](../filters/) for complex queries
-- Read [main README](../../README.md) for all configuration options
-
-## Troubleshooting
-
-### Still Getting Rate Limit Errors?
-
-1. **Check your provider's limits**: Visit your provider's dashboard
-2. **Reduce request rate**: Lower `EMBEDDING_MAX_REQUESTS_PER_MINUTE` by 20%
-3. **Increase retry attempts**: Set `EMBEDDING_RETRY_ATTEMPTS=5`
-4. **Wait between batches**: For very large operations, split into multiple sessions
-
-### Slow Performance?
-
-If operations seem slow:
-
-- This is expected with rate limiting
-- It's better than failed operations
-- Upgrade your provider's tier for higher limits
-- Consider using Ollama for unlimited local processing
+- Review [main README](../../README.md) for all configuration options

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhalder/qdrant-mcp-server",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "MCP server for semantic search using local Qdrant and Ollama (default) with support for OpenAI, Cohere, and Voyage AI",
   "type": "module",
   "bin": {