MCP server for hybrid (semantic + full-text) search over a knowledge base of
Markdown — and, opted in, plain text, PDF, Office documents and source code.
The command is groove.
Out of the box — no config file, default model — it indexes English Markdown
with YAML frontmatter. Japanese or other multilingual content needs
--model bge-m3; every other file format is an opt-in in .
MCP server for semantic hybrid search (sqlite-vec + FTS5 with optional cross-encoder reranking) over a Markdown / plain-text knowledge base
Estrellas
10
Herramientas
—
Disponibilidad
—
groove.toml
Parses Markdown (and optionally .txt / .pdf / .docx / .xlsx / .pptx, plus Rust source since v1.2.0, and Python since v1.3.0 and PHP since v1.5.0, whose grammars you download and place) files with YAML frontmatter, splits them into heading-based chunks — or, for source code, one chunk per definition, generates embeddings with FastEmbed by default (BGE-small-en-v1.5, or BGE-M3 for multilingual/Japanese knowledge bases), and stores everything in SQLite with sqlite-vec for vector similarity search. A trusted configuration can instead opt into an OpenAI-compatible embedding endpoint. Connects to Claude Code, Cursor, or any MCP-compatible client via stdio (default, 1 client) or Streamable HTTP (many clients) transport.
A live-sync file watcher keeps the index fresh on manual edits, git pull, and external scripts; an optional TOML schema can validate frontmatter conventions via groove validate, and since v1.9.0 the additional keys it declares (beyond title / date / topic / depth / tags) are stored by groove index so groove search --field can filter on them.
A third-party benchmark against QMD on a 57-document synthetic corpus — like-for-like
numbers, the classes GrooveSeek lost or tied, and what decided it — is reproduced with
attribution in docs/eval.md.
Versioning: releases before 1.0.0 are beta and carry no compatibility
guarantee. From 1.0.0, what this project promises not to break — and what it
deliberately does not promise, including the web interface and the Rust API — is
written down in docs/stability.md.
Install
Pre-built binaries (recommended for non-Rust users)
Download the archive for your platform from the latest GitHub release, extract it, and place groove (or groove.exe on Windows) somewhere on PATH. Available targets:
Intel Mac (x86_64-apple-darwin) is not shipped as a prebuilt: the upstream ONNX Runtime crate (ort-sys) does not provide a binary for that target. Build from source as described below.
Windows: two more archives, if you will run groove as a service. They are separate downloads (v0.14.0+), and both belong in the same directory as groove.exe:
Archive
Why
groove-svc-x86_64-pc-windows-msvc.zip
groove service install points the logon task at groove-svc.exe when it sits next to groove.exe, and falls back to a console-visible launcher when it does not — which means a console window flashes at every login. The fallback is reported as a warning, but extracting this archive before running service install saves you the second install.
groove-tray-x86_64-pc-windows-msvc.zip
Optional. The system tray monitor; needed only for service install --with-tray.
A language whose grammar is not compiled in needs one more archive. Rust is built into groove; every other language arrives as its own download — groove-grammar-<language>-<target>.tar.xz, or .zip on Windows, built for the same targets as the table above. Published so far: groove-grammar-python (v1.3.0+, enabled as "py"), groove-grammar-php (v1.5.0+, as "php"). Unpack the library into the directory grammar_dir names, then add that id to [parsers].enabled. Nothing is downloaded automatically, and no library is opened unless that key names the language it belongs to — see Placing a grammar plugin.
Each archive ships the binary plus CHANGELOG.md, LICENSE-MIT, LICENSE-APACHE, THIRD-PARTY-LICENSES.md (the notices of every crate linked in), and README.md. Verify the SHA-256 checksum (each release exposes sha256.sum and per-archive *.sha256 files) before running. Archives are also signed with a GitHub artifact attestation; gh attestation verify <archive> --repo alphabet-h/grooveseek checks that a download was built by GitHub Actions in this repository.
ONNX runtime and SQLite are statically linked into the binary, so no extra DLLs are required. With the default FastEmbed provider, embedding models (ONNX) are downloaded from HuggingFace on first run — see Working around HuggingFace TLS failures if your network blocks that.
Build from source
cargo build --release
The binary is produced at target/release/groove (or groove.exe on Windows).
Quick start
Index a knowledge base, then point an MCP client at it:
For a Japanese or otherwise multilingual knowledge base, pass --model bge-m3
to index and serve alike. It is a larger download and a different index, so
it is worth choosing before you build one — the trade-off is in
docs/usage.md.
With --transport http, the server also answers on /ui: an operator view of
the machine it runs on, searching through the same /mcp endpoint an MCP client
uses.
What 1.0.0 freezes, and what it deliberately does not
A Japanese version of every page above sits alongside it as *.ja.md.
Ready-to-adapt deployment recipes — personal stdio, NAS-shared, intranet HTTP —
are in grooveseek/examples/deployments/.
Those are repository paths. The same pages are published as a site at
https://alphabet-h.github.io/grooveseek/, which is where to read them if you
installed from a release archive — the archive carries this README but not
docs/. The site tracks main; to read the version you installed instead, open
https://github.com/alphabet-h/grooveseek/tree/main/docs with main replaced by
your release tag.
MCP surface
Six tools — search, get_document, list_topics, get_connection_graph,
get_best_practice, rebuild_index — four prompts, and the knowledge base
itself exposed as kb:// resources. Parameters and return shapes are in
docs/mcp-tools.md.
Design decisions
Decisions that shaped the architecture — what was chosen, which alternatives were rejected, and what it cost — are recorded as Architecture Decision Records in docs/decisions/. Start with ADR-0000, which describes when a decision is recorded and when a changelog entry is enough. Japanese versions are alongside as *.ja.md.
Security
Report a vulnerability through GitHub's private reporting rather than a public
issue — the steps, the response target and what is in scope are in
SECURITY.md.
License
Dual-licensed under MIT or Apache-2.0, at
your option. The licenses of the crates linked into the binaries are collected
in THIRD-PARTY-LICENSES.md.
G
Grooveseek
alphabet-h·10 estrellas·
MCP server for semantic hybrid search (sqlite-vec + FTS5 with optional cross-encoder reranking) over a Markdown / plain-text knowledge base
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Preguntas
¿Cómo instalo Grooveseek?
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
¿Grooveseek necesita una clave de API?
Este registro no indica ninguna variable de entorno obligatoria.
¿Qué transporte usa Grooveseek?
Grooveseek se ejecuta localmente por stdio.
¿Cuándo se comprobó Grooveseek por última vez?
Última comprobación: 2026-10-28. MCP server for semantic hybrid search (sqlite-vec + FTS5 with optional cross-encoder reranking) over a Markdown / plain-text knowledge base