Workspace-Qdrant-MCP

Conocimiento de código y metadatos con actualización en vivo, biblioteca de conocimiento, búsquedas semánticas y vectoriales

GitHub

Prueba este MCPPatrocinado

Documentación

workspace-qdrant-mcp

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

🚧 Reconstrucción de v0.2.0 en curso

workspace-qdrant-mcp se está reconstruyendo desde cero en preparación para v0.2.0 — un modelo de almacenamiento unificado, mejor calidad de búsqueda, monitoreo de archivos más confiable y una arquitectura más limpia, con una migración sin re-indexación para usuarios existentes. Una vez que el diseño esté definido (previsto para principios de julio), abriremos el trabajo a colaboradores externos. Consulte el Roadmap para conocer el plan general.

Características

Búsqueda híbrida - Combina similitud semántica con coincidencia de palabras clave mediante fusión de rango recíproco
Detección de proyectos - Reconocimiento automático de repositorios Git y colecciones con alcance de proyecto
7 herramientas MCP - search, retrieve, rules, store, grep, list, embedding
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
Demonio en segundo plano - memexd para monitoreo 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 las 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: Instale Visual Studio Build Tools con la carga de trabajo de C++
Clang/LLVM - Requerido solo para compilar memexd desde el código fuente, para el núcleo C++ de LadybugDB (el backend de grafo predeterminado). Los binarios precompilados (Homebrew, artefactos de lanzamiento) no lo necesitan.
- macOS: Las herramientas de línea de comandos de Xcode incluyen Clang (xcode-select --install)
- Linux: apt install clang libclang-dev (Debian/Ubuntu) o dnf install clang (Fedora)
- Alternativa: compile sin el conjunto de herramientas C++ usando el backend solo SQLite — cargo build --no-default-features --features sqlite

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, memexd y workspace-qdrant-mcp 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

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

Configurar MCP

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "workspace-qdrant-mcp": {
      "command": "workspace-qdrant-mcp",
      "env": {
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

Claude Code:

claude mcp add workspace-qdrant-mcp -- workspace-qdrant-mcp

Verificar

wqm --version
wqm status health

Integración con CLAUDE.md

Agregue lo siguiente al CLAUDE.md de su proyecto (o a su ~/.claude/CLAUDE.md global) para que Claude Code use workspace-qdrant de manera 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 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 de proyecto y estructura de carpetas

Consulte 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	Multiinquilino por `tenant_id`
`libraries`	Documentación de referencia (libros, artículos, documentos)	Multiinquilino por `library_name`
`rules`	Reglas de comportamiento y preferencias	Multiinquilino por `project_id`
`scratchpad`	Almacenamiento de trabajo temporal	Por sesión

Referencia de 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 (respects CLAUDE_CONFIG_DIR)

# Queue and monitoring
wqm queue stats                # Queue statistics

Consulte la Referencia de CLI para obtener 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

Integración con Claude Code

wqm init hooks lee y escribe el settings.json de Claude Code. La ubicación se resuelve desde:

Variable	Predeterminado	Descripción
`CLAUDE_CONFIG_DIR`	`~/.claude`	Directorio de configuración de Claude Code utilizado por `wqm init hooks install/uninstall/status`. Establezca esto para Claude Code Enterprise o cualquier instalación no predeterminada.

Ejemplo — Claude Code Enterprise:

export CLAUDE_CONFIG_DIR=~/.config/claude/claude-ent
wqm init hooks install

Observabilidad

El demonio expone métricas y trazas. Ambos están deshabilitados de forma predeterminada.

Prometheus (`/metrics`, pull)

Habilite mediante configuración o variable de entorno, luego recopile:

# in the daemon config
observability:
  telemetry:
    prometheus:
      enabled: true
      port: 9464
      bind: 0.0.0.0

WQM_PROMETHEUS_ENABLED=true WQM_PROMETHEUS_PORT=9464 memexd --foreground
curl http://localhost:9464/metrics | head

El indicador de CLI --metrics-port <N> es un atajo que fuerza enabled=true y anula el puerto. Consulte docs/observability/prometheus-scrape-example.yaml para un fragmento de scrape_configs y docs/observability/memexd-telemetry-dashboard.json para un panel de Grafana 10.

Trazas OTLP (push)

Los spans de #[tracing::instrument] en el procesador de cola, el observador, gRPC, incrustación y rutas de Qdrant se exportan a través de OTLP/gRPC cuando:

observability:
  telemetry:
    service_name: memexd
    otlp:
      enabled: true
      endpoint: http://collector.example:4317
      protocol: grpc   # http/protobuf is also recognized (logs a warning)
      sample_rate: 0.1

Se respetan las variables de entorno estándar de OpenTelemetry: OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_HEADERS, OTEL_TRACES_SAMPLER_ARG.

La exportación de métricas OTLP no está implementada actualmente — Prometheus es la superficie de métricas canónica.

Arquitectura

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

El demonio Rust maneja el monitoreo de archivos, la generación de incrustaciones, la extracción del grafo de código y el procesamiento de colas. Todas las escrituras pasan por el demonio para garantizar la consistencia.

Documentación

Guías de usuario:

Inicio rápido — póngase en marcha 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 CLI — todos los comandos de wqm
Herramientas MCP — parámetros y ejemplos de herramientas
Configuración — todas las opciones y valores predeterminados
Arquitectura — descripción general de componentes

Consulte el Índice de documentación para especificaciones, ADR y recursos para desarrolladores.

Desarrollo

# Rust daemon, CLI, and MCP server (from src/rust/)
# Builds memexd (daemon), wqm (CLI), and workspace-qdrant-mcp (MCP server)
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

Contribuciones

Consulte CONTRIBUTING.md para la configuración de desarrollo y las pautas.

Licencia

Licencia Apache 2.0 - consulte LICENSE para obtener detalles.

Inspirado en claude-qdrant-mcp

Workspace-Qdrant-MCP

Documentación

workspace-qdrant-mcp

🚧 Reconstrucción de v0.2.0 en curso

Características

Inicio rápido

Requisitos previos

Instalación

Configurar MCP

Verificar

Integración con CLAUDE.md

Herramientas MCP

Colecciones

Referencia de CLI

Configuración

Variables de entorno

Integración con Claude Code

Observabilidad

Prometheus (/metrics, pull)

Trazas OTLP (push)

Arquitectura

Documentación

Desarrollo

Contribuciones

Licencia

Prometheus (`/metrics`, pull)