neuro-vault-mcp 8.0.0 → 8.2.0

package/README.md

@@ -72,7 +72,7 @@ One question, one answer. Your assistant stops being a file browser and starts b
 { "query": "trading lessons", "filter": { "tags": ["trading"] } }
 ```
 
-`filter` accepts `path_prefix`, `tags` (ANY-of), and a `frontmatter` sift filter. Composition is `filter` AND `threshold` AND semantic. See the [Semantic Search guide](./docs/guide/semantic-search.md#pre-filter-filter-parameter) for full details.
+`filter` accepts `path_prefix` (string or array), `exclude_path_prefix` (string or array — drops matched subtrees), `tags` (ANY-of), and a `frontmatter` sift filter. Composition is include → exclude → tags → frontmatter → threshold → semantic. See the [Semantic Search guide](./docs/guide/semantic-search.md#pre-filter-filter-parameter) for full details.
 
 ---
 

package/dist/cli.d.ts

@@ -72,7 +72,8 @@ declare class WikilinkGraphIndex {
 }
 
 interface NoteFilter {
-    path_prefix?: string;
+    path_prefix?: string | string[];
+    exclude_path_prefix?: string | string[];
     tags?: string[];
     frontmatter?: Record<string, unknown>;
 }

package/dist/cli.js

@@ -15202,6 +15202,56 @@ function normalizeVaultPathPrefix(raw, invalid) {
   return slashed.replace(/\/+$/, "");
 }
 
+// src/lib/obsidian/query/path-prefix-set.ts
+function normalizePrefixList(raw, field, errorCode) {
+  if (raw === void 0) return void 0;
+  const invalid = (message) => new ToolHandlerError(errorCode, message, { details: { field } });
+  if (Array.isArray(raw)) {
+    if (raw.length === 0) {
+      throw invalid(`${field} must contain at least one prefix`);
+    }
+    const out = /* @__PURE__ */ new Set();
+    for (const entry of raw) {
+      if (typeof entry !== "string") {
+        throw invalid(`${field} elements must be strings`);
+      }
+      const normalized2 = normalizeVaultPathPrefix(entry, invalid);
+      if (normalized2 !== void 0) out.add(normalized2);
+    }
+    return out.size === 0 ? void 0 : [...out];
+  }
+  if (typeof raw !== "string") {
+    throw invalid(`${field} must be a string or array of strings`);
+  }
+  const normalized = normalizeVaultPathPrefix(raw, invalid);
+  return normalized === void 0 ? void 0 : [normalized];
+}
+function matchesAnyPrefix(p, prefixes) {
+  for (const q of prefixes) {
+    if (p === q) return true;
+    if (p.startsWith(`${q}/`)) return true;
+  }
+  return false;
+}
+function rethrowPathNotFoundWithIndex(err, prefix, index, total) {
+  const isRaw = err instanceof ScanPathNotFoundError;
+  const isWrapped = err instanceof ToolHandlerError && err.code === "PATH_NOT_FOUND";
+  if (!isRaw && !isWrapped) {
+    throw err;
+  }
+  if (total <= 1) {
+    if (isRaw) {
+      throw new ToolHandlerError("PATH_NOT_FOUND", err.message);
+    }
+    throw err;
+  }
+  throw new ToolHandlerError(
+    "PATH_NOT_FOUND",
+    `path_prefix[${index}] not found: ${JSON.stringify(prefix)}`,
+    { details: { path_prefix: prefix, index } }
+  );
+}
+
 // src/lib/obsidian/query/whitelist.ts
 var ALLOWED_OPERATORS = /* @__PURE__ */ new Set([
   "$eq",
@@ -15289,6 +15339,9 @@ async function collectMatchingPaths(input, deps) {
         }
         continue;
       }
+      if (input.excludePathPrefixes !== void 0 && matchesAnyPrefix(item.path, input.excludePathPrefixes)) {
+        continue;
+      }
       const backlinkCount = graph?.getBacklinkCount(item.path) ?? 0;
       const record2 = toNoteRecord(item, backlinkCount);
       let isMatch;
@@ -15312,16 +15365,37 @@ async function runQueryNotes(input, reader, graph) {
   if (graph) {
     await graph.ensureFresh();
   }
-  const earlyExitAllowed = !validated.sort || validated.sort.field === "path" && validated.sort.order === "asc";
-  const matched = await collectMatchingPaths(
-    {
-      filter: effectiveFilter,
-      pathPrefix: validated.pathPrefix,
-      includeContent: validated.includeContent,
-      earlyExitAfter: earlyExitAllowed ? validated.limit : void 0
-    },
-    { reader, graph }
+  const sortOrderMatchesScan = !validated.sort || validated.sort.field === "path" && validated.sort.order === "asc";
+  const includes = validated.includePrefixes ?? [void 0];
+  const multiPrefix = includes.length > 1;
+  const earlyExitAfter = sortOrderMatchesScan && !multiPrefix ? validated.limit : void 0;
+  const totalIncludes = includes.length;
+  const batches = await Promise.all(
+    includes.map((prefix, i) => {
+      const promise2 = collectMatchingPaths(
+        {
+          filter: effectiveFilter,
+          pathPrefix: prefix,
+          includeContent: validated.includeContent,
+          earlyExitAfter,
+          excludePathPrefixes: validated.excludePrefixes
+        },
+        { reader, graph }
+      );
+      return prefix === void 0 ? promise2 : promise2.catch(
+        (err) => rethrowPathNotFoundWithIndex(err, prefix, i, totalIncludes)
+      );
+    })
   );
+  const seen = /* @__PURE__ */ new Set();
+  const matched = [];
+  for (const rows of batches) {
+    for (const row of rows) {
+      if (seen.has(row.record.path)) continue;
+      seen.add(row.record.path);
+      matched.push(row);
+    }
+  }
   if (validated.sort) {
     sortInPlace(matched, validated.sort);
   }
@@ -15351,13 +15425,12 @@ function validateInput(input) {
   if (typeof input.filter !== "object" || Array.isArray(input.filter)) {
     throw invalidParams("filter must be a JSON object", "filter");
   }
-  let pathPrefix;
-  if (input.path_prefix !== void 0) {
-    if (typeof input.path_prefix !== "string") {
-      throw invalidParams("path_prefix must be a string", "path_prefix");
-    }
-    pathPrefix = normalizeScanPrefixInput(input.path_prefix);
-  }
+  const includePrefixes = normalizePrefixList(input.path_prefix, "path_prefix", "INVALID_PARAMS");
+  const excludePrefixes = normalizePrefixList(
+    input.exclude_path_prefix,
+    "exclude_path_prefix",
+    "INVALID_PARAMS"
+  );
   let sort;
   if (input.sort !== void 0) {
     sort = validateSort(input.sort);
@@ -15378,15 +15451,13 @@ function validateInput(input) {
   }
   return {
     filter: input.filter,
-    pathPrefix,
+    includePrefixes,
+    excludePrefixes,
     sort,
     limit,
     includeContent
   };
 }
-function normalizeScanPrefixInput(raw) {
-  return normalizeVaultPathPrefix(raw, (message) => invalidParams(message, "path_prefix"));
-}
 function validateSort(raw) {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
     throw invalidParams("sort must be an object { field, order }", "sort");
@@ -15448,47 +15519,71 @@ function invalidParams(message, field) {
 // src/lib/obsidian/query/list-matching-paths.ts
 function createListMatchingPaths(deps) {
   return async (filter) => {
-    const { path_prefix, tags, frontmatter } = filter;
-    const hasPathPrefix = path_prefix !== void 0 && path_prefix !== "";
+    const { path_prefix, exclude_path_prefix, tags, frontmatter } = filter;
+    const includePrefixes = normalizePrefixList(path_prefix, "path_prefix", "INVALID_FILTER");
+    const excludePrefixes = normalizePrefixList(
+      exclude_path_prefix,
+      "exclude_path_prefix",
+      "INVALID_FILTER"
+    );
+    const hasInclude = includePrefixes !== void 0;
+    const hasExclude = excludePrefixes !== void 0;
     const hasTags = Array.isArray(tags) && tags.length > 0;
     const hasFrontmatter = frontmatter !== void 0 && Object.keys(frontmatter).length > 0;
-    if (!hasPathPrefix && !hasTags && !hasFrontmatter) {
+    if (!hasInclude && !hasExclude && !hasTags && !hasFrontmatter) {
       throw new ToolHandlerError(
         "INVALID_FILTER",
-        "filter must specify at least one of: path_prefix, tags, frontmatter"
+        "filter must specify at least one of: path_prefix, exclude_path_prefix, tags, frontmatter"
       );
     }
-    const normalizedPrefix = hasPathPrefix ? normalizeVaultPathPrefix(
-      path_prefix,
-      (message) => new ToolHandlerError("INVALID_FILTER", message)
-    ) : void 0;
-    if (hasPathPrefix && !hasTags && !hasFrontmatter) {
-      try {
-        const paths = await deps.reader.scan({ pathPrefix: normalizedPrefix });
-        return new Set(paths);
-      } catch (err) {
-        if (err instanceof ScanPathNotFoundError) {
-          throw new ToolHandlerError("PATH_NOT_FOUND", err.message, {
-            details: { path_prefix: normalizedPrefix }
-          });
+    if (!hasTags && !hasFrontmatter) {
+      const collected = /* @__PURE__ */ new Set();
+      if (hasInclude) {
+        const total = includePrefixes.length;
+        const scans = await Promise.all(
+          includePrefixes.map(
+            (p, i) => deps.reader.scan({ pathPrefix: p }).catch((err) => rethrowPathNotFoundWithIndex(err, p, i, total))
+          )
+        );
+        for (const list of scans) for (const p of list) collected.add(p);
+      } else {
+        for (const p of await deps.reader.scan({ pathPrefix: void 0 })) collected.add(p);
+      }
+      if (hasExclude) {
+        for (const p of [...collected]) {
+          if (matchesAnyPrefix(p, excludePrefixes)) collected.delete(p);
         }
-        throw err;
       }
+      return collected;
     }
     if (hasFrontmatter) {
       validateFilter(frontmatter);
     }
     const internalFilter = compileFilter({ tags, frontmatter });
     const effectiveFilter = applyDefaultRegexOptions(internalFilter);
-    const rows = await collectMatchingPaths(
-      {
-        filter: effectiveFilter,
-        pathPrefix: normalizedPrefix,
-        includeContent: false
-      },
-      deps
+    const scanPrefixes = hasInclude ? [...includePrefixes] : [void 0];
+    const totalIncludes = scanPrefixes.length;
+    const batched = await Promise.all(
+      scanPrefixes.map((prefix, i) => {
+        const promise2 = collectMatchingPaths(
+          {
+            filter: effectiveFilter,
+            pathPrefix: prefix,
+            includeContent: false,
+            excludePathPrefixes: hasExclude ? excludePrefixes : void 0
+          },
+          deps
+        );
+        return prefix === void 0 ? promise2 : promise2.catch(
+          (err) => rethrowPathNotFoundWithIndex(err, prefix, i, totalIncludes)
+        );
+      })
     );
-    return new Set(rows.map((row) => row.record.path));
+    const out = /* @__PURE__ */ new Set();
+    for (const rows of batched) {
+      for (const row of rows) out.add(row.record.path);
+    }
+    return out;
   };
 }
 function compileFilter(parts) {
@@ -16013,8 +16108,10 @@ async function executeMultiRetrieval(input) {
 }
 
 // src/modules/semantic/tools/search-notes.ts
+var prefixSchema = external_exports.union([external_exports.string(), external_exports.array(external_exports.string()).min(1)]);
 var filterSchema = external_exports.object({
-  path_prefix: external_exports.string().optional(),
+  path_prefix: prefixSchema.optional(),
+  exclude_path_prefix: prefixSchema.optional(),
   tags: external_exports.array(external_exports.string()).optional(),
   frontmatter: external_exports.record(external_exports.string(), external_exports.unknown()).optional()
 });
@@ -16034,10 +16131,11 @@ function wrapDependencyError2(error48, message, details) {
   return new ToolHandlerError("DEPENDENCY_ERROR", message, { details, cause: error48 });
 }
 function isFilterEmpty(filter) {
-  const hasPath = filter.path_prefix !== void 0 && filter.path_prefix !== "";
+  const hasInclude = filter.path_prefix !== void 0 && (Array.isArray(filter.path_prefix) ? filter.path_prefix.length > 0 : filter.path_prefix !== "");
+  const hasExclude = filter.exclude_path_prefix !== void 0 && (Array.isArray(filter.exclude_path_prefix) ? filter.exclude_path_prefix.length > 0 : filter.exclude_path_prefix !== "");
   const hasTags = Array.isArray(filter.tags) && filter.tags.length > 0;
   const hasFm = filter.frontmatter !== void 0 && Object.keys(filter.frontmatter).length > 0;
-  return !hasPath && !hasTags && !hasFm;
+  return !hasInclude && !hasExclude && !hasTags && !hasFm;
 }
 function narrowSources(sources, allowed) {
   const out = /* @__PURE__ */ new Map();
@@ -16068,7 +16166,7 @@ async function runSearchForEntry(entry, input, deps) {
     if (isFilterEmpty(input.filter)) {
       throw new ToolHandlerError(
         "INVALID_ARGUMENT",
-        "filter must specify at least one of: path_prefix, tags, frontmatter"
+        "filter must specify at least one of: path_prefix, exclude_path_prefix, tags, frontmatter"
       );
     }
     let allowed;
@@ -16208,13 +16306,15 @@ function buildSearchNotesTool(deps) {
     "",
     "PRE-FILTER (filter parameter):",
     "- filter: optional structural narrowing applied BEFORE semantic ranking. Best when vault has many narrative notes that crowd top-K on a niche query.",
-    "  Shape: { path_prefix?, tags?, frontmatter? }. At least one field required.",
-    '  - path_prefix: scope to a folder (e.g. "Resources/").',
+    "  Shape: { path_prefix?, exclude_path_prefix?, tags?, frontmatter? }. At least one field required.",
+    '  - path_prefix: scope to a folder, or array of folders for OR-semantics (e.g. ["Tasks/", "Reflections/"]).',
+    '  - exclude_path_prefix: drop notes whose path starts with any of the listed prefixes (e.g. ["Resources/", "Archive/"]). Valid as the sole filter field \u2014 "search the whole vault except these subtrees".',
     '  - tags: notes that have ANY of these tags (OR within the array; no leading "#").',
     '  - frontmatter: sift filter on frontmatter keys (e.g. { type: "reflection", status: "active" }). Same operator allow-list as query_notes.',
-    "  Composition: filter AND threshold AND semantic. Use this instead of querying twice and intersecting on the client.",
+    "  Composition: include \u2192 exclude \u2192 tags \u2192 frontmatter \u2192 threshold \u2192 semantic. Use this instead of querying twice and intersecting on the client.",
     '- scoped recall: search_notes({query: "trading lessons", filter: {tags: ["trading"]}}) \u2014 semantic only inside notes tagged trading.',
-    '- scoped multi-query: search_notes({query: ["embeddings","\u0432\u0435\u043A\u0442\u043E\u0440\u043D\u0438\u0439 \u043F\u043E\u0448\u0443\u043A"], filter: {path_prefix: "Resources/"}, mode: "deep"}).',
+    '- carve out noise: search_notes({query: "active thinking", filter: {exclude_path_prefix: ["Resources/", "Archive/"]}, mode: "deep"}).',
+    '- scoped multi-query: search_notes({query: ["embeddings","\u0432\u0435\u043A\u0442\u043E\u0440\u043D\u0438\u0439 \u043F\u043E\u0448\u0443\u043A"], filter: {path_prefix: ["Resources/", "Inbox/"]}, mode: "deep"}).',
     ...registry2.isMulti() ? [
       "",
       "In multi-vault mode, omit `vault:` to fan out across all registered vaults \u2014 the response shape switches to `results_by_vault: [...]` with `skipped_vaults: [...]` (vaults without a semantic index are listed in `skipped_vaults`).",
@@ -16708,12 +16808,14 @@ async function runQueryForEntry(entry, input) {
   }));
   return { results, count: raw.count, truncated: raw.truncated };
 }
+var queryNotesPrefixSchema = external_exports.union([external_exports.string(), external_exports.array(external_exports.string()).min(1)]);
 function buildQueryNotesTool(deps) {
   const { registry: registry2 } = deps;
   const inputSchema = external_exports.object({
     ...vaultParamShape(registry2),
     filter: external_exports.record(external_exports.string(), external_exports.unknown()),
-    path_prefix: external_exports.string().optional(),
+    path_prefix: queryNotesPrefixSchema.optional(),
+    exclude_path_prefix: queryNotesPrefixSchema.optional(),
     sort: queryNotesSortSchema.optional(),
     limit: external_exports.number().int().min(1).max(1e3).optional(),
     include_content: external_exports.boolean().optional()
@@ -16721,7 +16823,7 @@ function buildQueryNotesTool(deps) {
   return {
     name: "query_notes",
     title: "Query Notes",
-    description: 'Run a structured MongoDB-style query against the vault\'s frontmatter, tags, and wikilink graph. `filter` is a sift/MongoDB filter object evaluated against `NoteRecord` shape `{ path, frontmatter, tags, backlink_count }` \u2014 `tags` is an array of strings (no leading `#`) extracted from the `tags:` frontmatter field; `backlink_count` is the number of vault-wide wikilinks (and `![[embeds]]`) that point at the note. Reference frontmatter keys with the dotted prefix `frontmatter.<key>`. Supported operators: `$eq`, `$ne`, `$in`, `$nin`, `$gt`, `$gte`, `$lt`, `$lte`, `$exists`, `$regex`, `$options`, `$and`, `$or`, `$nor`, `$not`. `$regex` is case-insensitive by default; pass `$options` (e.g. `\'\'` for case-sensitive, `\'m\'` for multiline-only) to override. Optional `path_prefix` restricts the scan to a vault subtree (vault-relative POSIX, no leading slash). Optional `sort` is `{ field, order }` \u2014 `field` must be `"path"`, `"backlink_count"`, or start with `"frontmatter."`. Optional `limit` defaults to 100, max 1000. Optional `include_content` (default false) \u2014 when true, each result also carries `content` (note body). Returns `{ results, count, truncated }`; each result item carries `vault` and `backlink_count`. `truncated` is true when more notes matched than `limit` allowed. Reads directly from disk and does not require Obsidian to be running.' + describeMultiVault(
+    description: 'Run a structured MongoDB-style query against the vault\'s frontmatter, tags, and wikilink graph. `filter` is a sift/MongoDB filter object evaluated against `NoteRecord` shape `{ path, frontmatter, tags, backlink_count }` \u2014 `tags` is an array of strings (no leading `#`) extracted from the `tags:` frontmatter field; `backlink_count` is the number of vault-wide wikilinks (and `![[embeds]]`) that point at the note. Reference frontmatter keys with the dotted prefix `frontmatter.<key>`. Supported operators: `$eq`, `$ne`, `$in`, `$nin`, `$gt`, `$gte`, `$lt`, `$lte`, `$exists`, `$regex`, `$options`, `$and`, `$or`, `$nor`, `$not`. `$regex` is case-insensitive by default; pass `$options` (e.g. `\'\'` for case-sensitive, `\'m\'` for multiline-only) to override. Optional `path_prefix` restricts the scan to a vault subtree (vault-relative POSIX, no leading slash); pass an array for OR-semantics across multiple subtrees (e.g. `["Tasks/", "Reflections/"]`). Optional `exclude_path_prefix` (string or array) drops notes whose path starts with any listed prefix \u2014 valid as the sole path filter, e.g. `["Resources/", "Archive/"]` to search the whole vault except those subtrees. Optional `sort` is `{ field, order }` \u2014 `field` must be `"path"`, `"backlink_count"`, or start with `"frontmatter."`. Optional `limit` defaults to 100, max 1000. Optional `include_content` (default false) \u2014 when true, each result also carries `content` (note body). Returns `{ results, count, truncated }`; each result item carries `vault` and `backlink_count`. `truncated` is true when more notes matched than `limit` allowed. Reads directly from disk and does not require Obsidian to be running.' + describeMultiVault(
       registry2,
       'In multi-vault mode, omit `vault:` to fan out across all registered vaults \u2014 the response shape switches to `results_by_vault: [...]` with `skipped_vaults: [...]`. Pass `vault: "<name>"` to target a specific vault when multiple are registered.'
     ),