{"id":31537716,"url":"https://github.com/chrisgve/workspace-qdrant-mcp","last_synced_at":"2026-06-08T08:05:10.734Z","repository":{"id":312076093,"uuid":"1045853533","full_name":"ChrisGVE/workspace-qdrant-mcp","owner":"ChrisGVE","description":"Project-scoped Qdrant MCP server for workspace collections with scratchbook functionality. Python port of claude-qdrant-mcp with FastEmbed and project-aware collection management.","archived":false,"fork":false,"pushed_at":"2026-04-18T21:17:02.000Z","size":366458,"stargazers_count":1,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T21:31:17.068Z","etag":null,"topics":["ai-tools","asyncio","claude-code","claude-desktop","cli","document-management","embeddings","fastmcp","hybrid-search","mcp","mcp-server","model-context-protocol","pydantic","qdrant","search","semantic-search","vector-database","workspace"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChrisGVE.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-27T20:08:26.000Z","updated_at":"2026-04-18T21:16:54.000Z","dependencies_parsed_at":"2026-02-16T02:21:15.847Z","dependency_job_id":"7fd0b64c-cd81-43a8-9190-f4527dd33310","html_url":"https://github.com/ChrisGVE/workspace-qdrant-mcp","commit_stats":null,"previous_names":["chrisgve/workspace-qdrant-mcp"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/ChrisGVE/workspace-qdrant-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisGVE%2Fworkspace-qdrant-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisGVE%2Fworkspace-qdrant-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisGVE%2Fworkspace-qdrant-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisGVE%2Fworkspace-qdrant-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChrisGVE","download_url":"https://codeload.github.com/ChrisGVE/workspace-qdrant-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisGVE%2Fworkspace-qdrant-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32081122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T06:27:27.065Z","status":"ssl_error","status_checked_at":"2026-04-21T06:27:21.250Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","asyncio","claude-code","claude-desktop","cli","document-management","embeddings","fastmcp","hybrid-search","mcp","mcp-server","model-context-protocol","pydantic","qdrant","search","semantic-search","vector-database","workspace"],"created_at":"2025-10-04T08:10:46.222Z","updated_at":"2026-06-08T08:05:10.727Z","avatar_url":"https://github.com/ChrisGVE.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# workspace-qdrant-mcp\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-green.svg)](LICENSE)\n[![GitHub Release](https://img.shields.io/github/v/release/ChrisGVE/workspace-qdrant-mcp)](https://github.com/ChrisGVE/workspace-qdrant-mcp/releases)\n[![Glama](https://glama.ai/mcp/servers/ChrisGVE/workspace-qdrant-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ChrisGVE/workspace-qdrant-mcp)\n[![Homebrew](https://img.shields.io/badge/Homebrew-tap-orange.svg)](https://github.com/ChrisGVE/homebrew-tap)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue.svg)](https://www.typescriptlang.org/)\n[![Rust](https://img.shields.io/badge/Rust-1.75%2B-orange.svg)](https://www.rust-lang.org/)\n[![Qdrant](https://img.shields.io/badge/Qdrant-1.7%2B-red.svg)](https://qdrant.tech)\n\nProject-scoped vector database for AI assistants, providing hybrid semantic + keyword search with automatic project detection.\n\n## Features\n\n- **Hybrid Search** - Combines semantic similarity with keyword matching using Reciprocal Rank Fusion\n- **Project Detection** - Automatic Git repository awareness and project-scoped collections\n- **7 MCP Tools** - search, retrieve, rules, store, grep, list, embedding\n- **Code Intelligence** - Tree-sitter semantic chunking + LSP integration for active projects\n- **Code Graph** - Relationship graph with algorithms (PageRank, community detection, betweenness centrality)\n- **High-Performance CLI** - Rust-based `wqm` command-line tool\n- **Background Daemon** - `memexd` for continuous file monitoring and processing\n\n## Quick Start\n\n### Prerequisites\n\n- **Qdrant** - `docker run -d -p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrant`\n- **C compiler** - Required for compiling Tree-sitter grammars on first use. Tree-sitter grammars are distributed as C source and compiled locally.\n  - **macOS**: `xcode-select --install` (Xcode Command Line Tools)\n  - **Linux**: `apt install build-essential` (Debian/Ubuntu) or `dnf groupinstall \"Development Tools\"` (Fedora)\n  - **Windows**: Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with C++ workload\n\n### Install\n\n**Option 1: Homebrew (Recommended — macOS \u0026 Linux)**\n\n```bash\nbrew install ChrisGVE/tap/workspace-qdrant\nbrew services start workspace-qdrant\n```\n\n**Option 2: Pre-built Binaries**\n\n```bash\n# macOS / Linux\ncurl -fsSL https://raw.githubusercontent.com/ChrisGVE/workspace-qdrant-mcp/main/scripts/download-install.sh | bash\n\n# Windows (PowerShell)\nirm https://raw.githubusercontent.com/ChrisGVE/workspace-qdrant-mcp/main/scripts/download-install.ps1 | iex\n```\n\nInstalls `wqm` and `memexd` to `~/.local/bin` (Linux/macOS) or `%LOCALAPPDATA%\\wqm\\bin` (Windows).\n\n**Option 3: Build from Source**\n\n```bash\ngit clone https://github.com/ChrisGVE/workspace-qdrant-mcp.git\ncd workspace-qdrant-mcp\n./install.sh\n```\n\nSee [Installation Reference](docs/reference/installation.md) for detailed instructions and platform-specific notes. For Windows, see the [Windows Installation Guide](docs/reference/windows-installation.md).\n\n### Configure MCP\n\n**Claude Desktop** (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"workspace-qdrant-mcp\": {\n      \"command\": \"workspace-qdrant-mcp\",\n      \"env\": {\n        \"QDRANT_URL\": \"http://localhost:6333\"\n      }\n    }\n  }\n}\n```\n\n**Claude Code**:\n\n```bash\nclaude mcp add workspace-qdrant-mcp -- workspace-qdrant-mcp\n```\n\n### Verify\n\n```bash\nwqm --version\nwqm status health\n```\n\n### CLAUDE.md Integration\n\nAdd the following to your project's `CLAUDE.md` (or your global `~/.claude/CLAUDE.md`) so Claude Code uses workspace-qdrant proactively:\n\n````markdown\n## workspace-qdrant\n\nThe `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.\n\n### Primary Search and Knowledge Base\n\n**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.\n\n**Three-step protocol:**\n1. **Search** with `workspace-qdrant` (`search`, `grep`, `list`, or `retrieve`)\n2. **Fall back** to `Grep`, `Glob`, `WebSearch` only when workspace-qdrant is insufficient or unavailable\n3. **Store** any new findings, analysis, or design rationale via `store` so they are retrievable in future sessions\n\nWhen a fresh handover or strong prior context already covers what you need, skip the exploratory search — but always store new findings at the end.\n\n**Collections and their purpose:**\n- `projects` — indexed codebase; use `scope=\"project\"` (current project) or `scope=\"all\"` (across all projects)\n- `libraries` — external reference docs, API specs, third-party documentation; add via `store` with `collection=\"libraries\"` and search with `includeLibraries=true`\n- `scratchpad` — analysis, design rationale, research transcripts, architectural insights; complements session handovers by building a growing, semantically searchable knowledge layer across sessions\n- `rules` — persistent behavioral rules; load at session start via `rules` → `action=\"list\"`\n\n**Practical notes:**\n- Use `grep` for exact strings or regex; `list` with `format=\"summary\"` to explore project structure\n- Store external docs or specs into `libraries` so they are searchable alongside code\n- Use the scratchpad to record *why* decisions were made, not just *what* was done — future sessions can retrieve the reasoning\n\n### Sub-Agents\n\nSub-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:\n\n\u003e \"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.\"\n\n### Project Registration\n\nAt 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.\n\n### Behavioral Rules\n\nThe `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.\n\n### Issue Reporting\n\nworkspace-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.\n````\n\n## MCP Tools\n\n| Tool | Purpose |\n|------|---------|\n| `search` | Hybrid semantic + keyword search across indexed content |\n| `retrieve` | Direct document lookup by ID or metadata filter |\n| `rules` | Manage persistent behavioral rules |\n| `store` | Store content, register projects, save notes |\n| `grep` | Exact substring or regex search using FTS5 |\n| `list` | List project files and folder structure |\n\nSee [MCP Tools Reference](docs/reference/mcp-tools.md) for parameters and examples.\n\n## Collections\n\n| Collection | Purpose | Isolation |\n|------------|---------|-----------|\n| `projects` | Project code and documentation | Multi-tenant by `tenant_id` |\n| `libraries` | Reference documentation (books, papers, docs) | Multi-tenant by `library_name` |\n| `rules` | Behavioral rules and preferences | Multi-tenant by `project_id` |\n| `scratchpad` | Temporary working storage | Per-session |\n\n## CLI Reference\n\n```bash\n# Service management\nwqm service start              # Start background daemon\nwqm service status             # Check daemon status\nwqm status health              # System health check\n\n# Search and content\nwqm search \"query\"             # Search collections\nwqm ingest file path.py        # Ingest a file\nwqm rules list                 # List behavioral rules\n\n# Project and library\nwqm project list               # List registered projects\nwqm project watch pause        # Pause file watchers\nwqm library list               # List libraries\nwqm tags list                  # List tags with counts\n\n# Administration\nwqm admin collections list     # List collections\nwqm admin rebuild all          # Rebuild all indexes\nwqm admin backup create        # Backup snapshots\nwqm admin stats overview       # Search analytics\n\n# Code graph\nwqm graph stats --tenant \u003ct\u003e   # Node/edge counts\nwqm graph query --node-id \u003cid\u003e --tenant \u003ct\u003e --hops 2   # Related nodes\nwqm graph impact --symbol \u003cname\u003e --tenant \u003ct\u003e           # Impact analysis\nwqm graph pagerank --tenant \u003ct\u003e --top-k 20              # PageRank centrality\n\n# Setup\nwqm init completions zsh       # Shell completions\nwqm init man install           # Install man pages\nwqm init hooks install         # Install Claude Code hooks (respects CLAUDE_CONFIG_DIR)\n\n# Queue and monitoring\nwqm queue stats                # Queue statistics\n```\n\nSee [CLI Reference](docs/reference/cli.md) for complete documentation.\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `QDRANT_URL` | `http://localhost:6333` | Qdrant server URL |\n| `QDRANT_API_KEY` | - | API key (required for Qdrant Cloud) |\n| `FASTEMBED_MODEL` | `all-MiniLM-L6-v2` | Embedding model |\n\n### Claude Code Integration\n\n`wqm init hooks` reads and writes Claude Code's `settings.json`. The\nlocation is resolved from:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CLAUDE_CONFIG_DIR` | `~/.claude` | Claude Code config directory used by `wqm init hooks install/uninstall/status`. Set this for Claude Code Enterprise or any non-default install. |\n\nExample — Claude Code Enterprise:\n\n```bash\nexport CLAUDE_CONFIG_DIR=~/.config/claude/claude-ent\nwqm init hooks install\n```\n\n## Observability\n\nThe daemon exposes metrics and traces. Both are disabled by default.\n\n### Prometheus (`/metrics`, pull)\n\nEnable via config or env var, then scrape:\n\n```yaml\n# in the daemon config\nobservability:\n  telemetry:\n    prometheus:\n      enabled: true\n      port: 9464\n      bind: 0.0.0.0\n```\n\nor:\n\n```bash\nWQM_PROMETHEUS_ENABLED=true WQM_PROMETHEUS_PORT=9464 memexd --foreground\ncurl http://localhost:9464/metrics | head\n```\n\nThe `--metrics-port \u003cN\u003e` CLI flag is a shortcut that forces\n`enabled=true` and overrides the port. See\n`docs/observability/prometheus-scrape-example.yaml` for a\n`scrape_configs` snippet and\n`docs/observability/memexd-telemetry-dashboard.json` for a Grafana 10\ndashboard.\n\n### OTLP traces (push)\n\n`#[tracing::instrument]` spans on the queue processor, watcher, gRPC,\nembedding, and Qdrant paths are exported over OTLP/gRPC when:\n\n```yaml\nobservability:\n  telemetry:\n    service_name: memexd\n    otlp:\n      enabled: true\n      endpoint: http://collector.example:4317\n      protocol: grpc   # http/protobuf is also recognized (logs a warning)\n      sample_rate: 0.1\n```\n\nStandard OpenTelemetry env vars are honored: `OTEL_SERVICE_NAME`,\n`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`,\n`OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_TRACES_SAMPLER_ARG`.\n\nOTLP metrics export is **not** currently implemented — Prometheus is\nthe canonical metrics surface.\n\n## Architecture\n\n```\n                    +-----------------+\n                    |  Claude/Client  |\n                    +--------+--------+\n                             |\n                    +--------v--------+\n                    |   MCP Server    |  (TypeScript)\n                    +--------+--------+\n                             |\n              +--------------+--------------+\n              |                             |\n     +--------v--------+           +--------v--------+\n     |   Rust Daemon   |           |     Qdrant      |\n     |    (memexd)     |           | Vector Database |\n     +--------+--------+           +-----------------+\n              |\n     +--------v--------+\n     |  File Watcher   |\n     |  Code Graph     |\n     |  Embeddings     |\n     +-----------------+\n```\n\nThe Rust daemon handles file watching, embedding generation, code graph extraction, and queue processing. All writes route through the daemon for consistency.\n\n## Documentation\n\n**User guides:**\n- [Quick Start](docs/quick-start.md) — get running in 5 minutes\n- [User Manual](docs/user-manual.md) — full usage guide\n- [LLM Integration](docs/reference/mcp-best-practices.md) — best practices for Claude\n\n**Reference:**\n- [Installation](docs/reference/installation.md) | [Windows](docs/reference/windows-installation.md)\n- [CLI Reference](docs/reference/cli.md) — all `wqm` commands\n- [MCP Tools](docs/reference/mcp-tools.md) — tool parameters and examples\n- [Configuration](docs/reference/configuration.md) — all options and defaults\n- [Architecture](docs/reference/architecture.md) — component overview\n\nSee the [Documentation Index](docs/INDEX.md) for specifications, ADRs, and developer resources.\n\n## Development\n\n```bash\n# Rust daemon, CLI, and MCP server (from src/rust/)\n# Builds memexd (daemon), wqm (CLI), and workspace-qdrant-mcp (MCP server)\ncargo build --release\ncargo test\n\n# Graph benchmarks\ncargo bench --package workspace-qdrant-core --bench graph_bench\n\n# Binaries output to:\n# - target/release/wqm\n# - target/release/memexd\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n\n## License\n\nApache License 2.0 - see [LICENSE](LICENSE) for details.\n\n---\n\n*Inspired by [claude-qdrant-mcp](https://github.com/marlian/claude-qdrant-mcp)*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrisgve%2Fworkspace-qdrant-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchrisgve%2Fworkspace-qdrant-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrisgve%2Fworkspace-qdrant-mcp/lists"}