@mhalder/qdrant-mcp-server 1.1.0 → 1.2.0

package/examples/README.md

@@ -1,315 +1,140 @@
-# Qdrant MCP Server Examples
+# Examples
 
-Practical examples demonstrating how to use the Qdrant MCP Server for various use cases.
+Practical examples demonstrating Qdrant MCP Server usage.
 
-## Quick Start
+## Prerequisites
 
-Before running these examples, ensure you have:
+Before running examples:
 
-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
+```bash
+# Start services
+docker compose up -d
+
+# Pull embedding model
+docker exec ollama ollama pull nomic-embed-text
+```
+
+Configure MCP server as described in [main README](../README.md).
 
 ## Available Examples
 
 ### 🎯 [Basic Usage](./basic/)
 
-**Start here if you're new to the MCP server.**
-
-Learn fundamental operations:
+**Start here** - fundamental operations
 
 - Creating collections
 - Adding documents
-- Performing semantic searches
-- Managing resources
+- Semantic search
+- Resource management
 
-**Time:** 5-10 minutes
-**Difficulty:** Beginner
+**Time:** 5-10 minutes | **Difficulty:** Beginner
 
 ---
 
-### ⚡ [Rate Limiting](./rate-limiting/)
+### 🔀 [Hybrid Search](./hybrid-search/)
 
-**Understand automatic rate limit handling for batch operations.**
+Combine semantic and keyword search for better results
 
-Topics covered:
+- Understanding hybrid search benefits
+- Creating hybrid-enabled collections
+- Comparing semantic vs hybrid search
+- Best practices for technical content
 
-- 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
+**Use cases:** Technical docs, product search, legal documents, code search
 
-**Time:** 10-15 minutes
-**Difficulty:** Beginner to Intermediate
+**Time:** 15-20 minutes | **Difficulty:** Intermediate
 
 ---
 
-### 📚 [Knowledge Base](./knowledge-base/)
-
-**Build a searchable documentation system with metadata.**
+### ⚡ [Rate Limiting](./rate-limiting/)
 
-Topics covered:
+Automatic rate limit handling for batch operations
 
-- Structuring documents with rich metadata
-- Organizing content by team, topic, and difficulty
-- Filtering searches by categories
-- Scaling and maintenance strategies
-
-**Use cases:**
+- Configuring provider rate limits
+- Batch document processing
+- Exponential backoff retry
+- Monitoring and troubleshooting
 
-- Company documentation
-- Help centers
-- Internal wikis
-- Educational content
+**Use cases:** High-volume ingestion, free tier optimization, production reliability
 
-**Time:** 15-20 minutes
-**Difficulty:** Intermediate
+**Time:** 10-15 minutes | **Difficulty:** Beginner to Intermediate
 
 ---
 
-### 🔍 [Advanced Filtering](./filters/)
-
-**Master complex search filters with boolean logic.**
-
-Learn to:
+### 📚 [Knowledge Base](./knowledge-base/)
 
-- 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
+Searchable documentation system with metadata
 
-**Use cases:**
+- Structuring documents with rich metadata
+- Organizing by team, topic, difficulty
+- Filtering searches by categories
+- Scaling and maintenance
 
-- Product catalogs
-- Inventory management
-- Content filtering
-- Access control
+**Use cases:** Company docs, help centers, internal wikis, education
 
-**Time:** 20-30 minutes
-**Difficulty:** Intermediate to Advanced
+**Time:** 15-20 minutes | **Difficulty:** Intermediate
 
 ---
 
-## 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:
+### 🔍 [Advanced Filtering](./filters/)
 
-- Metadata design patterns
-- Filter syntax and structure
-- Search result ranking
-- Collection organization
+Complex search filters with boolean logic
 
-### Option 3: Adapt for Your Use Case
+- Multiple filter conditions (AND, OR, NOT)
+- Filtering by categories, ratings, availability
+- Range filters for numeric values
+- E-commerce search patterns
 
-Use examples as templates:
+**Use cases:** Product catalogs, inventory, content filtering, access control
 
-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
+**Time:** 20-30 minutes | **Difficulty:** Intermediate to Advanced
 
 ## 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  │
-└─────────────┘
+Basic → Hybrid Search → Rate Limiting → Knowledge Base → Advanced 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
+| Pattern              | Metadata Structure                                 | Use Case              |
+| -------------------- | -------------------------------------------------- | --------------------- |
+| Content Organization | `category`, `topic`, `author`, `date`              | Blogs, docs, articles |
+| E-commerce           | `category`, `price`, `rating`, `in_stock`, `brand` | Product catalogs      |
+| Access Control       | `visibility`, `department`, `sensitivity`          | Enterprise knowledge  |
+| Temporal Data        | `created_at`, `updated_at`, `status`, `version`    | Versioned content     |
 
-### 4. Test Searches
+## Tips
 
-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"
-```
+1. **Start Small** - Test with 5-10 documents before scaling
+2. **Design Metadata First** - Plan fields, types, and filters
+3. **Use Consistent IDs** - Choose a scheme (sequential, prefixed, semantic, UUIDs)
+4. **Test Searches** - Validate semantic matching and filters
+5. **Clean Up** - Delete test collections when done
 
 ## 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
+| Issue                  | Solution                                            |
+| ---------------------- | --------------------------------------------------- |
+| Collection exists      | `Delete collection "name"` then recreate            |
+| No search results      | Check collection has documents, try without filters |
+| Unexpected results     | Validate metadata and filter syntax                 |
+| "Collection not found" | Create collection first                             |
+| "Bad Request"          | Check filter JSON syntax                            |
+| API errors             | Verify 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
+1. Review [main README](../README.md) for full tool documentation
+2. Apply patterns to your own use cases
+3. Explore advanced features and configurations
+4. Share your examples via [CONTRIBUTING.md](../CONTRIBUTING.md)
 
 ## 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)
+- [OpenAI Embeddings](https://platform.openai.com/docs/guides/embeddings)
+- [Cohere Embeddings](https://docs.cohere.com/docs/embeddings)
+- [Voyage AI](https://docs.voyageai.com/)
+- [Ollama](https://ollama.ai/docs)
 - [Model Context Protocol](https://modelcontextprotocol.io/)
-- [Main Project README](../README.md)

package/examples/basic/README.md

@@ -1,94 +1,39 @@
-# Basic Usage Example
+# Basic Usage
 
-This example demonstrates the fundamental operations of the Qdrant MCP Server.
+Learn fundamental operations: create collections, add documents, search, and manage resources.
 
-## What You'll Learn
+**Time:** 5-10 minutes | **Difficulty:** Beginner
 
-- 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
+## Workflow
 
 ```
+# 1. Create 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
-
-```
+# 2. Add documents (auto-embedded with Ollama)
 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
 
-```
+# 3. Search
 Search basic-example for "AI and computer programs"
-```
+# Expected: Doc 2 ranks highest (ML/AI), Doc 3 lower (programming)
 
-Expected results:
-
-- Document 2 (ML/AI) should rank highest
-- Document 3 (Python/programming) may appear with lower score
-
-### 4. Get Collection Information
-
-```
+# 4. Get info
 Get info about "basic-example" collection
-```
-
-Returns:
-
-- Vector dimensions
-- Number of documents
-- Distance metric used
 
-### 5. View All Collections
-
-```
+# 5. List all
 List all collections
-```
-
-Shows all available collections in your Qdrant instance.
 
-### 6. Delete Documents (Optional)
-
-```
+# 6. Delete documents (optional)
 Delete documents [1, 3] from basic-example
-```
-
-Removes specific documents by ID.
 
-### 7. Clean Up
-
-```
+# 7. Clean up
 Delete collection "basic-example"
 ```
 
-Removes the collection and all its data.
-
-## Try It Yourself
-
-Copy these commands into Claude Code:
+## Try It
 
 ```
 Create a collection named "my-first-collection"
@@ -100,12 +45,14 @@ Add these documents to my-first-collection:
 
 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
+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