{"id":29224755,"url":"https://github.com/triepod-ai/mcp-server-qdrant-enhanced","last_synced_at":"2025-07-03T06:07:53.640Z","repository":{"id":302536133,"uuid":"1012169263","full_name":"triepod-ai/mcp-server-qdrant-enhanced","owner":"triepod-ai","description":"Enhanced Qdrant MCP Server is a production-ready fork of the original that transforms the basic MCP server into an enterprise-grade solution with GPU acceleration, multi-vector support, and automated deployment infrastructure. ","archived":false,"fork":false,"pushed_at":"2025-07-02T22:24:20.000Z","size":300,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-02T23:27:48.777Z","etag":null,"topics":["cuda-support","docker","mcp-server","mcp-tools","qdrant-vector-database","storage","vectorization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/triepod-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-01T23:40:14.000Z","updated_at":"2025-07-02T22:51:03.000Z","dependencies_parsed_at":"2025-07-02T23:38:06.330Z","dependency_job_id":null,"html_url":"https://github.com/triepod-ai/mcp-server-qdrant-enhanced","commit_stats":null,"previous_names":["triepod-ai/mcp-server-qdrant-enhanced"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/triepod-ai/mcp-server-qdrant-enhanced","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triepod-ai%2Fmcp-server-qdrant-enhanced","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triepod-ai%2Fmcp-server-qdrant-enhanced/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triepod-ai%2Fmcp-server-qdrant-enhanced/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triepod-ai%2Fmcp-server-qdrant-enhanced/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/triepod-ai","download_url":"https://codeload.github.com/triepod-ai/mcp-server-qdrant-enhanced/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triepod-ai%2Fmcp-server-qdrant-enhanced/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263271499,"owners_count":23440396,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cuda-support","docker","mcp-server","mcp-tools","qdrant-vector-database","storage","vectorization"],"created_at":"2025-07-03T06:07:53.151Z","updated_at":"2025-07-03T06:07:53.611Z","avatar_url":"https://github.com/triepod-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Enhanced Qdrant MCP Server\n\n[![NPM Package](https://img.shields.io/npm/v/@triepod-ai/mcp-server-qdrant-enhanced)](https://www.npmjs.com/package/@triepod-ai/mcp-server-qdrant-enhanced)\n[![Docker Image](https://img.shields.io/docker/v/triepod-ai/mcp-server-qdrant-enhanced?label=docker)](https://github.com/triepod-ai/mcp-server-qdrant-enhanced/pkgs/container/mcp-server-qdrant-enhanced)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![GitHub Actions](https://github.com/triepod-ai/mcp-server-qdrant-enhanced/workflows/Build%20and%20Publish/badge.svg)](https://github.com/triepod-ai/mcp-server-qdrant-enhanced/actions)\n\n\u003e **🚀 Production-Ready Enhancement** of the original [mcp-server-qdrant](https://github.com/modelcontextprotocol/mcp-server-qdrant) with GPU acceleration, multi-vector support, and enterprise-grade deployment infrastructure.\n\n**Enhanced Model Context Protocol server** for [Qdrant](https://qdrant.tech/) vector database with advanced features including GPU acceleration, collection-specific embedding models, and production deployment automation.\n\n## 🌟 Why This Enhanced Version?\n\nThis fork transforms the basic MCP server into a **production-ready solution** with:\n\n- **🚀 10x Performance**: GPU acceleration with FastEmbed and CUDA support\n- **🧠 Smart Model Selection**: Automatic 384D/768D/1024D embedding selection based on collection type  \n- **🐳 Production Infrastructure**: Complete Docker automation with 4.49GB optimized containers\n- **📦 Dual Installation**: NPM package + Docker options for maximum accessibility\n- **⚡ Zero-Config Setup**: Interactive installer with platform detection\n- **🔄 48 Production Collections**: Battle-tested with real workloads\n\n## Overview\n\nAn enhanced Model Context Protocol server for keeping and retrieving memories in the Qdrant vector search engine with **structured data returns**, **TypeScript-inspired type validation**, **collection-specific embedding models**, and **optimized 768D career collections**.\n\n### ✨ Enhanced Features\n\n- **🎯 Structured Data Returns**: JSON objects instead of formatted strings for better programmatic access\n- **🛡️ Type Safety**: TypeScript-inspired type guards and comprehensive validation\n- **📊 Score-Based Filtering**: Relevance thresholds and result ranking\n- **🔄 Retry Logic**: Exponential backoff for robust error handling\n- **🎨 Multi-Vector Support**: Collection-specific embedding models (384D/768D/1024D)\n- **⚡ Enhanced Performance**: Optimized search with connection management\n- **🚀 768D Career Collections**: Migrated career collections using BGE-Base models for superior semantic understanding\n- **🔒 Safe Migration**: Zero data loss migration with comprehensive backup strategies\n\n## 🚀 Quick Start\n\nGet up and running with the Enhanced Qdrant MCP Server in under 2 minutes! Choose your preferred installation method:\n\n### 🎯 One-Command Setup (Recommended)\n\nThe easiest way to get started - interactive setup that guides you through the entire process:\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/triepod-ai/mcp-server-qdrant-enhanced/main/setup-qdrant-enhanced.sh | bash\n```\n\nThis script will:\n- ✅ Detect your platform and requirements  \n- ✅ Let you choose between NPM or Docker installation\n- ✅ Configure Qdrant connection settings\n- ✅ Generate MCP client configurations (Claude Desktop, VS Code)\n- ✅ Test your setup and validate connectivity\n\n### 📦 Option 1: NPM Package (Development)\n\nPerfect for developers who want direct command access and easy integration:\n\n```bash\n# Install globally\nnpm install -g @triepod-ai/mcp-server-qdrant-enhanced\n\n# Verify installation\nmcp-server-qdrant-enhanced --help\n\n# Quick test (requires running Qdrant instance)\nQDRANT_URL=\"http://localhost:6333\" COLLECTION_NAME=\"test\" mcp-server-qdrant-enhanced --transport stdio\n```\n\n**Requirements:** Node.js 18+, Python 3.10+, running Qdrant instance\n\n### 🐳 Option 2: Docker Container (Production)\n\nComplete isolation with all dependencies and models pre-installed:\n\n```bash\n# Pull the pre-built image (4.49GB with embedded models)\ndocker pull ghcr.io/triepod-ai/mcp-server-qdrant-enhanced:latest\n\n# Quick run with host networking\ndocker run -it --rm --network host \\\n  -e QDRANT_URL=\"http://localhost:6333\" \\\n  -e COLLECTION_NAME=\"enhanced-collection\" \\\n  ghcr.io/triepod-ai/mcp-server-qdrant-enhanced:latest\n\n# Or use Docker Compose for persistent setup\ncurl -sSL https://raw.githubusercontent.com/triepod-ai/mcp-server-qdrant-enhanced/main/docker-compose.yml -o docker-compose.yml\ndocker-compose up -d\n```\n\n**Requirements:** Docker, running Qdrant instance\n\n### ⚡ What You Get\n\nAfter installation, you'll have access to:\n\n- **🎯 Enhanced MCP Tools**: `qdrant-store`, `qdrant-find`, `qdrant-list-collections`, etc.\n- **🧠 Smart Model Selection**: Automatic 384D/768D/1024D model selection based on collection type\n- **🚀 GPU Acceleration**: FastEmbed with CUDA support for lightning-fast embeddings\n- **📊 Production Collections**: 48 pre-configured collection types with optimal model mappings\n- **🔄 Zero-Config Operation**: Works out of the box with sensible defaults\n\n### 🔧 Quick Integration\n\nAdd to your MCP client configuration:\n\n**Claude Desktop** (`claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"qdrant-enhanced\": {\n      \"command\": \"mcp-server-qdrant-enhanced\",\n      \"args\": [\"--transport\", \"stdio\"],\n      \"env\": {\n        \"QDRANT_URL\": \"http://localhost:6333\",\n        \"COLLECTION_NAME\": \"your-collection\"\n      }\n    }\n  }\n}\n```\n\n**Need help?** The setup script generates these configurations automatically! 🎊\n\n---\n\n## Components\n\n### Tools\n\n1. `qdrant-store`\n   - Store information with automatic collection-specific embedding model selection\n   - Input:\n     - `information` (string): Information to store\n     - `metadata` (JSON): Optional metadata to store with validation\n     - `collection_name` (string): Collection name (required if no default)\n   - Returns: Confirmation with model info (`\"Stored in collection using model (dimensions): content\"`)\n\n2. `qdrant-find` **[Enhanced with Structured Returns]**\n   - Retrieve relevant information with structured results and filtering\n   - Input:\n     - `query` (string): Search query with automatic sanitization\n     - `collection_name` (string): Collection name (required if no default)\n     - `limit` (integer, optional): Maximum results to return (default: 10)\n     - `score_threshold` (float, optional): Minimum relevance score (default: 0.0)\n   - Returns: **Structured JSON response**:\n     ```json\n     {\n       \"query\": \"search terms\",\n       \"collection\": \"collection_name\",\n       \"results\": [\n         {\n           \"content\": \"document content\",\n           \"score\": 0.95,\n           \"metadata\": {\"key\": \"value\"},\n           \"collection\": \"collection_name\", \n           \"vector_model\": \"bge-large-en-v1.5\"\n         }\n       ],\n       \"total_found\": 1,\n       \"search_params\": {\"limit\": 10, \"score_threshold\": 0.0},\n       \"timestamp\": \"2025-01-15T10:30:00Z\"\n     }\n     ```\n\n3. `qdrant-list-collections` **[New]**\n   - List all collections with configuration details\n   - Returns: Formatted collection info with vector dimensions and models\n\n4. `qdrant-collection-info` **[New]**\n   - Get detailed information about a specific collection\n   - Input: `collection_name` (string)\n   - Returns: Comprehensive collection details including optimization status\n\n5. `qdrant-model-mappings` **[New]**\n   - Show current collection-to-model mappings and available configurations\n   - Returns: Model mapping configuration and available options\n\n## 🎯 Collection-Specific Embedding Models\n\nThis server automatically selects optimal embedding models based on collection names:\n\n### 🏆 Career Collections (768D BGE-Base Models)\n- **`resume_projects`**: Portfolio and resume content using BAAI/bge-base-en (768D)\n- **`job_search`**: Job applications and career materials using BAAI/bge-base-en (768D)  \n- **`mcp-optimization-knowledge`**: Technical optimization knowledge using BAAI/bge-base-en (768D)\n- **`project_achievements`**: Career accomplishments using BAAI/bge-base-en (768D)\n\n### 🔬 Legal \u0026 Workplace (1024D BGE-Large Models)\n- **`legal_analysis`**: Complex legal content using BAAI/bge-large-en-v1.5 (1024D)\n- **`workplace_documentation`**: Business and workplace docs using BAAI/bge-base-en-v1.5 (768D)\n\n### ⚡ Technical Collections (384D MiniLM Models)\n- **`working_solutions`**: Quick technical solutions using sentence-transformers/all-MiniLM-L6-v2 (384D)\n- **`debugging_patterns`**: Debug patterns using sentence-transformers/all-MiniLM-L6-v2 (384D)\n- **`troubleshooting`**: General troubleshooting and technical issues using sentence-transformers/all-MiniLM-L6-v2 (384D)\n- **Default collections**: Use 384D MiniLM for speed and efficiency\n\n### 📊 Search Quality Improvements\nRecent migration to optimized models achieved **0.75-0.82 search scores** for career content, representing significant quality improvements over generic embeddings.\n\n## 🚀 Migration from Legacy Version\n\n**Breaking Change Notice**: The `qdrant-find` tool now returns structured JSON instead of formatted strings.\n\n### Quick Migration Guide\n\n**Before (Legacy)**:\n```python\nresults = await qdrant_find(ctx, \"query\", \"collection\")\n# Returns: [\"Results for query 'query'\", \"\u003centry\u003e\u003ccontent\u003e...\u003c/content\u003e\u003c/entry\u003e\"]\n```\n\n**After (Enhanced)**:\n```python\nresponse = await qdrant_find(ctx, \"query\", \"collection\", score_threshold=0.7)\n# Returns: {\"query\": \"query\", \"results\": [{\"content\": \"...\", \"score\": 0.95, ...}], ...}\n\n# Direct access to structured data\nfor result in response[\"results\"]:\n    content = result[\"content\"]\n    score = result[\"score\"] \n    metadata = result[\"metadata\"]\n```\n\n📖 **[Complete Migration Guide](docs/MIGRATION_GUIDE.md)** | 💡 **[Usage Examples](examples/enhanced_usage.py)**\n\n## 🏆 What Makes This Enhancement Special\n\n### ✅ Enterprise-Grade Performance\n- **GPU Acceleration**: FastEmbed with CUDA support for 10x faster embedding generation\n- **Smart Model Selection**: Collection-specific routing to optimal 384D/768D/1024D models\n- **Quantization Optimized**: 40% memory reduction while maintaining search quality\n- **Production Validated**: Sub-second response times across 48 active collections\n\n### 🔧 Advanced Architecture\n- **Separation of Concerns**: MCP server (4.49GB with models) + Qdrant DB (279MB storage)\n- **Multi-Vector Support**: Automatic model selection based on collection naming patterns\n- **Zero-Config Deployment**: Interactive setup with platform detection and validation\n- **CI/CD Automation**: GitHub Actions with multi-architecture builds and security scanning\n\n### 📊 Real-World Results\n- **Search Quality**: Achieved 0.75-0.82 scores for career content (major improvement over generic embeddings)\n- **Production Scale**: 48 active collections with zero data loss migrations\n- **Developer Experience**: One-command setup, dual installation methods, comprehensive documentation\n\n## Environment Variables\n\nThe configuration of the server is done using environment variables:\n\n| Name                          | Description                                                         | Default Value                                                     |\n|-------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|\n| `QDRANT_URL`                  | URL of the Qdrant server                                            | None                                                              |\n| `QDRANT_API_KEY`              | API key for the Qdrant server                                       | None                                                              |\n| `COLLECTION_NAME`             | Name of the default collection to use                               | None                                                              |\n| `QDRANT_LOCAL_PATH`           | Path to the local Qdrant database (alternative to `QDRANT_URL`)     | None                                                              |\n| `EMBEDDING_PROVIDER`          | Embedding provider to use (currently only \"fastembed\" is supported) | `fastembed`                                                       |\n| `EMBEDDING_MODEL`             | Name of the embedding model to use (overridden by collection mappings) | `sentence-transformers/all-MiniLM-L6-v2`                          |\n| `QDRANT_AUTO_CREATE_COLLECTIONS` | **[Enhanced]** Auto-create collections with optimal settings    | `true`                                                            |\n| `QDRANT_ENABLE_QUANTIZATION`  | **[Enhanced]** Enable vector quantization for memory optimization   | `true`                                                            |\n| `COLLECTION_MODEL_MAPPINGS`   | **[Enhanced]** JSON mapping of collections to specific embedding models | Auto-configured based on collection names                         |\n| `QDRANT_SEARCH_LIMIT`         | **[Enhanced]** Default maximum search results                       | `10`                                                              |\n| `QDRANT_HNSW_EF_CONSTRUCT`    | **[Enhanced]** HNSW ef_construct parameter                          | `128`                                                             |\n| `QDRANT_HNSW_M`               | **[Enhanced]** HNSW M parameter                                     | `16`                                                              |\n| `TOOL_STORE_DESCRIPTION`      | Custom description for the store tool                               | See default in [`settings.py`](src/mcp_server_qdrant/settings.py) |\n| `TOOL_FIND_DESCRIPTION`       | Custom description for the find tool                                | See default in [`settings.py`](src/mcp_server_qdrant/settings.py) |\n\nNote: You cannot provide both `QDRANT_URL` and `QDRANT_LOCAL_PATH` at the same time.\n\n\u003e [!IMPORTANT]\n\u003e Command-line arguments are not supported anymore! Please use environment variables for all configuration.\n\n## Installation Options\n\n\u003e **⚡ Quick Setup Available!** For the fastest installation experience, see the [Quick Start](#-quick-start) section above which includes both NPM and Docker options with automated setup.\n\n### Enhanced Installation Methods\n\nThis enhanced fork offers multiple installation paths optimized for different use cases:\n\n1. **🎯 [Interactive Setup Script](#-one-command-setup-recommended)** - One command, fully guided setup\n2. **📦 [NPM Package](#-option-1-npm-package-development)** - Perfect for development and easy integration  \n3. **🐳 [Docker Container](#-option-2-docker-container-production)** - Production-ready with embedded models\n\n### Traditional Docker Compose Setup\n\nFor users who prefer manual Docker Compose configuration without the automated setup:\n\n**Prerequisites:**\n- Docker and Docker Compose installed.\n- An existing Qdrant instance (either local or remote).\n\n**Configuration:**\n    *   Create a `.env` file to manage environment variables:\n\n        ```dotenv\n        # .env file\n        QDRANT_URL=http://host.docker.internal:6333\n        COLLECTION_NAME=my-collection\n        MCP_TRANSPORT=sse\n        HOST_PORT=8002\n        # QDRANT_API_KEY=YOUR_API_KEY # Uncomment and set if your Qdrant requires authentication\n        # EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2 # Optional: Overrides the default model\n        ```\n\n    **Important**: Use `host.docker.internal:6333` instead of `localhost:6333` for Docker networking.\n\n3.  **Platform-specific Setup:**\n\n    **Windows/macOS (Docker Desktop):**\n    ```bash\n    docker-compose up -d\n    ```\n\n    **Linux (host networking):**\n    ```bash\n    docker-compose -f docker-compose.linux.yml up -d\n    ```\n\n4.  **Testing the Deployment:**\n    ```bash\n    ./test-docker-deployment.sh\n    ```\n\n5.  **Stopping the Server:**\n    ```bash\n    docker-compose down\n    ```\n\n### Installing via Smithery\n\nTo install Qdrant MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/protocol/mcp-server-qdrant):\n\n```bash\nnpx @smithery/cli install mcp-server-qdrant --client claude\n```\n\n### Manual configuration of Claude Desktop\n\nTo use this server with the Claude Desktop app, add the following configuration to the \"mcpServers\" section of your\n`claude_desktop_config.json`:\n\n#### Docker Deployment (Recommended)\n\nAfter running the enhanced setup script, use this configuration:\n\n```json\n{\n  \"qdrant-enhanced\": {\n    \"command\": \"mcp-server-qdrant-enhanced\",\n    \"args\": [\"--transport\", \"stdio\"],\n    \"env\": {\n      \"QDRANT_URL\": \"http://localhost:6333\",\n      \"COLLECTION_NAME\": \"your-collection\"\n    }\n  }\n}\n```\n\n#### Legacy uvx Deployment (Deprecated)\n\n```json\n{\n  \"qdrant\": {\n    \"command\": \"uvx\",\n    \"args\": [\"mcp-server-qdrant\"],\n    \"env\": {\n      \"QDRANT_URL\": \"http://localhost:6333\",\n      \"COLLECTION_NAME\": \"my-collection\",\n      \"MCP_TRANSPORT\": \"sse\"\n    }\n  }\n}\n```\n\n\u003e [!NOTE]\n\u003e Some MCP clients (like Windsurf, Claude Desktop, or certain VS Code configurations) may require a `command` entry in their settings and might not support connecting directly to a running container via `sseUrl` alone. In such cases, using `uvx` as a proxy is necessary. Ensure the `env` block within the client configuration correctly sets `MCP_TRANSPORT: \"sse\"` for the `uvx` process, and the client's `transportType` is also set to `\"sse\"`. Example:\n\u003e ```json\n\u003e // In cline_mcp_settings.json or claude_desktop_config.json\n\u003e \"qdrant-via-uvx\": {\n\u003e   \"command\": \"uvx\",\n\u003e   \"args\": [ \"mcp-server-qdrant\" ],\n\u003e   \"env\": {\n\u003e     \"QDRANT_URL\": \"http://localhost:6333\", // Or your Qdrant URL\n\u003e     \"COLLECTION_NAME\": \"my-collection\",    // Your collection name\n\u003e     \"MCP_TRANSPORT\": \"sse\"                 // Instruct uvx process\n\u003e     // \"QDRANT_API_KEY\": \"YOUR_API_KEY\",   // Add if needed\n\u003e   },\n\u003e   \"transportType\": \"sse\",                  // Instruct client\n\u003e   \"disabled\": false,\n\u003e   \"autoApprove\": []\n\u003e }\n\u003e ```\n\nFor local Qdrant mode:\n\n```json\n{\n  \"qdrant\": {\n    // NOTE: Configuration below assumes direct uvx execution, which is deprecated.\n    // Please refer to the 'Installation and Running with Docker Compose' section\n    // and configure your MCP client accordingly. Local path mode is generally\n    // not applicable with the standard Docker Compose setup.\n    // Example using uvx (deprecated):\n    // \"command\": \"uvx\",\n    // \"args\": [\"mcp-server-qdrant\", \"--transport\", \"stdio\"], // Stdio might work locally but SSE is preferred\n    // \"env\": {\n    //  \"QDRANT_LOCAL_PATH\": \"/path/to/qdrant/database\",\n      \"COLLECTION_NAME\": \"your-collection-name\",\n      \"EMBEDDING_MODEL\": \"sentence-transformers/all-MiniLM-L6-v2\"\n    }\n  }\n}\n```\n\nThis MCP server will automatically create a collection with the specified name if it doesn't exist.\n\nThe server automatically selects optimal embedding models based on collection names:\n- **Career collections** use 768D BGE-Base models for superior semantic understanding\n- **Legal/complex content** uses 1024D BGE-Large models for maximum precision  \n- **Technical/debug content** uses 384D MiniLM models for speed and efficiency\n- **Default collections** fall back to `sentence-transformers/all-MiniLM-L6-v2`\n\nOnly [FastEmbed](https://qdrant.github.io/fastembed/) models are currently supported.\n\n## Support for other tools\n\nThis MCP server can be used with any MCP-compatible client. For example, you can use it with\n[Cursor](https://docs.cursor.com/context/model-context-protocol) and [VS Code](https://code.visualstudio.com/docs), which provide built-in support for the Model Context\nProtocol.\n\n### Using with Cursor/Windsurf\n\nYou can configure this MCP server to work as a code search tool for Cursor or Windsurf by customizing the tool\ndescriptions:\n\n```bash\nQDRANT_URL=\"http://localhost:6333\" \\\nCOLLECTION_NAME=\"code-snippets\" \\\nTOOL_STORE_DESCRIPTION=\"Store reusable code snippets for later retrieval. \\\nThe 'information' parameter should contain a natural language description of what the code does, \\\nwhile the actual code should be included in the 'metadata' parameter as a 'code' property. \\\nThe value of 'metadata' is a Python dictionary with strings as keys. \\\nUse this whenever you generate some code snippet.\" \\\nTOOL_FIND_DESCRIPTION=\"Search for relevant code snippets based on natural language descriptions. The 'query' parameter should describe what you're looking for, and the tool will return the most relevant code snippets. Use this when you need to find existing code snippets for reuse or reference.\"\n# Make sure the server is running via `docker compose up -d`\n```\n\nIn Cursor/Windsurf, you can configure the MCP server in your settings. Connect to the running Docker container using the SSE transport protocol. The setup process is detailed in the [Cursor documentation](https://docs.cursor.com/context/model-context-protocol#adding-an-mcp-server-to-cursor). If the container is running locally and port `8002` is mapped (as per the `docker-compose.yml`), use this URL:\n\n```\nhttp://localhost:8002/sse\n```\n\n\u003e [!TIP]\n\u003e We suggest SSE transport as a preferred way to connect Cursor/Windsurf to the MCP server, as it can support remote\n\u003e connections. That makes it easy to share the server with your team or use it in a cloud environment.\n\nThis configuration transforms the Qdrant MCP server into a specialized code search tool that can:\n\n1. Store code snippets, documentation, and implementation details\n2. Retrieve relevant code examples based on semantic search\n3. Help developers find specific implementations or usage patterns\n\nYou can populate the database by storing natural language descriptions of code snippets (in the `information` parameter)\nalong with the actual code (in the `metadata.code` property), and then search for them using natural language queries\nthat describe what you're looking for.\n\n\u003e [!NOTE]\n\u003e The tool descriptions provided above are examples and may need to be customized for your specific use case. Consider\n\u003e adjusting the descriptions to better match your team's workflow and the specific types of code snippets you want to\n\u003e store and retrieve.\n\n**If you have successfully installed the `mcp-server-qdrant`, but still can't get it to work with Cursor, please\nconsider creating the [Cursor rules](https://docs.cursor.com/context/rules-for-ai) so the MCP tools are always used when\nthe agent produces a new code snippet.** You can restrict the rules to only work for certain file types, to avoid using\nthe MCP server for the documentation or other types of content.\n\n### Using with Claude Code\n\nYou can enhance Claude Code's capabilities by connecting it to this MCP server, enabling semantic search over your\nexisting codebase.\n\n#### Setting up mcp-server-qdrant\n\n1. Add the MCP server to Claude Code:\n\n    ```shell\n    # Add mcp-server-qdrant configured for code search\n    claude mcp add code-search \\\n    -e QDRANT_URL=\"http://localhost:6333\" \\\n    -e COLLECTION_NAME=\"code-repository\" \\\n    -e EMBEDDING_MODEL=\"sentence-transformers/all-MiniLM-L6-v2\" \\\n    -e TOOL_STORE_DESCRIPTION=\"Store code snippets with descriptions. The 'information' parameter should contain a natural language description of what the code does, while the actual code should be included in the 'metadata' parameter as a 'code' property.\" \\\n    -e TOOL_FIND_DESCRIPTION=\"Search for relevant code snippets using natural language. The 'query' parameter should describe the functionality you're looking for.\" \\\n    # NOTE: The `claude mcp add` command shown uses uvx directly, which is deprecated.\n    # Adapt this for your Docker Compose setup. You might configure Claude Code\n    # to connect directly to the running container's SSE endpoint\n    # (e.g., http://localhost:8002/sse) if Claude Code supports that,\n    # or use a tool like docker-mcp within Claude Code's MCP settings\n    # to manage the Docker Compose lifecycle.\n    # Example Connection (Conceptual - check Claude Code docs for specifics):\n    # claude mcp add code-search-docker --transport sse --sse-url http://localhost:8002/sse\n    ```\n\n2. Verify the server was added:\n\n    ```shell\n    claude mcp list\n    ```\n\n#### Using Semantic Code Search in Claude Code\n\nTool descriptions, specified in `TOOL_STORE_DESCRIPTION` and `TOOL_FIND_DESCRIPTION`, guide Claude Code on how to use\nthe MCP server. The ones provided above are examples and may need to be customized for your specific use case. However,\nClaude Code should be already able to:\n\n1. Use the `qdrant-store` tool to store code snippets with descriptions.\n2. Use the `qdrant-find` tool to search for relevant code snippets using natural language.\n\n### Run MCP server in Development Mode\n\nThe MCP server can be run in development mode using the `mcp dev` command. This will start the server and open the MCP\ninspector in your browser.\n\n```shell\nCOLLECTION_NAME=mcp-dev mcp dev src/mcp_server_qdrant/server.py\n```\n\n### Using with VS Code\n\n\u003c!-- Installation buttons using deprecated methods (uvx, docker run) have been removed. --\u003e\n\u003c!-- Please refer to the Docker Compose instructions above. --\u003e\n\n#### Manual Installation\n\nAdd the following JSON block to your User Settings (`settings.json`) or Workspace Settings (`.vscode/settings.json`) file in VS Code.\n\n**Recommended Method: Using `docker-mcp` (Requires `docker-mcp` server)**\n\nThis method uses the `docker-mcp` server to manage the Docker Compose lifecycle.\n\n```json\n// In your main MCP settings file (e.g., cline_mcp_settings.json)\n// Ensure docker-mcp server is configured first.\n{\n  \"mcpServers\": {\n    // ... other servers ...\n    \"docker-managed-qdrant\": {\n      \"command\": \"docker-mcp\", // Use the docker-mcp server\n      \"args\": [\n        \"deploy-compose\",\n        \"--project-name\", \"mcp-qdrant\",\n        \"--compose-yaml\", \"l:/ToolNexusMCP_plugins/mcp-server-qdrant/docker-compose.yml\" // Adjust path if needed\n        // Environment variables are handled by docker-compose.yml and .env file\n      ],\n      \"transportType\": \"stdio\" // docker-mcp uses stdio\n    }\n    // Note: The actual qdrant server tools will be exposed via the container's connection,\n    // usually SSE on http://localhost:8002/sse. The docker-mcp entry above just manages deployment.\n    // You might need a separate entry to connect to the service itself, or the client\n    // might automatically detect it if using a standard discovery mechanism.\n  }\n}\n\n// Alternatively, configure VS Code to connect directly via SSE:\n{\n  \"mcp\": {\n    \"servers\": {\n      \"qdrant-sse\": {\n        \"transportType\": \"sse\",\n        \"sseUrl\": \"http://localhost:8002/sse\"\n        // Assumes the container is running independently (e.g., via `docker compose up -d`)\n      }\n    }\n  }\n}\n```\n\n**(Deprecated Examples Below - For Reference Only)**\n\n```json\n// DEPRECATED Example using uvx:\n// {\n//   \"mcp\": {\n//     \"inputs\": [ /* ... define inputs if needed ... */ ],\n//     \"servers\": {\n//       \"qdrant-uvx-deprecated\": {\n//         \"command\": \"uvx\",\n//         \"args\": [\"mcp-server-qdrant\", \"--transport\", \"sse\"], // Use SSE\n//         \"env\": {\n//           \"QDRANT_URL\": \"${input:qdrantUrl}\", // Requires inputs defined\n//           \"QDRANT_API_KEY\": \"${input:qdrantApiKey}\",\n//           \"COLLECTION_NAME\": \"${input:collectionName}\"\n//         }\n//       }\n//     }\n//   }\n// }\n```\n\n```json\n// DEPRECATED Example using docker run:\n// {\n//   \"mcp\": {\n//     \"inputs\": [ /* ... define inputs if needed ... */ ],\n//     \"servers\": {\n//       \"qdrant-docker-run-deprecated\": {\n//         \"command\": \"docker\",\n//         \"args\": [\n//           \"run\",\n//           \"-p\", \"8002:8000\", // Use updated port mapping\n//           \"-i\",\n//           \"--rm\", // Consider removing --rm if you want to reuse the container\n//           \"--network\", \"chroma-mcp_chroma-memory-network\", // Example network\n//           \"-e\", \"QDRANT_URL=${input:qdrantUrl}\", // Pass env vars directly\n//           \"-e\", \"QDRANT_API_KEY=${input:qdrantApiKey}\",\n//           \"-e\", \"COLLECTION_NAME=${input:collectionName}\",\n//           \"mcp-server-qdrant:latest\" // Assumes image is built/pulled with 'latest' tag\n//         ],\n//         // Env here might be redundant if passed in args\n//         \"env\": {}\n//       }\n//     }\n//   }\n// }\n```\n\n\u003e [!NOTE]\n\u003e The VS Code examples above primarily use deprecated `uvx` or `docker run` methods directly within the VS Code settings. For setups using **Docker Compose** (as recommended earlier), connecting VS Code typically involves either:\n\u003e 1.  **Direct SSE Connection:** If your VS Code MCP extension supports it, configure it to connect directly to the running container's mapped SSE port (e.g., `http://localhost:8002/sse` if using the provided `docker-compose.yml`). This might look like the \"Alternatively\" example under the `docker-mcp` section but ensure your extension supports the `sseUrl` field directly.\n\u003e 2.  **`docker-mcp`:** Use the `docker-mcp` server to manage the compose lifecycle (as shown in the \"Recommended Method\"). The connection to the actual tools would still happen via SSE, either automatically detected or configured separately.\n\u003e 3.  **`uvx` as Proxy (if direct SSE fails):** If direct SSE connection isn't supported by your VS Code client setup, use the `uvx` method similar to the configuration shown in the note under \"Manual configuration of Claude Desktop\", ensuring `env.MCP_TRANSPORT` and `transportType` are both `sse`.\n\n## 🤝 Contributing\n\nWe welcome contributions to the Enhanced Qdrant MCP Server! This project demonstrates how to enhance open-source projects with enterprise-grade features.\n\n### 🚀 Getting Started\n\n1. **Fork and Clone**:\n   ```bash\n   git clone https://github.com/triepod-ai/mcp-server-qdrant-enhanced.git\n   cd mcp-server-qdrant-enhanced\n   ```\n\n2. **Development Setup**:\n   ```bash\n   # Quick development environment\n   ./dev setup\n   \n   # Or manual setup\n   make dev-setup\n   ```\n\n3. **Development Workflow**:\n   ```bash\n   ./dev start     # Start server (preserves existing workflow)\n   ./dev dev       # Development mode with live reloading  \n   ./dev test      # Run tests and validation\n   ./dev lint      # Run linting and formatting\n   ```\n\n### 💡 Contribution Areas\n\n- **Performance Optimizations**: GPU acceleration, quantization improvements\n- **Model Integration**: New embedding models, collection-specific optimizations\n- **Deployment Automation**: CI/CD enhancements, installation methods\n- **Documentation**: Usage examples, migration guides, tutorials\n- **Testing**: Unit tests, integration tests, performance benchmarks\n\n### 🔧 Development Tools\n\nThis project includes comprehensive development tools while preserving the original workflow:\n\n- **Makefile**: Standard development commands (`make start`, `make test`, `make lint`)\n- **Development Scripts**: `./dev` entry point for common tasks\n- **Docker Development**: Live-reload containers for fast iteration\n- **GitHub Actions**: Automated testing, building, and publishing\n\nIf you have suggestions for improvements or want to report a bug, please open an issue! We'd love all contributions that help make this enhanced MCP server even better.\n\n### 🧪 Testing Locally\n\n#### MCP Inspector (Recommended)\n\nUse the [MCP inspector](https://github.com/modelcontextprotocol/inspector) for interactive testing:\n\n```bash\n# Enhanced server with memory-based Qdrant\nQDRANT_URL=\":memory:\" COLLECTION_NAME=\"test\" \\\nmcp dev src/mcp_server_qdrant/enhanced_main.py\n\n# Open browser to http://localhost:5173\n```\n\n#### Quick Development Testing\n\n```bash\n# Start development environment\n./dev dev\n\n# Run quick validation\n./dev quick-test\n\n# View logs\n./dev logs\n```\n\n#### Production Testing\n\n```bash\n# Test NPM package installation\nnpm install -g @triepod-ai/mcp-server-qdrant-enhanced\nmcp-server-qdrant-enhanced --help\n\n# Test Docker container\ndocker run -it --rm ghcr.io/triepod-ai/mcp-server-qdrant-enhanced:latest --help\n```\n\n## 🔒 Data Safety and Migration\n\n### Backup Strategy\n- **Automated Backups**: Comprehensive data backup before any migration operations\n- **Zero Data Loss**: All migrations performed with complete data preservation\n- **Rollback Capability**: Ability to restore previous collection configurations\n- **Timestamped Backups**: All backup data stored with timestamps for audit trails\n\n### Migration Features  \n- **Safe Collection Migration**: Migrate between different embedding models with zero downtime\n- **Model Optimization**: Automatic selection of optimal models based on content type\n- **Performance Validation**: Search quality verification after migrations\n- **Docker Integration**: Seamless configuration updates in containerized environments\n\n## 📄 License\n\nThis Enhanced Qdrant MCP Server is licensed under the Apache License 2.0. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the Apache License 2.0. \n\nFor more details, please see the [LICENSE](LICENSE) file in the project repository.\n\n## 🙏 Acknowledgments\n\n- **Original Project**: Built upon the excellent foundation of [mcp-server-qdrant](https://github.com/modelcontextprotocol/mcp-server-qdrant)\n- **Qdrant Team**: For the powerful vector database that makes this possible\n- **FastEmbed**: For GPU-accelerated embedding generation\n- **Model Context Protocol**: For the standardized framework enabling LLM integrations\n\n## 🔗 Related Projects\n\n- **[Original mcp-server-qdrant](https://github.com/modelcontextprotocol/mcp-server-qdrant)**: The foundational MCP server this enhancement is based on\n- **[Qdrant](https://qdrant.tech/)**: The vector search engine powering the storage layer\n- **[FastEmbed](https://github.com/qdrant/fastembed)**: GPU-accelerated embedding generation library\n- **[Model Context Protocol](https://modelcontextprotocol.io/)**: The standardized protocol for LLM tool integration\n\n---\n\n**Made with ❤️ by [triepod-ai](https://github.com/triepod-ai)** | **Enhanced for Production Use** | **Star ⭐ if this helps your project!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftriepod-ai%2Fmcp-server-qdrant-enhanced","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftriepod-ai%2Fmcp-server-qdrant-enhanced","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftriepod-ai%2Fmcp-server-qdrant-enhanced/lists"}