@mhalder/qdrant-mcp-server 1.1.0

package/examples/README.md

@@ -0,0 +1,315 @@
+# Qdrant MCP Server Examples
+
+Practical examples demonstrating how to use the Qdrant MCP Server for various use cases.
+
+## Quick Start
+
+Before running these examples, ensure you have:
+
+1. **Qdrant and Ollama running**: `docker compose up -d`
+2. **Ollama model pulled**: `docker exec ollama ollama pull nomic-embed-text`
+3. **MCP Server configured**: See main [README](../README.md) for setup
+4. **Optional - Alternative providers**: Configure API key for OpenAI, Cohere, or Voyage AI if not using Ollama
+
+## Available Examples
+
+### 🎯 [Basic Usage](./basic/)
+
+**Start here if you're new to the MCP server.**
+
+Learn fundamental operations:
+
+- Creating collections
+- Adding documents
+- Performing semantic searches
+- Managing resources
+
+**Time:** 5-10 minutes
+**Difficulty:** Beginner
+
+---
+
+### ⚡ [Rate Limiting](./rate-limiting/)
+
+**Understand automatic rate limit handling for batch operations.**
+
+Topics covered:
+
+- Configuring rate limits for your embedding provider
+- Batch document processing
+- Exponential backoff retry behavior
+- Monitoring and troubleshooting
+
+**Use cases:**
+
+- High-volume document ingestion
+- Free tier optimization
+- Production reliability
+- Batch operations
+
+**Time:** 10-15 minutes
+**Difficulty:** Beginner to Intermediate
+
+---
+
+### 📚 [Knowledge Base](./knowledge-base/)
+
+**Build a searchable documentation system with metadata.**
+
+Topics covered:
+
+- Structuring documents with rich metadata
+- Organizing content by team, topic, and difficulty
+- Filtering searches by categories
+- Scaling and maintenance strategies
+
+**Use cases:**
+
+- Company documentation
+- Help centers
+- Internal wikis
+- Educational content
+
+**Time:** 15-20 minutes
+**Difficulty:** Intermediate
+
+---
+
+### 🔍 [Advanced Filtering](./filters/)
+
+**Master complex search filters with boolean logic.**
+
+Learn to:
+
+- Combine multiple filter conditions (AND, OR, NOT)
+- Filter by categories, prices, ratings, and availability
+- Use range filters for numeric values
+- Build sophisticated e-commerce searches
+
+**Use cases:**
+
+- Product catalogs
+- Inventory management
+- Content filtering
+- Access control
+
+**Time:** 20-30 minutes
+**Difficulty:** Intermediate to Advanced
+
+---
+
+## Example Structure
+
+Each example includes:
+
+- **README.md** - Step-by-step tutorial with commands
+- **Sample data** - Documents with metadata to copy/paste
+- **Search examples** - Real queries you can try
+- **Best practices** - Tips and recommendations
+
+## How to Use These Examples
+
+### Option 1: Interactive with Claude Code
+
+Copy commands directly into Claude Code:
+
+```
+Create a collection named "test"
+Add documents...
+Search for...
+```
+
+### Option 2: Understand the Concepts
+
+Read through examples to understand:
+
+- Metadata design patterns
+- Filter syntax and structure
+- Search result ranking
+- Collection organization
+
+### Option 3: Adapt for Your Use Case
+
+Use examples as templates:
+
+1. Start with the closest matching example
+2. Modify metadata structure for your data
+3. Adjust search queries for your needs
+4. Scale up with your own documents
+
+## Learning Path
+
+```
+┌─────────────┐
+│   Basic     │  Start here - core operations
+└──────┬──────┘
+       │
+       ├──────────┐
+       │          ▼
+       │     ┌─────────────┐
+       │     │    Rate     │  Learn automatic rate limit handling
+       │     │  Limiting   │  (especially for batch operations)
+       │     └─────────────┘
+       │
+       ▼
+┌─────────────┐
+│ Knowledge   │  Add structure with metadata
+│    Base     │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  Advanced   │  Master complex filtering
+│  Filtering  │
+└─────────────┘
+```
+
+## Common Patterns
+
+### Pattern 1: Content Organization
+
+```
+metadata: {
+  "category": "type",
+  "topic": "subject",
+  "author": "creator",
+  "date": "2024-01-15"
+}
+```
+
+Good for: Blogs, documentation, articles
+
+### Pattern 2: E-commerce
+
+```
+metadata: {
+  "category": "electronics",
+  "price": 99.99,
+  "rating": 4.5,
+  "in_stock": true,
+  "brand": "BrandName"
+}
+```
+
+Good for: Product catalogs, inventory systems
+
+### Pattern 3: Access Control
+
+```
+metadata: {
+  "visibility": "internal",
+  "department": "engineering",
+  "sensitivity": "confidential"
+}
+```
+
+Good for: Enterprise knowledge bases, secure documents
+
+### Pattern 4: Temporal Data
+
+```
+metadata: {
+  "created_at": "2024-01-15",
+  "updated_at": "2024-03-20",
+  "status": "published",
+  "version": "2.1"
+}
+```
+
+Good for: Versioned content, time-series data
+
+## Tips for All Examples
+
+### 1. Start Small
+
+Test with 5-10 documents before scaling to thousands.
+
+### 2. Design Metadata First
+
+Plan your metadata structure before adding documents:
+
+- What fields do you need?
+- What will you filter by?
+- What types (string, number, boolean)?
+
+### 3. Use Consistent IDs
+
+Choose an ID scheme:
+
+- Sequential: `1`, `2`, `3`
+- Prefixed: `doc-001`, `doc-002`
+- Semantic: `eng-api-auth`, `sales-pricing`
+- UUIDs: Generated automatically
+
+### 4. Test Searches
+
+Try various queries to validate:
+
+- Semantic matching works correctly
+- Filters return expected results
+- Result ranking makes sense
+
+### 5. Clean Up
+
+Delete test collections when done:
+
+```
+Delete collection "collection-name"
+```
+
+## Troubleshooting
+
+### Collection Already Exists
+
+```
+Delete collection "name"
+Create a collection named "name"
+```
+
+### No Search Results
+
+- Check collection has documents: `Get info about "collection-name"`
+- Verify filter syntax matches metadata exactly
+- Try search without filters first
+
+### Unexpected Results
+
+- Check document metadata structure
+- Validate filter conditions
+- Review semantic similarity scores
+
+### Error Messages
+
+- **"Collection not found"**: Create the collection first
+- **"Bad Request"**: Check filter JSON syntax
+- **"API error"**: Verify your embedding provider API key and credits
+
+## Next Steps
+
+After completing these examples:
+
+1. **Read the main [README](../README.md)** - Full tool documentation
+2. **Explore your own data** - Apply concepts to real use cases
+3. **Check out advanced features** - Quantization, hybrid search (future)
+4. **Join the community** - Contribute examples and improvements
+
+## Contributing
+
+Have a great example to share? Please open a PR!
+
+We're especially interested in:
+
+- Domain-specific use cases (legal, medical, finance)
+- Integration examples (RAG pipelines, chatbots)
+- Performance optimization patterns
+- Novel metadata structures
+
+## Additional Resources
+
+- [Qdrant Documentation](https://qdrant.tech/documentation/)
+- [OpenAI Embeddings Guide](https://platform.openai.com/docs/guides/embeddings)
+- [Cohere Embeddings Guide](https://docs.cohere.com/docs/embeddings)
+- [Voyage AI Documentation](https://docs.voyageai.com/)
+- [Ollama Documentation](https://ollama.ai/docs)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Main Project README](../README.md)

package/examples/basic/README.md

@@ -0,0 +1,111 @@
+# Basic Usage Example
+
+This example demonstrates the fundamental operations of the Qdrant MCP Server.
+
+## What You'll Learn
+
+- Creating a collection
+- Adding documents with metadata
+- Performing semantic search
+- Cleaning up resources
+
+## Prerequisites
+
+- Qdrant and Ollama running via Docker Compose
+- Ollama model pulled (nomic-embed-text)
+- Qdrant MCP Server configured
+- Claude Code or another MCP client
+
+**Optional**: Configure OpenAI, Cohere, or Voyage AI if not using Ollama (default)
+
+## Example Workflow
+
+### 1. Create a Collection
+
+```
+Create a collection named "basic-example"
+```
+
+This creates a new vector collection with default settings (Cosine distance, 768 dimensions for Ollama's nomic-embed-text model).
+
+### 2. Add Documents
+
+```
+Add these documents to basic-example:
+- id: 1, text: "The quick brown fox jumps over the lazy dog"
+- id: 2, text: "Machine learning is a subset of artificial intelligence"
+- id: 3, text: "Python is a popular programming language"
+```
+
+Documents are automatically embedded using Ollama (or your configured alternative provider).
+
+### 3. Search for Similar Documents
+
+```
+Search basic-example for "AI and computer programs"
+```
+
+Expected results:
+
+- Document 2 (ML/AI) should rank highest
+- Document 3 (Python/programming) may appear with lower score
+
+### 4. Get Collection Information
+
+```
+Get info about "basic-example" collection
+```
+
+Returns:
+
+- Vector dimensions
+- Number of documents
+- Distance metric used
+
+### 5. View All Collections
+
+```
+List all collections
+```
+
+Shows all available collections in your Qdrant instance.
+
+### 6. Delete Documents (Optional)
+
+```
+Delete documents [1, 3] from basic-example
+```
+
+Removes specific documents by ID.
+
+### 7. Clean Up
+
+```
+Delete collection "basic-example"
+```
+
+Removes the collection and all its data.
+
+## Try It Yourself
+
+Copy these commands into Claude Code:
+
+```
+Create a collection named "my-first-collection"
+
+Add these documents to my-first-collection:
+- id: "doc1", text: "Coffee is a popular morning beverage"
+- id: "doc2", text: "Tea comes in many varieties like green, black, and oolong"
+- id: "doc3", text: "Orange juice is rich in vitamin C"
+
+Search my-first-collection for "healthy drinks"
+
+Get info about "my-first-collection" collection
+
+Delete collection "my-first-collection"
+```
+
+## Next Steps
+
+- [Knowledge Base Example](../knowledge-base/) - Learn about metadata and organization
+- [Advanced Filtering](../filters/) - Discover powerful search filtering

package/examples/filters/README.md

@@ -0,0 +1,262 @@
+# Advanced Filtering Examples
+
+This example demonstrates powerful metadata filtering capabilities using Qdrant's filter syntax.
+
+## What You'll Learn
+
+- Complex boolean logic (AND, OR, NOT)
+- Range filters for numeric values
+- Combining multiple filter conditions
+- Real-world filtering scenarios
+
+## Setup
+
+Create a collection with sample e-commerce data:
+
+```
+Create a collection named "products"
+
+Add these documents to products:
+- id: "p1", text: "Wireless Bluetooth headphones with noise cancellation and 30-hour battery life", metadata: {"category": "electronics", "price": 199.99, "rating": 4.5, "in_stock": true, "brand": "AudioTech"}
+- id: "p2", text: "Organic cotton t-shirt, comfortable fit, available in multiple colors", metadata: {"category": "clothing", "price": 29.99, "rating": 4.2, "in_stock": true, "brand": "EcoWear"}
+- id: "p3", text: "Stainless steel water bottle, insulated, keeps drinks cold for 24 hours", metadata: {"category": "accessories", "price": 34.99, "rating": 4.8, "in_stock": false, "brand": "HydroFlow"}
+- id: "p4", text: "Mechanical keyboard with RGB lighting and customizable switches", metadata: {"category": "electronics", "price": 149.99, "rating": 4.6, "in_stock": true, "brand": "KeyMaster"}
+- id: "p5", text: "Yoga mat with excellent grip, eco-friendly materials, includes carrying strap", metadata: {"category": "sports", "price": 39.99, "rating": 4.7, "in_stock": true, "brand": "FlexFit"}
+- id: "p6", text: "Smart watch with fitness tracking, heart rate monitor, and GPS", metadata: {"category": "electronics", "price": 299.99, "rating": 4.3, "in_stock": true, "brand": "TechTime"}
+- id: "p7", text: "Running shoes with responsive cushioning and breathable mesh upper", metadata: {"category": "sports", "price": 89.99, "rating": 4.4, "in_stock": false, "brand": "SpeedFoot"}
+- id: "p8", text: "Leather laptop bag with padded compartments and adjustable shoulder strap", metadata: {"category": "accessories", "price": 79.99, "rating": 4.5, "in_stock": true, "brand": "ProCarry"}
+```
+
+## Filter Examples
+
+### 1. Simple Match Filter (AND)
+
+Find electronics products:
+
+```
+Search products for "device for music" with filter {"must": [{"key": "category", "match": {"value": "electronics"}}]}
+```
+
+Expected: Returns p1, p4, p6 (all electronics)
+
+### 2. Multiple Conditions (AND)
+
+Find in-stock electronics:
+
+```
+Search products for "gadgets" with filter {"must": [{"key": "category", "match": {"value": "electronics"}}, {"key": "in_stock", "match": {"value": true}}]}
+```
+
+Expected: Returns p1, p4, p6 (in-stock electronics only)
+
+### 3. OR Logic with Should
+
+Find either sports or accessories:
+
+```
+Search products for "gear" with filter {"should": [{"key": "category", "match": {"value": "sports"}}, {"key": "category", "match": {"value": "accessories"}}]}
+```
+
+Expected: Returns p3, p5, p7, p8 (sports OR accessories)
+
+### 4. Negation with Must Not
+
+Find everything except clothing:
+
+```
+Search products for "shopping" with filter {"must_not": [{"key": "category", "match": {"value": "clothing"}}]}
+```
+
+Expected: Returns all products except p2
+
+### 5. Range Filter - Greater Than
+
+**Note:** Range filters require Qdrant's range condition syntax. The current implementation supports match filters. For range queries, you would need to use Qdrant's native range syntax:
+
+Conceptual example (not yet implemented in MCP server):
+
+```json
+{
+  "must": [
+    {
+      "key": "price",
+      "range": {
+        "gt": 100.0
+      }
+    }
+  ]
+}
+```
+
+### 6. Complex Boolean Logic
+
+Find in-stock products that are either:
+
+- Electronics with rating > 4.5, OR
+- Sports items under $50
+
+```
+Search products for "quality products" with filter {"must": [{"key": "in_stock", "match": {"value": true}}], "should": [{"key": "category", "match": {"value": "electronics"}}, {"key": "category", "match": {"value": "sports"}}]}
+```
+
+### 7. Combining Multiple Must Conditions
+
+Find highly-rated in-stock electronics:
+
+```
+Search products for "best gadgets" with filter {"must": [{"key": "category", "match": {"value": "electronics"}}, {"key": "in_stock", "match": {"value": true}}, {"key": "rating", "match": {"value": 4.5}}]}
+```
+
+Note: Exact match on rating. For range queries, use Qdrant's range filter syntax.
+
+### 8. Brand Filtering
+
+Find AudioTech products:
+
+```
+Search products for "audio equipment" with filter {"must": [{"key": "brand", "match": {"value": "AudioTech"}}]}
+```
+
+Expected: Returns p1 only
+
+### 9. Out of Stock Products
+
+Find what needs restocking:
+
+```
+Search products for "items" with filter {"must": [{"key": "in_stock", "match": {"value": false}}]}
+```
+
+Expected: Returns p3, p7 (out of stock items)
+
+### 10. Category Exclusion with Multiple Conditions
+
+Find non-electronic in-stock items:
+
+```
+Search products for "shopping" with filter {"must": [{"key": "in_stock", "match": {"value": true}}], "must_not": [{"key": "category", "match": {"value": "electronics"}}]}
+```
+
+Expected: Returns p2, p5, p8 (in-stock, non-electronics)
+
+## Filter Syntax Reference
+
+### Structure
+
+```json
+{
+  "must": [], // AND - all conditions must be true
+  "should": [], // OR - at least one condition must be true
+  "must_not": [] // NOT - conditions must be false
+}
+```
+
+### Match Filter
+
+Exact value matching:
+
+```json
+{
+  "key": "field_name",
+  "match": {
+    "value": "exact_value"
+  }
+}
+```
+
+Works with:
+
+- Strings: `"value": "electronics"`
+- Numbers: `"value": 4.5`
+- Booleans: `"value": true`
+
+### Range Filter (Qdrant Native)
+
+For numeric comparisons (future enhancement):
+
+```json
+{
+  "key": "price",
+  "range": {
+    "gt": 50, // greater than
+    "gte": 50, // greater than or equal
+    "lt": 200, // less than
+    "lte": 200 // less than or equal
+  }
+}
+```
+
+## Real-World Scenarios
+
+### E-commerce Product Search
+
+"Show me affordable fitness equipment"
+
+```
+Search products for "fitness equipment" with filter {"must": [{"key": "category", "match": {"value": "sports"}}, {"key": "in_stock", "match": {"value": true}}]}
+```
+
+### Inventory Management
+
+"Which electronics need restocking?"
+
+```
+Search products for "electronics" with filter {"must": [{"key": "category", "match": {"value": "electronics"}}, {"key": "in_stock", "match": {"value": false}}]}
+```
+
+### Quality Control
+
+"Show me all highly-rated available products"
+
+```
+Search products for "top rated products" with filter {"must": [{"key": "in_stock", "match": {"value": true}}]}
+```
+
+## Limitations and Workarounds
+
+### Current Limitations
+
+1. **No native range filters**: Can't directly filter by price ranges like "between $50-$100"
+2. **No text search on metadata**: Metadata matching is exact, not fuzzy
+3. **No nested object queries**: Flat metadata structure only
+
+### Workarounds
+
+1. **Price ranges**: Add price_tier to metadata:
+
+   ```json
+   {"price_tier": "budget", "price": 29.99}  // budget: <$50
+   {"price_tier": "mid", "price": 149.99}    // mid: $50-$200
+   {"price_tier": "premium", "price": 299.99} // premium: >$200
+   ```
+
+2. **Multiple categories**: Use array-based tags:
+
+   ```json
+   { "tags": ["electronics", "wearable", "fitness"] }
+   ```
+
+3. **Date filtering**: Store dates as strings in comparable format:
+   ```json
+   { "created_date": "2024-03-15" } // YYYY-MM-DD for lexicographic comparison
+   ```
+
+## Best Practices
+
+1. **Keep metadata flat**: Avoid deep nesting for better filter performance
+2. **Use consistent types**: Don't mix strings and numbers for the same field
+3. **Index commonly filtered fields**: Design metadata around common queries
+4. **Test filters first**: Validate filter syntax before complex queries
+5. **Combine with semantic search**: Use filters to narrow, then semantic search to rank
+
+## Clean Up
+
+```
+Delete collection "products"
+```
+
+## Next Steps
+
+- Review [Qdrant filtering documentation](https://qdrant.tech/documentation/concepts/filtering/)
+- Explore the [Knowledge Base Example](../knowledge-base/) for organizational patterns
+- Check the main README for full filter syntax support