Workspace Qdrant MCP
workspace-qdrant-mcp
AI 어시스턴트를 위한 프로젝트 범위의 벡터 데이터베이스로, 자동 프로젝트 감지 기능을 갖춘 하이브리드 의미론적 + 키워드 검색을 제공합니다.
기능
하이브리드 검색 - Reciprocal Rank Fusion을 사용하여 의미론적 유사성과 키워드 매칭을 결합합니다.
프로젝트 감지 - 자동 Git 저장소 인식 및 프로젝트 범위의 컬렉션 관리
6가지 MCP 도구 - search, retrieve, rules, store, grep, list
코드 인텔리전스 - 활성 프로젝트를 위한 Tree-sitter 의미론적 청킹 + LSP 통합
코드 그래프 - 알고리즘(PageRank, 커뮤니티 탐지, 매개 중심성)을 포함한 관계 그래프
고성능 CLI - Rust 기반
wqm명령줄 도구백그라운드 데몬 - 지속적인 파일 모니터링 및 처리를 위한
memexd
Related MCP server: Super-Memory-TS
빠른 시작
사전 요구 사항
Qdrant -
docker run -d -p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrantC 컴파일러 - 처음 사용할 때 Tree-sitter 문법을 컴파일하는 데 필요합니다. Tree-sitter 문법은 C 소스로 배포되며 로컬에서 컴파일됩니다.
macOS:
xcode-select --install(Xcode Command Line Tools)Linux:
apt install build-essential(Debian/Ubuntu) 또는dnf groupinstall "Development Tools"(Fedora)Windows: C++ 워크로드가 포함된 Visual Studio Build Tools를 설치하세요.
설치
옵션 1: Homebrew (권장 — macOS & Linux)
brew install ChrisGVE/tap/workspace-qdrant
brew services start workspace-qdrant옵션 2: 사전 빌드된 바이너리
# 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 | iexwqm 및 memexd를 ~/.local/bin(Linux/macOS) 또는 %LOCALAPPDATA%\wqm\bin(Windows)에 설치합니다.
옵션 3: 소스에서 빌드
git clone https://github.com/ChrisGVE/workspace-qdrant-mcp.git
cd workspace-qdrant-mcp
./install.sh자세한 지침 및 플랫폼별 참고 사항은 설치 참조를 확인하세요. Windows의 경우 Windows 설치 가이드를 참조하세요.
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확인
wqm --version
wqm status healthCLAUDE.md 통합
Claude Code가 workspace-qdrant를 선제적으로 사용하도록 프로젝트의 CLAUDE.md(또는 전역 ~/.claude/CLAUDE.md)에 다음을 추가하세요:
## 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 도구
도구 | 목적 |
| 인덱싱된 콘텐츠 전반에 걸친 하이브리드 의미론적 + 키워드 검색 |
| ID 또는 메타데이터 필터를 통한 직접적인 문서 조회 |
| 지속적인 행동 규칙 관리 |
| 콘텐츠 저장, 프로젝트 등록, 메모 저장 |
| FTS5를 사용한 정확한 부분 문자열 또는 정규식 검색 |
| 프로젝트 파일 및 폴더 구조 나열 |
매개변수 및 예제는 MCP 도구 참조를 확인하세요.
컬렉션
컬렉션 | 목적 | 격리 |
| 프로젝트 코드 및 문서 |
|
| 참조 문서 (도서, 논문, 문서) |
|
| 행동 규칙 및 환경 설정 |
|
| 임시 작업 저장소 | 세션별 |
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전체 문서는 CLI 참조를 확인하세요.
구성
환경 변수
변수 | 기본값 | 설명 |
|
| Qdrant 서버 URL |
| - | API 키 (Qdrant Cloud에 필요) |
|
| 임베딩 모델 |
아키텍처
+-----------------+
| Claude/Client |
+--------+--------+
|
+--------v--------+
| MCP Server | (TypeScript)
+--------+--------+
|
+--------------+--------------+
| |
+--------v--------+ +--------v--------+
| Rust Daemon | | Qdrant |
| (memexd) | | Vector Database |
+--------+--------+ +-----------------+
|
+--------v--------+
| File Watcher |
| Code Graph |
| Embeddings |
+-----------------+Rust 데몬은 파일 감시, 임베딩 생성, 코드 그래프 추출 및 큐 처리를 담당합니다. 일관성을 위해 모든 쓰기 작업은 데몬을 통해 라우팅됩니다.
문서
사용자 가이드:
참조:
사양, ADR 및 개발자 리소스는 문서 인덱스를 확인하세요.
개발
# 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기여
개발 설정 및 지침은 CONTRIBUTING.md를 확인하세요.
라이선스
MIT 라이선스 - 자세한 내용은 LICENSE를 참조하세요.
claude-qdrant-mcp에서 영감을 받음
Available Tools
6 toolsgrepB
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.
searchA
Search for documents using hybrid semantic and keyword search. Use this tool FIRST when answering questions about the user's codebase, project architecture, or stored knowledge. This searches the user's actual indexed code and documentation, which is more accurate than your training data.
Inputs: query (required), collection, mode, scope, +14 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
Scored across 6 tools
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.
All tool names are single lowercase verbs (grep, list, retrieve, rules, search, store), following a consistent and predictable pattern.
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.
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
Related MCP Connectors
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Universal memory for AI agents and tools. Save, organize and search context anywhere.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenancePersistent 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 PyPI34MIT
- AlicenseNot gradedqualityDmaintenanceLocal-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 npmMIT
- AlicenseCqualityBmaintenanceGives AI coding assistants persistent project memory and semantic code search, running fully locally with no API keys required.56MIT
- AlicenseNot gradedqualityFmaintenanceIndexes codebases into Qdrant for semantic search, enabling AI assistants to find relevant code by meaning without re-exploring the repo.MIT