@oomkapwn/enquire-mcp 1.6.0 → 1.8.0

package/docs/api.md

@@ -1,6 +1,6 @@
 # enquire — API
 
-**enquire is an MCP server for Obsidian vaults.** 23 MCP tools (19 always-on read + 1 opt-in read via `--persistent-index` + 3 opt-in write via `--enable-write`), 2 + 1 opt-in MCP resources, 10 MCP prompts. The server speaks stdio JSON-RPC and is launched per-vault.
+**enquire is an MCP server for Obsidian vaults.** 26 MCP tools (22 always-on read + 1 opt-in read via `--persistent-index` + 3 opt-in write via `--enable-write`), 2 + 1 opt-in MCP resources, 10 MCP prompts. The server speaks stdio JSON-RPC and is launched per-vault.
 
 > Versioned dynamically — see [`CHANGELOG.md`](../CHANGELOG.md) for the current release.
 
@@ -346,6 +346,57 @@ Returns an `obsidian://open?vault=<v>&file=<f>` URI for hand-off to the running
 
 **Returns:** `{ uri, vault_name, path, title }`. The `vault_name` is the leaf folder of the vault root path; Obsidian matches on this OR on the absolute file path, so the URI works even if the user's Obsidian instance opened the vault under a different name.
 
+## `obsidian_list_canvases`
+
+Lists `.canvas` files (Obsidian's whiteboard format — JSON nodes + edges) in the vault, with each canvas's node and edge counts. Honors `--exclude-glob` and `--read-paths`. Use this to discover which canvases exist before calling `obsidian_read_canvas`.
+
+| Argument | Type             | Notes                                       |
+|----------|------------------|---------------------------------------------|
+| `folder` | `string?`        | Restrict the listing to a subfolder.        |
+| `limit`  | `number?` (≤ 500)| Max canvases to return. Default 100.        |
+
+**Returns:** `Array<{ path, name, size_bytes, mtime, node_count, edge_count }>`, sorted newest-first.
+
+## `obsidian_read_canvas`
+
+Parses one `.canvas` file into typed nodes + edges. Each node has a `kind` field — `text` / `file` / `link` / `group` / `unknown` (forward-compat for new Obsidian canvas node types). Each `file` node carries a `file_resolved` field — the vault-relative path the canvas's file reference resolved to (or `null` if broken).
+
+| Argument | Type     | Notes                                                  |
+|----------|----------|--------------------------------------------------------|
+| `path`   | `string` | Vault-relative path of the `.canvas` file (`.canvas` extension auto-appended). |
+
+**Returns:** `{ path, name, size_bytes, mtime, nodes: CanvasNode[], edges: CanvasEdge[], summary: { text, file, link, group, unknown }, broken_file_refs: string[] }`. Throws on path-traversal, missing file, or invalid JSON.
+
+`CanvasNode` discriminated union by `kind`:
+- `{ kind: "text", id, x, y, width, height, text, color? }`
+- `{ kind: "file", id, x, y, width, height, file, file_resolved, subpath?, color? }`
+- `{ kind: "link", id, x, y, width, height, url, color? }`
+- `{ kind: "group", id, x, y, width, height, label?, color? }`
+- `{ kind: "unknown", id, raw_type, raw }` — preserves any future canvas node type unchanged.
+
+`CanvasEdge`: `{ id, from_node, from_side?, to_node, to_side?, label?, color? }`.
+
+`broken_file_refs` lists canvas `file:` nodes that didn't resolve to any markdown in the current vault — useful as a vault-hygiene signal alongside `obsidian_get_unresolved_wikilinks`.
+
+## `obsidian_semantic_search`
+
+Pure-JS TF-IDF cosine retrieval. Tokenizes (alphanumeric + hyphen, stop-words filtered, ≥ 2 chars), TF-IDFs, L2-normalizes every note's body once per session, then ranks notes by cosine similarity to the query. Catches synonym + related-term matches that `obsidian_search_text` (substring) and `obsidian_full_text_search` (BM25) miss.
+
+| Argument    | Type             | Notes                                                                          |
+|-------------|------------------|--------------------------------------------------------------------------------|
+| `query`     | `string`         | Required. Free-form, multi-word, natural language is fine.                     |
+| `folder`    | `string?`        | Restrict to a subfolder.                                                       |
+| `limit`     | `number?` (≤ 100)| Max hits. Default 10.                                                          |
+| `min_score` | `number?` (0–1)  | Drop hits below this cosine score. Default 0.05. Cosine ranges 0–1.            |
+
+**Returns:** `{ query, total_docs, method: "tfidf-cosine", matches: [{ path, title, score, snippet, matched_terms, mtime }] }`. `matched_terms` is sorted highest-IDF first (the most-discriminating terms in the corpus). `snippet` is taken from the first occurrence of the highest-IDF matched term.
+
+**Caching:** the IDF index is built lazily on first call and memoized via `WeakMap` keyed on the `entries` array. Subsequent calls reuse the index when `listMarkdown()` returns the same paths + mtimes; the index rebuilds automatically when the vault changes.
+
+**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?** Real ML embedding retrieval (v2.0 roadmap) would need a 25–50 MB model file and an ONNX/WASM runtime. TF-IDF cosine ships zero new deps, runs offline, and meaningfully improves over BM25 alone for the related-term case. Smart Connections (the dominant Obsidian semantic-search plugin) paywalled this functionality — enquire-mcp gives it free.
+
 ## Write tools (opt-in)
 
 All three write tools are **only registered when the server is started with `--enable-write`**. Without that flag the tools are not advertised to the client at all.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomkapwn/enquire-mcp",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Drop-in MCP server for Obsidian vaults. Wikilinks resolved, backlinks ranked, frontmatter typed, Dataview-style queries. Read-only by default; opt-in writes. Works with Claude Code, Cursor, OpenClaw, Codex, Devin, and any MCP-compatible client.",
   "type": "module",
   "bin": {