{"id":31684548,"url":"https://github.com/mhalder/qdrant-mcp-server","last_synced_at":"2026-08-27T15:57:27.073Z","repository":{"id":318190610,"uuid":"1070298377","full_name":"mhalder/qdrant-mcp-server","owner":"mhalder","description":"MCP server for semantic search using local Qdrant vector database and OpenAI embeddings","archived":false,"fork":false,"pushed_at":"2026-06-14T15:09:24.000Z","size":949,"stargazers_count":36,"open_issues_count":6,"forks_count":24,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-08-27T14:24:18.760Z","etag":null,"topics":["claude","embeddings","mcp","model-context-protocol","openai","qdrant","semantic-search","typescript","vector-search"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mhalder.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-05T16:55:53.000Z","updated_at":"2026-08-09T20:10:48.000Z","dependencies_parsed_at":"2025-10-30T10:14:09.298Z","dependency_job_id":"08fb0526-c8c4-4245-95ba-77e3121bfa65","html_url":"https://github.com/mhalder/qdrant-mcp-server","commit_stats":null,"previous_names":["mhalder/qdrant-mcp-server"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/mhalder/qdrant-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhalder%2Fqdrant-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhalder%2Fqdrant-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhalder%2Fqdrant-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhalder%2Fqdrant-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mhalder","download_url":"https://codeload.github.com/mhalder/qdrant-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhalder%2Fqdrant-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36944064,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-22T15:14:58.755Z","status":"online","status_checked_at":"2026-08-27T02:00:07.166Z","response_time":96,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["claude","embeddings","mcp","model-context-protocol","openai","qdrant","semantic-search","typescript","vector-search"],"created_at":"2025-10-08T08:09:52.458Z","updated_at":"2026-08-27T15:57:27.067Z","avatar_url":"https://github.com/mhalder.png","language":"TypeScript","funding_links":[],"categories":["Database \u0026 Messaging Mcp Servers"],"sub_categories":[],"readme":"# Qdrant MCP Server\n\n[![CI](https://github.com/mhalder/qdrant-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/mhalder/qdrant-mcp-server/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/mhalder/qdrant-mcp-server/branch/main/graph/badge.svg)](https://codecov.io/gh/mhalder/qdrant-mcp-server)\n\nA Model Context Protocol (MCP) server providing semantic search capabilities using Qdrant vector database with multiple embedding providers.\n\n## Features\n\n- **Zero Setup**: Works out of the box with Ollama - no API keys required\n- **Privacy-First**: Local embeddings and vector storage - data never leaves your machine\n- **Code Vectorization**: Intelligent codebase indexing with AST-aware chunking and semantic code search\n- **Git History Search**: Index commit history for semantic search over past changes, fixes, and patterns\n- **Advanced Search**: Contextual search (code + git with correlations) and federated search across multiple repositories\n- **Multiple Providers**: Ollama (default), OpenAI, Cohere, and Voyage AI\n- **Hybrid Search**: Combine semantic and keyword search for better results\n- **Semantic Search**: Natural language search with metadata filtering\n- **Incremental Indexing**: Efficient updates - only re-index changed files\n- **Configurable Prompts**: Create custom prompts for guided workflows without code changes\n- **Rate Limiting**: Intelligent throttling with exponential backoff\n- **Full CRUD**: Create, search, and manage collections and documents\n- **Structured Logging**: JSON logging via Pino with configurable log levels\n- **Flexible Deployment**: Run locally (stdio) or as a remote HTTP server\n- **API Key Authentication**: Connect to secured Qdrant instances (Qdrant Cloud, self-hosted with API keys)\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 22.x or 24.x\n- Podman or Docker with Compose support\n\n### Installation\n\n```bash\n# Clone and install\ngit clone https://github.com/mhalder/qdrant-mcp-server.git\ncd qdrant-mcp-server\n\n# Node 22.x\nnpm install\n\n# Node 24.x (requires C++20 flag for native module compilation)\nCXXFLAGS='-std=c++20' npm install\n\n# Start services (choose one)\npodman compose up -d   # Using Podman\ndocker compose up -d   # Using Docker\n\n# Pull the embedding model\npodman exec ollama ollama pull nomic-embed-text  # Podman\ndocker exec ollama ollama pull nomic-embed-text  # Docker\n\n# Build\nnpm run build\n```\n\n### Configuration\n\n#### Local Setup (stdio transport)\n\n```bash\nclaude mcp add --transport stdio qdrant -- node /path/to/qdrant-mcp-server/build/index.js\n```\n\nOr add to `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"qdrant\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\"/path/to/qdrant-mcp-server/build/index.js\"]\n    }\n  }\n}\n```\n\nFor Qdrant Cloud or secured instances, add `--env QDRANT_API_KEY=your-key` or set in env config.\n\n**Try it:**\n\n```\nCreate a collection called \"notes\" and add a document about machine learning\n```\n\n**Enable example prompts:** Copy `prompts.example.json` to `prompts.json` and restart. Use `/prompt` to list available prompts.\n\n#### Remote Setup (HTTP transport)\n\n\u003e **⚠️ Security Warning**: When deploying the HTTP transport in production:\n\u003e\n\u003e - **Always** run behind a reverse proxy (nginx, Caddy) with HTTPS\n\u003e - Implement authentication/authorization at the proxy level\n\u003e - Use firewalls to restrict access to trusted networks\n\u003e - Never expose directly to the public internet without protection\n\u003e - Consider implementing rate limiting at the proxy level\n\u003e - Monitor server logs for suspicious activity\n\n**Start the server:**\n\n```bash\nTRANSPORT_MODE=http HTTP_PORT=3000 node build/index.js\n```\n\n**Option 1: Using `claude mcp add`**\n\n```bash\nclaude mcp add --transport http qdrant http://your-server:3000/mcp\n```\n\n**Option 2: Add to `~/.claude.json`**\n\n```json\n{\n  \"mcpServers\": {\n    \"qdrant\": {\n      \"type\": \"http\",\n      \"url\": \"http://your-server:3000/mcp\"\n    }\n  }\n}\n```\n\n**Using a different provider:**\n\n```json\n\"env\": {\n  \"EMBEDDING_PROVIDER\": \"openai\",  // or \"cohere\", \"voyage\"\n  \"OPENAI_API_KEY\": \"sk-...\",      // provider-specific API key\n  \"QDRANT_URL\": \"http://localhost:6333\"\n}\n```\n\nRestart after making changes.\n\nSee [Advanced Configuration](#advanced-configuration) section below for all options.\n\n## Tools\n\n### Collection Management\n\n| Tool                  | Description                                                          |\n| --------------------- | -------------------------------------------------------------------- |\n| `create_collection`   | Create collection with specified distance metric (Cosine/Euclid/Dot) |\n| `list_collections`    | List all collections                                                 |\n| `get_collection_info` | Get collection details and statistics                                |\n| `delete_collection`   | Delete collection and all documents                                  |\n\n### Document Operations\n\n| Tool               | Description                                                                   |\n| ------------------ | ----------------------------------------------------------------------------- |\n| `add_documents`    | Add documents with automatic embedding (supports string/number IDs, metadata) |\n| `semantic_search`  | Natural language search with optional metadata filtering                      |\n| `hybrid_search`    | Hybrid search combining semantic and keyword (BM25) search with RRF           |\n| `delete_documents` | Delete specific documents by ID                                               |\n\n### Code Vectorization\n\n| Tool               | Description                                                                |\n| ------------------ | -------------------------------------------------------------------------- |\n| `index_codebase`   | Index a codebase for semantic code search with AST-aware chunking          |\n| `search_code`      | Search indexed codebase using natural language queries                     |\n| `reindex_changes`  | Incrementally re-index only changed files (detects added/modified/deleted) |\n| `get_index_status` | Get indexing status and statistics for a codebase                          |\n| `clear_index`      | Delete all indexed data for a codebase                                     |\n\n### Git History\n\n| Tool                   | Description                                                              |\n| ---------------------- | ------------------------------------------------------------------------ |\n| `index_git_history`    | Index git commit history for semantic search over past changes and fixes |\n| `search_git_history`   | Search indexed git history using natural language queries                |\n| `index_new_commits`    | Incrementally index only new commits since last indexing                 |\n| `get_git_index_status` | Get indexing status and statistics for a repository's git history        |\n| `clear_git_index`      | Delete all indexed git history data for a repository                     |\n\n### Advanced Search\n\n| Tool                | Description                                                                   |\n| ------------------- | ----------------------------------------------------------------------------- |\n| `contextual_search` | Combined code + git history search with file-commit correlations              |\n| `federated_search`  | Search across multiple repositories with Reciprocal Rank Fusion (RRF) ranking |\n\n### Resources\n\n- `qdrant://collections` - List all collections\n- `qdrant://collection/{name}` - Collection details\n\n## Configurable Prompts\n\nCreate custom prompts tailored to your specific use cases without modifying code. Prompts provide guided workflows for common tasks.\n\n**Note**: By default, the server looks for `prompts.json` in the project root directory. If the file exists, prompts are automatically loaded. You can specify a custom path using the `PROMPTS_CONFIG_FILE` environment variable.\n\n### Setup\n\n1. **Create a prompts configuration file** (e.g., `prompts.json` in the project root):\n\n   See [`prompts.example.json`](prompts.example.json) for example configurations you can copy and customize.\n\n2. **Configure the server** (optional - only needed for custom path):\n\nIf you place `prompts.json` in the project root, no additional configuration is needed. To use a custom path:\n\n```json\n{\n  \"mcpServers\": {\n    \"qdrant\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/qdrant-mcp-server/build/index.js\"],\n      \"env\": {\n        \"QDRANT_URL\": \"http://localhost:6333\",\n        \"PROMPTS_CONFIG_FILE\": \"/custom/path/to/prompts.json\"\n      }\n    }\n  }\n}\n```\n\n3. **Use prompts** in your AI assistant:\n\n**Claude Code:**\n\n```bash\n/mcp__qdrant__find_similar_docs papers \"neural networks\" 10\n```\n\n**VSCode:**\n\n```bash\n/mcp.qdrant.find_similar_docs papers \"neural networks\" 10\n```\n\n### Example Prompts\n\nSee [`prompts.example.json`](prompts.example.json) for ready-to-use prompts including:\n\n- `setup_rag_collection` - Create RAG-optimized collections\n- `analyze_and_optimize` - Collection insights and recommendations\n- `compare_search_strategies` - Semantic vs hybrid search comparison\n- `migrate_to_hybrid` - Collection migration guide\n- `debug_search_quality` - Troubleshoot poor search results\n- `build_knowledge_base` - Structured documentation with metadata\n- `index_git_history` - Index repository commit history for semantic search\n- `search_project_history` - Search git history to understand feature implementations\n- `investigate_code_with_history` - Deep dive into code with contextual search\n- `cross_repo_search` - Search patterns across multiple repositories\n- `trace_feature_evolution` - Track how features evolved over time\n- `security_audit_search` - Find security-related code and fixes\n\n### Template Syntax\n\nTemplates use `{{variable}}` placeholders:\n\n- Required arguments must be provided\n- Optional arguments use defaults if not specified\n- Unknown variables are left as-is in the output\n\n## Code Vectorization\n\nIntelligently index and search your codebase using semantic code search. Perfect for AI-assisted development, code exploration, and understanding large codebases.\n\n### Features\n\n- **AST-Aware Chunking**: Intelligent code splitting at function/class boundaries using tree-sitter\n- **Multi-Language Support**: 35+ file types including TypeScript, Python, Java, Go, Rust, C++, and more\n- **Incremental Updates**: Only re-index changed files for fast updates\n- **Smart Ignore Patterns**: Respects .gitignore, .dockerignore, and custom .contextignore files\n- **Semantic Search**: Natural language queries to find relevant code\n- **Metadata Filtering**: Filter by file type, path patterns, or language\n- **Local-First**: All processing happens locally - your code never leaves your machine\n\n### Quick Start\n\n**1. Index your codebase:**\n\n```bash\n# Via Claude Code MCP tool\n/mcp__qdrant__index_codebase /path/to/your/project\n```\n\n**2. Search your code:**\n\n```bash\n# Natural language search\n/mcp__qdrant__search_code /path/to/your/project \"authentication middleware\"\n\n# Filter by file type\n/mcp__qdrant__search_code /path/to/your/project \"database schema\" --fileTypes .ts,.js\n\n# Filter by path pattern\n/mcp__qdrant__search_code /path/to/your/project \"API endpoints\" --pathPattern src/api/**\n```\n\n**3. Update after changes:**\n\n```bash\n# Incrementally re-index only changed files\n/mcp__qdrant__reindex_changes /path/to/your/project\n```\n\n### Usage Examples\n\n#### Index a TypeScript Project\n\n```typescript\n// The MCP tool automatically:\n// 1. Scans all .ts, .tsx, .js, .jsx files\n// 2. Respects .gitignore patterns (skips node_modules, dist, etc.)\n// 3. Chunks code at function/class boundaries\n// 4. Generates embeddings using your configured provider\n// 5. Stores in Qdrant with metadata (file path, line numbers, language)\n\nindex_codebase({\n  path: \"/workspace/my-app\",\n  forceReindex: false, // Set to true to re-index from scratch\n});\n\n// Output:\n// ✓ Indexed 247 files (1,823 chunks) in 45.2s\n```\n\n#### Search for Authentication Code\n\n```typescript\nsearch_code({\n  path: \"/workspace/my-app\",\n  query: \"how does user authentication work?\",\n  limit: 5,\n});\n\n// Results include file path, line numbers, and code snippets:\n// [\n//   {\n//     filePath: \"src/auth/middleware.ts\",\n//     startLine: 15,\n//     endLine: 42,\n//     content: \"export async function authenticateUser(req: Request) { ... }\",\n//     score: 0.89,\n//     language: \"typescript\"\n//   },\n//   ...\n// ]\n```\n\n#### Search with Filters\n\n```typescript\n// Only search TypeScript files\nsearch_code({\n  path: \"/workspace/my-app\",\n  query: \"error handling patterns\",\n  fileTypes: [\".ts\", \".tsx\"],\n  limit: 10,\n});\n\n// Only search in specific directories\nsearch_code({\n  path: \"/workspace/my-app\",\n  query: \"API route handlers\",\n  pathPattern: \"src/api/**\",\n  limit: 10,\n});\n```\n\n#### Incremental Re-indexing\n\n```typescript\n// After making changes to your codebase\nreindex_changes({\n  path: \"/workspace/my-app\",\n});\n\n// Output:\n// ✓ Updated: +3 files added, ~5 files modified, -1 files deleted\n// ✓ Chunks: +47 added, -23 deleted in 8.3s\n```\n\n#### Check Indexing Status\n\n```typescript\nget_index_status({\n  path: \"/workspace/my-app\",\n});\n\n// Output:\n// {\n//   status: \"indexed\",      // \"not_indexed\" | \"indexing\" | \"indexed\"\n//   isIndexed: true,        // deprecated: use status instead\n//   collectionName: \"code_a3f8d2e1\",\n//   chunksCount: 1823,\n//   filesCount: 247,\n//   lastUpdated: \"2025-01-30T10:15:00Z\",\n//   languages: [\"typescript\", \"javascript\", \"json\"]\n// }\n```\n\n### Supported Languages\n\n**Programming Languages** (35+ file types):\n\n- **Web**: TypeScript, JavaScript, Vue, Svelte\n- **Backend**: Python, Java, Go, Rust, Ruby, PHP\n- **Systems**: C, C++, C#\n- **Mobile**: Swift, Kotlin, Dart\n- **Functional**: Scala, Clojure, Haskell, OCaml\n- **Scripting**: Bash, Shell, Fish\n- **Data**: SQL, GraphQL, Protocol Buffers\n- **Config**: JSON, YAML, TOML, XML, Markdown\n\nSee [configuration](#code-vectorization-configuration) for full list and customization options.\n\n### Custom Ignore Patterns\n\nCreate a `.contextignore` file in your project root to specify additional patterns to ignore:\n\n```gitignore\n# .contextignore\n**/test/**\n**/*.test.ts\n**/*.spec.ts\n**/fixtures/**\n**/mocks/**\n**/__tests__/**\n```\n\n### Best Practices\n\n1. **Index Once, Update Incrementally**: Use `index_codebase` for initial indexing, then `reindex_changes` for updates\n2. **Use Filters**: Narrow search scope with `fileTypes` and `pathPattern` for better results\n3. **Meaningful Queries**: Use natural language that describes what you're looking for (e.g., \"database connection pooling\" instead of \"db\")\n4. **Check Status First**: Use `get_index_status` to verify a codebase is indexed before searching\n5. **Local Embedding**: Use Ollama (default) to keep everything local and private\n\n### Performance\n\nTypical performance on a modern laptop (Apple M1/M2 or similar):\n\n| Codebase Size     | Files | Indexing Time | Search Latency |\n| ----------------- | ----- | ------------- | -------------- |\n| Small (10k LOC)   | 50    | ~10s          | \u003c100ms         |\n| Medium (100k LOC) | 500   | ~2min         | \u003c200ms         |\n| Large (500k LOC)  | 2,500 | ~10min        | \u003c500ms         |\n\n**Note**: Indexing time varies based on embedding provider. Ollama (local) is fastest for initial indexing.\n\n## Git History Search\n\nIndex and search your repository's git commit history using natural language. Perfect for finding past fixes, understanding change patterns, and learning from previous work.\n\n### Features\n\n- **Semantic Commit Search**: Find commits by describing what you're looking for in natural language\n- **Conventional Commit Classification**: Automatic classification of commits (feat, fix, refactor, etc.)\n- **Incremental Updates**: Only index new commits for efficient updates\n- **Rich Filtering**: Filter by commit type, author, or date range\n- **Metadata Extraction**: Includes files changed, insertions/deletions, and full commit context\n\n### Quick Start\n\n**1. Index your repository's git history:**\n\n```bash\n# Via Claude Code MCP tool\n/mcp__qdrant__index_git_history /path/to/your/repo\n```\n\n**2. Search for relevant commits:**\n\n```bash\n# Natural language search\n/mcp__qdrant__search_git_history /path/to/your/repo \"fix authentication bug\"\n\n# Filter by commit type\n/mcp__qdrant__search_git_history /path/to/your/repo \"database optimization\" --commitTypes fix,perf\n\n# Filter by author\n/mcp__qdrant__search_git_history /path/to/your/repo \"API changes\" --authors \"john@example.com\"\n```\n\n**3. Keep index up to date:**\n\n```bash\n# Incrementally index only new commits\n/mcp__qdrant__index_new_commits /path/to/your/repo\n```\n\n### Use Cases\n\n- **Finding Similar Fixes**: \"How was the null pointer issue in auth fixed before?\"\n- **Understanding Patterns**: \"What refactoring was done to the database layer?\"\n- **Learning from History**: \"Show me examples of API endpoint implementations\"\n- **Code Archaeology**: \"What changes were made to the payment system last year?\"\n\n## Advanced Search\n\nCombine code and git history search for deeper codebase understanding. Requires repositories to be indexed with both `index_codebase` and `index_git_history` first.\n\n- **Contextual Search**: Query code + git history together with automatic file-commit correlations\n- **Federated Search**: Search across multiple repositories with RRF ranking\n\nSee **[Advanced Search Examples](examples/advanced-search/)** for detailed usage, workflows, and scenarios.\n\n## Examples\n\nSee [examples/](examples/) directory for detailed guides:\n\n- **[Basic Usage](examples/basic/)** - Create collections, add documents, search\n- **[Hybrid Search](examples/hybrid-search/)** - Combine semantic and keyword search\n- **[Knowledge Base](examples/knowledge-base/)** - Structured documentation with metadata\n- **[Advanced Filtering](examples/filters/)** - Complex boolean filters\n- **[Rate Limiting](examples/rate-limiting/)** - Batch processing with cloud providers\n- **[Code Search](examples/code-search/)** - Index codebases and semantic code search\n- **[Advanced Search](examples/advanced-search/)** - Contextual and federated search across repositories\n\n## Advanced Configuration\n\n### Environment Variables\n\n#### Core Configuration\n\n| Variable                  | Description                                              | Default               |\n| ------------------------- | -------------------------------------------------------- | --------------------- |\n| `TRANSPORT_MODE`          | \"stdio\" or \"http\"                                        | stdio                 |\n| `HTTP_PORT`               | Port for HTTP transport                                  | 3000                  |\n| `HTTP_REQUEST_TIMEOUT_MS` | Request timeout for HTTP transport (ms)                  | 300000                |\n| `EMBEDDING_PROVIDER`      | \"ollama\", \"openai\", \"cohere\", \"voyage\"                   | ollama                |\n| `QDRANT_URL`              | Qdrant server URL                                        | http://localhost:6333 |\n| `QDRANT_API_KEY`          | API key for Qdrant authentication                        | -                     |\n| `LOG_LEVEL`               | Logging level (fatal/error/warn/info/debug/trace/silent) | info                  |\n| `PROMPTS_CONFIG_FILE`     | Path to prompts configuration JSON                       | prompts.json          |\n\n#### Embedding Configuration\n\n| Variable                            | Description              | Default           |\n| ----------------------------------- | ------------------------ | ----------------- |\n| `EMBEDDING_MODEL`                   | Model name               | Provider-specific |\n| `EMBEDDING_BASE_URL`                | Custom API URL           | Provider-specific |\n| `EMBEDDING_MAX_REQUESTS_PER_MINUTE` | Rate limit               | Provider-specific |\n| `EMBEDDING_RETRY_ATTEMPTS`          | Retry count              | 3                 |\n| `EMBEDDING_RETRY_DELAY`             | Initial retry delay (ms) | 1000              |\n| `OPENAI_API_KEY`                    | OpenAI API key           | -                 |\n| `COHERE_API_KEY`                    | Cohere API key           | -                 |\n| `VOYAGE_API_KEY`                    | Voyage AI API key        | -                 |\n\n#### Code Vectorization Configuration\n\n| Variable                 | Description                                  | Default |\n| ------------------------ | -------------------------------------------- | ------- |\n| `CODE_CHUNK_SIZE`        | Maximum chunk size in characters             | 2500    |\n| `CODE_CHUNK_OVERLAP`     | Overlap between chunks in characters         | 300     |\n| `CODE_ENABLE_AST`        | Enable AST-aware chunking (tree-sitter)      | true    |\n| `CODE_BATCH_SIZE`        | Number of chunks to embed in one batch       | 100     |\n| `CODE_CUSTOM_EXTENSIONS` | Additional file extensions (comma-separated) | -       |\n| `CODE_CUSTOM_IGNORE`     | Additional ignore patterns (comma-separated) | -       |\n| `CODE_DEFAULT_LIMIT`     | Default search result limit                  | 5       |\n\n#### Git History Configuration\n\n| Variable                   | Description                              | Default |\n| -------------------------- | ---------------------------------------- | ------- |\n| `GIT_MAX_COMMITS`          | Maximum commits to index per run         | 5000    |\n| `GIT_INCLUDE_FILES`        | Include changed file list in chunks      | true    |\n| `GIT_INCLUDE_DIFF`         | Include truncated diff in chunks         | true    |\n| `GIT_MAX_DIFF_SIZE`        | Maximum diff size in bytes per commit    | 5000    |\n| `GIT_TIMEOUT`              | Timeout for git commands (ms)            | 300000  |\n| `GIT_MAX_CHUNK_SIZE`       | Maximum characters per chunk             | 3000    |\n| `GIT_BATCH_SIZE`           | Number of chunks to embed in one batch   | 100     |\n| `GIT_BATCH_RETRY_ATTEMPTS` | Retry attempts for failed batches        | 3       |\n| `GIT_SEARCH_LIMIT`         | Default search result limit              | 10      |\n| `GIT_ENABLE_HYBRID`        | Enable hybrid search with sparse vectors | true    |\n\n### Provider Comparison\n\n| Provider   | Models                                                          | Dimensions     | Rate Limit | Notes                |\n| ---------- | --------------------------------------------------------------- | -------------- | ---------- | -------------------- |\n| **Ollama** | `nomic-embed-text` (default), `mxbai-embed-large`, `all-minilm` | 768, 1024, 384 | None       | Local, no API key    |\n| **OpenAI** | `text-embedding-3-small` (default), `text-embedding-3-large`    | 1536, 3072     | 3500/min   | Cloud API            |\n| **Cohere** | `embed-english-v3.0` (default), `embed-multilingual-v3.0`       | 1024           | 100/min    | Multilingual support |\n| **Voyage** | `voyage-2` (default), `voyage-large-2`, `voyage-code-2`         | 1024, 1536     | 300/min    | Code-specialized     |\n\n**Note:** Ollama models require pulling before use:\n\n- Podman: `podman exec ollama ollama pull \u003cmodel-name\u003e`\n- Docker: `docker exec ollama ollama pull \u003cmodel-name\u003e`\n\n## Troubleshooting\n\n| Issue                          | Solution                                                                                  |\n| ------------------------------ | ----------------------------------------------------------------------------------------- |\n| **Qdrant not running**         | `podman compose up -d` or `docker compose up -d`                                          |\n| **Collection missing**         | Create collection first before adding documents                                           |\n| **Ollama not running**         | Verify with `curl http://localhost:11434`, start with `podman compose up -d`              |\n| **Model missing**              | `podman exec ollama ollama pull nomic-embed-text` or `docker exec ollama ollama pull ...` |\n| **Rate limit errors**          | Adjust `EMBEDDING_MAX_REQUESTS_PER_MINUTE` to match your provider tier                    |\n| **API key errors**             | Verify correct API key in environment configuration                                       |\n| **Qdrant unauthorized**        | Set `QDRANT_API_KEY` environment variable for secured instances                           |\n| **Filter errors**              | Ensure Qdrant filter format, check field names match metadata                             |\n| **Codebase not indexed**       | Run `index_codebase` before `search_code`                                                 |\n| **Slow indexing**              | Use Ollama (local) for faster indexing, or increase `CODE_BATCH_SIZE`                     |\n| **Files not found**            | Check `.gitignore` and `.contextignore` patterns                                          |\n| **Search returns no results**  | Try broader queries, check if codebase is indexed with `get_index_status`                 |\n| **Out of memory during index** | Reduce `CODE_CHUNK_SIZE` or `CODE_BATCH_SIZE`                                             |\n| **Node 24 tree-sitter error**  | Run `CXXFLAGS='-std=c++20' npm install` - Node 24 requires C++20 for native modules       |\n\n## Development\n\n```bash\nnpm run dev          # Development with auto-reload\nnpm run build        # Production build\nnpm run type-check   # TypeScript validation\nnpm test             # Run test suite\nnpm run test:coverage # Coverage report\n```\n\n### Testing\n\n**771 tests** across 28 test files with **97%+ coverage**:\n\n- **Unit Tests**: QdrantManager (56), Ollama (41), OpenAI (25), Cohere (29), Voyage (31), Factory (43), Prompts (50), Transport (15), MCP Server (19)\n- **Integration Tests**: Code indexer (56), scanner (15), chunker (24), synchronizer (42), snapshot (26), merkle tree (28)\n- **Git History Tests**: Git extractor (28), extractor integration (11), chunker (30), indexer (42), synchronizer (18)\n- **Advanced Search Tests**: Federated tools (30) - normalizeScores, calculateRRFScore, buildCorrelations, contextual_search, federated_search\n\n**CI/CD**: GitHub Actions runs build, type-check, and tests on Node.js 22.x and 24.x for every push/PR.\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for:\n\n- Development workflow\n- Conventional commit format (`feat:`, `fix:`, `BREAKING CHANGE:`)\n- Testing requirements (run `npm test`, `npm run type-check`, `npm run build`)\n\n**Automated releases**: Semantic versioning via conventional commits - `feat:` → minor, `fix:` → patch, `BREAKING CHANGE:` → major.\n\n## Acknowledgments\n\nThe code vectorization feature is inspired by and builds upon concepts from the excellent [claude-context](https://github.com/zilliztech/claude-context) project (MIT License, Copyright 2025 Zilliz).\n\n## License\n\nMIT - see [LICENSE](LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhalder%2Fqdrant-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmhalder%2Fqdrant-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhalder%2Fqdrant-mcp-server/lists"}