@mauricio.wolff/mcp-obsidian 0.7.5 → 0.8.2

package/dist/server.js

@@ -3,51 +3,54 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { FileSystemService } from "./src/filesystem.js";
-import { FrontmatterHandler } from "./src/frontmatter.js";
+import { FrontmatterHandler, parseFrontmatter } from "./src/frontmatter.js";
 import { PathFilter } from "./src/pathfilter.js";
 import { SearchService } from "./src/search.js";
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
-import { dirname, join } from "path";
+import { dirname, join, resolve } from "path";
 // Get package.json version
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8"));
 const VERSION = packageJson.version;
 // Handle --version and --help flags
-const arg = process.argv[2];
-if (arg === "--version" || arg === "-v") {
+const cliArgs = process.argv.slice(2);
+const firstArg = cliArgs[0];
+if (firstArg === "--version" || firstArg === "-v") {
     console.log(VERSION);
     process.exit(0);
 }
-if (arg === "--help" || arg === "-h") {
+if (firstArg === "--help" || firstArg === "-h") {
     console.log(`
 @mauricio.wolff/mcp-obsidian v${VERSION}
 
 Universal AI bridge for Obsidian vaults - connect any MCP-compatible assistant
 
 Usage:
-  npx @mauricio.wolff/mcp-obsidian <vault-path>
+  npx @mauricio.wolff/mcp-obsidian [vault-path]
 
 Arguments:
-  <vault-path>    Path to your Obsidian vault directory
+  [vault-path]    Optional path to your Obsidian vault directory
+                  Defaults to current working directory when omitted
 
 Options:
   --version, -v   Show version number
   --help, -h      Show this help message
 
 Examples:
+  npx @mauricio.wolff/mcp-obsidian
   npx @mauricio.wolff/mcp-obsidian ~/Documents/MyVault
+  npx @mauricio.wolff/mcp-obsidian ./Vault
   npx @mauricio.wolff/mcp-obsidian /path/to/obsidian/vault
+  npx @mauricio.wolff/mcp-obsidian "/path/with spaces/Obsidian Vault"
 `);
     process.exit(0);
 }
-const vaultPath = arg;
-if (!vaultPath) {
-    console.error("Usage: npx @mauricio.wolff/mcp-obsidian /path/to/vault");
-    console.error("Run 'npx @mauricio.wolff/mcp-obsidian --help' for more information");
-    process.exit(1);
-}
+// Join trailing args to support vault paths with spaces.
+// When omitted, default to current working directory.
+const vaultPathArg = cliArgs.join(' ').trim();
+const vaultPath = resolve(vaultPathArg || process.cwd());
 // Initialize services
 const pathFilter = new PathFilter();
 const frontmatterHandler = new FrontmatterHandler();
@@ -140,7 +143,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "list_directory",
-                description: "List files and directories in the vault",
+                description: "List files and directories in the vault (includes non-note filenames, while read/write tools remain note-only)",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -237,6 +240,37 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["oldPath", "newPath"]
                 }
             },
+            {
+                name: "move_file",
+                description: "Move or rename any file in the vault (binary-safe, file-only, requires confirmation)",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        oldPath: {
+                            type: "string",
+                            description: "Current path of the file"
+                        },
+                        newPath: {
+                            type: "string",
+                            description: "New path for the file"
+                        },
+                        confirmOldPath: {
+                            type: "string",
+                            description: "Confirmation: must exactly match oldPath"
+                        },
+                        confirmNewPath: {
+                            type: "string",
+                            description: "Confirmation: must exactly match newPath"
+                        },
+                        overwrite: {
+                            type: "boolean",
+                            description: "Allow overwriting existing file (default: false)",
+                            default: false
+                        }
+                    },
+                    required: ["oldPath", "newPath", "confirmOldPath", "confirmNewPath"]
+                }
+            },
             {
                 name: "read_multiple_notes",
                 description: "Read multiple notes in a batch (max 10 files)",
@@ -392,6 +426,12 @@ function trimPaths(args) {
     if (trimmed.confirmPath && typeof trimmed.confirmPath === 'string') {
         trimmed.confirmPath = trimmed.confirmPath.trim();
     }
+    if (trimmed.confirmOldPath && typeof trimmed.confirmOldPath === 'string') {
+        trimmed.confirmOldPath = trimmed.confirmOldPath.trim();
+    }
+    if (trimmed.confirmNewPath && typeof trimmed.confirmNewPath === 'string') {
+        trimmed.confirmNewPath = trimmed.confirmNewPath.trim();
+    }
     // Trim path arrays
     if (trimmed.paths && Array.isArray(trimmed.paths)) {
         trimmed.paths = trimmed.paths.map((p) => typeof p === 'string' ? p.trim() : p);
@@ -419,10 +459,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             case "write_note": {
+                const fm = parseFrontmatter(trimmedArgs.frontmatter);
                 await fileSystem.writeNote({
                     path: trimmedArgs.path,
                     content: trimmedArgs.content,
-                    frontmatter: trimmedArgs.frontmatter,
+                    ...(fm !== undefined && { frontmatter: fm }),
                     mode: trimmedArgs.mode || 'overwrite'
                 });
                 return {
@@ -515,6 +556,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     isError: !result.success
                 };
             }
+            case "move_file": {
+                const result = await fileSystem.moveFile({
+                    oldPath: trimmedArgs.oldPath,
+                    newPath: trimmedArgs.newPath,
+                    confirmOldPath: trimmedArgs.confirmOldPath,
+                    confirmNewPath: trimmedArgs.confirmNewPath,
+                    overwrite: trimmedArgs.overwrite
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2)
+                        }
+                    ],
+                    isError: !result.success
+                };
+            }
             case "read_multiple_notes": {
                 const result = await fileSystem.readMultipleNotes({
                     paths: trimmedArgs.paths,
@@ -535,9 +594,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             case "update_frontmatter": {
+                const fm = parseFrontmatter(trimmedArgs.frontmatter);
+                if (!fm) {
+                    throw new Error('frontmatter is required');
+                }
                 await fileSystem.updateFrontmatter({
                     path: trimmedArgs.path,
-                    frontmatter: trimmedArgs.frontmatter,
+                    frontmatter: fm,
                     merge: trimmedArgs.merge
                 });
                 return {

package/dist/src/filesystem.js

@@ -1,5 +1,5 @@
 import { join, resolve, relative, dirname } from 'path';
-import { readdir, stat, readFile, writeFile, unlink, mkdir, access } from 'node:fs/promises';
+import { readdir, stat, readFile, writeFile, unlink, mkdir, access, rename, copyFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import { FrontmatterHandler } from './frontmatter.js';
 import { PathFilter } from './pathfilter.js';
@@ -68,6 +68,10 @@ export class FileSystemService {
         if (!this.pathFilter.isAllowed(path)) {
             throw new Error(`Access denied: ${path}. This path is restricted (system files like .obsidian, .git, and dotfiles are not accessible).`);
         }
+        // Validate content is a defined string to prevent writing literal "undefined"
+        if (content === undefined || content === null) {
+            throw new Error(`Content is required for writing a note: ${path}. The content parameter must be a string.`);
+        }
         // Validate frontmatter if provided
         if (frontmatter) {
             const validation = this.frontmatterHandler.validate(frontmatter);
@@ -141,7 +145,7 @@ export class FileSystemService {
                 message: 'oldString cannot be empty'
             };
         }
-        if (newString === '') {
+        if (!newString) {
             return {
                 success: false,
                 path,
@@ -212,7 +216,7 @@ export class FileSystemService {
             const directories = [];
             for (const entry of entries) {
                 const entryPath = normalizedPath ? `${normalizedPath}/${entry.name}` : entry.name;
-                if (!this.pathFilter.isAllowed(entryPath)) {
+                if (!this.pathFilter.isAllowedForListing(entryPath)) {
                     continue;
                 }
                 if (entry.isDirectory()) {
@@ -407,6 +411,126 @@ export class FileSystemService {
             };
         }
     }
+    async moveFile(params) {
+        const { oldPath, newPath, confirmOldPath, confirmNewPath, overwrite = false } = params;
+        if (oldPath !== confirmOldPath || newPath !== confirmNewPath) {
+            return {
+                success: false,
+                oldPath,
+                newPath,
+                message: "Move cancelled: confirmation paths do not match. For safety, oldPath must equal confirmOldPath and newPath must equal confirmNewPath."
+            };
+        }
+        if (!this.pathFilter.isAllowedForListing(oldPath)) {
+            return {
+                success: false,
+                oldPath,
+                newPath,
+                message: `Access denied: ${oldPath}. This path is restricted (system files like .obsidian, .git, and dotfiles are not accessible).`
+            };
+        }
+        if (!this.pathFilter.isAllowedForListing(newPath)) {
+            return {
+                success: false,
+                oldPath,
+                newPath,
+                message: `Access denied: ${newPath}. This path is restricted (system files like .obsidian, .git, and dotfiles are not accessible).`
+            };
+        }
+        const oldFullPath = this.resolvePath(oldPath);
+        const newFullPath = this.resolvePath(newPath);
+        try {
+            const sourceStat = await stat(oldFullPath);
+            if (sourceStat.isDirectory()) {
+                return {
+                    success: false,
+                    oldPath,
+                    newPath,
+                    message: `Source path is a directory: ${oldPath}. move_file currently supports files only.`
+                };
+            }
+        }
+        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 {
+                success: false,
+                oldPath,
+                newPath,
+                message: `Failed to inspect source file: ${error instanceof Error ? error.message : 'Unknown error'}`
+            };
+        }
+        try {
+            if (!overwrite) {
+                try {
+                    await access(newFullPath, constants.F_OK);
+                    return {
+                        success: false,
+                        oldPath,
+                        newPath,
+                        message: `Target file already exists: ${newPath}. Use overwrite=true to replace it.`
+                    };
+                }
+                catch (error) {
+                    if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') {
+                        throw error;
+                    }
+                }
+            }
+            await mkdir(dirname(newFullPath), { recursive: true });
+            if (overwrite) {
+                try {
+                    const targetStat = await stat(newFullPath);
+                    if (targetStat.isDirectory()) {
+                        return {
+                            success: false,
+                            oldPath,
+                            newPath,
+                            message: `Target path is a directory: ${newPath}. Please provide a file path.`
+                        };
+                    }
+                    await unlink(newFullPath);
+                }
+                catch (error) {
+                    if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') {
+                        throw error;
+                    }
+                }
+            }
+            try {
+                await rename(oldFullPath, newFullPath);
+            }
+            catch (error) {
+                if (error instanceof Error && 'code' in error && error.code === 'EXDEV') {
+                    await copyFile(oldFullPath, newFullPath);
+                    await unlink(oldFullPath);
+                }
+                else {
+                    throw error;
+                }
+            }
+            return {
+                success: true,
+                oldPath,
+                newPath,
+                message: `Successfully moved file from ${oldPath} to ${newPath}`
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                oldPath,
+                newPath,
+                message: `Failed to move file: ${error instanceof Error ? error.message : 'Unknown error'}`
+            };
+        }
+    }
     async readMultipleNotes(params) {
         const { paths, includeContent = true, includeFrontmatter = true } = params;
         if (paths.length > 10) {
@@ -595,19 +719,18 @@ export class FileSystemService {
             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`)) {
+                    if (!this.pathFilter.isAllowedForListing(entryRelativePath)) {
                         continue;
                     }
                     totalFolders++;
                     await scanDirectory(fullEntryPath, entryRelativePath);
                 }
                 else if (entry.isFile()) {
+                    if (!this.pathFilter.isAllowed(entryRelativePath)) {
+                        continue;
+                    }
                     totalNotes++;
                     const stats = await stat(fullEntryPath);
                     totalSize += stats.size;

package/dist/src/filesystem.test.js

@@ -1,6 +1,7 @@
 import { test, expect, beforeEach, afterEach } from "vitest";
 import { FileSystemService } from "./filesystem.js";
-import { writeFile, mkdir, mkdtemp, rm } from "fs/promises";
+import { PathFilter } from "./pathfilter.js";
+import { writeFile, readFile, mkdir, mkdtemp, rm } from "fs/promises";
 import { join } from "path";
 import { tmpdir } from "os";
 let testVaultPath;
@@ -184,6 +185,68 @@ test("patch note fails with empty newString", async () => {
     expect(result.success).toBe(false);
     expect(result.message).toMatch(/empty|filled|required/i);
 });
+test("patch note fails with undefined newString", async () => {
+    const testPath = "test-note.md";
+    const content = "# Test Note\n\nSome content.";
+    await writeFile(join(testVaultPath, testPath), content);
+    const result = await fileSystem.patchNote({
+        path: testPath,
+        oldString: "content",
+        newString: undefined,
+        replaceAll: false
+    });
+    expect(result.success).toBe(false);
+    expect(result.message).toMatch(/empty|filled|required/i);
+    // Verify the note was NOT corrupted
+    const note = await fileSystem.readNote(testPath);
+    expect(note.content).not.toContain("undefined");
+    expect(note.content).toContain("Some content.");
+});
+test("patch note fails with null newString", async () => {
+    const testPath = "test-note.md";
+    const content = "# Test Note\n\nSome content.";
+    await writeFile(join(testVaultPath, testPath), content);
+    const result = await fileSystem.patchNote({
+        path: testPath,
+        oldString: "content",
+        newString: null,
+        replaceAll: false
+    });
+    expect(result.success).toBe(false);
+    expect(result.message).toMatch(/empty|filled|required/i);
+    // Verify the note was NOT corrupted
+    const note = await fileSystem.readNote(testPath);
+    expect(note.content).not.toContain("null");
+    expect(note.content).toContain("Some content.");
+});
+test("writeNote rejects undefined content", async () => {
+    const testPath = "test-note.md";
+    await expect(fileSystem.writeNote({
+        path: testPath,
+        content: undefined
+    })).rejects.toThrow(/Content is required/);
+});
+test("writeNote rejects null content", async () => {
+    const testPath = "test-note.md";
+    await expect(fileSystem.writeNote({
+        path: testPath,
+        content: null
+    })).rejects.toThrow(/Content is required/);
+});
+test("writeNote append with undefined content does not corrupt note", async () => {
+    const testPath = "test-note.md";
+    const content = "# Test Note\n\nOriginal content.";
+    await writeFile(join(testVaultPath, testPath), content);
+    await expect(fileSystem.writeNote({
+        path: testPath,
+        content: undefined,
+        mode: 'append'
+    })).rejects.toThrow(/Content is required/);
+    // Verify the note was NOT corrupted
+    const note = await fileSystem.readNote(testPath);
+    expect(note.content).not.toContain("undefined");
+    expect(note.content).toContain("Original content.");
+});
 test("patch note handles regex special characters literally", async () => {
     const testPath = "test-note.md";
     const content = "Price: $10.50 (special)";
@@ -199,6 +262,34 @@ test("patch note handles regex special characters literally", async () => {
     expect(updatedNote.content).toContain("$15.75");
     expect(updatedNote.content).not.toContain("$10.50");
 });
+test("patch note works with fenced code blocks", async () => {
+    const testPath = "code-fence-test.md";
+    const content = "# Example\n\n```rust\nfn main() {\n    println!(\"hello\");\n}\n```\n";
+    await writeFile(join(testVaultPath, testPath), content);
+    const result = await fileSystem.patchNote({
+        path: testPath,
+        oldString: "println!(\"hello\");",
+        newString: "println!(\"hello world\");",
+        replaceAll: false
+    });
+    expect(result.success).toBe(true);
+    const updatedNote = await fileSystem.readNote(testPath);
+    expect(updatedNote.originalContent).toContain("println!(\"hello world\");");
+});
+test("patch note works with markdown tables", async () => {
+    const testPath = "table-test.md";
+    const content = "| Tool | Status |\n|---|---|\n| patch_note | flaky |\n";
+    await writeFile(join(testVaultPath, testPath), content);
+    const result = await fileSystem.patchNote({
+        path: testPath,
+        oldString: "| patch_note | flaky |",
+        newString: "| patch_note | stable |",
+        replaceAll: false
+    });
+    expect(result.success).toBe(true);
+    const updatedNote = await fileSystem.readNote(testPath);
+    expect(updatedNote.originalContent).toContain("| patch_note | stable |");
+});
 test("patch note preserves tabs and spaces", async () => {
     const testPath = "test-note.md";
     const content = "Line with\ttabs\n  Line with spaces\n\tTabbed line";
@@ -514,6 +605,14 @@ test("frontmatter validation with invalid data", async () => {
         }
     })).rejects.toThrow(/Invalid frontmatter/);
 });
+test("listDirectory includes non-note files but readNote still blocks them", async () => {
+    const imagePath = "assets/diagram.png";
+    await mkdir(join(testVaultPath, "assets"), { recursive: true });
+    await writeFile(join(testVaultPath, imagePath), "fake-png-content");
+    const listing = await fileSystem.listDirectory("assets");
+    expect(listing.files).toContain("diagram.png");
+    await expect(fileSystem.readNote(imagePath)).rejects.toThrow(/Access denied/);
+});
 // ============================================================================
 // NON-EXISTENT VAULT TESTS
 // ============================================================================
@@ -615,6 +714,96 @@ test("move note with special chars in both paths", async () => {
     const note = await fileSystem.readNote(newPath);
     expect(note.content).toContain("Moving note");
 });
+test("move_file moves binary files without corruption", async () => {
+    const oldPath = "attachments/original image.png";
+    const newPath = "assets/original image.png";
+    const binaryContent = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x00, 0xff, 0x10, 0x42]);
+    await mkdir(join(testVaultPath, "attachments"), { recursive: true });
+    await writeFile(join(testVaultPath, oldPath), binaryContent);
+    const result = await fileSystem.moveFile({
+        oldPath,
+        newPath,
+        confirmOldPath: oldPath,
+        confirmNewPath: newPath
+    });
+    expect(result.success).toBe(true);
+    const moved = await readFile(join(testVaultPath, newPath));
+    expect(Buffer.compare(moved, binaryContent)).toBe(0);
+    await expect(readFile(join(testVaultPath, oldPath))).rejects.toMatchObject({ code: "ENOENT" });
+});
+test("move_file respects overwrite=false", async () => {
+    const oldPath = "attachments/image.png";
+    const newPath = "assets/image.png";
+    await mkdir(join(testVaultPath, "attachments"), { recursive: true });
+    await mkdir(join(testVaultPath, "assets"), { recursive: true });
+    await writeFile(join(testVaultPath, oldPath), Buffer.from([0x01, 0x02, 0x03]));
+    await writeFile(join(testVaultPath, newPath), Buffer.from([0xaa, 0xbb]));
+    const result = await fileSystem.moveFile({
+        oldPath,
+        newPath,
+        confirmOldPath: oldPath,
+        confirmNewPath: newPath,
+        overwrite: false
+    });
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("Target file already exists");
+});
+test("move_file overwrites existing file when overwrite=true", async () => {
+    const oldPath = "attachments/image.png";
+    const newPath = "assets/image.png";
+    const replacement = Buffer.from([0xde, 0xad, 0xbe, 0xef]);
+    await mkdir(join(testVaultPath, "attachments"), { recursive: true });
+    await mkdir(join(testVaultPath, "assets"), { recursive: true });
+    await writeFile(join(testVaultPath, oldPath), replacement);
+    await writeFile(join(testVaultPath, newPath), Buffer.from([0x00]));
+    const result = await fileSystem.moveFile({
+        oldPath,
+        newPath,
+        confirmOldPath: oldPath,
+        confirmNewPath: newPath,
+        overwrite: true
+    });
+    expect(result.success).toBe(true);
+    const moved = await readFile(join(testVaultPath, newPath));
+    expect(Buffer.compare(moved, replacement)).toBe(0);
+});
+test("move_file rejects directory sources", async () => {
+    await mkdir(join(testVaultPath, "attachments/folder"), { recursive: true });
+    const result = await fileSystem.moveFile({
+        oldPath: "attachments/folder",
+        newPath: "assets/folder",
+        confirmOldPath: "attachments/folder",
+        confirmNewPath: "assets/folder"
+    });
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("supports files only");
+});
+test("move_file blocks restricted system paths", async () => {
+    const result = await fileSystem.moveFile({
+        oldPath: ".obsidian/plugins/data.json",
+        newPath: "assets/data.json",
+        confirmOldPath: ".obsidian/plugins/data.json",
+        confirmNewPath: "assets/data.json"
+    });
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("Access denied");
+});
+test("move_file requires matching confirmation paths", async () => {
+    const oldPath = "attachments/check.png";
+    const newPath = "assets/check.png";
+    await mkdir(join(testVaultPath, "attachments"), { recursive: true });
+    await writeFile(join(testVaultPath, oldPath), Buffer.from([0x11, 0x22]));
+    const result = await fileSystem.moveFile({
+        oldPath,
+        newPath,
+        confirmOldPath: "attachments/other.png",
+        confirmNewPath: newPath
+    });
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("confirmation paths do not match");
+    const stillExists = await readFile(join(testVaultPath, oldPath));
+    expect(Buffer.compare(stillExists, Buffer.from([0x11, 0x22]))).toBe(0);
+});
 test("patch note with regex special chars in oldString", async () => {
     const testPath = "regex-test.md";
     const content = "Price: $10.50 (discount)";
@@ -703,6 +892,34 @@ test("get vault stats excludes filtered paths", async () => {
     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 excludes files matched by custom ** ignored patterns", async () => {
+    const customFilter = new PathFilter({
+        ignoredPatterns: ["ignored/**"]
+    });
+    const customFileSystem = new FileSystemService(testVaultPath, customFilter);
+    await mkdir(join(testVaultPath, "ignored"), { recursive: true });
+    await mkdir(join(testVaultPath, "ignored/nested"), { recursive: true });
+    await writeFile(join(testVaultPath, "ignored/something.md"), "# Disallowed 1");
+    await writeFile(join(testVaultPath, "ignored/nested/something.md"), "# Disallowed 2");
+    await writeFile(join(testVaultPath, "visible.md"), "# Visible");
+    const stats = await customFileSystem.getVaultStats(10);
+    const recentPaths = stats.recentlyModified.map(file => file.path);
+    expect(stats.totalNotes).toBe(1);
+    expect(recentPaths).toContain("visible.md");
+    expect(recentPaths).not.toContain("ignored/something.md");
+    expect(recentPaths).not.toContain("ignored/nested/something.md");
+});
+test("get vault stats includes notes inside directories that contain dots", async () => {
+    await mkdir(join(testVaultPath, "2026.03"), { recursive: true });
+    await writeFile(join(testVaultPath, "2026.03/nested.md"), "# Nested");
+    await writeFile(join(testVaultPath, "root.md"), "# Root");
+    const stats = await fileSystem.getVaultStats(10);
+    const recentPaths = stats.recentlyModified.map(file => file.path);
+    expect(stats.totalNotes).toBe(2);
+    expect(stats.totalFolders).toBe(1);
+    expect(recentPaths).toContain("2026.03/nested.md");
+    expect(recentPaths).toContain("root.md");
+});
 test("get vault stats calculates total size correctly", async () => {
     const content1 = "# Note 1 with some content";
     const content2 = "# Note 2 with more content here";

package/dist/src/frontmatter.js

@@ -1,4 +1,30 @@
 import matter from 'gray-matter';
+/**
+ * Parse a frontmatter value that may be a JSON string (LLM clients sometimes
+ * pass frontmatter as a serialized JSON string instead of an object).
+ * Returns undefined if the value is null/undefined, or throws if invalid.
+ */
+export function parseFrontmatter(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        try {
+            const parsed = JSON.parse(value);
+            if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // not valid JSON
+        }
+        throw new Error('frontmatter must be a JSON object, got a string that is not valid JSON');
+    }
+    throw new Error(`frontmatter must be a JSON object, got ${typeof value}`);
+}
 export class FrontmatterHandler {
     parse(content) {
         try {