@bitbonsai/mcpvault 0.16.1 → 0.17.1

package/README.md

@@ -258,6 +258,21 @@ Add `--read-only` after the vault path to expose only read tools. Mutating tools
 
 The CLI also accepts `--read-only true` and `--read-only=true` for configuration systems that require explicit values. Omit the option, or set it to `false`, to keep normal read/write access.
 
+**Default search and listing exclusions:**
+
+Repeat `--exclude <subtree>` to hide vault-relative folders from `search_notes` and `list_directory` in every session. Per-call `excludePaths` add to these defaults. Direct read and write tools remain available for excluded paths.
+
+```json
+"args": [
+  "@bitbonsai/mcpvault@latest",
+  "/Users/yourname/Documents/ResearchVault",
+  "--exclude", "Archive",
+  "--exclude", "Snapshots/Old"
+]
+```
+
+MCPVault does not read Obsidian's `.obsidian/app.json`; exclusions stay explicit in the MCP server configuration.
+
 **Configuration File Locations:**
 
 - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
@@ -981,6 +996,8 @@ Only grant write access to clients and conversations you trust. Use `--read-only
 ## Architecture
 
 - `server.ts` - MCP server entry point
+- `src/cli.ts` - CLI option parsing for vault path, read-only mode, and default exclusions
+- `src/createServer.ts` - MCP tool registration, request routing, and discovery defaults
 - `src/frontmatter.ts` - YAML frontmatter handling with gray-matter
 - `src/filesystem.ts` - File operations with path validation
 - `src/pathfilter.ts` - Directory and file filtering

package/dist/server.js

@@ -24,7 +24,7 @@ mcpvault v${VERSION}
 Universal AI bridge for Obsidian vaults - connect any MCP-compatible assistant
 
 Usage:
-  npx @bitbonsai/mcpvault [vault-path] [--read-only[=true|false]]
+  npx @bitbonsai/mcpvault [vault-path] [--read-only[=true|false]] [--exclude <subtree>]...
 
 Arguments:
   [vault-path]    Optional path to your Obsidian vault directory
@@ -35,12 +35,15 @@ Options:
   --help, -h      Show this help message
   --read-only     Expose read tools only and reject all vault mutations
                   May be passed alone, with true/false, or as --read-only=true
+  --exclude PATH  Hide a vault-relative subtree from search and directory listings
+                  Repeat for multiple subtrees; direct read/write tools are unaffected
 
 Examples:
   npx @bitbonsai/mcpvault
   npx @bitbonsai/mcpvault ~/Documents/MyVault
   npx @bitbonsai/mcpvault ./Vault
   npx @bitbonsai/mcpvault ./Vault --read-only
+  npx @bitbonsai/mcpvault ./Vault --exclude Archive --exclude "Snapshots/Old"
   npx @bitbonsai/mcpvault /path/to/obsidian/vault
   npx @bitbonsai/mcpvault "/path/with spaces/Obsidian Vault"
 `);
@@ -48,11 +51,11 @@ Examples:
 }
 // Remove runtime options before joining trailing args, preserving support for
 // unquoted vault paths with spaces. When omitted, use the current directory.
-const { vaultPathArg, readOnly } = parseCliArgs(cliArgs);
+const { vaultPathArg, readOnly, excludePaths } = parseCliArgs(cliArgs);
 const vaultPath = resolve(vaultPathArg || process.cwd());
 // 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) });
+const serverHandle = serveStdio(() => createServer(vaultPath, { version: VERSION, readOnly, excludePaths }), { 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).

package/dist/src/cli.d.ts

@@ -1,6 +1,7 @@
 export interface ParsedCliArgs {
     vaultPathArg: string;
     readOnly: boolean;
+    excludePaths: string[];
 }
 /**
  * Parse runtime options without importing server.ts, which starts the MCP

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

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAkC1D"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAuD1D"}

package/dist/src/cli.js

@@ -5,6 +5,7 @@
  */
 export function parseCliArgs(args) {
     const pathArgs = [];
+    const excludePaths = [];
     let readOnly = false;
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
@@ -27,10 +28,28 @@ export function parseCliArgs(args) {
             readOnly = value === "true";
             continue;
         }
+        if (arg === "--exclude") {
+            const value = args[index + 1]?.trim();
+            if (!value || value.startsWith("--")) {
+                throw new Error("--exclude requires a subtree path");
+            }
+            excludePaths.push(value);
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--exclude=")) {
+            const value = arg.slice("--exclude=".length).trim();
+            if (!value) {
+                throw new Error("--exclude requires a subtree path");
+            }
+            excludePaths.push(value);
+            continue;
+        }
         pathArgs.push(arg);
     }
     return {
         vaultPathArg: pathArgs.join(" ").trim(),
         readOnly,
+        excludePaths,
     };
 }

package/dist/src/createServer.d.ts

@@ -8,6 +8,8 @@ export interface CreateServerOptions {
     frontmatterHandler?: FrontmatterHandler;
     /** Expose read tools only and reject direct calls to mutating tools. */
     readOnly?: boolean;
+    /** Vault-relative subtrees hidden from search and directory listings. */
+    excludePaths?: string[];
 }
 export declare function createServer(vaultPath: string, options?: CreateServerOptions): Server;
 //# sourceMappingURL=createServer.d.ts.map

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,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"}
+{"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;IACnB,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAoCD,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAofzF"}

package/dist/src/createServer.js

@@ -4,7 +4,7 @@ import { FrontmatterHandler, parseFrontmatter } from "./frontmatter.js";
 import { PathFilter } from "./pathfilter.js";
 import { SearchService } from "./search.js";
 import { handleWikiLinkTool } from "./wikilink/index.js";
-import { resolve } from "path";
+import { posix, resolve } from "path";
 const MUTATING_TOOLS = new Set([
     "write_note",
     "patch_note",
@@ -14,8 +14,29 @@ const MUTATING_TOOLS = new Set([
     "update_frontmatter",
     "manage_tags",
 ]);
+function normalizeSubtree(path) {
+    let relativePath = path.trim().replace(/\\/g, "/");
+    while (relativePath.startsWith("/"))
+        relativePath = relativePath.slice(1);
+    const normalizedPath = posix.normalize(relativePath);
+    if (normalizedPath === ".")
+        return "";
+    return normalizedPath.endsWith("/") ? normalizedPath.slice(0, -1) : normalizedPath;
+}
+function mergeExcludePaths(defaults, requested) {
+    const provided = Array.isArray(requested) ? requested : [];
+    return [...new Set([...defaults, ...provided]
+            .filter((path) => typeof path === "string")
+            .map(normalizeSubtree)
+            .filter(Boolean))];
+}
+function isExcluded(path, excludePaths) {
+    const normalizedPath = normalizeSubtree(path);
+    return excludePaths.some((excluded) => normalizedPath === excluded || normalizedPath.startsWith(`${excluded}/`));
+}
 export function createServer(vaultPath, options = {}) {
-    const { name = "mcpvault", version = "0.0.0", pathFilter = new PathFilter(), frontmatterHandler = new FrontmatterHandler(), readOnly = false, } = options;
+    const { name = "mcpvault", version = "0.0.0", pathFilter = new PathFilter(), frontmatterHandler = new FrontmatterHandler(), readOnly = false, excludePaths = [], } = options;
+    const defaultExcludePaths = mergeExcludePaths([], excludePaths);
     const resolvedVaultPath = resolve(vaultPath);
     const fileSystem = new FileSystemService(resolvedVaultPath, pathFilter, frontmatterHandler);
     const searchService = new SearchService(resolvedVaultPath, pathFilter);
@@ -317,10 +338,17 @@ export function createServer(vaultPath, options = {}) {
                     };
                 }
                 case "list_directory": {
-                    const listing = await fileSystem.listDirectory(trimmedArgs.path || '');
+                    const requestedPath = normalizeSubtree(trimmedArgs.path || "");
+                    if (isExcluded(requestedPath, defaultExcludePaths)) {
+                        throw new Error(`Directory excluded by server configuration: ${requestedPath}`);
+                    }
+                    const listing = await fileSystem.listDirectory(trimmedArgs.path || "");
+                    const prefix = requestedPath ? `${requestedPath}/` : "";
+                    const directories = listing.directories.filter((name) => !isExcluded(`${prefix}${name}`, defaultExcludePaths));
+                    const files = listing.files.filter((name) => !isExcluded(`${prefix}${name}`, defaultExcludePaths));
                     const indent = trimmedArgs.prettyPrint ? 2 : undefined;
                     return {
-                        content: [{ type: "text", text: JSON.stringify({ dirs: listing.directories, files: listing.files }, null, indent) }]
+                        content: [{ type: "text", text: JSON.stringify({ dirs: directories, files }, null, indent) }]
                     };
                 }
                 case "delete_note": {
@@ -342,7 +370,7 @@ export function createServer(vaultPath, options = {}) {
                         searchFrontmatter: trimmedArgs.searchFrontmatter,
                         caseSensitive: trimmedArgs.caseSensitive,
                         pathPrefix: trimmedArgs.pathPrefix,
-                        excludePaths: trimmedArgs.excludePaths
+                        excludePaths: mergeExcludePaths(defaultExcludePaths, trimmedArgs.excludePaths)
                     });
                     const indent = trimmedArgs.prettyPrint ? 2 : undefined;
                     return {
@@ -487,5 +515,8 @@ function trimPaths(args) {
     if (trimmed.paths && Array.isArray(trimmed.paths)) {
         trimmed.paths = trimmed.paths.map((p) => typeof p === 'string' ? p.trim() : p);
     }
+    if (trimmed.excludePaths && Array.isArray(trimmed.excludePaths)) {
+        trimmed.excludePaths = trimmed.excludePaths.map((p) => typeof p === 'string' ? p.trim() : p);
+    }
     return trimmed;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../../src/filesystem.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,UAAU,EAAE,eAAe,EAAE,eAAe,EAAE,uBAAuB,EAAE,QAAQ,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE3V;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAiBtE;AAoBD,qBAAa,iBAAiB;IAK1B,OAAO,CAAC,SAAS;IAJnB,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,UAAU,CAAa;IAE/B,YACU,SAAS,EAAE,MAAM,EACzB,UAAU,CAAC,EAAE,UAAU,EACvB,kBAAkB,CAAC,EAAE,kBAAkB,EAWxC;IAED;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAsBrB,OAAO,CAAC,WAAW;IAkDb,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CA+BhD;IAEK,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA0EtD;IAEK,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA4FjE;IAEK,aAAa,CAAC,IAAI,GAAE,MAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA4DhE;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAc3C;IAEK,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAchD;IAEK,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAyGhE;IAEK,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAoF1D;IAEK,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CA+H1D;IAEK,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA+CzE;IAEK,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCtE;IAEK,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CA0CvD;IAEK,UAAU,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAqG1E;IAED,YAAY,IAAI,MAAM,CAErB;IAED;;;;;;;;;;;;;;OAcG;IACG,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA+CjE;IAEK,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CA+EzD;IAEK,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAehE;IAEK,aAAa,CAAC,WAAW,GAAE,MAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAuDhE;IAEK,WAAW,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAiDlE;CACF"}
+{"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../../src/filesystem.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,UAAU,EAAE,eAAe,EAAE,eAAe,EAAE,uBAAuB,EAAE,QAAQ,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE3V;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAiBtE;AAoBD,qBAAa,iBAAiB;IAK1B,OAAO,CAAC,SAAS;IAJnB,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,UAAU,CAAa;IAE/B,YACU,SAAS,EAAE,MAAM,EACzB,UAAU,CAAC,EAAE,UAAU,EACvB,kBAAkB,CAAC,EAAE,kBAAkB,EAWxC;IAED;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAsBrB,OAAO,CAAC,WAAW;IAgDb,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CA+BhD;IAEK,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA0EtD;IAEK,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA4FjE;IAEK,aAAa,CAAC,IAAI,GAAE,MAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA4DhE;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAc3C;IAEK,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAchD;IAEK,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAyGhE;IAEK,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CA4H1D;IAEK,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CA+H1D;IAEK,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA+CzE;IAEK,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCtE;IAEK,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CA0CvD;IAEK,UAAU,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAqG1E;IAED,YAAY,IAAI,MAAM,CAErB;IAED;;;;;;;;;;;;;;OAcG;IACG,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA+CjE;IAEK,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CA+EzD;IAEK,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAehE;IAEK,aAAa,CAAC,WAAW,GAAE,MAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAuDhE;IAEK,WAAW,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAiDlE;CACF"}

package/dist/src/filesystem.js

@@ -1,7 +1,7 @@
 import { join, resolve, relative, dirname } from 'path';
 import { homedir } from 'os';
 import { readdir, stat, readFile, writeFile, unlink, mkdir, access, rename, copyFile } from 'node:fs/promises';
-import { constants, realpathSync } from 'node:fs';
+import { constants, lstatSync, realpathSync } from 'node:fs';
 import trash from 'trash';
 import { FrontmatterHandler } from './frontmatter.js';
 import { PathFilter } from './pathfilter.js';
@@ -104,46 +104,45 @@ export class FileSystemService {
         if (relativeToVault.startsWith('..')) {
             throw new Error(`Path traversal not allowed: ${relativePath}. Paths must be within the vault directory.`);
         }
-        // Security check: ensure symlinks don't escape vault boundary
-        try {
-            const realPath = realpathSync(fullPath);
-            const realRelative = relative(this.vaultPath, realPath);
-            if (realRelative.startsWith('..')) {
-                throw new Error(`Symlink target is outside vault: ${relativePath}. Symbolic links must resolve to a path within the vault directory.`);
+        // Walk missing parents to the nearest existing ancestor, without following dangling links.
+        let candidate = fullPath;
+        while (true) {
+            try {
+                const realPath = realpathSync(candidate);
+                if (relative(this.vaultPath, realPath).startsWith('..')) {
+                    throw new Error(`Symlink target is outside vault: ${relativePath}. Symbolic links must resolve to a path within the vault directory.`);
+                }
+                break;
             }
-        }
-        catch (err) {
-            if (err instanceof Error && 'code' in err) {
-                const code = err.code;
-                if (code === 'ENOENT') {
-                    // File doesn't exist yet (e.g. writing a new note). Verify the parent directory resolves inside vault.
+            catch (err) {
+                if (!(err instanceof Error) || !('code' in err))
+                    throw err;
+                if (err.code === 'ENOENT') {
                     try {
-                        const parentReal = realpathSync(dirname(fullPath));
-                        const parentRelative = relative(this.vaultPath, parentReal);
-                        if (parentRelative.startsWith('..')) {
-                            throw new Error(`Symlink target is outside vault: ${relativePath}. Symbolic links must resolve to a path within the vault directory.`);
+                        if (lstatSync(candidate).isSymbolicLink()) {
+                            throw new Error(`Cannot resolve symlink: ${relativePath}. Symbolic links must point to an existing path within the vault.`);
                         }
                     }
-                    catch (parentErr) {
-                        // Parent doesn't exist either (will be created by mkdir). Lexical check above is sufficient.
-                        if (parentErr instanceof Error && parentErr.message.includes('outside vault')) {
-                            throw parentErr;
+                    catch (linkError) {
+                        if (!(linkError instanceof Error) || !('code' in linkError) || linkError.code !== 'ENOENT') {
+                            throw linkError;
                         }
                     }
+                    const parent = dirname(candidate);
+                    if (candidate === this.vaultPath || parent === candidate)
+                        throw err;
+                    candidate = parent;
                 }
-                else if (code === 'ELOOP') {
+                else if (err.code === 'ELOOP') {
                     throw new Error(`Circular symlink detected: ${relativePath}. The symbolic link chain forms a loop.`);
                 }
-                else if (code === 'EACCES') {
+                else if (err.code === 'EACCES' || err.code === 'EPERM') {
                     throw new Error(`Permission denied resolving symlink: ${relativePath}. Cannot verify the symbolic link target is within the vault.`);
                 }
                 else {
                     throw err;
                 }
             }
-            else {
-                throw err;
-            }
         }
         return fullPath;
     }
@@ -527,20 +526,43 @@ export class FileSystemService {
         }
         const oldFullPath = this.resolvePath(oldPath);
         const newFullPath = this.resolvePath(newPath);
+        if (oldFullPath === newFullPath) {
+            return {
+                success: false,
+                oldPath,
+                newPath,
+                message: `Source and target paths are the same: ${oldPath}. Please provide a different target path.`
+            };
+        }
+        const sourceDirectoryResult = {
+            success: false,
+            oldPath,
+            newPath,
+            message: `Source path is a directory: ${oldPath}. Please provide a file path.`
+        };
+        const targetDirectoryResult = {
+            success: false,
+            oldPath,
+            newPath,
+            message: `Target path is a directory: ${newPath}. Please provide a file path.`
+        };
+        const sourceMissingResult = {
+            success: false,
+            oldPath,
+            newPath,
+            message: `Source file not found: ${oldPath}. Use list_directory to see available files.`
+        };
         try {
-            // Read source content (will throw ENOENT if not found)
             let content;
             try {
                 content = await readFile(oldFullPath, 'utf-8');
             }
             catch (error) {
                 if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
-                    return {
-                        success: false,
-                        oldPath,
-                        newPath,
-                        message: `Source file not found: ${oldPath}. Use list_directory to see available files.`
-                    };
+                    return sourceMissingResult;
+                }
+                if (error instanceof Error && 'code' in error && error.code === 'EISDIR') {
+                    return sourceDirectoryResult;
                 }
                 throw error;
             }
@@ -557,13 +579,29 @@ export class FileSystemService {
                 }
             }
             catch (error) {
-                if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
-                    return {
-                        success: false,
-                        oldPath,
-                        newPath,
-                        message: `Target file already exists: ${newPath}. Use overwrite=true to replace it.`
-                    };
+                if (error instanceof Error && 'code' in error) {
+                    if (error.code === 'EISDIR') {
+                        return targetDirectoryResult;
+                    }
+                    // Inspect only after a failed write; these codes also cover Windows directories.
+                    if (error.code === 'EEXIST' || error.code === 'EPERM' || error.code === 'EACCES') {
+                        try {
+                            if ((await stat(newFullPath)).isDirectory()) {
+                                return targetDirectoryResult;
+                            }
+                        }
+                        catch {
+                            // Preserve the write error if the target changed or cannot be inspected.
+                        }
+                    }
+                    if (error.code === 'EEXIST') {
+                        return {
+                            success: false,
+                            oldPath,
+                            newPath,
+                            message: `Target file already exists: ${newPath}. Use overwrite=true to replace it.`
+                        };
+                    }
                 }
                 throw error;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitbonsai/mcpvault",
-  "version": "0.16.1",
+  "version": "0.17.1",
   "description": "Universal AI bridge for Obsidian vaults - connect any MCP-compatible assistant",
   "homepage": "https://mcpvault.org",
   "author": "bitbonsai",