obsidian-mcp-server 2.0.2 → 2.0.4

package/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.4] - 2025-06-13
+
+### Added
+
+- **Recursive File Listing**: The `obsidian_list_files` tool now supports recursive listing of directories with a `recursionDepth` parameter.
+
+### Changed
+
+- **Documentation**:
+  - Consolidated tool specifications into `obsidian_mcp_tools_spec.md`.
+  - Updated `.clinerules` with a detailed logger implementation example for the agent.
+  - Updated the repository's directory tree documentation.
+
+## [2.0.3] - 2025-06-12
+
+### Fixed
+
+- **NPM Package Display**: Explicitly included `README.md`, `LICENSE`, and `CHANGELOG.md` in the `files` array in `package.json` to ensure they are displayed correctly on the npm package page.
+
+## [2.0.2] - 2025-06-12
+
+### Fixed
+
+- **NPM Package Version**: Bad npm package. Bumping to v2.0.2 for publishing.
+
+## [2.0.1] - 2025-06-12
+
+### Added
+
+- **Enhanced Documentation**:
+  - Added a warning to the `VaultCacheService` documentation about its potential for high memory usage on large vaults.
+  - Added a code comment in `obsidianManageFrontmatterTool` to clarify the regex-based key deletion strategy.
+
+### Changed
+
+- **Improved SSL Handling**: The `OBSIDIAN_VERIFY_SSL` environment variable is now correctly parsed as a boolean, ensuring more reliable SSL verification behavior.
+- **API Service Refactoring**: Simplified the `httpsAgent` handling within the `ObsidianRestApiService` to improve code clarity and remove redundant agent creation on each request.
+
+### Fixed
+
+- **Path Import Correction**: Corrected a path import in the `obsidianGlobalSearchTool` to use `node:path/posix` for better cross-platform compatibility.
+
+## [2.0.0] - 2025-06-12
+
+Version 2.0.0 is a complete overhaul of the Obsidian MCP Server, migrating it to my [`cyanheads/mcp-ts-template`](https://github.com/cyanheads/mcp-ts-template). This release introduces a more robust architecture, a streamlined toolset, enhanced security, and significant performance improvements. It is a breaking change from the 1.x series.
+
+### Added
+
+- **New Core Architecture**: The server is now built on the [`cyanheads/mcp-ts-template`](https://github.com/cyanheads/mcp-ts-template), providing a standardized, modular, and maintainable structure.
+- **Hono HTTP Transport**: The HTTP transport has been migrated from Express to Hono, offering a more lightweight and performant server.
+- **Vault Cache Service**: A new in-memory `VaultCacheService` has been introduced. It caches vault content to improve performance for search operations and provides a resilient fallback if the Obsidian API is temporarily unavailable. It also refreshes periodically.
+- **Advanced Authentication**:
+  - Added support for **OAuth 2.1** bearer token validation alongside the existing secret key-based JWTs.
+  - Introduced `authContext` using `AsyncLocalStorage` for secure, request-scoped access to authentication details.
+- **New Tools**:
+  - `obsidian_delete_file`: A new tool to permanently delete files from the vault.
+  - `obsidian_search_replace`: A powerful new tool to perform search and replace operations with regex support.
+- **Enhanced Utilities**:
+  - **Request Context**: A robust request context system (`requestContextService`) for improved logging and tracing.
+  - **Error Handling**: A centralized `ErrorHandler` for consistent and detailed error reporting.
+  - **Async Utilities**: A `retryWithDelay` utility is now used across the application to make API calls more resilient.
+- **New Development Scripts**: Added `docs:generate` (for TypeDoc) and `inspect:stdio`/`inspect:http` (for MCP Inspector) to `package.json`.
+
+### Changed
+
+- **Project Structure**: The entire project has been reorganized to align with the [`cyanheads/mcp-ts-template`](https://github.com/cyanheads/mcp-ts-template), improving separation of concerns (e.g., `services`, `mcp-server`, `types-global`).
+- **Tool Consolidation and Enhancement**: The toolset has been redesigned for clarity and power:
+  - `obsidian_list_files` replaces `obsidian_list_files_in_vault` and `obsidian_list_files_in_dir`, offering more flexible filtering.
+  - `obsidian_read_file` replaces `obsidian_get_file_contents` and now supports returning content as structured JSON.
+  - `obsidian_update_file` replaces `obsidian_append_content` and `obsidian_update_content` with explicit modes (`append`, `prepend`, `overwrite`).
+  - `obsidian_global_search` replaces `obsidian_find_in_file` with added support for path/date filtering and pagination.
+  - `obsidian_manage_frontmatter` replaces `obsidian_get_properties` and `obsidian_update_properties` with atomic get/set/delete operations.
+  - `obsidian_manage_tags` replaces `obsidian_get_tags` and now manages both frontmatter and inline tags.
+- **Configuration Overhaul**: Environment variables have been renamed for consistency and clarity.
+  - `OBSIDIAN_BASE_URL` now consolidates protocol, host, and port.
+  - New variables like `MCP_TRANSPORT_TYPE`, `MCP_LOG_LEVEL`, and `MCP_AUTH_SECRET_KEY` have been introduced.
+- **Dependency Updates**: All dependencies, including the MCP SDK, have been updated to their latest stable versions.
+- **Obsidian API Service**: The `ObsidianRestApiService` has been completely refactored into a modular class, providing a typed, resilient, and centralized client for all interactions with the Obsidian Local REST API.
+
+### Removed
+
+- **Removed Tools**: The following tools from version 1.x have been removed and their functionality integrated into the new, more comprehensive tools:
+  - `obsidian_list_files_in_vault`
+  - `obsidian_list_files_in_dir`
+  - `obsidian_get_file_contents`
+  - `obsidian_append_content`
+  - `obsidian_update_content`
+  - `obsidian_find_in_file`
+  - `obsidian_complex_search` (path-based searching is now a filter in `obsidian_global_search`)
+  - `obsidian_get_tags`
+  - `obsidian_get_properties`
+  - `obsidian_update_properties`
+- **Removed Resources**: The `obsidian://tags` resource has been removed. Tag information is now available through the `obsidian_manage_tags` tool. I may add the resource back in the future if there is demand for it. Please open an issue if you would like to see it return.
+- **Old Configuration**: All old, non-prefixed environment variables (e.g., `VERIFY_SSL`, `REQUEST_TIMEOUT`) have been removed in favor of the new, standardized configuration schema.

package/README.md

@@ -2,7 +2,7 @@
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)
 [![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.12.1-green.svg)](https://modelcontextprotocol.io/)
-[![Version](https://img.shields.io/badge/Version-2.0.2-blue.svg)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-2.0.3-blue.svg)](./CHANGELOG.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Status](https://img.shields.io/badge/Status-Production-brightgreen.svg)](https://github.com/cyanheads/obsidian-mcp-server/issues)
 [![GitHub](https://img.shields.io/github/stars/cyanheads/obsidian-mcp-server?style=social)](https://github.com/cyanheads/obsidian-mcp-server)

package/dist/mcp-server/tools/obsidianListFilesTool/logic.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @fileoverview Core logic for the 'obsidian_list_files' tool.
+ * This module defines the input schema, response types, and processing logic for
+ * recursively listing files and directories in an Obsidian vault with filtering.
+ * @module src/mcp-server/tools/obsidianListFilesTool/logic
+ */
 import { z } from "zod";
 import { ObsidianRestApiService } from "../../../services/obsidianRestAPI/index.js";
 import { RequestContext } from "../../../utils/index.js";
@@ -7,58 +13,56 @@ import { RequestContext } from "../../../utils/index.js";
 export declare const ObsidianListFilesInputSchema: z.ZodObject<{
     /**
      * The vault-relative path to the directory whose contents should be listed.
-     * Examples: "Attachments/Images", "Projects", "" (for vault root), "/" (for vault root).
      * The path is treated as case-sensitive by the underlying Obsidian API.
      */
     dirPath: z.ZodString;
     /**
      * Optional array of file extensions (including the leading dot) to filter the results.
-     * Only files matching one of these extensions will be included. Directories are always included regardless of this filter.
-     * Example: [".md", ".png"]
+     * Only files matching one of these extensions will be included. Directories are always included.
      */
     fileExtensionFilter: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     /**
      * Optional JavaScript-compatible regular expression pattern string to filter results by name.
      * Only files and directories whose names match the regex will be included.
-     * Example: "^\\d{4}-\\d{2}-\\d{2}" (matches names starting with YYYY-MM-DD)
      */
     nameRegexFilter: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /**
+     * The maximum depth of subdirectories to list recursively.
+     * - A value of `0` lists only the files and directories in the specified `dirPath`.
+     * - A value of `1` lists the contents of `dirPath` and the contents of its immediate subdirectories.
+     * - A value of `-1` (the default) indicates infinite recursion, listing all subdirectories.
+     */
+    recursionDepth: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     dirPath: string;
+    recursionDepth: number;
     fileExtensionFilter?: string[] | undefined;
     nameRegexFilter?: string | null | undefined;
 }, {
     dirPath: string;
     fileExtensionFilter?: string[] | undefined;
     nameRegexFilter?: string | null | undefined;
+    recursionDepth?: number | undefined;
 }>;
 /**
  * TypeScript type inferred from the input schema (`ObsidianListFilesInputSchema`).
- * Represents the validated input parameters used within the core processing logic.
  */
 export type ObsidianListFilesInput = z.infer<typeof ObsidianListFilesInputSchema>;
 /**
- * Defines the structure of the successful response returned by the `processObsidianListFiles` function.
- * This object is typically serialized to JSON and sent back to the client.
+ * Defines the structure of the successful response returned by the core logic function.
  */
 export interface ObsidianListFilesResponse {
-    /** The vault-relative path of the directory whose contents were listed (normalized, e.g., "/" for root). */
     directoryPath: string;
-    /** A string representation of the directory contents formatted as a simple tree structure. */
     tree: string;
-    /** The total number of files and directories included in the formatted tree after filtering. */
     totalEntries: number;
 }
 /**
- * Processes the core logic for listing files and directories within a specified
- * directory in the Obsidian vault. Applies optional filters and formats the output.
+ * Processes the core logic for listing files and directories recursively within the Obsidian vault.
  *
  * @param {ObsidianListFilesInput} params - The validated input parameters.
  * @param {RequestContext} context - The request context for logging and correlation.
  * @param {ObsidianRestApiService} obsidianService - An instance of the Obsidian REST API service.
- * @returns {Promise<ObsidianListFilesResponse>} A promise resolving to the structured success response
- *   containing the listed directory path, a formatted tree string, and the total entry count.
- * @throws {McpError} Throws an McpError if the directory cannot be listed (e.g., not found)
- *   or if any other API interaction or validation fails.
+ * @returns {Promise<ObsidianListFilesResponse>} A promise resolving to the structured success response.
+ * @throws {McpError} Throws an McpError if the initial directory is not found or another error occurs.
  */
 export declare const processObsidianListFiles: (params: ObsidianListFilesInput, context: RequestContext, obsidianService: ObsidianRestApiService) => Promise<ObsidianListFilesResponse>;

package/dist/mcp-server/tools/obsidianListFilesTool/logic.js

@@ -1,4 +1,10 @@
-import path from "node:path"; // Using POSIX path functions for vault path manipulation
+/**
+ * @fileoverview Core logic for the 'obsidian_list_files' tool.
+ * This module defines the input schema, response types, and processing logic for
+ * recursively listing files and directories in an Obsidian vault with filtering.
+ * @module src/mcp-server/tools/obsidianListFilesTool/logic
+ */
+import path from "node:path";
 import { z } from "zod";
 import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
 import { logger, retryWithDelay, } from "../../../utils/index.js";
@@ -12,7 +18,6 @@ export const ObsidianListFilesInputSchema = z
     .object({
     /**
      * The vault-relative path to the directory whose contents should be listed.
-     * Examples: "Attachments/Images", "Projects", "" (for vault root), "/" (for vault root).
      * The path is treated as case-sensitive by the underlying Obsidian API.
      */
     dirPath: z
@@ -20,160 +25,190 @@ export const ObsidianListFilesInputSchema = z
         .describe('The vault-relative path to the directory to list (e.g., "developer/atlas-mcp-server", "/" for root). Case-sensitive.'),
     /**
      * Optional array of file extensions (including the leading dot) to filter the results.
-     * Only files matching one of these extensions will be included. Directories are always included regardless of this filter.
-     * Example: [".md", ".png"]
+     * Only files matching one of these extensions will be included. Directories are always included.
      */
     fileExtensionFilter: z
         .array(z.string().startsWith(".", "Extension must start with a dot '.'"))
         .optional()
-        .describe('Optional array of file extensions (e.g., [".md") to filter files. Directories are always included.'),
+        .describe('Optional array of file extensions (e.g., [".md"]) to filter files. Directories are always included.'),
     /**
      * Optional JavaScript-compatible regular expression pattern string to filter results by name.
      * Only files and directories whose names match the regex will be included.
-     * Example: "^\\d{4}-\\d{2}-\\d{2}" (matches names starting with YYYY-MM-DD)
      */
     nameRegexFilter: z
         .string()
         .nullable()
-        .optional() // Allow null in addition to string/undefined
+        .optional()
         .describe("Optional regex pattern (JavaScript syntax) to filter results by name."),
+    /**
+     * The maximum depth of subdirectories to list recursively.
+     * - A value of `0` lists only the files and directories in the specified `dirPath`.
+     * - A value of `1` lists the contents of `dirPath` and the contents of its immediate subdirectories.
+     * - A value of `-1` (the default) indicates infinite recursion, listing all subdirectories.
+     */
+    recursionDepth: z
+        .number()
+        .int()
+        .default(-1)
+        .describe("Maximum recursion depth. 0 for no recursion, -1 for infinite (default)."),
 })
-    .describe("Input parameters for listing files and subdirectories within a specified Obsidian vault directory, with optional filtering.");
+    .describe("Input parameters for listing files and subdirectories within a specified Obsidian vault directory, with optional filtering and recursion.");
 // ====================================================================================
 // Helper Functions
 // ====================================================================================
 /**
- * Formats a list of file and directory names into a simple tree-like string representation.
- * Directories (indicated by a trailing '/') are listed first, then files, both sorted alphabetically.
+ * Recursively builds a formatted tree string from a nested array of FileTreeNode objects.
  *
- * @param {string[]} fileNames - An array of file and directory names (directories should end with '/').
- * @returns {string} A formatted string representing the directory tree, or "(empty directory)" if the input array is empty.
+ * @param {FileTreeNode[]} nodes - The array of nodes to format.
+ * @param {string} [indent=""] - The indentation prefix for the current level.
+ * @returns {{ tree: string, count: number }} An object containing the formatted tree string and the total count of entries.
  */
-function formatAsTree(fileNames) {
-    if (!fileNames || fileNames.length === 0) {
-        return "(empty directory)";
-    }
-    // Sort entries: directories first, then files, alphabetically within each group.
-    fileNames.sort((a, b) => {
-        const aIsDir = a.endsWith("/");
-        const bIsDir = b.endsWith("/");
-        // Group directories before files
-        if (aIsDir && !bIsDir)
-            return -1; // a (dir) comes before b (file)
-        if (!aIsDir && bIsDir)
-            return 1; // b (dir) comes before a (file)
-        // Within the same type (both dirs or both files), sort alphabetically.
-        // Remove trailing slash for comparison if it's a directory.
-        const nameA = aIsDir ? a.slice(0, -1) : a;
-        const nameB = bIsDir ? b.slice(0, -1) : b;
-        return nameA.localeCompare(nameB);
-    });
-    // Build the tree string with prefixes
+function formatTree(nodes, indent = "") {
     let treeString = "";
-    const lastIndex = fileNames.length - 1;
-    fileNames.forEach((name, index) => {
-        const isLast = index === lastIndex;
-        const prefix = isLast ? "└── " : "├── "; // Use different connectors for the last item
-        treeString += prefix + name + (isLast ? "" : "\n"); // Add newline except for the last item
+    let count = nodes.length;
+    nodes.forEach((node, index) => {
+        const isLast = index === nodes.length - 1;
+        const prefix = isLast ? "└── " : "├── ";
+        const childIndent = isLast ? "    " : "│   ";
+        treeString += `${indent}${prefix}${node.name}\n`;
+        if (node.children && node.children.length > 0) {
+            const result = formatTree(node.children, indent + childIndent);
+            treeString += result.tree;
+            count += result.count;
+        }
     });
-    return treeString;
+    return { tree: treeString, count };
+}
+/**
+ * Recursively builds a file tree by fetching directory contents from the Obsidian API.
+ *
+ * @param {string} dirPath - The path of the directory to process.
+ * @param {number} currentDepth - The current recursion depth.
+ * @param {ObsidianListFilesInput} params - The original validated input parameters, including filters and max depth.
+ * @param {RequestContext} context - The request context for logging.
+ * @param {ObsidianRestApiService} obsidianService - The Obsidian API service instance.
+ * @returns {Promise<FileTreeNode[]>} A promise that resolves to an array of file tree nodes.
+ */
+async function buildFileTree(dirPath, currentDepth, params, context, obsidianService) {
+    const { recursionDepth, fileExtensionFilter, nameRegexFilter } = params;
+    // Stop recursion if max depth is reached (and it's not infinite)
+    if (recursionDepth !== -1 && currentDepth > recursionDepth) {
+        return [];
+    }
+    let fileNames;
+    try {
+        fileNames = await obsidianService.listFiles(dirPath, context);
+    }
+    catch (error) {
+        if (error instanceof McpError && error.code === BaseErrorCode.NOT_FOUND) {
+            logger.warning(`Directory not found during recursive list: ${dirPath}. Skipping.`, context);
+            return []; // Return empty array if a subdirectory is not found
+        }
+        throw error; // Re-throw other errors
+    }
+    const regex = nameRegexFilter && nameRegexFilter.trim() !== ""
+        ? new RegExp(nameRegexFilter)
+        : null;
+    const treeNodes = [];
+    for (const name of fileNames) {
+        const fullPath = path.posix.join(dirPath, name);
+        const isDirectory = name.endsWith("/");
+        const cleanName = isDirectory ? name.slice(0, -1) : name;
+        // Apply filters
+        if (regex && !regex.test(cleanName)) {
+            continue;
+        }
+        if (!isDirectory &&
+            fileExtensionFilter &&
+            fileExtensionFilter.length > 0) {
+            const extension = path.posix.extname(name);
+            if (!fileExtensionFilter.includes(extension)) {
+                continue;
+            }
+        }
+        const node = {
+            name: cleanName,
+            type: isDirectory ? "directory" : "file",
+            children: [],
+        };
+        if (isDirectory) {
+            node.name += "/"; // Add trailing slash back for display
+            node.children = await buildFileTree(fullPath, currentDepth + 1, params, context, obsidianService);
+        }
+        treeNodes.push(node);
+    }
+    // Sort entries: directories first, then files, alphabetically
+    treeNodes.sort((a, b) => {
+        if (a.type === "directory" && b.type === "file")
+            return -1;
+        if (a.type === "file" && b.type === "directory")
+            return 1;
+        return a.name.localeCompare(b.name);
+    });
+    return treeNodes;
 }
 // ====================================================================================
 // Core Logic Function
 // ====================================================================================
 /**
- * Processes the core logic for listing files and directories within a specified
- * directory in the Obsidian vault. Applies optional filters and formats the output.
+ * Processes the core logic for listing files and directories recursively within the Obsidian vault.
  *
  * @param {ObsidianListFilesInput} params - The validated input parameters.
  * @param {RequestContext} context - The request context for logging and correlation.
  * @param {ObsidianRestApiService} obsidianService - An instance of the Obsidian REST API service.
- * @returns {Promise<ObsidianListFilesResponse>} A promise resolving to the structured success response
- *   containing the listed directory path, a formatted tree string, and the total entry count.
- * @throws {McpError} Throws an McpError if the directory cannot be listed (e.g., not found)
- *   or if any other API interaction or validation fails.
+ * @returns {Promise<ObsidianListFilesResponse>} A promise resolving to the structured success response.
+ * @throws {McpError} Throws an McpError if the initial directory is not found or another error occurs.
  */
 export const processObsidianListFiles = async (params, context, obsidianService) => {
-    const { dirPath, fileExtensionFilter, nameRegexFilter } = params;
-    // Normalize dirPath for logging and response (use "/" for root)
+    const { dirPath } = params;
     const dirPathForLog = dirPath === "" || dirPath === "/" ? "/" : dirPath;
-    logger.debug(`Processing obsidian_list_files request for path: ${dirPathForLog}`, { ...context, fileExtensionFilter, nameRegexFilter });
+    logger.debug(`Processing obsidian_list_files request for path: ${dirPathForLog}`, { ...context, params });
     try {
-        // Normalize path for the API call as well
         const effectiveDirPath = dirPath === "" ? "/" : dirPath;
-        // --- Step 1: Fetch initial list from Obsidian API ---
-        const listContext = { ...context, operation: "listFilesApiCall" };
-        logger.debug(`Calling Obsidian API to list directory: ${effectiveDirPath}`, listContext);
+        // --- Step 1: Build the file tree recursively with retry for the initial call ---
+        const buildTreeContext = { ...context, operation: "buildFileTreeWithRetry" };
         const shouldRetryNotFound = (err) => err instanceof McpError && err.code === BaseErrorCode.NOT_FOUND;
-        let fileNames = await retryWithDelay(() => obsidianService.listFiles(effectiveDirPath, listContext), {
-            operationName: "listFilesWithRetry",
-            context: listContext,
+        const fileTree = await retryWithDelay(() => buildFileTree(effectiveDirPath, 0, // Start at depth 0
+        params, buildTreeContext, obsidianService), {
+            operationName: "buildFileTreeWithRetry",
+            context: buildTreeContext,
             maxRetries: 3,
             delayMs: 300,
             shouldRetry: shouldRetryNotFound,
         });
-        logger.debug(`Successfully listed ${fileNames.length} initial items in: ${dirPathForLog}`, listContext);
-        // --- Step 2: Apply Filters ---
-        const filterContext = { ...context, operation: "applyFilters" };
-        // Apply extension filter if provided
-        if (fileExtensionFilter && fileExtensionFilter.length > 0) {
-            const initialCount = fileNames.length;
-            fileNames = fileNames.filter((fileName) => {
-                // Always keep directories (identified by trailing '/')
-                if (fileName.endsWith("/"))
-                    return true;
-                // Check if the file's extension is in the filter list
-                const extension = path.posix.extname(fileName); // Use path.posix.extname for consistency
-                return fileExtensionFilter.includes(extension);
-            });
-            logger.debug(`Applied extension filter (${fileExtensionFilter.join(", ")}). ${initialCount} -> ${fileNames.length} items remaining.`, filterContext);
-        }
-        // Apply regex name filter if provided and is a non-empty string
-        if (nameRegexFilter && nameRegexFilter.trim() !== "") {
-            const initialCount = fileNames.length;
-            try {
-                const regex = new RegExp(nameRegexFilter); // Compile the regex pattern
-                fileNames = fileNames.filter((fileName) => regex.test(fileName)); // Test each name against the regex
-                logger.debug(`Applied regex filter /${nameRegexFilter}/. ${initialCount} -> ${fileNames.length} items remaining.`, filterContext);
-            }
-            catch (regexError) {
-                // Handle invalid regex patterns provided by the user
-                logger.error(`Invalid regex pattern provided: ${nameRegexFilter}`, regexError instanceof Error ? regexError : undefined, filterContext);
-                throw new McpError(BaseErrorCode.VALIDATION_ERROR, // It's an input validation issue
-                `Invalid regex pattern provided for nameRegexFilter: ${nameRegexFilter}. Error: ${regexError instanceof Error ? regexError.message : "Unknown regex error"}`, filterContext);
-            }
-        }
-        // --- Step 3: Format Output and Return ---
+        // --- Step 2: Format the tree and count entries ---
         const formatContext = { ...context, operation: "formatResponse" };
-        const totalEntries = fileNames.length;
-        logger.debug(`Formatting final list of ${totalEntries} entries as tree.`, formatContext);
-        // Format the potentially filtered list into a tree string
-        const treeString = formatAsTree(fileNames);
-        // Construct the final response object
+        if (fileTree.length === 0) {
+            logger.debug("Directory is empty or all items were filtered out.", formatContext);
+            return {
+                directoryPath: dirPathForLog,
+                tree: "(empty or all items filtered)",
+                totalEntries: 0,
+            };
+        }
+        const { tree, count } = formatTree(fileTree);
+        // --- Step 3: Construct and return the response ---
         const response = {
-            directoryPath: dirPathForLog, // Return the normalized path
-            tree: treeString,
-            totalEntries: totalEntries,
+            directoryPath: dirPathForLog,
+            tree: tree.trimEnd(), // Remove trailing newline
+            totalEntries: count,
         };
-        logger.debug(`Successfully processed list request for ${dirPathForLog}.`, context);
+        logger.debug(`Successfully processed list request for ${dirPathForLog}. Found ${count} entries.`, context);
         return response;
     }
     catch (error) {
-        // Handle errors, ensuring they are McpError instances before re-throwing.
         if (error instanceof McpError) {
-            // Provide a more specific message if the directory wasn't found
+            // Provide a more specific message if the directory wasn't found after retries
             if (error.code === BaseErrorCode.NOT_FOUND) {
-                logger.error(`Directory not found for listing: ${dirPathForLog}`, error, context);
-                throw new McpError(error.code, `Directory not found for listing: ${dirPathForLog}`, context);
+                const notFoundMsg = `Directory not found after retries: ${dirPathForLog}`;
+                logger.error(notFoundMsg, error, context);
+                throw new McpError(error.code, notFoundMsg, context);
             }
             logger.error(`McpError during file listing for ${dirPathForLog}: ${error.message}`, error, context);
-            throw error; // Re-throw known McpError
-        }
-        else {
-            // Catch and wrap unexpected errors
-            const errorMessage = `Unexpected error listing Obsidian files in ${dirPathForLog}`;
-            logger.error(errorMessage, error instanceof Error ? error : undefined, context);
-            throw new McpError(BaseErrorCode.INTERNAL_ERROR, `${errorMessage}: ${error instanceof Error ? error.message : String(error)}`, context);
+            throw error;
         }
+        const errorMessage = `Unexpected error listing Obsidian files in ${dirPathForLog}`;
+        logger.error(errorMessage, error instanceof Error ? error : undefined, context);
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, `${errorMessage}: ${error instanceof Error ? error.message : String(error)}`, context);
     }
 };

package/dist/mcp-server/tools/obsidianListFilesTool/registration.d.ts

@@ -1,14 +1,18 @@
+/**
+ * @fileoverview Registers the 'obsidian_list_files' tool with the MCP server.
+ * This file defines the tool's metadata and sets up the handler that links
+ * the tool call to its core processing logic.
+ * @module src/mcp-server/tools/obsidianListFilesTool/registration
+ */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ObsidianRestApiService } from "../../../services/obsidianRestAPI/index.js";
 /**
  * Registers the 'obsidian_list_files' tool with the MCP server.
  *
  * This tool lists the files and subdirectories within a specified directory
- * in the user's Obsidian vault. It supports optional filtering by file extension
- * or by a regular expression matching the entry name.
- *
- * The response includes the path of the listed directory, a formatted tree string
- * representing the contents, and the total count of entries listed after filtering.
+ * in the user's Obsidian vault. It supports optional filtering by file extension,
+ * by a regular expression matching the entry name, and recursive listing up to a
+ * specified depth.
  *
  * @param {McpServer} server - The MCP server instance to register the tool with.
  * @param {ObsidianRestApiService} obsidianService - An instance of the Obsidian REST API service

package/dist/mcp-server/tools/obsidianListFilesTool/registration.js

@@ -1,3 +1,9 @@
+/**
+ * @fileoverview Registers the 'obsidian_list_files' tool with the MCP server.
+ * This file defines the tool's metadata and sets up the handler that links
+ * the tool call to its core processing logic.
+ * @module src/mcp-server/tools/obsidianListFilesTool/registration
+ */
 import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
 import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
 import { ObsidianListFilesInputSchema, processObsidianListFiles, } from "./logic.js";
@@ -5,11 +11,9 @@ import { ObsidianListFilesInputSchema, processObsidianListFiles, } from "./logic
  * Registers the 'obsidian_list_files' tool with the MCP server.
  *
  * This tool lists the files and subdirectories within a specified directory
- * in the user's Obsidian vault. It supports optional filtering by file extension
- * or by a regular expression matching the entry name.
- *
- * The response includes the path of the listed directory, a formatted tree string
- * representing the contents, and the total count of entries listed after filtering.
+ * in the user's Obsidian vault. It supports optional filtering by file extension,
+ * by a regular expression matching the entry name, and recursive listing up to a
+ * specified depth.
  *
  * @param {McpServer} server - The MCP server instance to register the tool with.
  * @param {ObsidianRestApiService} obsidianService - An instance of the Obsidian REST API service
@@ -19,8 +23,7 @@ import { ObsidianListFilesInputSchema, processObsidianListFiles, } from "./logic
  */
 export const registerObsidianListFilesTool = async (server, obsidianService) => {
     const toolName = "obsidian_list_files";
-    // Updated description to reflect the simplified response (path, tree, count)
-    const toolDescription = "Lists files and subdirectories within a specified Obsidian vault folder. Supports optional filtering by extension or name regex. Returns an object containing the listed directory path, a formatted tree string of its contents, and the total entry count. Use an empty string or '/' for dirPath to list the vault root.";
+    const toolDescription = "Lists files and subdirectories within a specified Obsidian vault folder. Supports optional filtering by extension or name regex, and recursive listing to a specified depth (-1 for infinite). Returns an object containing the listed directory path, a formatted tree string of its contents, and the total entry count. Use an empty string or '/' for dirPath to list the vault root.";
     // Create a context specifically for the registration process.
     const registrationContext = requestContextService.createRequestContext({
         operation: "RegisterObsidianListFilesTool",
@@ -52,17 +55,16 @@ export const registerObsidianListFilesTool = async (server, obsidianService) =>
                     dirPath: params.dirPath,
                     fileExtensionFilter: params.fileExtensionFilter,
                     nameRegexFilter: params.nameRegexFilter,
+                    recursionDepth: params.recursionDepth,
                 },
             });
             logger.debug(`Handling '${toolName}' request`, handlerContext);
             // Wrap the core logic execution in a tryCatch block.
             return await ErrorHandler.tryCatch(async () => {
                 // Delegate the actual file listing and filtering logic to the processing function.
-                // Note: The input schema and shape are identical here, so no separate refinement parse is needed.
                 const response = await processObsidianListFiles(params, handlerContext, obsidianService);
                 logger.debug(`'${toolName}' processed successfully`, handlerContext);
                 // Format the successful response object from the logic function into the required MCP CallToolResult structure.
-                // The entire response object (directoryPath, tree, totalEntries) is serialized to JSON.
                 return {
                     content: [
                         {

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "obsidian-mcp-server",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "Obsidian Knowledge-Management MCP (Model Context Protocol) server that enables AI agents and development tools to interact with an Obsidian vault. It provides a comprehensive suite of tools for reading, writing, searching, and managing notes, tags, and frontmatter, acting as a bridge to the Obsidian Local REST API plugin.",
   "main": "dist/index.js",
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "bin": {
     "obsidian-mcp-server": "dist/index.js"