@bitbonsai/mcpvault 0.15.0 → 0.16.1

package/README.md

@@ -4,7 +4,7 @@
 
 [![MCP Toplist](https://mcptoplist.com/badge/glama%2Fbitbonsai%2Fmcpvault.svg)](https://mcptoplist.com/server/glama%2Fbitbonsai%2Fmcpvault)
 
-A universal AI bridge for Obsidian vaults using the Model Context Protocol (MCP) standard. Connect any MCP-compatible AI assistant to your knowledge base - works with Claude, ChatGPT, and future AI tools. This server provides safe read/write access to your notes while preventing YAML frontmatter corruption.
+A local MCP server that lets compatible clients read, search, and edit notes in an Obsidian vault. MCPVault works directly with vault files, restricts file operations to the configured vault root, and preserves formatting for unchanged frontmatter fields.
 
 <div align="center">
   
@@ -20,18 +20,18 @@ A universal AI bridge for Obsidian vaults using the Model Context Protocol (MCP)
 
 </div>
 
-## Universal Compatibility
+## Supported clients
 
-Works with any MCP-compatible AI assistant including Claude Desktop, Claude Code, ChatGPT Desktop (Enterprise+), OpenCode, Gemini CLI, OpenAI Codex, IntelliJ IDEA 2025.1+, Cursor IDE, Windsurf IDE, Ontheia, and future AI platforms that adopt the MCP standard.
+Configuration examples are available for Claude Desktop, Claude Code, ChatGPT Desktop (Enterprise+), OpenCode, Gemini CLI, OpenAI Codex, IntelliJ IDEA 2025.1+, Cursor, Windsurf, and Ontheia. Other clients can use MCPVault if they support local stdio MCP servers.
 
 https://github.com/user-attachments/assets/657ac4c6-1cd2-4cc3-829f-fd095a32f71c
 
-## Quick Start (5 minutes)
+## Quick start
 
 1. **Install Node.js runtime:**
 
    ```bash
-   # Download from https://nodejs.org (v18.0.0 or later)
+   # Download from https://nodejs.org (v20.0.0 or later)
    # or use a package manager like nvm, brew, apt, etc.
    ```
 
@@ -99,57 +99,41 @@ https://github.com/user-attachments/assets/657ac4c6-1cd2-4cc3-829f-fd095a32f71c
    - "Read my note called 'project-ideas.md'"
    - "Create a new note with today's date"
 
-**Success indicators:** Your AI should be able to list files and read notes from your vault.
+To verify the connection, ask your client to list MCPVault tools or read a known note.
 
-## Why MCPVault?
+## How it connects
 
-### Universal AI Compatibility
-
-Built on the open Model Context Protocol standard, MCPVault is not locked to any single AI provider. As more AI assistants adopt MCP, your investment in this tool grows more valuable. Today it works with Claude and ChatGPT - tomorrow it will work with whatever AI tools emerge.
-
-### Future-Proof Your Knowledge Base
-
-Instead of waiting for each AI company to build Obsidian integrations, MCPVault provides a universal adapter that works with any MCP-compatible assistant. One tool, endless possibilities.
-
-### Open Standard, No Lock-in
-
-MCP is an open protocol. You're not tied to any specific vendor or platform. Your notes remain yours, accessible through any compatible AI assistant.
+An MCP client starts MCPVault as a local stdio process and passes the vault path. MCPVault exposes the same tools to each supported client, so the server is not tied to one AI provider. Obsidian does not need to be running, and no Obsidian plugin is required.
 
 ## Features
 
-- ✅ Safe frontmatter parsing and validation using gray-matter with AST-aware updates that preserve raw formatting for unmodified fields
-- ✅ Path filtering to exclude `.obsidian` directory and other system files
-- ✅ **Complete MCP toolkit**: 18 tools covering all vault operations
+- AST-aware frontmatter updates preserve formatting for unchanged YAML fields.
+- Path checks block traversal, symlink escapes, dotfiles, `.obsidian`, `.git`, and `node_modules`.
+- Eighteen MCP tools cover note and file operations:
   - File operations: `read_note`, `write_note`, `patch_note`, `delete_note`, `move_note`, `move_file`
-  - Partial reads: `get_note_outline` (headings without loading the full file), `read_note_lines` (a specific line range)
-  - Directory operations: `list_directory`
-  - Batch operations: `read_multiple_notes`
-  - Search: `search_notes` with multi-word matching and BM25 relevance reranking
-  - Metadata: `get_frontmatter`, `update_frontmatter`, `get_notes_info`, `get_vault_stats`
-  - Tag management: `manage_tags` (add, remove, list), `list_all_tags`
-  - Wiki links: `wiki_link` picks the shallowest match first (vault root before nested folders), then uses locale-aware path sorting at the same depth. Other matches are returned as alternatives; punctuation may sort before digits, so `_Inbox` can come before `00.projects`.
-- ✅ Write modes: `overwrite`, `append`, `prepend` for flexible content editing
-- ✅ Tag management: add, remove, and list tags in notes
-- ✅ Safe deletion with confirmation requirement to prevent accidents
-- ✅ Automatic path trimming to handle whitespace in inputs
-- ✅ TypeScript support with Node.js runtime (using tsx for execution)
-- ✅ Comprehensive error handling and validation
-- ✅ **Token-optimized responses**: 40-60% smaller responses with minified field names and compact JSON (v0.6.3+)
-- ✅ **Optional pretty-printing**: Set `prettyPrint: true` for human-readable debugging
-- ✅ **Performance optimized**: No unnecessary token consumption, efficient for large vaults
-- ✅ **Zero dependencies**: No Obsidian plugins required, works with any vault structure
+  - Partial reads: `get_note_outline`, `read_note_lines`
+  - Directory and batch reads: `list_directory`, `read_multiple_notes`
+  - Search: `search_notes` with multi-word matching and BM25 reranking
+  - Metadata and tags: `get_frontmatter`, `update_frontmatter`, `get_notes_info`, `get_vault_stats`, `manage_tags`, `list_all_tags`
+  - Wiki links: `wiki_link` resolves names and returns alternative paths when a name is ambiguous
+- `write_note` supports overwrite, append, and prepend modes.
+- `delete_note` and `move_file` require matching confirmation paths.
+- Path arguments are trimmed before validation.
+- Search and batch tools return compact fields by default; set `prettyPrint: true` for expanded output.
+- The package exports TypeScript declarations and public types.
+- MCPVault requires no Obsidian plugin.
 
 ## Prerequisites
 
-- [Node.js](https://nodejs.org) runtime (v18.0.0 or later)
+- [Node.js](https://nodejs.org) runtime (v20.0.0 or later)
 - An Obsidian vault (local directory with `.md`, `.markdown`, `.txt`, `.base`, or `.canvas` files)
 - MCP-compatible AI client (Claude Desktop, ChatGPT Desktop, Claude Code, etc.)
 
 ## Installation
 
-### For End Users (Recommended)
+### For end users
 
-No installation needed! Use `npx` to run directly:
+`npx` downloads and runs the package:
 
 ```bash
 npx @bitbonsai/mcpvault@latest /path/to/your/obsidian/vault
@@ -157,7 +141,7 @@ npx @bitbonsai/mcpvault@latest /path/to/your/obsidian/vault
 
 If you omit the vault path, the server uses your current working directory as the vault root.
 
-### For Developers
+### For developers
 
 1. Clone this repository
 2. Use the correct Node.js version:
@@ -178,7 +162,7 @@ npm install  # Corepack automatically uses npm 10.9.0
 npx @modelcontextprotocol/inspector npm start /path/to/your/vault
 ```
 
-**Pro tip:** Use MCP Inspector to test all server functionality before configuring with AI clients:
+Use MCP Inspector to test the server before adding it to a client:
 
 ```bash
 # Install globally for easier access
@@ -375,12 +359,12 @@ Most modern MCP clients use similar JSON configuration patterns. Refer to your s
 - "List all markdown files in my 'Projects' folder"
 - "Delete the old draft note 'draft-ideas.md' (with confirmation)"
 
-#### Advanced Use Cases:
+#### Example workflows
 
-- **Knowledge Synthesis**: "Summarize all my research notes tagged with 'machine-learning' from the last month"
-- **Project Management**: "Update the status in all project notes to 'completed' and add today's date"
-- **Content Analysis**: "Find all notes that mention 'API design' and create a comprehensive guide"
-- **Smart Tagging**: "Review my untagged notes and suggest appropriate tags based on content"
+- "Summarize my research notes tagged with 'machine-learning' from the last month"
+- "Update the status in my project notes to 'completed' and add today's date"
+- "Find notes that mention 'API design' and draft a guide from them"
+- "Review my untagged notes and suggest tags based on their content"
 
 ## Troubleshooting
 
@@ -459,7 +443,7 @@ Read a note from the vault with parsed frontmatter.
 }
 ```
 
-**Response (optimized for tokens):**
+**Compact response:**
 
 ```json
 {
@@ -536,7 +520,7 @@ Write a note to the vault with optional frontmatter and write mode.
 
 ### `patch_note`
 
-Efficiently replace an exact string inside an existing note without rewriting the full file.
+Replace an exact string inside an existing note without rewriting the full file.
 
 **Request:**
 
@@ -592,7 +576,7 @@ Note: this includes non-note filenames (for example `pdf`, `png`, `jpg`) so AI a
 }
 ```
 
-**Response (optimized):**
+**Compact response:**
 
 ```json
 {
@@ -643,7 +627,7 @@ Delete a note from the vault (requires confirmation for safety).
 }
 ```
 
-**⚠️ Safety Note:** The `confirmPath` parameter must exactly match the `path` parameter to proceed with deletion. This prevents accidental deletions.
+**Confirmation:** `confirmPath` must exactly match `path` before deletion proceeds.
 
 ### `get_frontmatter`
 
@@ -661,7 +645,7 @@ Extract only the frontmatter from a note without reading the full content.
 }
 ```
 
-**Response (optimized, returns frontmatter directly):**
+**Compact response, returning frontmatter directly:**
 
 ```json
 {
@@ -745,7 +729,7 @@ Search for notes in the vault by content or frontmatter with multi-word matching
 }
 ```
 
-**Response (optimized with minified field names):**
+**Compact response:**
 
 ```json
 [
@@ -827,7 +811,7 @@ Move or rename any file in the vault with binary-safe file operations (file-only
 }
 ```
 
-**Safety Note:** `confirmOldPath` must exactly match `oldPath`, and `confirmNewPath` must exactly match `newPath`, otherwise the move is rejected.
+**Confirmation:** `confirmOldPath` must match `oldPath`, and `confirmNewPath` must match `newPath`.
 
 ### `read_multiple_notes`
 
@@ -847,7 +831,7 @@ Read multiple notes in a batch (maximum 10 files).
 }
 ```
 
-**Response (optimized, shortened field names):**
+**Compact response:**
 
 ```json
 {
@@ -911,7 +895,7 @@ Get metadata for notes without reading full content.
 }
 ```
 
-**Response (optimized, returns array directly):**
+**Compact response, returning an array directly:**
 
 ```json
 [
@@ -940,7 +924,7 @@ Get high-level vault statistics without reading note contents.
 }
 ```
 
-**Response (optimized):**
+**Compact response:**
 
 ```json
 {
@@ -957,9 +941,9 @@ Get high-level vault statistics without reading note contents.
 }
 ```
 
-## Security Considerations
+## Security boundaries
 
-This MCP server implements several security measures to protect your Obsidian vault:
+MCPVault applies these checks before file operations:
 
 ### Path Security
 
@@ -992,13 +976,13 @@ This MCP server implements several security measures to protect your Obsidian va
 - **Vault Structure:** Directory structure is visible to AI assistants
 - **File Metadata:** Creation times, file sizes, etc. are accessible
 
-**⚠️ Important:** Only grant vault access to trusted AI conversations. The server provides full read/write access to your notes within the security boundaries above.
+Only grant write access to clients and conversations you trust. Use `--read-only` when the client does not need to modify notes.
 
 ## Architecture
 
 - `server.ts` - MCP server entry point
 - `src/frontmatter.ts` - YAML frontmatter handling with gray-matter
-- `src/filesystem.ts` - Safe file operations with path validation
+- `src/filesystem.ts` - File operations with path validation
 - `src/pathfilter.ts` - Directory and file filtering
 - `src/search.ts` - Note search functionality with content and frontmatter support
 - `src/uri.ts` - Obsidian URI generation for deep links
@@ -1012,6 +996,8 @@ This MCP server implements several security measures to protect your Obsidian va
 4. Ensure all tests pass: `npm test`
 5. Submit a pull request
 
+Maintainers: production publishing is driven by GitHub Releases. See [RELEASING.md](RELEASING.md).
+
 ## License
 
 MIT

package/dist/server.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { createServer } from "./src/createServer.js";
 import { parseCliArgs } from "./src/cli.js";
 import { readFileSync } from "fs";
@@ -50,9 +50,9 @@ Examples:
 // unquoted vault paths with spaces. When omitted, use the current directory.
 const { vaultPathArg, readOnly } = parseCliArgs(cliArgs);
 const vaultPath = resolve(vaultPathArg || process.cwd());
-const server = createServer(vaultPath, { version: VERSION, readOnly });
-const transport = new StdioServerTransport();
-await server.connect(transport);
+// Serve both the legacy handshake-based protocol and MCP 2026-07-28 from the
+// same process. The opening exchange selects the era for this connection.
+const serverHandle = serveStdio(() => createServer(vaultPath, { version: VERSION, readOnly }), { onerror: (error) => console.error(error) });
 // Exit when the client disconnects (stdin EOF) or the process is asked to
 // terminate. Hosts that don't send an MCP shutdown request otherwise leave
 // this process running forever, orphaned once stdin closes (#159).
@@ -62,7 +62,7 @@ async function shutdown() {
         return;
     isShuttingDown = true;
     try {
-        await server.close();
+        await serverHandle.close();
     }
     catch {
         // Best-effort: exit regardless of transport close errors.

package/dist/src/createServer.d.ts

@@ -1,4 +1,4 @@
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { Server } from "@modelcontextprotocol/server";
 import { FrontmatterHandler } from "./frontmatter.js";
 import { PathFilter } from "./pathfilter.js";
 export interface CreateServerOptions {

package/dist/src/createServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createServer.d.ts","sourceRoot":"","sources":["../../src/createServer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAMnE,OAAO,EAAE,kBAAkB,EAAoB,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAK7C,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAYD,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAsezF"}
+{"version":3,"file":"createServer.d.ts","sourceRoot":"","sources":["../../src/createServer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAa,MAAM,8BAA8B,CAAC;AAEjE,OAAO,EAAE,kBAAkB,EAAoB,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAK7C,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAYD,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAsezF"}

package/dist/src/createServer.js

@@ -1,5 +1,4 @@
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { Server } from "@modelcontextprotocol/server";
 import { FileSystemService } from "./filesystem.js";
 import { FrontmatterHandler, parseFrontmatter } from "./frontmatter.js";
 import { PathFilter } from "./pathfilter.js";
@@ -23,7 +22,7 @@ export function createServer(vaultPath, options = {}) {
     const server = new Server({ name, version }, {
         capabilities: { tools: {} },
     });
-    server.setRequestHandler(ListToolsRequestSchema, async () => {
+    server.setRequestHandler("tools/list", async () => {
         const tools = [
             {
                 name: "read_note",
@@ -272,7 +271,7 @@ export function createServer(vaultPath, options = {}) {
                 : tools,
         };
     });
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    server.setRequestHandler("tools/call", async (request) => {
         const { name: toolName, arguments: args } = request.params;
         const trimmedArgs = trimPaths(args);
         if (readOnly && MUTATING_TOOLS.has(toolName)) {

package/dist/src/wikilink/wikiLinkTool.d.ts

@@ -1,4 +1,4 @@
-import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { CallToolResult } from '@modelcontextprotocol/server';
 import type { FileSystemService } from '../filesystem.js';
 export interface WikiLinkToolArgs {
     document: string;

package/dist/src/wikilink/wikiLinkTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wikiLinkTool.d.ts","sourceRoot":"","sources":["../../../src/wikilink/wikiLinkTool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAG1D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,iBAAiB,EAC7B,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,cAAc,CAAC,CAiDzB"}
+{"version":3,"file":"wikiLinkTool.d.ts","sourceRoot":"","sources":["../../../src/wikilink/wikiLinkTool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAG1D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,iBAAiB,EAC7B,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,cAAc,CAAC,CAiDzB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitbonsai/mcpvault",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Universal AI bridge for Obsidian vaults - connect any MCP-compatible assistant",
   "homepage": "https://mcpvault.org",
   "author": "bitbonsai",
@@ -33,19 +33,24 @@
     "prepack": "npm install",
     "publish:dry": "npm publish --dry-run",
     "publish:beta": "npm publish --tag beta",
-    "publish:latest": "npm publish"
+    "publish:latest": "npm publish",
+    "ship": "bun scripts/ship.ts",
+    "ship:setup": "bun scripts/ship.ts --setup",
+    "ship:update": "bun scripts/ship.ts --update"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/server": "^2.3.1",
     "gray-matter": "^4.0.3",
-    "trash": "^10.1.1",
+    "trash": "9.0.0",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
+    "@clack/prompts": "^1.7.0",
+    "@modelcontextprotocol/client": "^2.3.1",
     "@types/node": "^26.1.2",
     "tsx": "^4.23.9",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.12"
   },
   "engines": {
     "node": ">=20.0.0"