GrooveSeek
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 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.
日本語版: README.ja.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:
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.zipon 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 directorygrammar_dirnames, 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:
groove index --kb-path /path/to/knowledge-base
{
"mcpServers": {
"ai-knowledge": {
"command": "/path/to/groove",
"args": ["serve", "--kb-path", "/path/to/knowledge-base"],
"type": "stdio"
}
}
}
That goes in .mcp.json in your project root, or the equivalent MCP config for
your client. You can also query without a client at all:
groove search "semantic chunking" --kb-path /path/to/knowledge-base --limit 3
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.
Documentation
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.