@mauricio.wolff/mcp-obsidian 0.7.2 → 0.7.4

package/README.md

@@ -16,6 +16,7 @@ A universal AI bridge for Obsidian vaults using the Model Context Protocol (MCP)
 
 [![GitHub Stars](https://img.shields.io/github/stars/bitbonsai/mcp-obsidian?style=flat&logo=github&logoColor=white&color=9065ea&labelColor=262626)](https://github.com/bitbonsai/mcp-obsidian)
 [![npm version](https://img.shields.io/npm/v/@mauricio.wolff/mcp-obsidian?style=flat&logo=npm&logoColor=white&color=9065ea&labelColor=262626)](https://www.npmjs.com/package/@mauricio.wolff/mcp-obsidian)
+[![npm downloads](https://img.shields.io/npm/dt/@mauricio.wolff/mcp-obsidian?style=flat&logo=npm&logoColor=white&color=9065ea&labelColor=262626)](https://www.npmjs.com/package/@mauricio.wolff/mcp-obsidian)
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/BitBonsai?style=flat&logo=github&logoColor=white&color=9065ea&labelColor=262626)](https://github.com/sponsors/bitbonsai)
 [![Ko-Fi](https://img.shields.io/badge/Ko--fi-Support%20Me-9065ea?style=flat&logo=ko-fi&logoColor=white&labelColor=262626)](https://ko-fi.com/bitbonsai)
 [![Liberapay](https://img.shields.io/badge/Liberapay-Weekly%20Support-9065ea?style=flat&logo=liberapay&logoColor=white&labelColor=262626)](https://liberapay.com/bitbonsai/)
@@ -114,7 +115,6 @@ MCP is an open protocol. You're not tied to any specific vendor or platform. You
 - ✅ **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
-- ✅ **Intelligent link handling**: Smart processing of internal links and references
 
 ## Prerequisites
 
@@ -135,12 +135,16 @@ npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/obsidian/vault
 ### For Developers
 
 1. Clone this repository
-2. Install dependencies with npm:
+2. Use the correct Node.js version:
 ```bash
-npm install
+nvm use  # Uses Node 24 from .nvmrc
+```
+3. Install dependencies with npm:
+```bash
+npm install  # Corepack automatically uses npm 10.9.0
 ```
 
-3. Test locally with MCP inspector:
+4. Test locally with MCP inspector:
 ```bash
 npx @modelcontextprotocol/inspector npm start /path/to/your/vault
 ```

package/dist/server.js

@@ -353,6 +353,25 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     },
                     required: ["path", "operation"]
                 }
+            },
+            {
+                name: "get_vault_stats",
+                description: "Get vault statistics including total notes, folders, size, and recently modified files. Useful for understanding vault scope before batch operations.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        recentCount: {
+                            type: "number",
+                            description: "Number of recently modified files to return (default: 5, max: 20)",
+                            default: 5
+                        },
+                        prettyPrint: {
+                            type: "boolean",
+                            description: "Format JSON response with indentation (default: false)",
+                            default: false
+                        }
+                    }
+                }
             }
         ]
     };
@@ -570,6 +589,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     isError: !result.success
                 };
             }
+            case "get_vault_stats": {
+                const recentCount = Math.min(trimmedArgs.recentCount || 5, 20);
+                const stats = await fileSystem.getVaultStats(recentCount);
+                const indent = trimmedArgs.prettyPrint ? 2 : undefined;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                notes: stats.totalNotes,
+                                folders: stats.totalFolders,
+                                size: stats.totalSize,
+                                recent: stats.recentlyModified
+                            }, null, indent)
+                        }
+                    ]
+                };
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

package/dist/src/filesystem.js

@@ -29,14 +29,14 @@ export class FileSystemService {
         // Security check: ensure path is within vault
         const relativeToVault = relative(this.vaultPath, fullPath);
         if (relativeToVault.startsWith('..')) {
-            throw new Error(`Path traversal not allowed: ${relativePath}`);
+            throw new Error(`Path traversal not allowed: ${relativePath}. Paths must be within the vault directory.`);
         }
         return fullPath;
     }
     async readNote(path) {
         const fullPath = this.resolvePath(path);
         if (!this.pathFilter.isAllowed(path)) {
-            throw new Error(`Access denied: ${path}`);
+            throw new Error(`Access denied: ${path}. This path is restricted (system files like .obsidian, .git, and dotfiles are not accessible).`);
         }
         // Check if the path is a directory first
         const isDir = await this.isDirectory(path);
@@ -50,10 +50,10 @@ export class FileSystemService {
         catch (error) {
             if (error instanceof Error && 'code' in error) {
                 if (error.code === 'ENOENT') {
-                    throw new Error(`File not found: ${path}`);
+                    throw new Error(`File not found: ${path}. Use list_directory to see available files, or check the path spelling.`);
                 }
                 if (error.code === 'EACCES') {
-                    throw new Error(`Permission denied: ${path}`);
+                    throw new Error(`Permission denied: ${path}. The file exists but cannot be read due to filesystem permissions.`);
                 }
                 if (error.code === 'EISDIR') {
                     throw new Error(`Cannot read directory as file: ${path}. Use list_directory tool instead.`);
@@ -66,7 +66,7 @@ export class FileSystemService {
         const { path, content, frontmatter, mode = 'overwrite' } = params;
         const fullPath = this.resolvePath(path);
         if (!this.pathFilter.isAllowed(path)) {
-            throw new Error(`Access denied: ${path}`);
+            throw new Error(`Access denied: ${path}. This path is restricted (system files like .obsidian, .git, and dotfiles are not accessible).`);
         }
         // Validate frontmatter if provided
         if (frontmatter) {
@@ -130,7 +130,7 @@ export class FileSystemService {
             return {
                 success: false,
                 path,
-                message: `Access denied: ${path}`
+                message: `Access denied: ${path}. This path is restricted (system files like .obsidian, .git, and dotfiles are not accessible).`
             };
         }
         // Validate that strings are not empty
@@ -231,13 +231,13 @@ export class FileSystemService {
         catch (error) {
             if (error instanceof Error) {
                 if (error.message.includes('not found') || error.message.includes('ENOENT')) {
-                    throw new Error(`Directory not found: ${path}`);
+                    throw new Error(`Directory not found: ${path}. Use list_directory with no path or '/' to see root folders.`);
                 }
                 if (error.message.includes('permission') || error.message.includes('access')) {
-                    throw new Error(`Permission denied: ${path}`);
+                    throw new Error(`Permission denied: ${path}. The directory exists but cannot be read due to filesystem permissions.`);
                 }
                 if (error.message.includes('not a directory') || error.message.includes('ENOTDIR')) {
-                    throw new Error(`Not a directory: ${path}`);
+                    throw new Error(`Not a directory: ${path}. This path points to a file, not a folder. Use read_note to read files.`);
                 }
             }
             throw new Error(`Failed to list directory: ${path} - ${error instanceof Error ? error.message : 'Unknown error'}`);
@@ -284,7 +284,7 @@ export class FileSystemService {
             return {
                 success: false,
                 path: path,
-                message: `Access denied: ${path}`
+                message: `Access denied: ${path}. This path is restricted (system files like .obsidian, .git, and dotfiles are not accessible).`
             };
         }
         try {
@@ -311,14 +311,14 @@ export class FileSystemService {
                     return {
                         success: false,
                         path: path,
-                        message: `File not found: ${path}`
+                        message: `File not found: ${path}. Use list_directory to see available files.`
                     };
                 }
                 if (error.code === 'EACCES') {
                     return {
                         success: false,
                         path: path,
-                        message: `Permission denied: ${path}`
+                        message: `Permission denied: ${path}. The file exists but cannot be deleted due to filesystem permissions.`
                     };
                 }
             }
@@ -336,7 +336,7 @@ export class FileSystemService {
                 success: false,
                 oldPath,
                 newPath,
-                message: `Access denied: ${oldPath}`
+                message: `Access denied: ${oldPath}. This path is restricted (system files like .obsidian, .git, and dotfiles are not accessible).`
             };
         }
         if (!this.pathFilter.isAllowed(newPath)) {
@@ -344,7 +344,7 @@ export class FileSystemService {
                 success: false,
                 oldPath,
                 newPath,
-                message: `Access denied: ${newPath}`
+                message: `Access denied: ${newPath}. This path is restricted (system files like .obsidian, .git, and dotfiles are not accessible).`
             };
         }
         const oldFullPath = this.resolvePath(oldPath);
@@ -361,7 +361,7 @@ export class FileSystemService {
                         success: false,
                         oldPath,
                         newPath,
-                        message: `Source file not found: ${oldPath}`
+                        message: `Source file not found: ${oldPath}. Use list_directory to see available files.`
                     };
                 }
                 throw error;
@@ -414,7 +414,7 @@ export class FileSystemService {
         }
         const results = await Promise.allSettled(paths.map(async (path) => {
             if (!this.pathFilter.isAllowed(path)) {
-                throw new Error(`Access denied: ${path}`);
+                throw new Error(`Access denied: ${path}. This path is restricted (system files like .obsidian, .git, and dotfiles are not accessible).`);
             }
             const note = await this.readNote(path);
             const result = {
@@ -447,7 +447,7 @@ export class FileSystemService {
     async updateFrontmatter(params) {
         const { path, frontmatter, merge = true } = params;
         if (!this.pathFilter.isAllowed(path)) {
-            throw new Error(`Access denied: ${path}`);
+            throw new Error(`Access denied: ${path}. This path is restricted (system files like .obsidian, .git, and dotfiles are not accessible).`);
         }
         // Read the existing note
         const note = await this.readNote(path);
@@ -470,7 +470,7 @@ export class FileSystemService {
     async getNotesInfo(paths) {
         const results = await Promise.allSettled(paths.map(async (path) => {
             if (!this.pathFilter.isAllowed(path)) {
-                throw new Error(`Access denied: ${path}`);
+                throw new Error(`Access denied: ${path}. This path is restricted (system files like .obsidian, .git, and dotfiles are not accessible).`);
             }
             const fullPath = this.resolvePath(path);
             let stats;
@@ -510,7 +510,7 @@ export class FileSystemService {
                 operation,
                 tags: [],
                 success: false,
-                message: `Access denied: ${path}`
+                message: `Access denied: ${path}. This path is restricted (system files like .obsidian, .git, and dotfiles are not accessible).`
             };
         }
         try {
@@ -586,4 +586,55 @@ export class FileSystemService {
     getVaultPath() {
         return this.vaultPath;
     }
+    async getVaultStats(recentCount = 5) {
+        let totalNotes = 0;
+        let totalFolders = 0;
+        let totalSize = 0;
+        const recentFiles = [];
+        const scanDirectory = async (dirPath, relativePath = '') => {
+            const entries = await readdir(dirPath, { withFileTypes: true });
+            for (const entry of entries) {
+                const entryRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+                if (!this.pathFilter.isAllowed(entryRelativePath)) {
+                    continue;
+                }
+                const fullEntryPath = join(dirPath, entry.name);
+                if (entry.isDirectory()) {
+                    // Also check if directory contents would be filtered (e.g., .obsidian/**)
+                    if (!this.pathFilter.isAllowed(`${entryRelativePath}/test.md`)) {
+                        continue;
+                    }
+                    totalFolders++;
+                    await scanDirectory(fullEntryPath, entryRelativePath);
+                }
+                else if (entry.isFile()) {
+                    totalNotes++;
+                    const stats = await stat(fullEntryPath);
+                    totalSize += stats.size;
+                    // Track recent files
+                    const fileInfo = { path: entryRelativePath, modified: stats.mtime.getTime() };
+                    // Insert in sorted order (most recent first)
+                    const insertIndex = recentFiles.findIndex(f => f.modified < fileInfo.modified);
+                    if (insertIndex === -1) {
+                        if (recentFiles.length < recentCount) {
+                            recentFiles.push(fileInfo);
+                        }
+                    }
+                    else {
+                        recentFiles.splice(insertIndex, 0, fileInfo);
+                        if (recentFiles.length > recentCount) {
+                            recentFiles.pop();
+                        }
+                    }
+                }
+            }
+        };
+        await scanDirectory(this.vaultPath);
+        return {
+            totalNotes,
+            totalFolders,
+            totalSize,
+            recentlyModified: recentFiles
+        };
+    }
 }

package/dist/src/filesystem.test.js

@@ -650,3 +650,80 @@ test("handles emoji in file paths", async () => {
     const note = await fileSystem.readNote(testPath);
     expect(note.content).toContain("Emoji note");
 });
+// ============================================================================
+// VAULT STATS TESTS
+// ============================================================================
+test("get vault stats with empty vault", async () => {
+    const stats = await fileSystem.getVaultStats();
+    expect(stats.totalNotes).toBe(0);
+    expect(stats.totalFolders).toBe(0);
+    expect(stats.totalSize).toBe(0);
+    expect(stats.recentlyModified).toHaveLength(0);
+});
+test("get vault stats counts notes and folders", async () => {
+    await mkdir(join(testVaultPath, "folder1"), { recursive: true });
+    await mkdir(join(testVaultPath, "folder2/nested"), { recursive: true });
+    await writeFile(join(testVaultPath, "note1.md"), "# Note 1");
+    await writeFile(join(testVaultPath, "folder1/note2.md"), "# Note 2");
+    await writeFile(join(testVaultPath, "folder2/nested/note3.md"), "# Note 3");
+    const stats = await fileSystem.getVaultStats();
+    expect(stats.totalNotes).toBe(3);
+    expect(stats.totalFolders).toBe(3); // folder1, folder2, folder2/nested
+    expect(stats.totalSize).toBeGreaterThan(0);
+});
+test("get vault stats returns recently modified files in order", async () => {
+    // Create files with slight delays to ensure different modification times
+    await writeFile(join(testVaultPath, "old.md"), "# Old");
+    await new Promise(resolve => setTimeout(resolve, 10));
+    await writeFile(join(testVaultPath, "middle.md"), "# Middle");
+    await new Promise(resolve => setTimeout(resolve, 10));
+    await writeFile(join(testVaultPath, "recent.md"), "# Recent");
+    const stats = await fileSystem.getVaultStats(3);
+    expect(stats.recentlyModified).toHaveLength(3);
+    expect(stats.recentlyModified[0]?.path).toBe("recent.md");
+    expect(stats.recentlyModified[1]?.path).toBe("middle.md");
+    expect(stats.recentlyModified[2]?.path).toBe("old.md");
+});
+test("get vault stats respects recentCount limit", async () => {
+    await writeFile(join(testVaultPath, "note1.md"), "# Note 1");
+    await writeFile(join(testVaultPath, "note2.md"), "# Note 2");
+    await writeFile(join(testVaultPath, "note3.md"), "# Note 3");
+    const stats = await fileSystem.getVaultStats(2);
+    expect(stats.recentlyModified).toHaveLength(2);
+});
+test("get vault stats excludes filtered paths", async () => {
+    await mkdir(join(testVaultPath, ".obsidian"), { recursive: true });
+    await mkdir(join(testVaultPath, ".git"), { recursive: true });
+    await writeFile(join(testVaultPath, ".obsidian/config.json"), "{}");
+    await writeFile(join(testVaultPath, ".git/config"), "git config");
+    await writeFile(join(testVaultPath, "visible.md"), "# Visible");
+    const stats = await fileSystem.getVaultStats();
+    expect(stats.totalNotes).toBe(1);
+    expect(stats.totalFolders).toBe(0); // .obsidian and .git are filtered
+    expect(stats.recentlyModified.map(f => f.path)).toContain("visible.md");
+    expect(stats.recentlyModified.map(f => f.path)).not.toContain(".obsidian/config.json");
+});
+test("get vault stats calculates total size correctly", async () => {
+    const content1 = "# Note 1 with some content";
+    const content2 = "# Note 2 with more content here";
+    await writeFile(join(testVaultPath, "note1.md"), content1);
+    await writeFile(join(testVaultPath, "note2.md"), content2);
+    const stats = await fileSystem.getVaultStats();
+    const expectedSize = Buffer.byteLength(content1) + Buffer.byteLength(content2);
+    expect(stats.totalSize).toBe(expectedSize);
+});
+// ============================================================================
+// ERROR MESSAGE TESTS
+// ============================================================================
+test("error messages include remediation suggestions for file not found", async () => {
+    await expect(fileSystem.readNote("nonexistent.md"))
+        .rejects.toThrow(/list_directory/);
+});
+test("error messages include remediation suggestions for access denied", async () => {
+    await expect(fileSystem.readNote(".obsidian/config.json"))
+        .rejects.toThrow(/restricted/);
+});
+test("error messages include remediation suggestions for path traversal", async () => {
+    await expect(fileSystem.readNote("../outside.md"))
+        .rejects.toThrow(/within the vault/);
+});

package/dist/src/integration.test.js

@@ -196,8 +196,9 @@ describe("Performance: Post-PR#12 Overhead", () => {
             }
         }
         const duration = performance.now() - start;
-        // Should complete in reasonable time (< 100ms for 8000 checks)
-        expect(duration).toBeLessThan(100);
+        // Should complete in reasonable time (< 200ms for 8000 checks)
+        // Increased threshold to account for CI runner variability
+        expect(duration).toBeLessThan(200);
     });
     test("large batch operations performance", async () => {
         // Create 50 notes

package/dist/src/pathfilter.js

@@ -50,7 +50,26 @@ export class PathFilter {
         return true;
     }
     isFile(path) {
-        return path.includes('.') && !path.endsWith('/');
+        // A path is a file if it has a file extension at the end
+        // Paths ending with '/' are always directories
+        if (path.endsWith('/')) {
+            return false;
+        }
+        // Get the last component of the path
+        const lastSlashIndex = path.lastIndexOf('/');
+        const lastComponent = lastSlashIndex === -1 ? path : path.substring(lastSlashIndex + 1);
+        // Check if the last component has a file extension
+        // A file extension is a dot followed by 1-10 alphanumeric characters at the end
+        // This distinguishes "file.md" (file) from "1. Project" (directory with dot in name)
+        const lastDotIndex = lastComponent.lastIndexOf('.');
+        if (lastDotIndex === -1 || lastDotIndex === 0) {
+            // No dot, or dot at the start (like .gitignore) - treat as no extension
+            return false;
+        }
+        const extension = lastComponent.substring(lastDotIndex + 1);
+        // Extension should be 1-10 characters and contain only alphanumeric characters
+        // This allows .md, .txt, .markdown but not ". Project" (space after dot)
+        return extension.length >= 1 && extension.length <= 10 && /^[a-zA-Z0-9]+$/.test(extension);
     }
     filterPaths(paths) {
         return paths.filter(path => this.isAllowed(path));

package/dist/src/pathfilter.test.js

@@ -228,5 +228,16 @@ describe("PathFilter", () => {
             expect(filter.isAllowed("folder/subfolder/")).toBe(true);
             expect(filter.isAllowed("notes")).toBe(true);
         });
+        test("handles directories with dots in their names", () => {
+            const filter = new PathFilter();
+            // Folders with dots should be allowed (common pattern: "1. Project", "2.5 Notes")
+            expect(filter.isAllowed("1. Project")).toBe(true);
+            expect(filter.isAllowed("2. Archive")).toBe(true);
+            expect(filter.isAllowed("3.5 Research")).toBe(true);
+            expect(filter.isAllowed("1. Project/subfolder")).toBe(true);
+            expect(filter.isAllowed("1. Project/note.md")).toBe(true);
+            // But files in those folders should still need proper extensions
+            expect(filter.isAllowed("1. Project/file.js")).toBe(false);
+        });
     });
 });

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@mauricio.wolff/mcp-obsidian",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Universal AI bridge for Obsidian vaults - connect any MCP-compatible assistant",
   "author": "bitbonsai",
   "license": "MIT",
   "type": "module",
+  "packageManager": "npm@10.9.0+sha512.65a9c38a8172948f617a53619762cd77e12b9950fe1f9239debcb8d62c652f2081824b986fee7c0af6c0a7df615becebe4bf56e17ec27214a87aa29d9e038b4b",
   "main": "dist/server.js",
   "bin": {
     "mcp-obsidian": "./dist/server.js",
@@ -31,7 +32,7 @@
     "gray-matter": "^4.0.3"
   },
   "devDependencies": {
-    "@types/node": "^20.19.21",
+    "@types/node": "^24.10.1",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3",
     "vitest": "^4.0.15"