workspace-qdrant-mcp

License: MIT GitHub Release Glama Homebrew TypeScript Rust Qdrant

Base de datos vectorial con alcance de proyecto para asistentes de IA, que proporciona búsqueda semántica + por palabras clave híbrida con detección automática de proyectos.

Características

Búsqueda híbrida - Combina similitud semántica con coincidencia de palabras clave utilizando Reciprocal Rank Fusion (RRF).
Detección de proyectos - Reconocimiento automático de repositorios Git y colecciones con alcance de proyecto.
6 herramientas MCP - search, retrieve, rules, store, grep, list.
Inteligencia de código - Fragmentación semántica con Tree-sitter + integración LSP para proyectos activos.
Grafo de código - Grafo de relaciones con algoritmos (PageRank, detección de comunidades, centralidad de intermediación).
CLI de alto rendimiento - Herramienta de línea de comandos wqm basada en Rust.
Daemon en segundo plano - memexd para la supervisión y procesamiento continuo de archivos.

Inicio rápido

Requisitos previos

Qdrant - docker run -d -p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrant
Compilador C - Requerido para compilar gramáticas de Tree-sitter en el primer uso. Las gramáticas de Tree-sitter se distribuyen como código fuente C y se compilan localmente.
- macOS: xcode-select --install (Herramientas de línea de comandos de Xcode)
- Linux: apt install build-essential (Debian/Ubuntu) o dnf groupinstall "Development Tools" (Fedora)
- Windows: Instala Visual Studio Build Tools con la carga de trabajo de C++.

Instalación

Opción 1: Homebrew (Recomendado — macOS y Linux)

brew install ChrisGVE/tap/workspace-qdrant
brew services start workspace-qdrant

Opción 2: Binarios precompilados

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/ChrisGVE/workspace-qdrant-mcp/main/scripts/download-install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/ChrisGVE/workspace-qdrant-mcp/main/scripts/download-install.ps1 | iex

Instala wqm y memexd en ~/.local/bin (Linux/macOS) o %LOCALAPPDATA%\wqm\bin (Windows).

Opción 3: Compilar desde el código fuente

git clone https://github.com/ChrisGVE/workspace-qdrant-mcp.git
cd workspace-qdrant-mcp
./install.sh

Consulta la Referencia de instalación para obtener instrucciones detalladas y notas específicas de la plataforma. Para Windows, consulta la Guía de instalación de Windows.

Configurar MCP

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "workspace-qdrant-mcp": {
      "command": "node",
      "args": ["/path/to/workspace-qdrant-mcp/src/typescript/mcp-server/dist/index.js"],
      "env": {
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

Claude Code:

claude mcp add workspace-qdrant-mcp -- node /path/to/workspace-qdrant-mcp/src/typescript/mcp-server/dist/index.js

Verificar

wqm --version
wqm status health

Integración con CLAUDE.md

Añade lo siguiente al archivo CLAUDE.md de tu proyecto (o a tu ~/.claude/CLAUDE.md global) para que Claude Code utilice workspace-qdrant de forma proactiva:

## workspace-qdrant

The `workspace-qdrant` MCP server provides codebase-aware search, a library knowledge base, a scratchpad for accumulated insights, and persistent behavioral rules. The tool schemas are self-describing; these instructions cover *when* and *how* to use them.

### Primary Search and Knowledge Base

**Use `workspace-qdrant` first whenever context is uncertain** — first session on a project, returning after a significant gap, or exploring an unfamiliar subsystem. It is faster and more accurate than walking files manually, and it retrieves findings from prior sessions that would otherwise be lost.

**Three-step protocol:**
1. **Search** with `workspace-qdrant` (`search`, `grep`, `list`, or `retrieve`)
2. **Fall back** to `Grep`, `Glob`, `WebSearch` only when workspace-qdrant is insufficient or unavailable
3. **Store** any new findings, analysis, or design rationale via `store` so they are retrievable in future sessions

When a fresh handover or strong prior context already covers what you need, skip the exploratory search — but always store new findings at the end.

**Collections and their purpose:**
- `projects` — indexed codebase; use `scope="project"` (current project) or `scope="all"` (across all projects)
- `libraries` — external reference docs, API specs, third-party documentation; add via `store` with `collection="libraries"` and search with `includeLibraries=true`
- `scratchpad` — analysis, design rationale, research transcripts, architectural insights; complements session handovers by building a growing, semantically searchable knowledge layer across sessions
- `rules` — persistent behavioral rules; load at session start via `rules` → `action="list"`

**Practical notes:**
- Use `grep` for exact strings or regex; `list` with `format="summary"` to explore project structure
- Store external docs or specs into `libraries` so they are searchable alongside code
- Use the scratchpad to record *why* decisions were made, not just *what* was done — future sessions can retrieve the reasoning

### Sub-Agents

Sub-agents start with only the prompt you give them — they have no session history or handover context. They must always use `workspace-qdrant` first for any code exploration, without exception. Include this verbatim in every agent prompt:

> "You have no prior context about this codebase. Use `workspace-qdrant` as your mandatory first tool for ALL code searches — symbols, functions, architecture, patterns, prior findings. Use `search`, `grep`, `list`, or `retrieve` before touching any file with Read/Grep/Glob. Store any new findings, analysis, or design rationale via `store` (scratchpad for insights, libraries for reference docs) so they persist for future sessions."

### Project Registration

At session start, check whether the current project is registered with workspace-qdrant. If it is not, ask the user whether they want to register it (do not register silently). Once registered, the daemon handles file watching and ingestion automatically — no further action is needed.

### Behavioral Rules

The `rules` tool manages persistent rules that are injected into context across sessions. Rules are **user-initiated only** — add rules when the user explicitly instructs you to, never autonomously. Use `action="list"` at session start to load active rules.

### Issue Reporting

workspace-qdrant is under active development. If you encounter errors, unexpected behavior, or limitations with any workspace-qdrant tool, report them as GitHub issues at https://github.com/ChrisGVE/workspace-qdrant-mcp/issues using the `gh` CLI.

Herramientas MCP

Herramienta	Propósito
`search`	Búsqueda híbrida semántica + por palabras clave en el contenido indexado
`retrieve`	Búsqueda directa de documentos por ID o filtro de metadatos
`rules`	Gestionar reglas de comportamiento persistentes
`store`	Almacenar contenido, registrar proyectos, guardar notas
`grep`	Búsqueda exacta de subcadenas o expresiones regulares usando FTS5
`list`	Listar archivos del proyecto y estructura de carpetas

Consulta la Referencia de herramientas MCP para ver parámetros y ejemplos.

Colecciones

Colección	Propósito	Aislamiento
`projects`	Código y documentación del proyecto	Multi-inquilino por `tenant_id`
`libraries`	Documentación de referencia (libros, artículos, docs)	Multi-inquilino por `library_name`
`rules`	Reglas de comportamiento y preferencias	Multi-inquilino por `project_id`
`scratchpad`	Almacenamiento de trabajo temporal	Por sesión

Referencia de la CLI

# Service management
wqm service start              # Start background daemon
wqm service status             # Check daemon status
wqm status health              # System health check

# Search and content
wqm search "query"             # Search collections
wqm ingest file path.py        # Ingest a file
wqm rules list                 # List behavioral rules

# Project and library
wqm project list               # List registered projects
wqm project watch pause        # Pause file watchers
wqm library list               # List libraries
wqm tags list                  # List tags with counts

# Administration
wqm admin collections list     # List collections
wqm admin rebuild all          # Rebuild all indexes
wqm admin backup create        # Backup snapshots
wqm admin stats overview       # Search analytics

# Code graph
wqm graph stats --tenant <t>   # Node/edge counts
wqm graph query --node-id <id> --tenant <t> --hops 2   # Related nodes
wqm graph impact --symbol <name> --tenant <t>           # Impact analysis
wqm graph pagerank --tenant <t> --top-k 20              # PageRank centrality

# Setup
wqm init completions zsh       # Shell completions
wqm init man install           # Install man pages
wqm init hooks install         # Install Claude Code hooks

# Queue and monitoring
wqm queue stats                # Queue statistics

Consulta la Referencia de la CLI para obtener la documentación completa.

Configuración

Variables de entorno

Variable	Predeterminado	Descripción
`QDRANT_URL`	`http://localhost:6333`	URL del servidor Qdrant
`QDRANT_API_KEY`	-	Clave de API (requerida para Qdrant Cloud)
`FASTEMBED_MODEL`	`all-MiniLM-L6-v2`	Modelo de incrustación (embedding)

Arquitectura

                    +-----------------+
                    |  Claude/Client  |
                    +--------+--------+
                             |
                    +--------v--------+
                    |   MCP Server    |  (TypeScript)
                    +--------+--------+
                             |
              +--------------+--------------+
              |                             |
     +--------v--------+           +--------v--------+
     |   Rust Daemon   |           |     Qdrant      |
     |    (memexd)     |           | Vector Database |
     +--------+--------+           +-----------------+
              |
     +--------v--------+
     |  File Watcher   |
     |  Code Graph     |
     |  Embeddings     |
     +-----------------+

El daemon de Rust gestiona la supervisión de archivos, la generación de incrustaciones, la extracción del grafo de código y el procesamiento de colas. Todas las escrituras se dirigen a través del daemon para garantizar la consistencia.

Documentación

Guías de usuario:

Inicio rápido — empieza a trabajar en 5 minutos
Manual de usuario — guía de uso completa
Integración con LLM — mejores prácticas para Claude

Referencia:

Instalación | Windows
Referencia de la CLI — todos los comandos de wqm
Herramientas MCP — parámetros de herramientas y ejemplos
Configuración — todas las opciones y valores predeterminados
Arquitectura — descripción general de los componentes

Consulta el Índice de documentación para especificaciones, ADRs y recursos para desarrolladores.

Desarrollo

# TypeScript MCP server
cd src/typescript/mcp-server && npm install && npm run build && npm test

# Rust daemon and CLI (from src/rust/)
cargo build --release
cargo test

# Graph benchmarks
cargo bench --package workspace-qdrant-core --bench graph_bench

# Binaries output to:
# - target/release/wqm
# - target/release/memexd

Contribución

Consulta CONTRIBUTING.md para la configuración de desarrollo y las directrices.

Licencia

Licencia MIT - consulta LICENSE para más detalles.

Inspirado en claude-qdrant-mcp

Workspace Qdrant MCP