neuro-vault-mcp 3.2.0 → 3.3.0

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

@@ -15368,10 +15368,18 @@ function normalizePath(raw) {
 var VALID_FIELDS = ["frontmatter", "content"];
 var DEFAULT_FIELDS = ["frontmatter", "content"];
 function validateReadNotesInput(input) {
-  if (!Array.isArray(input.paths)) {
-    throw invalidArgument("paths must be an array", "paths");
+  let paths;
+  if (typeof input.paths === "string") {
+    if (input.paths === "") {
+      throw invalidArgument("paths must not be empty", "paths");
+    }
+    paths = [input.paths];
+  } else if (Array.isArray(input.paths)) {
+    paths = input.paths;
+  } else {
+    throw invalidArgument("paths must be a string or an array of strings", "paths");
   }
-  if (input.paths.length < 1 || input.paths.length > 50) {
+  if (paths.length < 1 || paths.length > 50) {
     throw invalidArgument("paths must contain between 1 and 50 entries", "paths");
   }
   let fields;
@@ -15391,7 +15399,7 @@ function validateReadNotesInput(input) {
     }
     fields = input.fields;
   }
-  return { paths: input.paths, fields };
+  return { paths, fields };
 }
 
 // src/modules/operations/tools/append-daily.ts
@@ -15901,7 +15909,7 @@ function buildReadDailyTool(deps) {
 // src/modules/operations/tools/read-notes.ts
 var readNotesFieldSchema = external_exports.enum(["frontmatter", "content"]);
 var inputSchema12 = external_exports.object({
-  paths: external_exports.array(external_exports.string()).min(1).max(50),
+  paths: external_exports.union([external_exports.string().min(1), external_exports.array(external_exports.string()).min(1).max(50)]),
   fields: external_exports.array(readNotesFieldSchema).min(1).optional()
 });
 function buildReadNotesTool(deps) {
@@ -15909,7 +15917,7 @@ function buildReadNotesTool(deps) {
   return {
     name: "read_notes",
     title: "Read Notes",
-    description: "Read multiple notes in one call. `paths` is an array of 1\u201350 vault-relative POSIX paths; duplicates are de-duplicated and results returned in input order. `fields` projects which parts of each note to return \u2014 choose from `frontmatter` and `content`; default `['frontmatter','content']`. One missing or unreadable path does not fail the others \u2014 per-item errors come back inline. A single MCP roundtrip with parallel disk reads. Reads are direct from disk and do not require Obsidian to be running.",
+    description: "Read one or more notes in one call. `paths` is a vault-relative POSIX path string or an array of 1\u201350 such paths; duplicates are de-duplicated and results returned in input order. `fields` projects which parts of each note to return \u2014 choose from `frontmatter` and `content`; default `['frontmatter','content']`. One missing or unreadable path does not fail the others \u2014 per-item errors come back inline. A single MCP roundtrip with parallel disk reads. Reads are direct from disk and do not require Obsidian to be running.",
     inputSchema: inputSchema12,
     handler: async (input) => {
       const { paths, fields } = validateReadNotesInput(input);
@@ -16067,12 +16075,24 @@ 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)
 
 Use \`read_notes\`, \`create_note\`, \`edit_note\`, \`read_daily\`, \`append_daily\` when the user asks to:
-- Read one or more notes by path (\`read_notes\` \u2014 accepts an array of 1\u201350 vault-relative POSIX paths; prefer this over multiple sequential reads)
+- Read one or more notes by path (\`read_notes\` \u2014 accepts a single vault-relative POSIX path string or an array of 1\u201350 such paths; prefer this over multiple sequential reads)
 - Create a new note, task, or idea (\`create_note\`)
 - Add content to an existing note (\`edit_note\`)
 - Read or update today's daily note (\`read_daily\` / \`append_daily\`)
@@ -16124,7 +16144,7 @@ Use \`search_notes\` when the user is recalling a topic fuzzily, asking a concep
 
 ## Routing between operations and semantic
 
-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.
+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 as a single string, or batching with sibling paths in an array) to see the details.
 
 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.
 `;