Skip to main content
Glama

workspace-qdrant-mcp

License: MIT GitHub Release Glama Homebrew TypeScript Rust Qdrant

Projektbezogene Vektordatenbank für KI-Assistenten, die eine hybride semantische Suche sowie Stichwortsuche mit automatischer Projekterkennung bietet.

Funktionen

  • Hybride Suche - Kombiniert semantische Ähnlichkeit mit Stichwortabgleich unter Verwendung von Reciprocal Rank Fusion

  • Projekterkennung - Automatische Erkennung von Git-Repositories und projektbezogenen Sammlungen

  • 6 MCP-Tools - search, retrieve, rules, store, grep, list

  • Code-Intelligenz - Tree-sitter semantisches Chunking + LSP-Integration für aktive Projekte

  • Code-Graph - Beziehungs-Graph mit Algorithmen (PageRank, Community-Erkennung, Betweenness Centrality)

  • Hochleistungs-CLI - Rust-basiertes wqm Befehlszeilen-Tool

  • Hintergrund-Daemon - memexd für kontinuierliche Dateiüberwachung und -verarbeitung

Related MCP server: Super-Memory-TS

Schnellstart

Voraussetzungen

  • Qdrant - docker run -d -p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrant

  • C-Compiler - Erforderlich für die Kompilierung von Tree-sitter-Grammatiken bei der ersten Verwendung. Tree-sitter-Grammatiken werden als C-Quellcode verteilt und lokal kompiliert.

    • macOS: xcode-select --install (Xcode Command Line Tools)

    • Linux: apt install build-essential (Debian/Ubuntu) oder dnf groupinstall "Development Tools" (Fedora)

    • Windows: Installieren Sie Visual Studio Build Tools mit der C++-Workload

Installation

Option 1: Homebrew (Empfohlen — macOS & Linux)

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

Option 2: Vorgefertigte Binärdateien

# 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

Installiert wqm und memexd nach ~/.local/bin (Linux/macOS) oder %LOCALAPPDATA%\wqm\bin (Windows).

Option 3: Aus Quellcode bauen

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

Siehe Installationsreferenz für detaillierte Anweisungen und plattformspezifische Hinweise. Für Windows siehe den Windows-Installationsleitfaden.

MCP konfigurieren

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

Überprüfung

wqm --version
wqm status health

CLAUDE.md Integration

Fügen Sie Folgendes zu Ihrer CLAUDE.md (oder Ihrer globalen ~/.claude/CLAUDE.md) hinzu, damit Claude Code workspace-qdrant proaktiv nutzt:

## 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.

MCP-Tools

Tool

Zweck

search

Hybride semantische Suche + Stichwortsuche über indizierte Inhalte

retrieve

Direkte Dokumentensuche nach ID oder Metadatenfilter

rules

Verwaltung persistenter Verhaltensregeln

store

Inhalte speichern, Projekte registrieren, Notizen sichern

grep

Exakte Teilzeichenfolgen- oder Regex-Suche mittels FTS5

list

Auflisten von Projektdateien und Ordnerstruktur

Siehe MCP-Tools-Referenz für Parameter und Beispiele.

Sammlungen

Sammlung

Zweck

Isolierung

projects

Projektcode und Dokumentation

Multi-Mandanten-fähig via tenant_id

libraries

Referenzdokumentation (Bücher, Paper, Docs)

Multi-Mandanten-fähig via library_name

rules

Verhaltensregeln und Präferenzen

Multi-Mandanten-fähig via project_id

scratchpad

Temporärer Arbeitsspeicher

Pro Sitzung

CLI-Referenz

# 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

Siehe CLI-Referenz für die vollständige Dokumentation.

Konfiguration

Umgebungsvariablen

Variable

Standard

Beschreibung

QDRANT_URL

http://localhost:6333

Qdrant-Server-URL

QDRANT_API_KEY

-

API-Schlüssel (erforderlich für Qdrant Cloud)

FASTEMBED_MODEL

all-MiniLM-L6-v2

Embedding-Modell

Architektur

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

Der Rust-Daemon übernimmt die Dateiüberwachung, die Erstellung von Embeddings, die Extraktion des Code-Graphen und die Warteschlangenverarbeitung. Alle Schreibvorgänge werden zur Konsistenz über den Daemon geleitet.

Dokumentation

Benutzerhandbücher:

Referenz:

Siehe den Dokumentationsindex für Spezifikationen, ADRs und Entwicklerressourcen.

Entwicklung

# 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

Mitwirken

Siehe CONTRIBUTING.md für die Entwicklungseinrichtung und Richtlinien.

Lizenz

MIT-Lizenz - siehe LICENSE für Details.


Inspiriert von claude-qdrant-mcp

Available Tools

6 tools
grepB

Search code with exact substring or regex pattern matching. Uses FTS5 trigram index for fast line-level search across indexed files.

Inputs: pattern (required), regex, caseSensitive, pathGlob, +5 more.

listA

List project files and folder structure. Shows only indexed files (excludes gitignored, node_modules, etc). Use format "summary" first to understand project layout, then drill into specific folders with the path parameter.

Inputs: path, depth, format, fileType, +7 more.

retrieveA

Retrieve documents by ID or metadata filter. Use this to access specific documents when you know the document ID. Prefer search for discovery, retrieve for known documents.

Inputs: documentId, collection, filter, limit, +3 more.

rulesA

Manage behavioral rules (add, update, remove, list). Check active rules at the start of each session to load the user's behavioral preferences. Rules persist across sessions and guide how you should work.

Inputs: action (required), content, label, scope, +5 more.

storeA

Store content or register a project. Use type "library" (default) to store reference documentation, type "url" to fetch and ingest a web page, type "scratchpad" to save persistent notes/scratch space, or type "project" to register a project directory for file watching and ingestion.

Inputs: type, content, libraryName, forProject, +8 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct function: grep searches code lines, list navigates files, retrieve fetches known documents, rules manages preferences, search discovers content, and store ingests content. There is no functional overlap.

    Naming Consistency5/5

    All tool names are single lowercase verbs (grep, list, retrieve, rules, search, store), following a consistent and predictable pattern.

    Tool Count5/5

    With 6 tools covering searching, navigation, retrieval, storage, and rule management, the count is well-scoped for a workspace knowledge server without being excessive or sparse.

    Completeness4/5

    The tool surface covers the core workflows of searching, browsing, retrieving, storing, and managing rules. One minor gap is the lack of explicit update/delete operations for stored documents, though store may allow overwriting.

    Maintenance

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Persistent knowledge memory layer for AI agents. Hybrid semantic + full-text search with pgvector, code dependency graph with blast-radius impact analysis, and incremental indexing for 7 languages. In-process ONNX embeddings, no external API required.
      45 PyPI
      34
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Local-first semantic memory server with project indexing for AI assistants. It enables AI assistants to store, retrieve, and search memories and project code using embeddings and vector search.
      68 npm
      MIT