Ce dépôt est un composant MCP du Hephaistos-Kit — utilisable seul, mais conçu pour être cloné en sous-module et installé via mcp/install.ps1.

🙏 Adapté de mhalder/qdrant-mcp-server — merci aux développeurs originaux pour la base qui a permis cette intégration au kit.

Qdrant MCP Server

A Model Context Protocol (MCP) server providing semantic search capabilities using Qdrant vector database with multiple embedding providers.

Features

• Zero Setup: Works out of the box with Ollama - no API keys required

• Privacy-First: Local embeddings and vector storage - data never leaves your machine

• Code Vectorization: Intelligent codebase indexing with AST-aware chunking and semantic code search

• Multiple Providers: Ollama (default), OpenAI, Cohere, and Voyage AI

• Hybrid Search: Combine semantic and keyword search for better results

• Semantic Search: Natural language search with metadata filtering

• Incremental Indexing: Efficient updates - only re-index changed files

• Configurable Prompts: Create custom prompts for guided workflows without code changes

• Rate Limiting: Intelligent throttling with exponential backoff

• Full CRUD: Create, search, and manage collections and documents

• Flexible Deployment: Run locally (stdio) or as a remote HTTP server

Related MCP server: MCP Codebase Index

Quick Start

Prerequisites

• Node.js 20+

• Docker and Docker Compose

Installation

# Clone and install
git clone https://github.com/mhalder/qdrant-mcp-server.git
cd qdrant-mcp-server
npm install

# Start services and pull model
docker compose up -d
docker exec ollama ollama pull nomic-embed-text

# Build
npm run build

Configuration

Local Setup (stdio transport)

Add to ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "qdrant": {
      "command": "node",
      "args": ["/path/to/qdrant-mcp-server/build/index.js"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "EMBEDDING_BASE_URL": "http://localhost:11434"
      }
    }
  }
}

Remote Setup (HTTP transport)

⚠️ Security Warning: When deploying the HTTP transport in production:

• Always run behind a reverse proxy (nginx, Caddy) with HTTPS

• Implement authentication/authorization at the proxy level

• Use firewalls to restrict access to trusted networks

• Never expose directly to the public internet without protection

• Consider implementing rate limiting at the proxy level

• Monitor server logs for suspicious activity

Start the server:

TRANSPORT_MODE=http HTTP_PORT=3000 node build/index.js

Configure client:

{
  "mcpServers": {
    "qdrant": {
      "url": "http://your-server:3000/mcp"
    }
  }
}

Using a different provider:

"env": {
  "EMBEDDING_PROVIDER": "nvidia",  // or "openai", "cohere", "voyage"
  "NVIDIA_API_KEY": "nvapi-...",   // provider-specific API key
  "QDRANT_URL": "http://localhost:6333"
}

Restart after making changes.

See Advanced Configuration section below for all options.

Tools

Collection Management

Document Operations

Code Vectorization

Resources

• qdrant://collections - List all collections

• qdrant://collection/{name} - Collection details

Configurable Prompts

Create custom prompts tailored to your specific use cases without modifying code. Prompts provide guided workflows for common tasks.

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.

Setup

1. Create a prompts configuration file (e.g., prompts.json in the project root):

   See prompts.example.json for example configurations you can copy and customize.

2. Configure the server (optional - only needed for custom path):

If you place prompts.json in the project root, no additional configuration is needed. To use a custom path:

{
  "mcpServers": {
    "qdrant": {
      "command": "node",
      "args": ["/path/to/qdrant-mcp-server/build/index.js"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "PROMPTS_CONFIG_FILE": "/custom/path/to/prompts.json"
      }
    }
  }
}

3. Use prompts in your AI assistant:

Claude Code:

/mcp__qdrant__find_similar_docs papers "neural networks" 10

VSCode:

/mcp.qdrant.find_similar_docs papers "neural networks" 10

Example Prompts

See prompts.example.json for ready-to-use prompts including:

• find_similar_docs - Semantic search with result explanation

• setup_rag_collection - Create RAG-optimized collections

• analyze_collection - Collection insights and recommendations

• bulk_add_documents - Guided bulk document insertion

• search_with_filter - Metadata filtering assistance

• compare_search_methods - Semantic vs hybrid search comparison

• collection_maintenance - Maintenance and cleanup workflows

• migrate_to_hybrid - Collection migration guide

Template Syntax

Templates use {{variable}} placeholders:

• Required arguments must be provided

• Optional arguments use defaults if not specified

• Unknown variables are left as-is in the output

Code Vectorization

Intelligently index and search your codebase using semantic code search. Perfect for AI-assisted development, code exploration, and understanding large codebases.

Features

• AST-Aware Chunking: Intelligent code splitting at function/class boundaries using tree-sitter

• Multi-Language Support: 35+ file types including TypeScript, Python, Java, Go, Rust, C++, and more

• Incremental Updates: Only re-index changed files for fast updates

• Smart Ignore Patterns: Respects .gitignore, .dockerignore, and custom .contextignore files

• Semantic Search: Natural language queries to find relevant code

• Metadata Filtering: Filter by file type, path patterns, or language

• Local-First: All processing happens locally - your code never leaves your machine

Quick Start

1. Index your codebase:

# Via Claude Code MCP tool
/mcp__qdrant__index_codebase /path/to/your/project

2. Search your code:

# Natural language search
/mcp__qdrant__search_code /path/to/your/project "authentication middleware"

# Filter by file type
/mcp__qdrant__search_code /path/to/your/project "database schema" --fileTypes .ts,.js

# Filter by path pattern
/mcp__qdrant__search_code /path/to/your/project "API endpoints" --pathPattern src/api/**

3. Update after changes:

# Incrementally re-index only changed files
/mcp__qdrant__reindex_changes /path/to/your/project

Usage Examples

Index a TypeScript Project

// The MCP tool automatically:
// 1. Scans all .ts, .tsx, .js, .jsx files
// 2. Respects .gitignore patterns (skips node_modules, dist, etc.)
// 3. Chunks code at function/class boundaries
// 4. Generates embeddings using your configured provider
// 5. Stores in Qdrant with metadata (file path, line numbers, language)

index_codebase({
  path: "/workspace/my-app",
  forceReindex: false  // Set to true to re-index from scratch
})

// Output:
// ✓ Indexed 247 files (1,823 chunks) in 45.2s

Search for Authentication Code

search_code({
  path: "/workspace/my-app",
  query: "how does user authentication work?",
  limit: 5
})

// Results include file path, line numbers, and code snippets:
// [
//   {
//     filePath: "src/auth/middleware.ts",
//     startLine: 15,
//     endLine: 42,
//     content: "export async function authenticateUser(req: Request) { ... }",
//     score: 0.89,
//     language: "typescript"
//   },
//   ...
// ]

Search with Filters

// Only search TypeScript files
search_code({
  path: "/workspace/my-app",
  query: "error handling patterns",
  fileTypes: [".ts", ".tsx"],
  limit: 10
})

// Only search in specific directories
search_code({
  path: "/workspace/my-app",
  query: "API route handlers",
  pathPattern: "src/api/**",
  limit: 10
})

Incremental Re-indexing

// After making changes to your codebase
reindex_changes({
  path: "/workspace/my-app"
})

// Output:
// ✓ Updated: +3 files added, ~5 files modified, -1 files deleted
// ✓ Chunks: +47 added, -23 deleted in 8.3s

Check Indexing Status

get_index_status({
  path: "/workspace/my-app"
})

// Output:
// {
//   isIndexed: true,
//   collectionName: "code_a3f8d2e1",
//   chunksCount: 1823,
//   filesCount: 247,
//   lastUpdated: "2025-01-30T10:15:00Z",
//   languages: ["typescript", "javascript", "json"]
// }

Supported Languages

Programming Languages (35+ file types):

• Web: TypeScript, JavaScript, Vue, Svelte

• Backend: Python, Java, Go, Rust, Ruby, PHP

• Systems: C, C++, C#

• Mobile: Swift, Kotlin, Dart

• Functional: Scala, Clojure, Haskell, OCaml

• Scripting: Bash, Shell, Fish

• Data: SQL, GraphQL, Protocol Buffers

• Config: JSON, YAML, TOML, XML, Markdown

See configuration for full list and customization options.

Custom Ignore Patterns

Create a .contextignore file in your project root to specify additional patterns to ignore:

# .contextignore
**/test/**
**/*.test.ts
**/*.spec.ts
**/fixtures/**
**/mocks/**
**/__tests__/**

Best Practices

1. Index Once, Update Incrementally: Use index_codebase for initial indexing, then reindex_changes for updates

2. Use Filters: Narrow search scope with fileTypes and pathPattern for better results

3. Meaningful Queries: Use natural language that describes what you're looking for (e.g., "database connection pooling" instead of "db")

4. Check Status First: Use get_index_status to verify a codebase is indexed before searching

5. Local Embedding: Use Ollama (default) to keep everything local and private

Performance

Typical performance on a modern laptop (Apple M1/M2 or similar):

Note: Indexing time varies based on embedding provider. Ollama (local) is fastest for initial indexing.

Examples

See examples/ directory for detailed guides:

• Basic Usage - Create collections, add documents, search

• Knowledge Base - Structured documentation with metadata

• Advanced Filtering - Complex boolean filters

• Rate Limiting - Batch processing with cloud providers

• Code Search - Index codebases and semantic code search

Advanced Configuration

Environment Variables

Core Configuration

Embedding Configuration

Code Vectorization Configuration

Provider Comparison

Note: Ollama models require docker exec ollama ollama pull <model-name> before use.

Troubleshooting

Development

npm run dev          # Development with auto-reload
npm run build        # Production build
npm run type-check   # TypeScript validation
npm test             # Run test suite
npm run test:coverage # Coverage report

Testing

422 tests (376 unit + 46 functional) with 98%+ coverage:

• Unit Tests: QdrantManager (21), Ollama (31), OpenAI (25), Cohere (29), Voyage (31), Factory (32), MCP Server (19)

• Functional Tests: Live API integration, end-to-end workflows (46)

CI/CD: GitHub Actions runs build, type-check, and tests on Node.js 20 & 22 for every push/PR.

Contributing

Contributions welcome! See CONTRIBUTING.md for:

• Development workflow

• Conventional commit format (feat:, fix:, BREAKING CHANGE:)

• Testing requirements (run npm test, npm run type-check, npm run build)

Automated releases: Semantic versioning via conventional commits - feat: → minor, fix: → patch, BREAKING CHANGE: → major.

Acknowledgments

The code vectorization feature is inspired by and builds upon concepts from the excellent claude-context project (MIT License, Copyright 2025 Zilliz).

License

MIT - see LICENSE file.