@bitbonsai/mcpvault 0.16.1 → 0.17.0

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/package.json

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