grooveseek

<picture> <source media="(prefers-color-scheme: dark)" srcset="https://github.com/alphabet-h/grooveseek/raw/main/assets/grooveseek-readme-hero-dark-v2.webp"> <img src="https://github.com/alphabet-h/grooveseek/raw/main/assets/grooveseek-readme-hero-light-v2.webp" alt="Markdown files flow into a chunker, a semantic path and a lexical path converge on one node, and ranked results leave it for an MCP client." width="100%"> </picture> # 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`. [](https://github.com/alphabet-h/grooveseek/actions/workflows/ci.yml) [](https://github.com/alphabet-h/grooveseek/releases/latest) [](https://alphabet-h.github.io/grooveseek/) [](#license) 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](docs/usage.md#external-openai-compatible-embeddings). 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](./docs/eval.md#a-third-party-measurement). > **日本語版**: [README.ja.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](./docs/stability.md). ## Install ### Pre-built binaries (recommended for non-Rust users) Download the archive for your platform from the [latest GitHub release](https://github.com/alphabet-h/grooveseek/releases/latest), extract it, and place `groove` (or `groove.exe` on Windows) somewhere on `PATH`. Available targets: | Platform | Archive | | --- | --- | | Linux x86_64 (glibc 2.38+ / Ubuntu 24.04+ / Debian 13+ / RHEL 9.5+) | `grooveseek-x86_64-unknown-linux-gnu.tar.xz` | | Linux aarch64 (glibc 2.38+) | `grooveseek-aarch64-unknown-linux-gnu.tar.xz` | | macOS Apple Silicon | `grooveseek-aarch64-apple-darwin.tar.xz` | | Windows x86_64 (Windows 10+) | `grooveseek-x86_64-pc-windows-msvc.zip` | > **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](docs/clients.md#placing-a-grammar-plugin-v130). 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](docs/clients.md#working-around-huggingface-tls-failures-on-first-download) if your network blocks that. ### Build from source ```bash 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: ```bash groove index --kb-path /path/to/knowledge-base ``` <!-- groove-pin: mcp-stdio-snippet --> ```json { "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: ```bash 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](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. <picture> <source media="(prefers-color-scheme: dark)" srcset="https://github.com/alphabet-h/grooveseek/raw/main/assets/screenshot-dark.png"> <img src="https://github.com/alphabet-h/grooveseek/raw/main/assets/screenshot-light.png" width="880" alt="The operator view: a status band showing version, document and chunk counts, the embedding model, watcher state, uptime and pid, above a search box and a list of results, each with a relevance score, a file path, a heading and its tags."> </picture> ## Documentation | Page | What is in it | | --- | --- | | [docs/usage.md](docs/usage.md) | Every command: `index`, `status`, `serve`, `search`, `graph`, `validate`, `doctor`, `eval`, `tune`, `service` | | [docs/configuration.md](docs/configuration.md) | Every `groove.toml` key, the discovery order, and which locations are trusted | | [docs/clients.md](docs/clients.md) | `.mcp.json` recipes, the HTTP transport, the PostToolUse hook, the file watcher | | [docs/mcp-tools.md](docs/mcp-tools.md) | The MCP surface: tools, prompts, and `kb://` resources | | [docs/behavior.md](docs/behavior.md) | What gets indexed, where it is stored, and which files are refused | | [docs/deployment-topologies.md](docs/deployment-topologies.md) | Which process shape to deploy, what residency costs, and where the same-host boundary comes from | | [docs/retrieval-pipeline.md](docs/retrieval-pipeline.md) | RRF, reranking, MMR, and parent retriever, in the order they run | | [docs/filters.md](docs/filters.md) | Narrowing search results | | [docs/citations.md](docs/citations.md) | `match_spans` and byte offsets, for quoting sources accurately | | [docs/eval.md](docs/eval.md) | Measuring retrieval quality against a golden query set | | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Source layout, and how a query flows through it | | [docs/stability.md](docs/stability.md) | 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/`](./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](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](docs/decisions/) in `docs/decisions/`. Start with [ADR-0000](docs/decisions/0000-record-decisions-as-adrs.md), 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](./SECURITY.md). ## License Dual-licensed under [MIT](./LICENSE-MIT) or [Apache-2.0](./LICENSE-APACHE), at your option. The licenses of the crates linked into the binaries are collected in [THIRD-PARTY-LICENSES.md](./THIRD-PARTY-LICENSES.md).