neuro-vault-mcp 1.4.0 → 1.5.0

package/README.md

@@ -1,6 +1,6 @@
 # Neuro Vault MCP
 
-**Semantic search over your Obsidian vault — right inside your AI assistant.**
+**Semantic vault search and expansion for your Obsidian vault — right inside your AI assistant.**
 
 [![npm version](https://img.shields.io/npm/v/neuro-vault-mcp)](https://www.npmjs.com/package/neuro-vault-mcp)
 [![Node.js](https://img.shields.io/node/v/neuro-vault-mcp)](https://nodejs.org)
@@ -8,7 +8,7 @@
 
 > "What did I write about that idea last month?"
 
-Neuro Vault MCP connects your Obsidian vault to any MCP-compatible AI assistant. It reuses the embeddings already computed by [Smart Connections](https://github.com/brianpetro/obsidian-smart-connections) — no re-indexing, no extra infrastructure, no API keys.
+Neuro Vault MCP provides semantic search over your Obsidian vault and semantic expansion for related notes. Agents can combine it with structural tools for exact note, path, date, tag, property, and link lookups when those tools are available. It reuses the embeddings already computed by [Smart Connections](https://github.com/brianpetro/obsidian-smart-connections) — no re-indexing, no extra infrastructure, no API keys.
 
 ---
 
@@ -19,20 +19,31 @@ Your question
      │
      ▼
  AI assistant
-     │ rewrites to keyword queries + picks mode
+     │ routes by intent
      ▼
- search_notes (MCP tool)
+     ├──────────────► Structural tools
+     │               (exact file, title, path, daily note, tag, property, wikilink, backlink, link traversal)
      │
-     ├─ vector search over Smart Connections embeddings
-     ├─ block-level search (all modes)
-     └─ expansion via similar notes (deep mode)
-     │
-     ▼
- Ranked results with note paths, similarity scores, section headings
+     └──────────────► search_notes
+                     (semantic retrieval)
+                             │
+                             ▼
+                     get_similar_notes
+                     (semantic expansion)
 ```
 
 The server loads `.smart-env/multi/*.ajson` into memory at startup and keeps it there. No background processes, no watchers, no database.
 
+## Search Routing
+
+Tool routing and retrieval policy are related, but not the same thing.
+
+- Use structural tools first for exact file, title, path, daily note, tag, property, wikilink, backlink, and link traversal requests.
+- Use `search_notes` for fuzzy topic, concept, and semantic retrieval.
+- Use `get_similar_notes` after you already have a relevant note and want semantic expansion.
+- Treat the routing guidance as behavior, not enforcement; the server does not hard-block other tool choices.
+- Use semantic retrieval to find likely notes, then switch to structural tools when you need exact anchors.
+
 ---
 
 ## Requirements
@@ -41,10 +52,19 @@ The server loads `.smart-env/multi/*.ajson` into memory at startup and keeps it
 - Obsidian vault with [Smart Connections](https://github.com/brianpetro/obsidian-smart-connections) plugin (embeddings must be generated)
 - Smart Connections data at `<vault>/.smart-env/multi/*.ajson`
 
+### Operations module (optional)
+
+- The [Obsidian CLI](https://github.com/AlexMost/obsidian-cli) installed and on `PATH` (or pass `--obsidian-cli`).
+- Obsidian running with the URI handler available.
+- Disable with `--no-operations` if you only want semantic search.
+
 ---
 
 ## Quick Start
 
+<details>
+     <summary>Install instructions...</summary>
+
 **1. Install**
 
 ```bash
@@ -92,6 +112,8 @@ Or run without installing using `npx`:
 }
 ```
 
+</details>
+
 **3. Try it**
 
 Ask your assistant:
@@ -198,6 +220,66 @@ Returns: `{ totalNotes, totalBlocks, embeddingDimension, modelKey }`
 
 ---
 
+## Vault Operations
+
+Direct, structural operations on the vault via the Obsidian CLI. Requires Obsidian to be running.
+
+### `read_note`
+
+Read a note's contents.
+
+```typescript
+read_note({
+  name?: string,    // wikilink-style: "My Note"
+  path?: string,    // vault-relative: "Folder/My Note.md"
+})
+```
+
+Returns `{ path, content }`. Provide exactly one of `name` or `path`.
+
+### `create_note`
+
+Create a new note.
+
+```typescript
+create_note({
+  name?: string,
+  path?: string,
+  content?: string,
+  template?: string,
+  overwrite?: boolean,
+})
+```
+
+`overwrite: true` is destructive — the AI assistant will ask before passing it.
+
+### `edit_note`
+
+Add content to an existing note.
+
+```typescript
+edit_note({
+  name?: string,
+  path?: string,
+  content: string,
+  position: 'append' | 'prepend',
+})
+```
+
+### `read_daily`
+
+Read today's daily note. Returns `{ path, content }`.
+
+### `append_daily`
+
+Append content to today's daily note.
+
+```typescript
+append_daily({ content: string });
+```
+
+---
+
 ## AGENTS.md / CLAUDE.md Snippet
 
 Add this to your `AGENTS.md` or `CLAUDE.md` to help the AI assistant use the vault effectively:
@@ -205,15 +287,9 @@ Add this to your `AGENTS.md` or `CLAUDE.md` to help the AI assistant use the vau
 ```markdown
 ## Vault search
 
-Use the `search_notes` MCP tool to search my Obsidian vault before answering questions about my notes, projects, or ideas.
-
-Search protocol:
-
-1. Choose mode: `quick` for specific questions, `deep` for broad topics
-2. Rewrite the query: extract 2-4 keywords, remove filler words
-3. Call search_notes once per concept — use separate calls for synonyms and UA↔EN translations
-
-Skip vault search for: general programming questions, translations, tasks with no personal knowledge component.
+Use vault-aware tools when vault context matters.
+Do not guess about note contents when the vault can be searched.
+Follow the Neuro Vault MCP server instructions for routing between semantic search (`search_notes`, `get_similar_notes`) and operations (`read_note`, `create_note`, `edit_note`, `read_daily`, `append_daily`).
 ```
 
 ---
@@ -222,10 +298,13 @@ Skip vault search for: general programming questions, translations, tasks with n
 
 ### CLI Arguments
 
-| Argument  | Required | Description                                   |
-| --------- | -------- | --------------------------------------------- |
-| `--vault` | yes      | Absolute path to the Obsidian vault directory |
-| `--help`  | no       | Show help                                     |
+| Argument         | Required | Default    | Description                                             |
+| ---------------- | -------- | ---------- | ------------------------------------------------------- |
+| `--vault`        | yes      | —          | Absolute path to the Obsidian vault directory           |
+| `--semantic`     | no       | `true`     | Enable semantic search module (`--no-semantic` to skip) |
+| `--operations`   | no       | `true`     | Enable vault operations module (`--no-operations`)      |
+| `--obsidian-cli` | no       | `obsidian` | Path to the `obsidian` CLI binary (override only)       |
+| `--help`         | no       | —          | Show help                                               |
 
 ### Startup Behavior
 
@@ -262,6 +341,7 @@ npm run format:write  # fix formatting
 - stdio transport only — not HTTP or SSE
 - Local vault path only — no remote vaults
 - Embedding model loaded at startup; first run can be slow
+- Operations tools require the Obsidian CLI and a running Obsidian instance — they fail gracefully per call when unavailable.
 
 ---
 

package/dist/cli.d.ts

@@ -98,12 +98,79 @@ interface SmartConnectionsCorpus {
     sources: Map<string, SmartSource>;
 }
 
-type ToolServer = Pick<McpServer, 'registerTool' | 'connect'>;
-interface NeuroVaultStartupDependencies {
+interface SemanticModuleDeps {
     loadCorpus?: (smartEnvPath: string, modelKey: string) => Promise<SmartConnectionsCorpus>;
-    embeddingServiceFactory?: (modelKey: string) => EmbeddingProvider;
+    embeddingServiceFactory?: (modelId: string) => EmbeddingProvider;
     searchEngine?: SearchEngine;
     toolHandlersFactory?: (deps: ToolHandlerDependencies) => ToolHandlers;
+}
+
+type NoteIdentifier = {
+    kind: 'name';
+    value: string;
+} | {
+    kind: 'path';
+    value: string;
+};
+interface ReadNoteInput {
+    identifier: NoteIdentifier;
+}
+interface ReadNoteResult {
+    path: string;
+    content: string;
+}
+interface CreateNoteInput {
+    name?: string;
+    path?: string;
+    content?: string;
+    template?: string;
+    overwrite?: boolean;
+}
+interface CreateNoteResult {
+    path: string;
+}
+type EditPosition = 'append' | 'prepend';
+interface EditNoteInput {
+    identifier: NoteIdentifier;
+    content: string;
+    position: EditPosition;
+}
+interface DailyNoteResult {
+    path: string;
+    content: string;
+}
+interface AppendDailyInput {
+    content: string;
+}
+interface VaultProvider {
+    readNote(input: ReadNoteInput): Promise<ReadNoteResult>;
+    createNote(input: CreateNoteInput): Promise<CreateNoteResult>;
+    editNote(input: EditNoteInput): Promise<void>;
+    readDaily(): Promise<DailyNoteResult>;
+    appendDaily(input: AppendDailyInput): Promise<void>;
+}
+
+type ExecFn = (binary: string, args: string[], options: {
+    timeout: number;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+interface ObsidianCLIProviderOptions {
+    binaryPath?: string;
+    vaultName?: string;
+    timeoutMs?: number;
+    exec?: ExecFn;
+}
+
+interface OperationsModuleDeps {
+    vaultProviderFactory?: (opts: ObsidianCLIProviderOptions) => VaultProvider;
+}
+
+type ToolServer = Pick<McpServer, 'registerTool' | 'connect'>;
+interface NeuroVaultStartupDependencies {
+    semantic?: SemanticModuleDeps;
+    operations?: OperationsModuleDeps;
     serverFactory?: () => ToolServer;
     transportFactory?: () => StdioServerTransport;
 }