neuro-vault-mcp 3.1.0 → 3.2.1

package/README.md

@@ -12,10 +12,11 @@
 
 ## ✨ Why Neuro Vault?
 
-- 🧠 **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. Pass `query: string[]` (up to 8) for synonyms, reformulations, or cross-language pairs — one merged result list with `matched_queries` per entry.
-- ✍️ **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.
+- 🧠 **Semantic search that already knows your vault** — reuses [Smart Connections](https://github.com/brianpetro/obsidian-smart-connections) embeddings. No re-indexing, no API keys, no extra infrastructure.
+- 🎯 **Quick or deep, your call** — fast direct lookups for "find that note", or exploratory mode with related-note expansion when the question is fuzzy.
+- 🧭 **A real navigation toolkit for your agent** — instead of grepping files and opening notes one by one, your assistant walks the vault like a database: filter by tags and properties, batch-read metadata, discover the structure, jump to semantic neighbours.
+- 🔎 **Ask structured questions in plain language** — _"active projects tagged #ai"_, _"todo tasks with a deadline this week"_, _"meeting notes from `Work/` newest first"_ — one call, ranked answer, no chains of reads.
+- ✍️ **Read and write through Obsidian itself** — create, append, edit notes, manage frontmatter and daily notes via the [Obsidian CLI](https://github.com/AlexMost/obsidian-cli), so Smart Connections, sync, and other plugins stay in the loop.
 - ⚡ **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.
 
@@ -36,6 +37,22 @@ For module wiring and internal data flow, see [docs/architecture/module-structur
 
 ---
 
+## 🧭 Your vault, but queryable
+
+A plain-text vault is great for humans and rough on agents. Without the right tools, an assistant ends up listing folders, opening dozens of notes, and grepping inside each one just to answer a simple question.
+
+Neuro Vault gives your assistant a way to **ask the vault directly** — by tag, by frontmatter property, by folder, by similarity. Things like:
+
+> _"What are my active projects tagged #ai with a deadline this quarter?"_
+> _"Show meeting notes from `Work/` from the last two weeks."_
+> _"Find notes similar to this one I'm reading."_
+
+One question, one answer. Your assistant stops being a file browser and starts being an actual second brain.
+
+→ See [docs/guide/vault-operations.md](./docs/guide/vault-operations.md#query_notes) for the full query language and examples.
+
+---
+
 ## ⚡ Quickstart
 
 ```bash

package/dist/cli.js

@@ -494,76 +494,6 @@ function getEmbeddingDimension(sources) {
   return expectedDimension ?? 0;
 }
 
-// src/lib/tool-response.ts
-var ToolHandlerError = class extends Error {
-  code;
-  details;
-  constructor(code, message, options) {
-    super(message);
-    this.name = "ToolHandlerError";
-    this.code = code;
-    this.details = options?.details;
-    if (options?.cause !== void 0) {
-      this.cause = options.cause;
-    }
-  }
-};
-function toToolResponse(value) {
-  const text = value === void 0 ? "ok" : JSON.stringify(value, null, 2);
-  const result = {
-    content: [{ type: "text", text }]
-  };
-  if (value !== void 0 && value !== null) {
-    result.structuredContent = value;
-  }
-  return result;
-}
-function toToolErrorResponse(error48) {
-  if (error48 instanceof ToolHandlerError) {
-    return {
-      content: [{ type: "text", text: error48.message }],
-      structuredContent: {
-        code: error48.code,
-        message: error48.message,
-        details: error48.details
-      },
-      isError: true
-    };
-  }
-  const message = error48 instanceof Error ? error48.message : "Unknown tool error";
-  return {
-    content: [{ type: "text", text: message }],
-    structuredContent: { message },
-    isError: true
-  };
-}
-async function invokeTool(handler) {
-  try {
-    const value = await handler();
-    return toToolResponse(value);
-  } catch (error48) {
-    return toToolErrorResponse(error48);
-  }
-}
-
-// src/lib/tool-registry.ts
-function registerTool(tool) {
-  return {
-    name: tool.name,
-    spec: {
-      ...tool.title !== void 0 ? { title: tool.title } : {},
-      description: tool.description,
-      inputSchema: tool.inputSchema,
-      ...tool.outputSchema !== void 0 ? { outputSchema: tool.outputSchema } : {},
-      ...tool.annotations !== void 0 ? { annotations: tool.annotations } : {}
-    },
-    handler: async (args) => invokeTool(async () => {
-      const parsed = tool.inputSchema.parse(args);
-      return tool.handler(parsed);
-    })
-  };
-}
-
 // node_modules/zod/v4/classic/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -14332,6 +14262,150 @@ function date4(params) {
 // node_modules/zod/v4/classic/external.js
 config(en_default());
 
+// src/lib/input-coercion.ts
+function unwrap(schema) {
+  let current = schema;
+  while (current instanceof external_exports.ZodOptional || current instanceof external_exports.ZodNullable || current instanceof external_exports.ZodDefault) {
+    const unwrapped = current.unwrap();
+    if (!unwrapped) break;
+    current = unwrapped;
+  }
+  return current;
+}
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function coerceField(schema, value) {
+  if (value === null || value === void 0) return value;
+  const inner = unwrap(schema);
+  if (inner instanceof external_exports.ZodNumber) {
+    if (typeof value === "string" && value.trim() !== "") {
+      const n = Number(value);
+      if (Number.isFinite(n)) return n;
+    }
+    return value;
+  }
+  if (inner instanceof external_exports.ZodBoolean) {
+    if (value === "true") return true;
+    if (value === "false") return false;
+    return value;
+  }
+  if (inner instanceof external_exports.ZodObject || inner instanceof external_exports.ZodRecord) {
+    if (typeof value === "string") {
+      try {
+        const parsed = JSON.parse(value);
+        if (isPlainObject2(parsed)) return parsed;
+      } catch {
+      }
+      return value;
+    }
+    return value;
+  }
+  return value;
+}
+function coerceInput(schema, value) {
+  const inner = unwrap(schema);
+  if (!(inner instanceof external_exports.ZodObject)) return value;
+  if (!isPlainObject2(value)) return value;
+  const shape = inner.shape;
+  const out = { ...value };
+  for (const key of Object.keys(shape)) {
+    if (key in out) {
+      out[key] = coerceField(shape[key], out[key]);
+    }
+  }
+  return out;
+}
+
+// src/lib/tool-response.ts
+var ToolHandlerError = class extends Error {
+  code;
+  details;
+  constructor(code, message, options) {
+    super(message);
+    this.name = "ToolHandlerError";
+    this.code = code;
+    this.details = options?.details;
+    if (options?.cause !== void 0) {
+      this.cause = options.cause;
+    }
+  }
+};
+function isPlainRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+}
+function toToolResponse(value) {
+  const text = value === void 0 ? "ok" : JSON.stringify(value, null, 2);
+  const result = {
+    content: [{ type: "text", text }]
+  };
+  if (isPlainRecord(value)) {
+    result.structuredContent = value;
+  }
+  return result;
+}
+function toToolErrorResponse(error48) {
+  if (error48 instanceof ToolHandlerError) {
+    return {
+      content: [{ type: "text", text: error48.message }],
+      structuredContent: {
+        code: error48.code,
+        message: error48.message,
+        details: error48.details
+      },
+      isError: true
+    };
+  }
+  const message = error48 instanceof Error ? error48.message : "Unknown tool error";
+  return {
+    content: [{ type: "text", text: message }],
+    structuredContent: { message },
+    isError: true
+  };
+}
+async function invokeTool(handler) {
+  try {
+    const value = await handler();
+    return toToolResponse(value);
+  } catch (error48) {
+    return toToolErrorResponse(error48);
+  }
+}
+
+// src/lib/tool-registry.ts
+function formatZodError(error48) {
+  const issues = error48.issues.map((issue2) => {
+    const path6 = issue2.path.length > 0 ? issue2.path.join(".") : "<root>";
+    const expected = issue2.expected;
+    const formatted = { path: path6, message: issue2.message };
+    if (typeof expected === "string") formatted.expected = expected;
+    return formatted;
+  });
+  const message = issues.map((i) => `${i.path}: ${i.message}`).join("; ");
+  return { message, issues };
+}
+function registerTool(tool) {
+  return {
+    name: tool.name,
+    spec: {
+      ...tool.title !== void 0 ? { title: tool.title } : {},
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      ...tool.outputSchema !== void 0 ? { outputSchema: tool.outputSchema } : {},
+      ...tool.annotations !== void 0 ? { annotations: tool.annotations } : {}
+    },
+    handler: async (args) => invokeTool(async () => {
+      const coerced = coerceInput(tool.inputSchema, args);
+      const result = tool.inputSchema.safeParse(coerced);
+      if (!result.success) {
+        const { message, issues } = formatZodError(result.error);
+        throw new ToolHandlerError("INVALID_PARAMS", message, { details: { issues } });
+      }
+      return tool.handler(result.data);
+    })
+  };
+}
+
 // src/modules/semantic/tool-helpers.ts
 import path3 from "path";
 var WINDOWS_ABSOLUTE_PATH_RE = /^[A-Za-z]:[\\/]/;
@@ -15578,7 +15652,7 @@ var ALLOWED_OPERATORS = /* @__PURE__ */ new Set([
   "$not"
 ]);
 function validateFilter(filter) {
-  if (!isPlainObject2(filter)) {
+  if (!isPlainObject3(filter)) {
     throw invalidFilter("filter must be a JSON object");
   }
   walk(filter, []);
@@ -15588,7 +15662,7 @@ function walk(value, pathSegments) {
     value.forEach((entry, idx) => walk(entry, [...pathSegments, `[${idx}]`]));
     return;
   }
-  if (!isPlainObject2(value)) return;
+  if (!isPlainObject3(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}`;
@@ -15597,7 +15671,7 @@ function walk(value, pathSegments) {
     walk(child, [...pathSegments, key]);
   }
 }
-function isPlainObject2(value) {
+function isPlainObject3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function invalidFilter(message) {
@@ -15993,6 +16067,18 @@ var require2 = createRequire(import.meta.url);
 var { name: SERVER_NAME, version: SERVER_VERSION } = require2("../package.json");
 var SERVER_INSTRUCTIONS = `This server provides two capability sets for an Obsidian vault: semantic search (when enabled) and direct vault operations (when enabled). Use the right one based on the user's intent.
 
+## Role: a second brain alongside the project
+
+This vault is the user's personal knowledge base \u2014 planning notes, brainstorm artifacts, decisions, reflections, drafts \u2014 that often predates and outlives any single project they bring to you. Before brainstorming new directions, drafting retrospectives, or answering "why did we decide X", check the vault first; the answer is often there but lives nowhere else.
+
+You don't know on your own how the user scopes notes for the current project \u2014 the same vault is typically connected to many, and different users organise differently (a tag, a folder, a frontmatter property like \`project\`, or a combination). The user's project-level instructions should name that scope and tell you how to query for it. If they don't, you have three ways forward, in order of preference:
+
+1. **Probe the vault structure** via \`list_tags\`, \`list_properties\`, and exploratory \`query_notes\` calls \u2014 common conventions (a \`project\` frontmatter field, a \`Projects/\` folder, a recurring tag) usually surface immediately and tell you how this vault is organised.
+2. **Use \`search_notes\`** with the project name and key concepts as a fuzzy entry point \u2014 relevant material may exist under unrelated names.
+3. **Ask the user**, and the first time they save project-specific notes propose a scoping scheme so future sessions have an explicit entry point.
+
+When operating directly inside the vault itself (not from an external project that connects to it), you have both filesystem access and MCP access to the same files. Prefer MCP tools \u2014 \`query_notes\` for structured filters, \`search_notes\` for semantic recall \u2014 over manually scanning files; they exist so frontmatter and similarity queries don't require reading every note.
+
 ## When to use vault operations
 
 ### Notes (body)