@oomkapwn/enquire-mcp 3.6.1 → 3.6.2

package/docs/COMPARISON.md

@@ -1,6 +1,6 @@
 # enquire-mcp vs. other Obsidian MCP servers
 
-There are several MCP servers for Obsidian vaults, and they make very different trade-offs. This document is a side-by-side feature matrix plus an honest "when to pick which" guide, written by the enquire-mcp maintainer. It is intentionally fair-not-sales: each alternative has scenarios where it is the better pick, and those scenarios are called out below. Numbers and feature claims for enquire-mcp are accurate as of v3.5.8 (2026-05-13); claims about the four alternatives are based on their public READMEs as of the same date — please verify against their current state before deciding.
+There are several MCP servers for Obsidian vaults, and they make very different trade-offs. This document is a side-by-side feature matrix plus an honest "when to pick which" guide, written by the enquire-mcp maintainer. It is intentionally fair-not-sales: each alternative has scenarios where it is the better pick, and those scenarios are called out below. Numbers and feature claims for enquire-mcp are accurate as of v3.6.1 (2026-05-15); claims about the four alternatives are based on their public READMEs as of the same date — please verify against their current state before deciding.
 
 ## Servers compared
 
@@ -56,7 +56,7 @@ Notes on the matrix:
 
 - **"Limited" for markus on Obsidian-side operations:** it covers a smaller subset of REST endpoints than cyanheads.
 
-- **Tool counts for alternatives** are approximate from public READMEs and may have shifted. enquire-mcp's 44-tool count is exact for v3.5.8 and is verified by the test suite.
+- **Tool counts for alternatives** are approximate from public READMEs and may have shifted. enquire-mcp's 44-tool count is exact for v3.6.1 and is verified by `tests/docs-consistency.test.ts` against `src/tool-manifest.ts` (machine-readable single source of truth, introduced v3.6.0-rc.2).
 
 - **License row** is informational, not a recommendation. MIT and Apache-2.0 are both permissive; pick what your org's policy requires.
 
@@ -233,13 +233,13 @@ This is a rough heuristic, not a verdict. The "when to pick X" sections above ar
 
 ## A note on benchmarks
 
-None of these servers (including enquire-mcp) ships a public, reproducible end-to-end retrieval benchmark against a shared Obsidian vault. The +5–10 NDCG@10 figure for the reranker is from the BGE model card on a standard IR benchmark, not from an enquire-mcp-specific eval. If retrieval quality is decisive for you, the only honest answer is **run a small eval against your own vault**. The `bench/` directory in this repo has scaffolding for that.
+As of v3.6.0-rc.4, **enquire-mcp ships public, reproducible end-to-end retrieval benchmarks** at [`docs/benchmarks.md`](./benchmarks.md): a 60-query ablation across 7 stack configurations on a deterministic synthetic Obsidian vault. Reproducible with `npm run bench:retrieval` (4-decimal precision across runs). Headline: `rerank-bge` adds **+24.7 MRR / +15.5 NDCG@10** over plain hybrid. The other alternatives in this matrix do not (as of 2026-05-15) ship comparable public benchmarks. If retrieval quality is decisive, **run our `bench:retrieval` against your own vault**, then run any equivalent eval (or hand-eval) the alternatives provide.
 
 ---
 
 ## Disclaimer
 
-This is a snapshot as of **2026-05-13**. All five servers are actively developed (or in some cases archived) and the feature matrix will drift. Before making a decision:
+This is a snapshot as of **2026-05-15** (v3.6.1). All five servers are actively developed (or in some cases archived) and the feature matrix will drift. Before making a decision:
 
 1. Re-read each alternative's current `README.md` — features land between matrix updates.
 2. Run each candidate against a sample of your own vault for an hour. Retrieval quality, in particular, is vault-specific and unreliable to compare from feature lists alone.
@@ -247,4 +247,4 @@ This is a snapshot as of **2026-05-13**. All five servers are actively developed
 
 Corrections to this document are welcome — open an issue or PR on [`oomkapwn/enquire-mcp`](https://github.com/oomkapwn/enquire-mcp). Specifically: if a row above understates an alternative's capabilities, that's a bug in this doc and we'd like to fix it.
 
-— enquire-mcp maintainer, v3.5.8
+— enquire-mcp maintainer, v3.6.1

package/docs/QUICKSTART.md

@@ -27,7 +27,7 @@ Verify the install:
 enquire-mcp --version
 ```
 
-Expected output: the current version string (e.g. `3.5.8`).
+Expected output: the current version string (e.g. `3.6.1`).
 
 ## Step 2 — Smoke test (30 seconds)
 
@@ -139,7 +139,7 @@ The drop-in hybrid config is in [`examples/claude-desktop-hybrid.json`](../examp
 
 **`enquire-mcp: command not found`.** The npm global bin directory isn't on your `PATH`. Run `npm config get prefix` to find it, then add `<prefix>/bin` to your `PATH` — or switch to the `npx` form of the Claude Desktop config (see Step 3): `"command": "npx"`, `"args": ["-y", "@oomkapwn/enquire-mcp@latest", "serve", "--vault", "/abs/path"]`.
 
-**`ENOENT` or `unsupported engine` on install.** You're on Node < 20. Run `node --version` to confirm, then upgrade (e.g. via `nvm install 20 && nvm use 20`). enquire-mcp targets Node 20 / 22 / 24 — the CI matrix runs all three.
+**`ENOENT` or `unsupported engine` on install.** You're on Node < 22. Run `node --version` to confirm, then upgrade (e.g. via `nvm install 22 && nvm use 22`). enquire-mcp's CI matrix tests Node 22 + 24 (Node 20 dropped in v3.5.11 — `pdfjs-dist@5.7+` requires `>=22.13`; the package's `engines: >=20` is still honored for non-PDF users on the prebuilt `dist/`).
 
 **`Error: vault path does not exist`.** Either the path is wrong, or you used `~` instead of the absolute form. MCP clients don't expand `~` — use `/Users/you/MyVault` on macOS/Linux or `C:\Users\you\MyVault` on Windows. Paths containing spaces are fine as long as the JSON string itself is well-formed; no shell escaping needed inside `claude_desktop_config.json`.
 

package/docs/api.md

@@ -1,8 +1,8 @@
 # enquire — API
 
-**enquire is an MCP server for Obsidian vaults.** 44 MCP tools (33 always-on read + 4 opt-in read + 7 opt-in write); the 4 opt-ins are: 1 via `--persistent-index` (`obsidian_full_text_search`) + 3 via `--diagnostic-search-tools` (the single-ranker `obsidian_search_text` / `obsidian_semantic_search` / `obsidian_embeddings_search` — gated by default in v2.0+ since `obsidian_search` auto-detects + fuses signals). 2 + 1 opt-in MCP resources, 19 MCP prompts. **v3.1.0+ adds `obsidian_hyde_search`** (HyDE-augmented retrieval, Gao et al 2023; agent supplies a synthetic answer, server embeds it for retrieval) plus the `vault_research` (sub-question decomposition) and `vault_synthesis_page` (Karpathy LLM-Wiki synthesis loop) prompts. v2.6.0+ also speaks Streamable HTTP via `serve-http` (bearer auth + rate-limit + CORS). v2.7.0+ indexes PDFs as a separate read tool surface; **v2.8.0+ blends PDF chunks into `obsidian_search` hybrid retrieval** with `--include-pdfs` — every hit carries a `kind: "md" | "pdf"` flag and PDF snippets include `[page: N]` markers for citation. **v2.9.0+ adds BGE cross-encoder reranking** on top of RRF with `--enable-reranker` — typical +5-10 NDCG@10 retrieval-quality boost. **v2.10.0+ adds Tesseract OCR for image-only / scanned PDFs** via `obsidian_ocr_pdf` — completes the PDF retrieval story.
+**enquire is an MCP server for Obsidian vaults.** 44 MCP tools (33 always-on read + 4 opt-in read + 7 opt-in write); the 4 opt-ins are: 1 via `--persistent-index` + `--diagnostic-search-tools` (`obsidian_full_text_search` — needs BOTH flags: persistent-index for the FTS5 index, diagnostic-search-tools to surface it as a single-ranker tool alongside the hybrid default `obsidian_search`) + 3 via `--diagnostic-search-tools` (the single-ranker `obsidian_search_text` / `obsidian_semantic_search` / `obsidian_embeddings_search` — gated by default in v2.0+ since `obsidian_search` auto-detects + fuses signals). 2 + 1 opt-in MCP resources, 19 MCP prompts. **v3.1.0+ adds `obsidian_hyde_search`** (HyDE-augmented retrieval, Gao et al 2023; agent supplies a synthetic answer, server embeds it for retrieval) plus the `vault_research` (sub-question decomposition) and `vault_synthesis_page` (Karpathy LLM-Wiki synthesis loop) prompts. v2.6.0+ also speaks Streamable HTTP via `serve-http` (bearer auth + rate-limit + CORS). v2.7.0+ indexes PDFs as a separate read tool surface; **v2.8.0+ blends PDF chunks into `obsidian_search` hybrid retrieval** with `--include-pdfs` — every hit carries a `kind: "md" | "pdf"` flag and PDF snippets include `[page: N]` markers for citation. **v2.9.0+ adds BGE cross-encoder reranking** on top of RRF with `--enable-reranker` — typical +5-10 NDCG@10 retrieval-quality boost. **v2.10.0+ adds Tesseract OCR for image-only / scanned PDFs** via `obsidian_ocr_pdf` — completes the PDF retrieval story.
 
-> **Channels:** stable v1.x (`@latest` on npm) ships 28 tools — no ML embeddings, no hybrid search. **v2.0 beta** (`@beta` on npm) adds `obsidian_search` (hybrid RRF) + `obsidian_embeddings_search` + the `install-model` / `build-embeddings` / `clear-embeddings` subcommands. This document covers the **v2.0 beta** surface.
+> **Channels:** stable v3.6.x (`@latest` on npm) ships 44 tools including `obsidian_search` (hybrid BM25 + TF-IDF + ML embeddings, RRF-fused) with optional BGE cross-encoder reranking, `obsidian_embeddings_search`, `obsidian_hyde_search`, plus the `install-model` / `build-embeddings` / `clear-embeddings` / `setup` / `doctor` / `eval` / `bench` subcommands. The `@rc` dist-tag carries the most recent release candidate. This document covers the **v3.6.x stable** surface.
 
 > Versioned dynamically — see [`CHANGELOG.md`](../CHANGELOG.md) for the current release.
 
@@ -79,7 +79,7 @@ Canonical list of every registered MCP tool. The `Kind` column splits read/write
 | `--cache-size <n>`     | 1024    | LRU cap for parsed-note cache.             |
 | `--persistent-cache`   | off     | Persist parsed-note cache to disk so cold starts skip re-parsing. **Stores full note bodies — see [Cache & privacy](../README.md#cache--privacy).** |
 | `--cache-file <path>`  | auto    | Override the persistent-cache file location. Default: `~/Library/Caches/enquire/<vault-hash>.json` (macOS) or `~/.cache/enquire/<vault-hash>.json` (Linux). |
-| `--persistent-index`   | off     | Maintain a SQLite FTS5 inverted index for sub-100ms BM25-ranked search. Registers `obsidian_full_text_search` + the `obsidian://chunk/{n}/{path}` resource. **Stores chunked note content + tag list + wikilink targets — see [SECURITY.md "Persistent FTS5 index"](../SECURITY.md#persistent-fts5-index-privacy-posture).** |
+| `--persistent-index`   | off     | Maintain a SQLite FTS5 inverted index for sub-100ms BM25-ranked search. Registers the `obsidian://chunk/{n}/{path}` resource; also registers `obsidian_full_text_search` **when combined with `--diagnostic-search-tools`** (since v3.5.9). **Stores chunked note content + tag list + wikilink targets — see [SECURITY.md "Persistent FTS5 index"](../SECURITY.md#persistent-fts5-index-privacy-posture).** |
 | `--tokenize <mode>`    | `unicode61` | FTS5 tokenize mode. `unicode61` (default; Latin/Cyrillic, removes diacritics) or `trigram` (CJK / mixed-script, ~2x index size). Changing this triggers an automatic index rebuild. |
 | `--index-file <path>`  | auto    | Override the FTS5 index file location. Default: `~/Library/Caches/enquire/<vault-hash>.fts5.db` (macOS) or `~/.cache/enquire/<vault-hash>.fts5.db` (Linux). |
 | `--exclude-glob <pattern...>` | none | Repeatable glob pattern(s) — paths matching any pattern are invisible to every tool and refuse direct reads. Privacy filter (denylist). Supports `*` (within-segment), `**` (cross-segment), `?` (single char). Example: `--exclude-glob '02_Personal/**' '*.private.md'`. |
@@ -111,9 +111,9 @@ Canonical list of every registered MCP tool. The `Kind` column splits read/write
 | `clear-cache` | `--vault <path>` `[--cache-file <path>]` | Delete the persistent-cache file for the given vault. Useful for purging stale or sensitive content. Returns 0 even if no cache file exists. |
 | `clear-index` | `--vault <path>` `[--index-file <path>]` | Delete the FTS5 search-index files (`.fts5.db` + WAL/SHM sidecar) for the given vault. Privacy purge for `--persistent-index` users. Returns 0 even if no files exist. |
 | `index` | `--vault <path>` `[--tokenize <mode>]` `[--index-file <path>]` | Cold-build (or refresh) the FTS5 search index for a vault. Useful before first `--persistent-index serve`. Reports `added`/`updated`/`deleted`/`unchanged` chunk counts. |
-| `install-model` (v2.0 beta) | `[alias]` (default `multilingual`) | Pre-download an embedding model so the first MCP call doesn't block on a ~120MB HuggingFace download. Aliases: `multilingual` (Xenova/paraphrase-multilingual-MiniLM-L12-v2, 384-dim, 50+ languages, ~120MB) or `bge` (Xenova/bge-small-en-v1.5, 384-dim, English-only, ~33MB). Models cached under `~/.cache/huggingface/transformers.js/` and reused across vaults. Idempotent. |
-| `build-embeddings` (v2.0 beta) | `--vault <path>` `[--embedding-model <alias>]` `[--embed-file <path>]` `[--exclude-glob <pattern...>]` `[--read-paths <pattern...>]` `[--late-chunk-context <chars>]` `[--quantize-embeddings <mode>]` | Cold-build (or refresh) the persistent embedding index for a vault. Required before `obsidian_embeddings_search` and `obsidian_search` (in hybrid mode) are useful. Same paragraph-level chunking as the FTS5 index — chunk identity matches across BM25 and embeddings. Incremental rebuilds via `source_state` mtime tracking. Reports `added`/`updated`/`deleted`/`unchanged` chunk counts. v2.15.0 `--late-chunk-context <chars>` prepends doc title + breadcrumb + neighbor-chunk tails of N chars before embedding (typical 100-200 for +2-5 NDCG@10). v2.17.0 `--quantize-embeddings <mode>` (`f32` default, `int8` for ~4× smaller BLOBs at ≈1-2% recall cost; mode change triggers a full rebuild). |
-| `clear-embeddings` (v2.0 beta) | `--vault <path>` `[--embed-file <path>]` | Delete the embedding-index files (`.embed.db` + WAL/SHM sidecar). Idempotent. |
+| `install-model` (v2.0+) | `[alias]` (default `multilingual`) | Pre-download an embedding model so the first MCP call doesn't block on a ~120MB HuggingFace download. Aliases: `multilingual` (Xenova/paraphrase-multilingual-MiniLM-L12-v2, 384-dim, 50+ languages, ~120MB) or `bge` (Xenova/bge-small-en-v1.5, 384-dim, English-only, ~33MB). Models cached under `~/.cache/huggingface/transformers.js/` and reused across vaults. Idempotent. |
+| `build-embeddings` (v2.0+) | `--vault <path>` `[--embedding-model <alias>]` `[--embed-file <path>]` `[--exclude-glob <pattern...>]` `[--read-paths <pattern...>]` `[--late-chunk-context <chars>]` `[--quantize-embeddings <mode>]` | Cold-build (or refresh) the persistent embedding index for a vault. Required before `obsidian_embeddings_search` and `obsidian_search` (in hybrid mode) are useful. Same paragraph-level chunking as the FTS5 index — chunk identity matches across BM25 and embeddings. Incremental rebuilds via `source_state` mtime tracking. Reports `added`/`updated`/`deleted`/`unchanged` chunk counts. v2.15.0 `--late-chunk-context <chars>` prepends doc title + breadcrumb + neighbor-chunk tails of N chars before embedding (typical 100-200 for +2-5 NDCG@10). v2.17.0 `--quantize-embeddings <mode>` (`f32` default, `int8` for ~4× smaller BLOBs at ≈1-2% recall cost; mode change triggers a full rebuild). |
+| `clear-embeddings` (v2.0+) | `--vault <path>` `[--embed-file <path>]` | Delete the embedding-index files (`.embed.db` + WAL/SHM sidecar). Idempotent. |
 
 ## Read tools (always registered)
 
@@ -490,9 +490,9 @@ Pure-JS TF-IDF cosine retrieval. Tokenizes (alphanumeric + hyphen, stop-words fi
 
 **Performance:** at 10k notes the cold-build is ~5–10s on Apple silicon (similar to FTS5 cold-build). Warm cosine is sub-100ms. For very large vaults, prefer `--persistent-index` + `obsidian_full_text_search` for raw query latency, and use `obsidian_semantic_search` when BM25 misses.
 
-**Why not embeddings?** TF-IDF cosine ships zero new deps, runs offline, and meaningfully improves over BM25 alone for the related-term case. For ML embeddings see `obsidian_embeddings_search` and `obsidian_search` (v2.0 beta).
+**Why not embeddings?** TF-IDF cosine ships zero new deps, runs offline, and meaningfully improves over BM25 alone for the related-term case. For ML embeddings see `obsidian_embeddings_search` and `obsidian_search` (v2.0+).
 
-## `obsidian_embeddings_search` _(v2.0 beta — requires `enquire-mcp install-model` + `enquire-mcp build-embeddings`)_
+## `obsidian_embeddings_search` _(v2.0+ — requires `enquire-mcp install-model` + `enquire-mcp build-embeddings`)_
 
 ML-embedding retrieval via [@huggingface/transformers](https://github.com/huggingface/transformers.js) + `paraphrase-multilingual-MiniLM-L12-v2` (default; 384-dim, 50+ languages, runs on CPU). Persistent SQLite vector index next to the FTS5 db. Brute-force cosine top-K (sub-100ms on 50K chunks; HNSW ladder is v2.1 if real users hit that ceiling).
 
@@ -515,7 +515,7 @@ If the index is missing, the tool returns a clean error pointing at `enquire-mcp
 
 **Caveat — token truncation.** The default multilingual model truncates at 128 tokens. The FTS5 chunker produces ~600-1000-token chunks, so the tail of long paragraphs is not embedded. Use the `bge` model (512-token limit) for longer-context English content, or split notes into shorter paragraphs.
 
-## `obsidian_search` _(v2.0 beta — the new default search tool)_
+## `obsidian_search` _(v2.0+ — the default search tool)_
 
 **Hybrid retrieval via Reciprocal Rank Fusion (Cormack et al, 2009).** Auto-detects every available retrieval signal — BM25 via FTS5, TF-IDF cosine, ML embeddings — and fuses them with RRF (k=60, equal weights). Gracefully degrades with whatever signals are available:
 
@@ -817,9 +817,9 @@ The note template implements `list`, so MCP clients with a resource browser will
 
 Every path argument is resolved relative to the vault root and rejected if it escapes the root via `..`. The server never reads outside the vault.
 
-## `obsidian_full_text_search` _(opt-in, requires `--persistent-index`)_
+## `obsidian_full_text_search` _(opt-in, requires `--persistent-index` AND `--diagnostic-search-tools`)_
 
-BM25-ranked full-text search over a SQLite FTS5 inverted index. Sub-100ms on multi-thousand-note vaults. Only registered when the server is started with `--persistent-index`; otherwise use `obsidian_search_text`.
+BM25-ranked full-text search over a SQLite FTS5 inverted index. Sub-100ms on multi-thousand-note vaults. Only registered when the server is started with BOTH `--persistent-index` (FTS5 index lifecycle) AND `--diagnostic-search-tools` (single-ranker surface — the hybrid `obsidian_search` tool is the recommended default); otherwise use `obsidian_search_text`.
 
 | Argument | Type                              | Notes                                                     |
 |----------|-----------------------------------|-----------------------------------------------------------|

package/package.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@oomkapwn/enquire-mcp",
-  "version": "3.6.1",
-  "description": "The most advanced MCP server for Obsidian vaults. Hybrid retrieval (BM25 + TF-IDF + multilingual ML embeddings, RRF-fused) with BGE cross-encoder reranking, HNSW vector index, int8 quantization, late-chunking, HyDE-augmented retrieval, sub-question decomposition, PDFs (with OCR), Bases (.base query execution, standalone — no Obsidian needed), GraphRAG-light (Louvain wikilink community detection), wikilinks, backlinks, Dataview, frontmatter, canvas. 44 tools, 19 MCP prompts, 5 cross-encoder reranker models, 715 tests, SLSA-3, semver-bound. Works with Claude Code, Claude Desktop, Cursor, ChatGPT custom GPT, Codex, and any MCP client.",
+  "version": "3.6.2",
+  "description": "The most advanced MCP server for Obsidian vaults. Hybrid retrieval (BM25 + TF-IDF + multilingual ML embeddings, RRF-fused) with BGE cross-encoder reranking, HNSW vector index, int8 quantization, late-chunking, HyDE-augmented retrieval, sub-question decomposition, PDFs (with OCR), Bases (.base query execution, standalone — no Obsidian needed), GraphRAG-light (Louvain wikilink community detection), wikilinks, backlinks, Dataview, frontmatter, canvas. 44 tools, 19 MCP prompts, 5 cross-encoder reranker models, 753 tests, SLSA-3, semver-bound. Works with Claude Code, Claude Desktop, Cursor, ChatGPT custom GPT, Codex, and any MCP client.",
   "type": "module",
   "bin": {
     "enquire-mcp": "dist/index.js"