neuro-vault-mcp 1.3.1 → 1.4.1

package/README.md

@@ -1,133 +1,277 @@
 # Neuro Vault MCP
 
-Neuro Vault MCP is a Model Context Protocol server for semantic search over an Obsidian vault that already has Smart Connections embeddings and note data on disk. It reads Smart Connections `.smart-env/multi/*.ajson` files, loads the corpus into memory, and exposes MCP tools over stdio so compatible clients can search the vault without extra infrastructure.
+**Semantic vault search and expansion for your Obsidian vault — right inside your AI assistant.**
 
-## Overview
+[![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)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
 
-The server is started by an MCP host or from the command line with an explicit vault path:
+> "What did I write about that idea last month?"
 
-```bash
-neuro-vault-mcp --vault /absolute/path/to/vault
-```
+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.
+
+---
 
-The vault path must be absolute. Neuro Vault MCP expects Smart Connections data in:
+## How It Works
 
-```text
-<vault>/.smart-env/multi/*.ajson
 ```
+Your question
+     │
+     ▼
+ AI assistant
+     │ routes by intent
+     ▼
+     ├──────────────► Structural tools
+     │               (exact file, title, path, daily note, tag, property, wikilink, backlink, link traversal)
+     │
+     └──────────────► 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.
 
-On first run, the query embedding model is downloaded automatically. That initial model download may add noticeable startup latency.
+## 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
 
-- Node.js 20 or newer
-- An Obsidian vault on the local machine
-- Smart Connections data present in `<vault>/.smart-env/multi/*.ajson`
+- Node.js 20+
+- 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`
+
+---
 
-## Installation
+## Quick Start
 
-Install globally:
+**1. Install**
 
 ```bash
 npm install -g neuro-vault-mcp
 ```
 
-Or run it on demand with `npx`:
+**2. Configure your MCP client**
 
-```bash
-npx -y neuro-vault-mcp --vault /absolute/path/to/vault
-```
+For Claude Code (`~/.claude/settings.json` or `.claude/settings.json` in your project):
 
-## MCP Configuration Example
+```json
+{
+  "mcpServers": {
+    "neuro-vault": {
+      "command": "neuro-vault-mcp",
+      "args": ["--vault", "/absolute/path/to/your/vault"]
+    }
+  }
+}
+```
 
-Most MCP hosts just need the binary and vault argument:
+For Cursor or Windsurf (`.cursor/mcp.json` / `.windsurf/mcp.json`):
 
 ```json
 {
-  "command": "neuro-vault-mcp",
-  "args": ["--vault", "/absolute/path/to/vault"]
+  "mcpServers": {
+    "neuro-vault": {
+      "command": "neuro-vault-mcp",
+      "args": ["--vault", "/absolute/path/to/your/vault"]
+    }
+  }
 }
 ```
 
-If your host uses a more explicit JSON configuration, the same launch command applies:
+Or run without installing using `npx`:
 
 ```json
 {
   "mcpServers": {
     "neuro-vault": {
-      "command": "neuro-vault-mcp",
-      "args": ["--vault", "/absolute/path/to/vault"]
+      "command": "npx",
+      "args": ["-y", "neuro-vault-mcp", "--vault", "/absolute/path/to/your/vault"]
     }
   }
 }
 ```
 
-## CLI Usage
+**3. Try it**
 
-After installing globally, launch the server directly from your shell:
+Ask your assistant:
 
-```bash
-neuro-vault-mcp --vault /absolute/path/to/vault
-```
+> "What did I write about building AI agents?"
+
+> "Find my notes on productivity systems"
+
+> "What are all my ideas related to embeddings?"
+
+On first run the embedding model downloads automatically (~40 MB). Subsequent starts are fast.
+
+---
+
+## Features
+
+### Mode-Based Search
+
+Every search picks a mode that controls retrieval depth:
 
-The process speaks MCP over stdio, so it is intended to be started by a compatible client or wrapper process rather than visited in a browser.
+| Mode    | Use when                          | Limit | Threshold | Expansion |
+| ------- | --------------------------------- | ----- | --------- | --------- |
+| `quick` | Specific question, need 1-2 notes | 3     | 0.50      | off       |
+| `deep`  | Broad topic, need an overview     | 8     | 0.35      | on        |
 
-## Available Tools
+The AI assistant picks the mode automatically based on your question. You can also pass it explicitly.
+
+### Block-Level Results (Deep Mode)
+
+In `deep` mode the server also searches by individual note sections (blocks), not just whole notes. This surfaces the exact paragraphs that are most relevant, not just the note they live in.
+
+### Expansion (Deep Mode)
+
+After finding top results, the server uses their embeddings to discover neighboring notes. This catches related notes that don't directly match your query but are semantically close to what you found.
+
+### Automatic Fallback
+
+When vector search returns nothing, the server retries with a lower similarity threshold (0.3). If still nothing — the AI assistant can search vault files using its own tools.
+
+---
+
+## Tools Reference
 
 ### `search_notes`
 
-Search the loaded corpus by semantic similarity.
+Search the vault by semantic similarity.
+
+```typescript
+search_notes({
+  query: string,               // short keyword query (1-4 words)
+  mode?: "quick" | "deep",    // default: "quick"
+  threshold?: number,          // override mode default (0–1)
+  expansion?: boolean,         // override mode default
+  expansion_limit?: number,    // how many top results to expand (default: 3)
+})
+```
+
+Returns `results` (ranked notes) and `blockResults` (ranked sections — scoped to matched notes in quick mode, all sources in deep mode).
+
+**Tips for better results:**
 
-Parameters:
+- Use short keyword queries (1–4 words), not full sentences
+- Call multiple times for synonyms and translations: `"embeddings"`, then `"векторний пошук"`, then `"vector search"`
+- Lower the threshold to `0.3` if nothing comes back
+- Use `deep` mode for exploratory questions
 
-- `query` `string` required
-- `limit` `number` optional, default `10`, must be a positive integer
-- `threshold` `number` optional, default `0.5`, must be between `0` and `1`
+---
 
 ### `get_similar_notes`
 
-Find notes similar to a vault-relative note path.
+Find notes similar to a given note path.
+
+```typescript
+get_similar_notes({
+  note_path: string,  // vault-relative POSIX path, e.g. "Projects/neuro-vault.md"
+  limit?: number,     // default: 10
+  threshold?: number, // default: 0.5
+})
+```
 
-Parameters:
+Use this after `search_notes` finds a relevant note — it discovers related content without needing a text query.
 
-- `note_path` `string` required, vault-relative and POSIX-style
-- `limit` `number` optional, default `10`, must be a positive integer
-- `threshold` `number` optional, default `0.5`, must be between `0` and `1`
+---
 
 ### `find_duplicates`
 
 Find note pairs with high embedding similarity.
 
-Parameters:
+```typescript
+find_duplicates({
+  threshold?: number, // default: 0.9
+})
+```
+
+Useful for vault maintenance: identifies notes that cover the same topic and could be merged.
 
-- `threshold` `number` optional, default `0.9`, must be between `0` and `1`
+---
 
 ### `get_stats`
 
-Report corpus and embedding statistics.
+Report loaded corpus statistics.
 
-Parameters:
+Returns: `{ totalNotes, totalBlocks, embeddingDimension, modelKey }`
 
-- none
+---
 
-## Tool Output
+## AGENTS.md / CLAUDE.md Snippet
 
-All search-style tools return note paths relative to the vault, similarity scores, and the note blocks preserved from Smart Connections data. `get_stats` returns the loaded corpus size, block count, embedding dimension, and model key.
+Add this to your `AGENTS.md` or `CLAUDE.md` to help the AI assistant use the vault effectively:
 
-## Development Commands
+```markdown
+## Vault search
+
+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 and retrieval.
+```
+
+---
+
+## Configuration
+
+### CLI Arguments
+
+| Argument  | Required | Description                                   |
+| --------- | -------- | --------------------------------------------- |
+| `--vault` | yes      | Absolute path to the Obsidian vault directory |
+| `--help`  | no       | Show help                                     |
+
+### Startup Behavior
+
+- Smart Connections `.ajson` files are loaded into memory once at startup
+- The embedding model (`TaylorAI/bge-micro-v2`) is downloaded on first run and cached by `@xenova/transformers`
+- If the vault path is missing or Smart Connections data is absent, the server exits immediately with an error
+
+### Troubleshooting
+
+**"Smart Connections directory does not exist"** — make sure the Smart Connections plugin has run and generated embeddings. Open Obsidian, let Smart Connections finish indexing, then restart the MCP server.
+
+**First startup is slow** — the embedding model (~40 MB) is downloading. Subsequent starts use the cached model.
+
+**Search returns nothing** — try lowering the threshold: `threshold: 0.3`. Also check that `get_stats` shows a non-zero `totalNotes`.
+
+---
+
+## Development
 
 ```bash
-npm run build
-npm run lint
-npm run format
-npm run format:write
-npm run test
+npm run build       # compile TypeScript to dist/
+npm run test        # run tests with vitest
+npm run lint        # ESLint
+npm run format      # check formatting with Prettier
+npm run format:write  # fix formatting
 ```
 
-## Limitations for v1
+---
+
+## Limitations
 
 - Requires Smart Connections `.ajson` files already present in the vault
-- Uses in-memory search only, with no persistent index
-- Starts over stdio only, not HTTP or SSE
-- Loads the embedding model at startup, so the first run can be slow
-- Expects a local vault path and does not support remote vaults
+- In-memory search only — no persistent index, no background re-indexing
+- stdio transport only — not HTTP or SSE
+- Local vault path only — no remote vaults
+- Embedding model loaded at startup; first run can be slow
+
+---
+
+## License
+
+ISC — see [LICENSE](LICENSE).
+
+Changelog: [Releases](https://github.com/AlexMost/neuro-vault/releases)

package/dist/cli.d.ts

@@ -2,6 +2,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 
+interface RetrievalOutput {
+    results: SearchResult[];
+    blockResults?: BlockSearchResult[];
+}
+
 interface SmartBlock {
     key: string;
     heading: string;
@@ -13,14 +18,15 @@ interface SmartSource {
     embedding: number[];
     blocks: SmartBlock[];
 }
-interface SearchResultBlock {
+interface BlockSearchResult {
+    path: string;
     heading: string;
     lines: [number, number];
+    similarity: number;
 }
 interface SearchResult {
     path: string;
     similarity: number;
-    blocks: SearchResultBlock[];
 }
 interface DuplicatePair {
     note_a: string;
@@ -39,15 +45,25 @@ interface SearchEngine {
         limit?: number;
         excludePath?: string;
     }): SearchResult[];
+    findBlockNeighbors(args: {
+        queryVector: number[];
+        sources: Iterable<SmartSource>;
+        threshold: number;
+        limit?: number;
+    }): BlockSearchResult[];
     findDuplicates(args: {
         sources: Iterable<SmartSource>;
         threshold: number;
     }): DuplicatePair[];
 }
+type SearchMode = 'quick' | 'deep';
 interface SearchNotesInput {
     query: string;
+    mode?: SearchMode;
     limit?: number;
     threshold?: number;
+    expansion?: boolean;
+    expansion_limit?: number;
 }
 interface GetSimilarNotesInput {
     note_path: string;
@@ -72,7 +88,7 @@ interface ToolHandlerDependencies {
     modelKey: string;
 }
 interface ToolHandlers {
-    searchNotes(input: SearchNotesInput): Promise<SearchResult[]>;
+    searchNotes(input: SearchNotesInput): Promise<RetrievalOutput>;
     getSimilarNotes(input: GetSimilarNotesInput): Promise<SearchResult[]>;
     findDuplicates(input?: FindDuplicatesInput): Promise<DuplicatePair[]>;
     getStats(): Promise<ToolStats>;