seekstone 0.20.2 → 0.20.3

package/README.md

@@ -4,7 +4,7 @@
 
 Seekstone is an Obsidian MCP server that gives Claude (and any [Model Context Protocol](https://modelcontextprotocol.io) client) direct read and write access to your Obsidian vault. No Obsidian app needs to be running, no plugins are required, and nothing leaves your machine.
 
-It reads your vault **directly from disk** instead of routing through the Obsidian Local REST API plugin, and holds a warm full-text index in-process. The practical difference: keyword searches return in **single-digit milliseconds** (semantic search in **~26 ms**) with **~2 KB payloads** that stay flat as your vault grows — a broad query that costs tens of megabytes of context through a REST-proxy server (up to **95 MB** at 10k notes) costs ~2 KB through Seekstone, up to a **~47,000× reduction**. Benchmarked against 7 other Obsidian MCP servers across committed 1k/5k/10k-note vaults — [fully reproducible](https://github.com/shaqmughal/seekstone/tree/main/packages/harness), full results at [seekstone.dev/benchmarks](https://seekstone.dev/benchmarks).
+It reads your vault **directly from disk** instead of routing through the Obsidian Local REST API plugin, and holds a warm full-text index in-process. The practical difference: keyword searches return in **single-digit milliseconds** (semantic search in **~26 ms**) with **~2 KB payloads** that stay flat as your vault grows — a broad query that costs tens of megabytes of context through a REST-proxy server (up to **95 MB** at 10k notes) costs ~2 KB through Seekstone, up to a **~47,000× reduction**. Benchmarked against 7 other Obsidian MCP servers across committed 1k/5k/10k-note vaults — [fully reproducible](https://github.com/shaqmughal/seekstone/tree/main/packages/harness), full results at [seekstone.dev/benchmarks](https://seekstone.dev/benchmarks/).
 
 (Previously also published as `obsidian-mcp-seekstone` — that alias is deprecated; existing installs keep working, but install `seekstone` going forward.)
 
@@ -209,6 +209,9 @@ Any MCP-over-stdio client: Claude Desktop, Claude Code, Cursor, VS Code, Windsur
 **Does it work on Windows?**
 Yes — tested on macOS, Linux, and Windows in CI on every commit.
 
+**Does search handle typos?**
+Yes, small ones. Keyword search allows one typo per word of 3–7 letters and two for words of 8 or more, so `benchamrk` still finds "benchmark". One- and two-letter words must match exactly, and swapping two letters counts as two typos. It also matches word prefixes: `kuber` finds "Kubernetes". The `tag` filter on `search`, `context_pack`, `query_notes`, and `list_notes` works like Obsidian's: it ignores case and includes nested tags, so `project` matches `#Project/alpha`. A tag no note has returns an `unknown_tag` error listing the closest existing tags.
+
 **Is it safe?**
 No network calls while running, no telemetry (the optional semantic-search model is downloaded once by the explicit `fetch-model` subcommand, SHA-256-verified, before any serving starts — or shipped inside the `seekstone-semantic.mcpb` bundle and reassembled from disk at boot, verified against the same pinned hashes). The vault path is sandboxed — no tool reads or writes outside it. Writes are covered by the tested Write-Safety Contract above, and `SEEKSTONE_READ_ONLY=1` removes the write tools entirely.
 

package/dist/index.js

@@ -1038,6 +1038,73 @@ function resolveLink(target, notes2, maps) {
 // src/tools/search.ts
 import { z as z2 } from "zod";
 
+// src/index/tags.ts
+function normalizeTag(tag) {
+  return tag.replace(/^#/, "").toLowerCase();
+}
+function noteHasTag(noteTags, wanted) {
+  for (const t of noteTags.split(" ")) {
+    if (!t) continue;
+    const tag = t.toLowerCase();
+    if (tag === wanted || tag.startsWith(`${wanted}/`)) return true;
+  }
+  return false;
+}
+function editDistance(a, b) {
+  let row = Array.from({ length: b.length + 1 }, (_, j) => j);
+  let dist = b.length;
+  for (let i = 0; i < a.length; i++) {
+    let diag = i;
+    let left = i + 1;
+    const next = [left];
+    for (const [j, up] of row.slice(1).entries()) {
+      left = Math.min(up + 1, left + 1, diag + (a[i] === b[j] ? 0 : 1));
+      diag = up;
+      next.push(left);
+    }
+    row = next;
+    dist = left;
+  }
+  return dist;
+}
+var MAX_SUGGESTIONS = 3;
+function suggestTags(notes2, wanted) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const note of notes2) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const t of note.tags.split(" ")) {
+      if (!t) continue;
+      const parts = t.toLowerCase().split("/");
+      for (let i = 1; i <= parts.length; i++) seen.add(parts.slice(0, i).join("/"));
+    }
+    for (const tag of seen) counts.set(tag, (counts.get(tag) ?? 0) + 1);
+  }
+  const budget = Math.max(2, Math.ceil(wanted.length / 3));
+  const scored = [];
+  for (const [tag, count] of counts) {
+    const leaf = tag.slice(tag.lastIndexOf("/") + 1);
+    const dist = Math.min(editDistance(wanted, tag), editDistance(wanted, leaf));
+    if (dist <= budget) scored.push({ tag, dist, count });
+  }
+  scored.sort((a, b) => a.dist - b.dist || b.count - a.count || a.tag.localeCompare(b.tag));
+  return scored.slice(0, MAX_SUGGESTIONS).map((s) => s.tag);
+}
+function assertTagExists(notes2, tag) {
+  const wanted = normalizeTag(tag);
+  for (const note of notes2.values()) {
+    if (noteHasTag(note.tags, wanted)) return;
+  }
+  const didYouMean = suggestTags(notes2.values(), wanted);
+  throw new Error(
+    JSON.stringify({
+      error: "unknown_tag",
+      tag,
+      ...didYouMean.length > 0 ? { didYouMean } : {},
+      hint: "No note in the vault has this tag. Matching ignores case and includes nested child tags. Retry with a suggested tag, or call list_tags to see the tags that exist."
+    })
+  );
+}
+
 // src/semantic/excerpt.ts
 function chunkExcerpt(body, span, terms, maxLen) {
   const normalized = body.includes("\r") ? body.replace(/\r\n/g, "\n") : body;
@@ -1072,7 +1139,9 @@ var SearchInput = z2.object({
   ),
   limit: z2.number().int().min(1).max(50).default(10).describe("Maximum number of results to return."),
   folder: z2.string().optional().describe("Restrict results to notes under this vault-relative folder prefix."),
-  tag: z2.string().optional().describe("Restrict results to notes containing this tag."),
+  tag: z2.string().optional().describe(
+    'Restrict results to notes with this tag. # optional, case-insensitive, and nested child tags match (e.g. "project" matches #project/alpha).'
+  ),
   excerptLength: z2.number().int().min(20).max(2e3).optional().describe(
     "Max characters of match context per hit (default 120). Lower trims payload; higher gives more context."
   )
@@ -1084,6 +1153,11 @@ function basenameNoExt(path2) {
   return dot > 0 ? base.slice(0, dot) : base;
 }
 function retrieve(ctx2, input) {
+  const result = retrieveUnchecked(ctx2, input);
+  if (result.hits.length === 0 && input.tag) assertTagExists(ctx2.notes, input.tag);
+  return result;
+}
+function retrieveUnchecked(ctx2, input) {
   const mode = input.mode ?? "lexical";
   if (mode === "lexical") return lexicalSearch(ctx2, input);
   const semantic = requireSemantic(ctx2);
@@ -1177,12 +1251,7 @@ function filterNote(ctx2, input, path2) {
   if (input.folder && !path2.startsWith(input.folder)) return void 0;
   const note = ctx2.notes.get(path2);
   if (!note) return void 0;
-  if (input.tag) {
-    const noteTags = note.tags.split(" ");
-    if (!noteTags.some((t) => t === input.tag || t === input.tag?.replace(/^#/, ""))) {
-      return void 0;
-    }
-  }
+  if (input.tag && !noteHasTag(note.tags, normalizeTag(input.tag))) return void 0;
   return note;
 }
 function decorate(hit, title, tags) {
@@ -1199,7 +1268,9 @@ var ContextPackInput = z3.object({
     "lexical = keyword search (default). semantic = meaning-based search over local embeddings (requires SEEKSTONE_SEMANTIC=1 and a fetched model). hybrid = exact-title lookups go lexical, everything else semantic. A question asked in words the note does not use needs semantic or hybrid."
   ),
   folder: z3.string().optional().describe("Restrict results to notes under this vault-relative folder prefix."),
-  tag: z3.string().optional().describe("Restrict results to notes containing this tag.")
+  tag: z3.string().optional().describe(
+    'Restrict results to notes with this tag. # optional, case-insensitive, and nested child tags match (e.g. "project" matches #project/alpha).'
+  )
 });
 var MAX_CANDIDATES = 10;
 var NEIGHBOR_HITS = 3;
@@ -1647,18 +1718,17 @@ var ListNotesInput = z8.object({
   folder: z8.string().optional().describe(
     'Vault-relative folder prefix to list. Omit for all notes. Example: "Daily Notes/2026".'
   ),
-  tag: z8.string().optional().describe("Filter by tag. Include or omit the leading #."),
+  tag: z8.string().optional().describe(
+    'Filter by tag. # optional, case-insensitive, and nested child tags match (e.g. "project" matches #project/alpha).'
+  ),
   limit: z8.number().int().min(1).max(500).default(100).describe("Maximum number of results.")
 });
 function listNotes(ctx2, input) {
-  const tag = input.tag?.replace(/^#/, "");
+  const tag = input.tag === void 0 ? void 0 : normalizeTag(input.tag);
   const results = [];
   for (const [path2, note] of ctx2.notes) {
     if (input.folder && !path2.startsWith(input.folder)) continue;
-    if (tag) {
-      const noteTags = note.tags.split(" ").filter(Boolean);
-      if (!noteTags.includes(tag)) continue;
-    }
+    if (tag && !noteHasTag(note.tags, tag)) continue;
     results.push({
       path: path2,
       title: note.title,
@@ -1667,6 +1737,7 @@ function listNotes(ctx2, input) {
     });
     if (results.length >= input.limit) break;
   }
+  if (results.length === 0 && input.tag) assertTagExists(ctx2.notes, input.tag);
   return results.sort((a, b) => a.path.localeCompare(b.path));
 }
 
@@ -2403,7 +2474,9 @@ var ISO_DATE = z16.string().refine((s) => !Number.isNaN(Date.parse(s)), { messag
 var QueryNotesInput = z16.object({
   where: z16.array(Predicate).max(20).default([]).describe("Frontmatter predicates. All must match (AND)."),
   folder: z16.string().optional().describe("Restrict to notes under this vault-relative folder prefix."),
-  tag: z16.string().optional().describe("Restrict to notes with this tag (# prefix optional)."),
+  tag: z16.string().optional().describe(
+    'Restrict to notes with this tag. # optional, case-insensitive, and nested child tags match (e.g. "project" matches #project/alpha).'
+  ),
   modifiedAfter: ISO_DATE.optional().describe(
     "Only notes modified at or after this ISO 8601 date/time."
   ),
@@ -2468,14 +2541,14 @@ function matches(fm, p) {
   }
 }
 function queryNotes(ctx2, input) {
-  const tag = input.tag?.replace(/^#/, "");
+  const tag = input.tag === void 0 ? void 0 : normalizeTag(input.tag);
   const after = input.modifiedAfter ? Date.parse(input.modifiedAfter) : void 0;
   const before = input.modifiedBefore ? Date.parse(input.modifiedBefore) : void 0;
   const fmKeys = input.select.filter((s) => s !== "mtime" && s !== "size" && s !== "tags");
   const hits = [];
   for (const [path2, note] of ctx2.notes) {
     if (input.folder && !path2.startsWith(input.folder)) continue;
-    if (tag && !note.tags.split(" ").filter(Boolean).includes(tag)) continue;
+    if (tag && !noteHasTag(note.tags, tag)) continue;
     if (after !== void 0 && note.mtimeMs < after) continue;
     if (before !== void 0 && note.mtimeMs >= before) continue;
     if (input.minSizeBytes !== void 0 && note.sizeBytes < input.minSizeBytes) continue;
@@ -2498,6 +2571,7 @@ function queryNotes(ctx2, input) {
     }
     hits.push({ hit, note });
   }
+  if (hits.length === 0 && input.tag) assertTagExists(ctx2.notes, input.tag);
   const dir = input.order === "desc" ? -1 : 1;
   hits.sort((a, b) => {
     switch (input.sort) {
@@ -4908,7 +4982,10 @@ var ALL_TOOLS = [
         },
         limit: { type: "number", description: "Max results (1\u201350, default 10)." },
         folder: { type: "string", description: "Restrict to a vault-relative folder prefix." },
-        tag: { type: "string", description: "Restrict to notes with this tag." },
+        tag: {
+          type: "string",
+          description: 'Restrict to notes with this tag. # optional, case-insensitive; nested child tags match ("project" matches project/alpha).'
+        },
         excerptLength: {
           type: "number",
           description: "Max characters of match context per hit (20\u20132000, default 120)."
@@ -4945,7 +5022,10 @@ var ALL_TOOLS = [
           }
         },
         folder: { type: "string", description: "Restrict to a vault-relative folder prefix." },
-        tag: { type: "string", description: "Restrict to notes with this tag (# optional)." },
+        tag: {
+          type: "string",
+          description: 'Restrict to notes with this tag. # optional, case-insensitive; nested child tags match ("project" matches project/alpha).'
+        },
         modifiedAfter: {
           type: "string",
           description: "Only notes modified at or after this ISO 8601 date/time."
@@ -4994,7 +5074,10 @@ var ALL_TOOLS = [
           description: "lexical = keyword search (default). semantic = meaning-based over local embeddings (needs SEEKSTONE_SEMANTIC=1 and a fetched model). hybrid = exact-title lookups go lexical, everything else semantic."
         },
         folder: { type: "string", description: "Restrict to a vault-relative folder prefix." },
-        tag: { type: "string", description: "Restrict to notes with this tag." }
+        tag: {
+          type: "string",
+          description: 'Restrict to notes with this tag. # optional, case-insensitive; nested child tags match ("project" matches project/alpha).'
+        }
       },
       required: ["query"]
     }
@@ -5046,7 +5129,10 @@ var ALL_TOOLS = [
       type: "object",
       properties: {
         folder: { type: "string", description: "Vault-relative folder prefix." },
-        tag: { type: "string", description: "Filter by tag (# prefix optional)." },
+        tag: {
+          type: "string",
+          description: 'Filter by tag. # optional, case-insensitive; nested child tags match ("project" matches project/alpha).'
+        },
         limit: { type: "number", description: "Max results (1\u2013500, default 100)." }
       },
       required: []
@@ -5542,7 +5628,7 @@ function startWatcher(ctx2, log2, opts) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.20.2" : "0.0.0-dev";
+var VERSION = true ? "0.20.3" : "0.0.0-dev";
 var intent = parseCliIntent(process.argv.slice(2));
 if (intent === "version") {
   process.stdout.write(`${VERSION}