neuro-vault-mcp 2.0.0 → 3.0.0

package/README.md

@@ -15,6 +15,7 @@
 - 🧠 **Semantic search over your existing vault** — reuses [Smart Connections](https://github.com/brianpetro/obsidian-smart-connections) embeddings already in your vault. No re-indexing, no API keys, no extra infrastructure.
 - 🎯 **Mode-aware retrieval** — `quick` for direct lookups, `deep` for exploratory questions with block-level results and semantic expansion of related notes.
 - ✍️ **Direct vault operations** — read, create, append, and prepend notes; manage frontmatter properties and inspect tags (including daily notes) straight from your AI assistant via the [Obsidian CLI](https://github.com/AlexMost/obsidian-cli).
+- 🔎 **Structured queries** — one MongoDB-style call (`query_notes`) replaces N+1 chains like "list tags → read each note's property". Ask "active projects with #ai" or "todo tasks created this week" and get a single ranked response.
 - ⚡ **Zero infrastructure** — local stdio MCP server, in-memory index, no database, no background processes, no watchers.
 - 🔌 **Drop-in for any MCP client** — Claude Code, Cursor, Windsurf — configuration is a single JSON block.
 
@@ -70,7 +71,7 @@ User guide lives in [`docs/guide/`](./docs/guide/README.md):
 
 - [Installation](./docs/guide/installation.md)
 - [Semantic Search](./docs/guide/semantic-search.md) — `search_notes`, `get_similar_notes`, `find_duplicates`, `get_stats`
-- [Vault Operations](./docs/guide/vault-operations.md) — note CRUD, daily notes, properties, tags
+- [Vault Operations](./docs/guide/vault-operations.md) — note CRUD, daily notes, properties, tags, structured queries (`query_notes`)
 - [Routing Between Tools](./docs/guide/routing.md)
 - [Configuration](./docs/guide/configuration.md) — CLI args, troubleshooting, limitations, **migration to 2.0**, development
 

package/dist/cli.d.ts

@@ -175,15 +175,6 @@ interface TagListEntry {
     name: string;
     count: number;
 }
-interface GetTagInput {
-    name: string;
-    includeFiles?: boolean;
-}
-interface GetTagResult {
-    name: string;
-    count: number;
-    files?: string[];
-}
 interface VaultProvider {
     createNote(input: CreateNoteInput): Promise<CreateNoteResult>;
     editNote(input: EditNoteInput): Promise<void>;
@@ -194,7 +185,6 @@ interface VaultProvider {
     removeProperty(input: RemovePropertyInput): Promise<void>;
     listProperties(): Promise<PropertyListEntry[]>;
     listTags(): Promise<TagListEntry[]>;
-    getTag(input: GetTagInput): Promise<GetTagResult>;
 }
 
 type ExecFn = (binary: string, args: string[], options: {
@@ -228,8 +218,12 @@ interface ReadNotesInput {
     paths: string[];
     fields: ReadNotesField[];
 }
+interface ScanOptions {
+    pathPrefix?: string;
+}
 interface VaultReader {
     readNotes(input: ReadNotesInput): Promise<ReadNotesItem[]>;
+    scan(opts?: ScanOptions): Promise<string[]>;
 }
 
 interface OperationsModuleDeps {

package/dist/cli.js

@@ -15014,46 +15014,6 @@ var ObsidianCLIProvider = class {
     const { stdout } = await this.runCommand("tags", ["counts", "sort=count", "format=json"]);
     return this.parseJsonList(stdout, "tags");
   }
-  async getTag(input) {
-    const includeFiles = input.includeFiles !== false;
-    const flag = includeFiles ? "verbose" : "total";
-    const { stdout } = await this.runCommand("tag", [`name=${input.name}`, flag]);
-    const COUNT_RE = /(\d+)\s*$/;
-    if (includeFiles) {
-      const lines = stdout.split("\n").map((s) => s.trim()).filter((s) => s.length > 0);
-      const match = lines[0]?.match(COUNT_RE);
-      if (!match) {
-        throw new ToolHandlerError(
-          "CLI_ERROR",
-          `Could not parse tag output for '${input.name}': expected count on first line`,
-          { details: { name: input.name, stdout: stdout.slice(0, 500) } }
-        );
-      }
-      const count2 = Number(match[1]);
-      const files = lines.slice(1);
-      if (count2 === 0) {
-        throw new ToolHandlerError("TAG_NOT_FOUND", `Tag not found: ${input.name}`, {
-          details: { name: input.name }
-        });
-      }
-      return { name: input.name, count: count2, files };
-    }
-    const totalMatch = stdout.trim().match(COUNT_RE);
-    if (!totalMatch) {
-      throw new ToolHandlerError(
-        "CLI_ERROR",
-        `Could not parse tag total for '${input.name}': expected numeric output`,
-        { details: { name: input.name, stdout: stdout.slice(0, 500) } }
-      );
-    }
-    const count = Number(totalMatch[1]);
-    if (count === 0) {
-      throw new ToolHandlerError("TAG_NOT_FOUND", `Tag not found: ${input.name}`, {
-        details: { name: input.name }
-      });
-    }
-    return { name: input.name, count };
-  }
   // Best-effort: a `text` property whose value happens to be "true" or "42"
   // will be coerced to boolean/number. Callers needing ground-truth types should
   // use read_notes and parse frontmatter directly.
@@ -15133,12 +15093,6 @@ var ObsidianCLIProvider = class {
         { details: { stderr, command }, cause: error48 }
       );
     }
-    if (command === "tag" && /tag not found/i.test(stderr)) {
-      return new ToolHandlerError("TAG_NOT_FOUND", `Tag not found: ${stderr.trim()}`, {
-        details: { stderr },
-        cause: error48
-      });
-    }
     if (/not found/i.test(stderr)) {
       return new ToolHandlerError("NOT_FOUND", `Note not found: ${stderr.trim() || "unknown"}`, {
         details: { stderr, command },
@@ -15158,8 +15112,353 @@ var ObsidianCLIProvider = class {
   }
 };
 
-// src/modules/operations/tool-handlers.ts
+// src/modules/operations/query/query-notes.ts
+import siftModule from "sift";
+
+// src/modules/operations/vault-reader.ts
+import { readFile as fsReadFile, stat as fsStat } from "fs/promises";
+import path5 from "path";
+import fastGlob from "fast-glob";
+var ScanPathNotFoundError = class extends Error {
+  code = "PATH_NOT_FOUND";
+  constructor(prefix) {
+    super(`path_prefix not found: ${prefix}`);
+    this.name = "ScanPathNotFoundError";
+  }
+};
+var FsVaultReader = class {
+  vaultRoot;
+  readFile;
+  stat;
+  glob;
+  constructor(opts) {
+    this.vaultRoot = opts.vaultRoot;
+    this.readFile = opts.readFile ?? ((p, enc) => fsReadFile(p, enc));
+    this.stat = opts.stat ?? ((p) => fsStat(p));
+    this.glob = opts.glob ?? ((pattern, options) => fastGlob(pattern, { ...options }));
+  }
+  async readNotes(input) {
+    return Promise.all(input.paths.map((p) => this.readOne(p)));
+  }
+  async scan(opts = {}) {
+    const prefix = normalizeScanPrefix(opts.pathPrefix);
+    if (prefix) {
+      const absPrefix = path5.join(this.vaultRoot, prefix);
+      try {
+        const stats = await this.stat(absPrefix);
+        if (!stats.isDirectory()) {
+          throw new ScanPathNotFoundError(prefix);
+        }
+      } catch (err) {
+        if (err instanceof ScanPathNotFoundError) throw err;
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR") {
+          throw new ScanPathNotFoundError(prefix);
+        }
+        throw err;
+      }
+    }
+    const cwd = prefix ? path5.join(this.vaultRoot, prefix) : this.vaultRoot;
+    const matches = await this.glob("**/*.md", {
+      cwd,
+      onlyFiles: true,
+      dot: false,
+      followSymbolicLinks: false
+    });
+    if (!prefix) {
+      return matches.map(toPosix).sort();
+    }
+    return matches.map((m) => `${prefix}/${toPosix(m)}`).sort();
+  }
+  async readOne(vaultRelativePath) {
+    const absPath = path5.join(this.vaultRoot, vaultRelativePath);
+    let raw;
+    try {
+      raw = await this.readFile(absPath, "utf8");
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT") {
+        return {
+          path: vaultRelativePath,
+          error: {
+            code: "NOT_FOUND",
+            message: `Note not found: ${vaultRelativePath}`
+          }
+        };
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        path: vaultRelativePath,
+        error: {
+          code: "READ_FAILED",
+          message: `Failed to read ${vaultRelativePath}: ${message}`
+        }
+      };
+    }
+    const { frontmatter, content } = splitFrontmatter(raw);
+    return { path: vaultRelativePath, frontmatter, content };
+  }
+};
+function toPosix(p) {
+  return p.replace(/\\/g, "/");
+}
+function normalizeScanPrefix(raw) {
+  if (raw === void 0) return "";
+  const trimmed = raw.trim();
+  if (trimmed === "" || trimmed === "." || trimmed === "./") return "";
+  const slashed = trimmed.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+  return slashed;
+}
+
+// src/modules/operations/query/note-record.ts
+function toNoteRecord(item) {
+  const frontmatter = item.frontmatter && typeof item.frontmatter === "object" ? item.frontmatter : {};
+  return {
+    path: item.path,
+    frontmatter,
+    tags: extractTags(frontmatter)
+  };
+}
+function extractTags(frontmatter) {
+  const raw = frontmatter["tags"];
+  if (raw === void 0 || raw === null) return [];
+  const list = Array.isArray(raw) ? raw : [raw];
+  const out = [];
+  for (const entry of list) {
+    if (entry === null || entry === void 0) continue;
+    const stringified = String(entry).trim().replace(/^#+/, "").trim();
+    if (stringified === "") continue;
+    out.push(stringified);
+  }
+  return out;
+}
+
+// src/modules/operations/query/whitelist.ts
+var ALLOWED_OPERATORS = /* @__PURE__ */ new Set([
+  "$eq",
+  "$ne",
+  "$in",
+  "$nin",
+  "$gt",
+  "$gte",
+  "$lt",
+  "$lte",
+  "$exists",
+  "$regex",
+  "$and",
+  "$or",
+  "$nor",
+  "$not"
+]);
+function validateFilter(filter) {
+  if (!isPlainObject2(filter)) {
+    throw invalidFilter("filter must be a JSON object");
+  }
+  walk(filter, []);
+}
+function walk(value, pathSegments) {
+  if (Array.isArray(value)) {
+    value.forEach((entry, idx) => walk(entry, [...pathSegments, `[${idx}]`]));
+    return;
+  }
+  if (!isPlainObject2(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    if (key.startsWith("$") && !ALLOWED_OPERATORS.has(key)) {
+      const where = pathSegments.length === 0 ? key : `${pathSegments.join(".")}.${key}`;
+      throw invalidFilter(`operator ${key} is not allowed (at ${where})`);
+    }
+    walk(child, [...pathSegments, key]);
+  }
+}
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function invalidFilter(message) {
+  return new ToolHandlerError("INVALID_FILTER", message);
+}
+
+// src/modules/operations/query/query-notes.ts
+var sift = typeof siftModule === "function" ? siftModule : siftModule.default;
+var DEFAULT_LIMIT = 100;
+var HARD_LIMIT_CAP = 1e3;
 var WINDOWS_ABSOLUTE_PATH_RE2 = /^[A-Za-z]:[\\/]/;
+var READ_BATCH_SIZE = 32;
+async function runQueryNotes(input, reader) {
+  const validated = validateInput(input);
+  validateFilter(validated.filter);
+  let paths;
+  try {
+    paths = await reader.scan({ pathPrefix: validated.pathPrefix });
+  } catch (err) {
+    if (err instanceof ScanPathNotFoundError) {
+      throw new ToolHandlerError("PATH_NOT_FOUND", err.message, {
+        details: { path_prefix: validated.pathPrefix }
+      });
+    }
+    throw err;
+  }
+  if (paths.length === 0) {
+    return { results: [], count: 0, truncated: false };
+  }
+  let matcher;
+  try {
+    matcher = sift(validated.filter);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ToolHandlerError("INVALID_FILTER", `filter rejected by sift: ${message}`);
+  }
+  const fields = validated.includeContent ? ["frontmatter", "content"] : ["frontmatter"];
+  const earlyExitAllowed = !validated.sort || validated.sort.field === "path" && validated.sort.order === "asc";
+  const matched = [];
+  for (let i = 0; i < paths.length; i += READ_BATCH_SIZE) {
+    const slice = paths.slice(i, i + READ_BATCH_SIZE);
+    const items = await reader.readNotes({ paths: slice, fields: [...fields] });
+    for (const item of items) {
+      if ("error" in item) {
+        if (item.error.code === "READ_FAILED") {
+          process.stderr.write(`[neuro-vault] query_notes: ${item.error.message}
+`);
+        }
+        continue;
+      }
+      const record2 = toNoteRecord(item);
+      let isMatch;
+      try {
+        isMatch = matcher(record2);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ToolHandlerError("INVALID_FILTER", `filter execution failed: ${message}`);
+      }
+      if (!isMatch) continue;
+      matched.push(validated.includeContent ? { record: record2, content: item.content } : { record: record2 });
+    }
+    if (earlyExitAllowed && matched.length > validated.limit) break;
+  }
+  if (validated.sort) {
+    sortInPlace(matched, validated.sort);
+  }
+  const truncated = matched.length > validated.limit;
+  const sliced = matched.slice(0, validated.limit);
+  const results = sliced.map(
+    (row) => validated.includeContent ? {
+      path: row.record.path,
+      frontmatter: row.record.frontmatter,
+      content: row.content
+    } : { path: row.record.path, frontmatter: row.record.frontmatter }
+  );
+  return { results, count: results.length, truncated };
+}
+function validateInput(input) {
+  if (!input || typeof input !== "object") {
+    throw invalidParams("input must be an object", "input");
+  }
+  if (input.filter === void 0 || input.filter === null) {
+    throw invalidParams("filter is required", "filter");
+  }
+  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);
+  }
+  let sort;
+  if (input.sort !== void 0) {
+    sort = validateSort(input.sort);
+  }
+  let limit = DEFAULT_LIMIT;
+  if (input.limit !== void 0) {
+    if (typeof input.limit !== "number" || !Number.isInteger(input.limit) || input.limit < 1 || input.limit > HARD_LIMIT_CAP) {
+      throw invalidParams(`limit must be an integer between 1 and ${HARD_LIMIT_CAP}`, "limit");
+    }
+    limit = input.limit;
+  }
+  let includeContent = false;
+  if (input.include_content !== void 0) {
+    if (typeof input.include_content !== "boolean") {
+      throw invalidParams("include_content must be a boolean", "include_content");
+    }
+    includeContent = input.include_content;
+  }
+  return {
+    filter: input.filter,
+    pathPrefix,
+    sort,
+    limit,
+    includeContent
+  };
+}
+function normalizeScanPrefixInput(raw) {
+  const trimmed = raw.trim();
+  if (trimmed === "" || trimmed === "." || trimmed === "./") return void 0;
+  if (trimmed.startsWith("/") || WINDOWS_ABSOLUTE_PATH_RE2.test(trimmed)) {
+    throw invalidParams("path_prefix must be vault-relative", "path_prefix");
+  }
+  const slashed = trimmed.replace(/\\/g, "/").replace(/^\.\//, "");
+  if (slashed.split("/").some((segment) => segment === "..")) {
+    throw invalidParams("path_prefix must be vault-relative", "path_prefix");
+  }
+  return slashed.replace(/\/+$/, "");
+}
+function validateSort(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw invalidParams("sort must be an object { field, order }", "sort");
+  }
+  const obj = raw;
+  if (typeof obj.field !== "string" || obj.field.trim() === "") {
+    throw invalidParams("sort.field must be a non-empty string", "sort.field");
+  }
+  if (obj.field !== "path" && !obj.field.startsWith("frontmatter.")) {
+    throw invalidParams('sort.field must be "path" or start with "frontmatter."', "sort.field");
+  }
+  if (obj.order !== "asc" && obj.order !== "desc") {
+    throw invalidParams('sort.order must be "asc" or "desc"', "sort.order");
+  }
+  return { field: obj.field, order: obj.order };
+}
+function sortInPlace(rows, sort) {
+  const direction = sort.order === "asc" ? 1 : -1;
+  rows.sort((a, b) => {
+    const av = readField(a.record, sort.field);
+    const bv = readField(b.record, sort.field);
+    return compare(av, bv) * direction;
+  });
+}
+function readField(record2, field) {
+  if (field === "path") return record2.path;
+  const segments = field.split(".").slice(1);
+  let cursor = record2.frontmatter;
+  for (const seg of segments) {
+    if (cursor === null || cursor === void 0) return void 0;
+    if (typeof cursor !== "object") return void 0;
+    cursor = cursor[seg];
+  }
+  return cursor;
+}
+function compare(a, b) {
+  if (a === void 0 || a === null) {
+    return b === void 0 || b === null ? 0 : 1;
+  }
+  if (b === void 0 || b === null) return -1;
+  if (typeof a === "number" && typeof b === "number") {
+    return a - b;
+  }
+  if (typeof a === "boolean" && typeof b === "boolean") {
+    return a === b ? 0 : a ? 1 : -1;
+  }
+  const sa = String(a);
+  const sb = String(b);
+  return sa < sb ? -1 : sa > sb ? 1 : 0;
+}
+function invalidParams(message, field) {
+  return new ToolHandlerError("INVALID_PARAMS", message, { details: { field } });
+}
+
+// src/modules/operations/tool-handlers.ts
+var WINDOWS_ABSOLUTE_PATH_RE3 = /^[A-Za-z]:[\\/]/;
 function invalidArgument(message, field) {
   return new ToolHandlerError("INVALID_ARGUMENT", message, {
     details: { field }
@@ -15246,7 +15545,7 @@ function normalizePath(raw) {
   const trimmed = raw.trim();
   if (!trimmed) throw invalidArgument("path must not be empty", "path");
   const slashed = trimmed.replace(/\\/g, "/");
-  if (slashed.startsWith("/") || WINDOWS_ABSOLUTE_PATH_RE2.test(slashed)) {
+  if (slashed.startsWith("/") || WINDOWS_ABSOLUTE_PATH_RE3.test(slashed)) {
     throw invalidArgument("path must be vault-relative", "path");
   }
   if (slashed.split("/").some((segment) => segment === "..")) {
@@ -15332,6 +15631,9 @@ function createOperationsHandlers(deps) {
       const errors = results.reduce((n, r) => n + ("error" in r ? 1 : 0), 0);
       return { results, count: results.length, errors };
     },
+    async queryNotes(input) {
+      return runQueryNotes(input, reader);
+    },
     async createNote(input) {
       if (input.name === void 0 && input.path === void 0) {
         throw invalidArgument("Provide name or path", "name");
@@ -15404,14 +15706,6 @@ function createOperationsHandlers(deps) {
     },
     async listTags(_input) {
       return provider.listTags();
-    },
-    async getTag(input) {
-      const stripped = (input.tag ?? "").trim().replace(/^#/, "").trim();
-      if (stripped === "") {
-        throw invalidArgument("tag must not be empty", "tag");
-      }
-      const includeFiles = input.include_files !== false;
-      return provider.getTag({ name: stripped, includeFiles });
     }
   };
 }
@@ -15426,6 +15720,17 @@ var readNotesSchema = external_exports.object({
   paths: external_exports.array(external_exports.string()).min(1).max(50),
   fields: external_exports.array(readNotesFieldSchema).min(1).optional()
 });
+var queryNotesSortSchema = external_exports.object({
+  field: external_exports.string().min(1),
+  order: external_exports.enum(["asc", "desc"])
+});
+var queryNotesSchema = external_exports.object({
+  filter: external_exports.record(external_exports.string(), external_exports.unknown()),
+  path_prefix: external_exports.string().optional(),
+  sort: queryNotesSortSchema.optional(),
+  limit: external_exports.number().int().min(1).max(1e3).optional(),
+  include_content: external_exports.boolean().optional()
+});
 var createNoteSchema = external_exports.object({
   ...noteIdentifierShape,
   content: external_exports.string().optional(),
@@ -15457,10 +15762,6 @@ var removePropertySchema = external_exports.object({
 });
 var listPropertiesSchema = external_exports.object({});
 var listTagsSchema = external_exports.object({});
-var getTagSchema = external_exports.object({
-  tag: external_exports.string(),
-  include_files: external_exports.boolean().optional()
-});
 function buildOperationsTools(handlers) {
   return [
     {
@@ -15472,6 +15773,15 @@ function buildOperationsTools(handlers) {
       },
       handler: async (args) => invokeTool(() => handlers.readNotes(readNotesSchema.parse(args)))
     },
+    {
+      name: "query_notes",
+      spec: {
+        title: "Query Notes",
+        description: 'Run a structured MongoDB-style query against the vault\'s frontmatter and tags. `filter` is a sift/MongoDB filter object evaluated against `NoteRecord` shape `{ path, frontmatter, tags }` \u2014 `tags` is an array of strings (no leading `#`) extracted from the `tags:` frontmatter field. Reference frontmatter keys with the dotted prefix `frontmatter.<key>`. Supported operators: `$eq`, `$ne`, `$in`, `$nin`, `$gt`, `$gte`, `$lt`, `$lte`, `$exists`, `$regex`, `$and`, `$or`, `$nor`, `$not`. 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"` 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 }`; `truncated` is true when more notes matched than `limit` allowed. Reads directly from disk and does not require Obsidian to be running.',
+        inputSchema: queryNotesSchema
+      },
+      handler: async (args) => invokeTool(() => handlers.queryNotes(queryNotesSchema.parse(args)))
+    },
     {
       name: "create_note",
       spec: {
@@ -15552,62 +15862,10 @@ function buildOperationsTools(handlers) {
         inputSchema: listTagsSchema
       },
       handler: async () => invokeTool(() => handlers.listTags({}))
-    },
-    {
-      name: "get_tag",
-      spec: {
-        title: "Get Tag",
-        description: "Get info about one tag. Provide `tag` (with or without the leading `#` \u2014 both `ai` and `#ai` work). Returns `{ name, count }` where `name` is the stripped tag string, plus `files: string[]` by default. Pass `include_files: false` for popular tags where the file list would be large.",
-        inputSchema: getTagSchema
-      },
-      handler: async (args) => invokeTool(() => handlers.getTag(getTagSchema.parse(args)))
     }
   ];
 }
 
-// src/modules/operations/vault-reader.ts
-import { readFile as fsReadFile } from "fs/promises";
-import path5 from "path";
-var FsVaultReader = class {
-  vaultRoot;
-  readFile;
-  constructor(opts) {
-    this.vaultRoot = opts.vaultRoot;
-    this.readFile = opts.readFile ?? ((p, enc) => fsReadFile(p, enc));
-  }
-  async readNotes(input) {
-    return Promise.all(input.paths.map((p) => this.readOne(p)));
-  }
-  async readOne(vaultRelativePath) {
-    const absPath = path5.join(this.vaultRoot, vaultRelativePath);
-    let raw;
-    try {
-      raw = await this.readFile(absPath, "utf8");
-    } catch (err) {
-      const code = err.code;
-      if (code === "ENOENT") {
-        return {
-          path: vaultRelativePath,
-          error: {
-            code: "NOT_FOUND",
-            message: `Note not found: ${vaultRelativePath}`
-          }
-        };
-      }
-      const message = err instanceof Error ? err.message : String(err);
-      return {
-        path: vaultRelativePath,
-        error: {
-          code: "READ_FAILED",
-          message: `Failed to read ${vaultRelativePath}: ${message}`
-        }
-      };
-    }
-    const { frontmatter, content } = splitFrontmatter(raw);
-    return { path: vaultRelativePath, frontmatter, content };
-  }
-};
-
 // src/modules/operations/index.ts
 function createOperationsModule(config2, deps = {}) {
   const providerFactory = deps.vaultProviderFactory ?? ((opts) => new ObsidianCLIProvider(opts));
@@ -15635,6 +15893,10 @@ Use \`read_notes\`, \`create_note\`, \`edit_note\`, \`read_daily\`, \`append_dai
 
 \`create_note\` with \`overwrite: true\` is destructive. Always ask the user before overwriting an existing note.
 
+### Structured queries
+
+Use \`query_notes\` for multi-criteria questions that combine tags, frontmatter properties, and ranges \u2014 for example "active projects with #ai", "todo tasks created this week", "notes with deadline set", "all notes tagged X". The \`filter\` is a MongoDB-style object evaluated against \`{ path, frontmatter, tags }\` \u2014 reference frontmatter keys as \`frontmatter.<key>\` and tags via the top-level \`tags\` field (no leading \`#\`). Supported operators: \`$eq\`, \`$ne\`, \`$in\`, \`$nin\`, \`$gt\`, \`$gte\`, \`$lt\`, \`$lte\`, \`$exists\`, \`$regex\`, \`$and\`, \`$or\`, \`$nor\`, \`$not\`. To list notes by a single tag use \`{ filter: { tags: 'X' } }\`. The result \`{ results, count, truncated }\` includes \`frontmatter\` always; pass \`include_content: true\` only when bodies are needed up-front (it can grow the response a lot). Reads directly from disk; does not need Obsidian running. \`limit\` defaults to 100 and is capped at 1000.
+
 ### Frontmatter properties
 
 Use \`set_property\`, \`read_property\`, \`remove_property\` when the user asks to read or modify a single YAML frontmatter field (status, due date, priority, etc.). Use \`list_properties\` to see what property names are already in use across the vault \u2014 useful before introducing a new one.
@@ -15645,11 +15907,11 @@ If you need frontmatter for one or more notes, call \`read_notes\` with \`fields
 
 ### Tags
 
-Use \`list_tags\` to see all tags ranked by frequency, and \`get_tag\` to find which files use a specific tag. Pass \`include_files: false\` to \`get_tag\` for very popular tags where the full file list would be large. The leading \`#\` on tag names is optional \u2014 both \`ai\` and \`#ai\` work.
+Use \`list_tags\` to see all tags ranked by frequency. To list the notes that carry a specific tag, call \`query_notes\` with \`{ filter: { tags: '<name>' } }\` (no leading \`#\`).
 
 ### CLI availability
 
-The vault-operations tools (other than \`read_notes\`) route through the Obsidian CLI and require Obsidian to be running. If a call fails with \`CLI_NOT_FOUND\` or \`CLI_UNAVAILABLE\`, tell the user and stop \u2014 do not retry. \`read_notes\` reads directly from disk and does not need Obsidian to be running.
+The vault-operations tools (other than \`read_notes\` and \`query_notes\`) route through the Obsidian CLI and require Obsidian to be running. If a call fails with \`CLI_NOT_FOUND\` or \`CLI_UNAVAILABLE\`, tell the user and stop \u2014 do not retry. \`read_notes\` and \`query_notes\` read directly from disk and do not need Obsidian to be running.
 
 ## When to use semantic search
 
@@ -15677,7 +15939,7 @@ Use \`search_notes\` when the user is recalling a topic fuzzily, asking a concep
 
 If the user gives an exact anchor (note path, daily note, tag, frontmatter field), prefer operations tools. If the user is recalling fuzzily or asking a conceptual question, prefer \`search_notes\`. After semantic search finds a relevant note, you can read it with \`read_notes\` (passing the path in a one-element array, or batching with sibling paths) to see the details.
 
-For tag-driven questions ("which notes are tagged X?", "show me everything in #ai") use \`get_tag\`, not \`search_notes\` \u2014 the answer is exact, not fuzzy.
+For tag-driven questions ("which notes are tagged X?", "show me everything in #ai") use \`query_notes\` with \`{ filter: { tags: '<name>' } }\`, not \`search_notes\` \u2014 the answer is exact, not fuzzy.
 `;
 function defaultServerFactory() {
   return new McpServer(