obsidian-mcp-server 1.5.8 → 2.0.2

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

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { ObsidianRestApiService } from "../../../services/obsidianRestAPI/index.js";
+import { VaultCacheService } from "../../../services/obsidianRestAPI/vaultCache/index.js";
+import { RequestContext } from "../../../utils/index.js";
+declare const ObsidianGlobalSearchInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    searchInPath: z.ZodOptional<z.ZodString>;
+    contextLength: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    modified_since: z.ZodOptional<z.ZodString>;
+    modified_until: z.ZodOptional<z.ZodString>;
+    useRegex: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    caseSensitive: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    maxMatchesPerFile: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    caseSensitive: boolean;
+    query: string;
+    contextLength: number;
+    useRegex: boolean;
+    pageSize: number;
+    page: number;
+    maxMatchesPerFile: number;
+    searchInPath?: string | undefined;
+    modified_since?: string | undefined;
+    modified_until?: string | undefined;
+}, {
+    query: string;
+    caseSensitive?: boolean | undefined;
+    searchInPath?: string | undefined;
+    contextLength?: number | undefined;
+    modified_since?: string | undefined;
+    modified_until?: string | undefined;
+    useRegex?: boolean | undefined;
+    pageSize?: number | undefined;
+    page?: number | undefined;
+    maxMatchesPerFile?: number | undefined;
+}>;
+export declare const ObsidianGlobalSearchInputSchemaShape: {
+    query: z.ZodString;
+    searchInPath: z.ZodOptional<z.ZodString>;
+    contextLength: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    modified_since: z.ZodOptional<z.ZodString>;
+    modified_until: z.ZodOptional<z.ZodString>;
+    useRegex: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    caseSensitive: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    maxMatchesPerFile: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+};
+export type ObsidianGlobalSearchInput = z.infer<typeof ObsidianGlobalSearchInputSchema>;
+export interface MatchContext {
+    context: string;
+    matchText?: string;
+    position?: number;
+}
+export interface GlobalSearchResult {
+    path: string;
+    filename: string;
+    matches: MatchContext[];
+    modifiedTime: string;
+    createdTime: string;
+    numericMtime: number;
+}
+export interface ObsidianGlobalSearchResponse {
+    success: boolean;
+    message: string;
+    results: GlobalSearchResult[];
+    totalFilesFound: number;
+    totalMatchesFound: number;
+    currentPage: number;
+    pageSize: number;
+    totalPages: number;
+    alsoFoundInFiles?: string[];
+}
+export declare const processObsidianGlobalSearch: (params: ObsidianGlobalSearchInput, context: RequestContext, obsidianService: ObsidianRestApiService, vaultCacheService: VaultCacheService | undefined) => Promise<ObsidianGlobalSearchResponse>;
+export {};

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

@@ -0,0 +1,341 @@
+import path from "node:path/posix";
+import { z } from "zod";
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+// Import formatTimestamp utility
+import { config } from "../../../config/index.js";
+import { dateParser, formatTimestamp, logger, retryWithDelay, sanitizeInputForLogging, } from "../../../utils/index.js";
+// ====================================================================================
+// Schema Definitions (Updated for Pagination, Match Limit, and Path Filter)
+// ====================================================================================
+const ObsidianGlobalSearchInputSchema = z
+    .object({
+    query: z
+        .string()
+        .min(1)
+        .describe("The search query (text or regex pattern)."),
+    searchInPath: z
+        .string()
+        .optional()
+        .describe("Optional vault-relative path to recursively search within (e.g., 'Notes/Projects'). If omitted, searches the entire vault."),
+    contextLength: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .default(100)
+        .describe("Characters of context around matches."),
+    modified_since: z
+        .string()
+        .optional()
+        .describe("Filter files modified *since* this date/time (e.g., '2 weeks ago', '2024-01-15')."),
+    modified_until: z
+        .string()
+        .optional()
+        .describe("Filter files modified *until* this date/time (e.g., 'today', '2024-03-20 17:00')."),
+    useRegex: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Treat 'query' as regex. Defaults to false."),
+    caseSensitive: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Perform case-sensitive search. Defaults to false."),
+    pageSize: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .default(50)
+        .describe("Maximum number of result files per page. Defaults to 50."),
+    page: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .default(1)
+        .describe("Page number of results to return. Defaults to 1."),
+    maxMatchesPerFile: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .default(5)
+        .describe("Maximum number of matches to show per file. Defaults to 5."),
+})
+    .describe("Performs search across vault content using text or regex. Supports filtering by modification date, directory path, pagination, and limiting matches per file.");
+export const ObsidianGlobalSearchInputSchemaShape = ObsidianGlobalSearchInputSchema.shape;
+// ====================================================================================
+// Helper Function (findMatchesInContent - for Cache Fallback)
+// ====================================================================================
+// Removed lineNumber calculation and return
+function findMatchesInContent(content, query, useRegex, caseSensitive, contextLength, context) {
+    const matches = [];
+    let regex;
+    const operation = "findMatchesInContent";
+    const opContext = { ...context, operation };
+    try {
+        const flags = `g${caseSensitive ? "" : "i"}`;
+        regex = useRegex
+            ? new RegExp(query, flags)
+            : new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), flags);
+    }
+    catch (e) {
+        const errorMsg = `[${operation}] Invalid regex pattern: ${query}`;
+        logger.error(errorMsg, e instanceof Error ? e : undefined, opContext);
+        throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid regex pattern: ${query}`, opContext);
+    }
+    let match;
+    // Removed line number calculation logic
+    while ((match = regex.exec(content)) !== null) {
+        const matchIndex = match.index;
+        const matchText = match[0];
+        const startIndex = Math.max(0, matchIndex - contextLength);
+        const endIndex = Math.min(content.length, matchIndex + matchText.length + contextLength);
+        const contextSnippet = content.substring(startIndex, endIndex);
+        // Find position *within* the snippet for consistency with API fallback
+        const positionInSnippet = contextSnippet
+            .toLowerCase()
+            .indexOf(matchText.toLowerCase());
+        matches.push({
+            // lineNumber removed
+            context: contextSnippet,
+            matchText: matchText, // Included for cache search
+            position: positionInSnippet >= 0 ? positionInSnippet : 0, // Included for cache search
+        });
+        if (matchText.length === 0)
+            regex.lastIndex++;
+    }
+    return matches;
+}
+// ====================================================================================
+// Core Logic Function (API-First with Cache Fallback)
+// ====================================================================================
+const API_SEARCH_TIMEOUT_MS = config.obsidianApiSearchTimeoutMs;
+export const processObsidianGlobalSearch = async (params, context, obsidianService, vaultCacheService) => {
+    const operation = "processObsidianGlobalSearch";
+    const opContext = { ...context, operation };
+    logger.info(`Processing obsidian_global_search request: "${params.query}" (API-first)`, { ...opContext, params: sanitizeInputForLogging(params) });
+    let sinceDate = null;
+    let untilDate = null;
+    let strategyMessage = "";
+    let allFilteredResults = []; // Store all results matching filters before pagination
+    let totalMatchesCount = 0; // Total matches across all files before limiting per file
+    // Normalize searchInPath: remove leading/trailing slashes and ensure it ends with a slash if not empty
+    const searchPathPrefix = params.searchInPath
+        ? params.searchInPath.replace(/^\/+|\/+$/g, "") +
+            (params.searchInPath === "/" ? "" : "/")
+        : ""; // Empty string means search entire vault
+    // 1. Parse Date Filters
+    const dateParseContext = { ...opContext, subOperation: "parseDates" };
+    try {
+        if (params.modified_since)
+            sinceDate = await dateParser.parseToDate(params.modified_since, dateParseContext);
+        if (params.modified_until)
+            untilDate = await dateParser.parseToDate(params.modified_until, dateParseContext);
+    }
+    catch (error) {
+        const errMsg = `Invalid date format provided`;
+        logger.error(errMsg, error instanceof Error ? error : undefined, dateParseContext);
+        throw new McpError(BaseErrorCode.VALIDATION_ERROR, errMsg, dateParseContext);
+    }
+    // 2. Attempt API Search with Retries and Timeout
+    let apiFailedOrTimedOut = false;
+    try {
+        strategyMessage = `Attempting live API search with retries (timeout: ${API_SEARCH_TIMEOUT_MS / 1000}s per attempt). `;
+        const apiSearchContext = {
+            ...opContext,
+            subOperation: "searchApiSimpleWithRetry",
+        };
+        const apiResults = await retryWithDelay(async () => {
+            logger.info(`Calling obsidianService.searchSimple for query: "${params.query}"`, apiSearchContext);
+            const apiCallPromise = obsidianService.searchSimple(params.query, params.contextLength, apiSearchContext);
+            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`API search timed out after ${API_SEARCH_TIMEOUT_MS}ms`)), API_SEARCH_TIMEOUT_MS));
+            return await Promise.race([apiCallPromise, timeoutPromise]);
+        }, {
+            operationName: "obsidianService.searchSimple",
+            context: apiSearchContext,
+            maxRetries: 2, // Total of 3 attempts
+            delayMs: 500,
+            shouldRetry: (err) => {
+                // Retry on any error during the API call phase
+                logger.warning(`API search attempt failed. Retrying...`, {
+                    ...apiSearchContext,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return true;
+            },
+        });
+        strategyMessage += `API search successful, returned ${apiResults.length} potential files. `;
+        logger.info(`API searchSimple returned ${apiResults.length} files with potential matches.`, apiSearchContext);
+        // Process API results (fetch stats for date filtering and inclusion)
+        const fetchStatsContext = {
+            ...opContext,
+            subOperation: "fetchStatsForApiResults",
+        };
+        let processedCount = 0;
+        for (const apiResult of apiResults) {
+            const filePathFromApi = apiResult.filename; // API uses 'filename' for the full path
+            // Apply path filter
+            if (searchPathPrefix && !filePathFromApi.startsWith(searchPathPrefix)) {
+                continue; // Skip if file is not in the specified path
+            }
+            let mtime;
+            let ctime;
+            // Fetch stats regardless of date filtering to include in results
+            try {
+                const noteJson = (await obsidianService.getFileContent(filePathFromApi, "json", fetchStatsContext));
+                mtime = noteJson.stat.mtime;
+                ctime = noteJson.stat.ctime; // Get ctime
+                // Apply date filtering if needed
+                if ((sinceDate && mtime < sinceDate.getTime()) ||
+                    (untilDate && mtime > untilDate.getTime())) {
+                    continue; // Skip due to date filter
+                }
+            }
+            catch (statError) {
+                logger.warning(`Failed to fetch stats for file ${filePathFromApi}. Skipping file. Error: ${statError instanceof Error ? statError.message : String(statError)}`, fetchStatsContext);
+                continue; // Skip if stats cannot be fetched
+            }
+            // Transform SimpleSearchMatch[] to MatchContext[] - OMITTING matchText and position
+            const transformedMatches = [];
+            for (const apiMatch of apiResult.matches) {
+                transformedMatches.push({
+                    // lineNumber removed
+                    context: apiMatch.context, // Use the context provided by the API
+                    // matchText and position are omitted as they cannot be reliably determined from API result
+                });
+            }
+            // Apply match limit per file
+            const limitedMatches = transformedMatches.slice(0, params.maxMatchesPerFile);
+            // Only add if we actually found matches after transformation/filtering
+            if (limitedMatches.length > 0) {
+                allFilteredResults.push({
+                    // Add to the unfiltered list first
+                    path: filePathFromApi,
+                    filename: path.basename(filePathFromApi),
+                    matches: limitedMatches, // Use limited matches
+                    modifiedTime: formatTimestamp(mtime, fetchStatsContext), // Format mtime
+                    createdTime: formatTimestamp(ctime, fetchStatsContext), // Format ctime
+                    numericMtime: mtime, // Store numeric mtime
+                });
+                totalMatchesCount += transformedMatches.length; // Count *all* matches before limiting for total count
+                processedCount++;
+            }
+        }
+        strategyMessage += `Processed ${processedCount} files matching all filters (including path: '${searchPathPrefix || "entire vault"}'). `;
+    }
+    catch (apiError) {
+        // API call failed or timed out internally
+        apiFailedOrTimedOut = true;
+        strategyMessage += `API search failed or timed out (${apiError instanceof Error ? apiError.message : String(apiError)}). `;
+        logger.warning(strategyMessage, {
+            ...opContext,
+            subOperation: "apiSearchFailedOrTimedOut",
+        });
+    }
+    // 3. Fallback to Cache if API Failed/Timed Out
+    if (apiFailedOrTimedOut) {
+        if (vaultCacheService && vaultCacheService.isReady()) {
+            strategyMessage += "Falling back to in-memory cache. ";
+            logger.info("API search failed/timed out. Falling back to in-memory cache.", opContext);
+            const cache = vaultCacheService.getCache();
+            const cacheSearchContext = {
+                ...opContext,
+                subOperation: "searchCacheFallback",
+            };
+            allFilteredResults = []; // Reset results for cache search
+            totalMatchesCount = 0;
+            let processedCount = 0;
+            for (const [filePath, cacheEntry] of cache.entries()) {
+                // Apply path filter
+                if (searchPathPrefix && !filePath.startsWith(searchPathPrefix)) {
+                    continue; // Skip if file is not in the specified path
+                }
+                const mtime = cacheEntry.mtime; // Get mtime from cache
+                // Apply date filtering
+                if ((sinceDate && mtime < sinceDate.getTime()) ||
+                    (untilDate && mtime > untilDate.getTime())) {
+                    continue;
+                }
+                try {
+                    const matches = findMatchesInContent(cacheEntry.content, params.query, params.useRegex, params.caseSensitive, params.contextLength, cacheSearchContext);
+                    // Apply match limit per file
+                    const limitedMatches = matches.slice(0, params.maxMatchesPerFile);
+                    if (limitedMatches.length > 0) {
+                        let ctime = null;
+                        // Attempt to fetch ctime as cache likely doesn't have it
+                        try {
+                            const noteJson = (await obsidianService.getFileContent(filePath, "json", cacheSearchContext));
+                            ctime = noteJson.stat.ctime;
+                        }
+                        catch (statError) {
+                            logger.warning(`Failed to fetch ctime for cached file ${filePath} during fallback. Error: ${statError instanceof Error ? statError.message : String(statError)}`, cacheSearchContext);
+                            // Proceed without ctime if fetch fails
+                        }
+                        allFilteredResults.push({
+                            // Add to unfiltered list
+                            path: filePath,
+                            filename: path.basename(filePath),
+                            modifiedTime: formatTimestamp(mtime, cacheSearchContext), // Format mtime
+                            createdTime: formatTimestamp(ctime ?? mtime, cacheSearchContext), // Format ctime (or mtime fallback)
+                            matches: limitedMatches, // Use limited matches
+                            numericMtime: mtime, // Store numeric mtime from cache
+                        });
+                        totalMatchesCount += matches.length; // Count *all* matches before limiting
+                        processedCount++;
+                    }
+                }
+                catch (matchError) {
+                    logger.warning(`Error matching content in cached file ${filePath} during fallback: ${matchError instanceof Error ? matchError.message : String(matchError)}`, cacheSearchContext);
+                }
+            }
+            strategyMessage += `Searched ${cache.size} cached files, processed ${processedCount} matching all filters (including path: '${searchPathPrefix || "entire vault"}'). `;
+        }
+        else {
+            // This block now handles both "cache disabled" and "cache not ready"
+            const reason = vaultCacheService ? "is not ready" : "is disabled";
+            strategyMessage += `Cache not available (${reason}), unable to fallback. `;
+            logger.error(`API search failed and cache ${reason}. Cannot perform search.`, opContext);
+            // Throw a specific error because the tool cannot function without a data source.
+            throw new McpError(BaseErrorCode.SERVICE_UNAVAILABLE, `Live API search failed and the cache is currently ${reason}. Please ensure the Obsidian REST API is running and reachable, and that the cache is enabled and has had time to build.`, opContext);
+        }
+    }
+    // 4. Apply Pagination and Sorting
+    const totalFilesFound = allFilteredResults.length;
+    const pageSize = params.pageSize;
+    const currentPage = params.page;
+    const totalPages = Math.ceil(totalFilesFound / pageSize);
+    const startIndex = (currentPage - 1) * pageSize;
+    const endIndex = startIndex + pageSize;
+    // Sort results by numeric modified time (descending) *before* pagination
+    allFilteredResults.sort((a, b) => {
+        return b.numericMtime - a.numericMtime; // Descending
+    });
+    const paginatedResults = allFilteredResults.slice(startIndex, endIndex);
+    // 5. Determine alsoFoundInFiles
+    let alsoFoundInFiles = undefined;
+    if (totalPages > 1) {
+        const paginatedFilePaths = new Set(paginatedResults.map((r) => r.path));
+        alsoFoundInFiles = allFilteredResults
+            .filter((r) => !paginatedFilePaths.has(r.path)) // Get files not on the current page
+            .map((r) => r.filename); // Then get their filenames
+        alsoFoundInFiles = [...new Set(alsoFoundInFiles)]; // Ensure unique filenames in the final list
+    }
+    // 6. Construct Final Response
+    const finalMessage = `${strategyMessage}Found ${totalMatchesCount} matches across ${totalFilesFound} files matching all criteria. Returning page ${currentPage} of ${totalPages} (${paginatedResults.length} files on this page, page size ${pageSize}, max matches per file ${params.maxMatchesPerFile}). Results sorted by modification date (newest first).`;
+    const response = {
+        success: true, // Indicate overall tool success, even if fallback was used or results are empty
+        message: finalMessage,
+        results: paginatedResults,
+        totalFilesFound: totalFilesFound,
+        totalMatchesFound: totalMatchesCount,
+        currentPage: currentPage,
+        pageSize: pageSize,
+        totalPages: totalPages,
+        alsoFoundInFiles: alsoFoundInFiles, // Add the list here
+    };
+    logger.info(`Global search processing completed. ${finalMessage}`, opContext);
+    return response;
+};

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

@@ -0,0 +1,18 @@
+/**
+ * @module ObsidianGlobalSearchToolRegistration
+ * @description Registers the 'obsidian_global_search' tool with the MCP server.
+ * This tool allows searching the Obsidian vault using text/regex queries with optional date filters.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ObsidianRestApiService } from "../../../services/obsidianRestAPI/index.js";
+import type { VaultCacheService } from "../../../services/obsidianRestAPI/vaultCache/index.js";
+/**
+ * Registers the 'obsidian_global_search' tool with the MCP server instance.
+ *
+ * @param {McpServer} server - The MCP server instance.
+ * @param {ObsidianRestApiService} obsidianService - The instance of the Obsidian REST API service.
+ * @param {VaultCacheService} vaultCacheService - The instance of the Vault Cache service.
+ * @returns {Promise<void>} A promise that resolves when the tool is registered.
+ * @throws {McpError} If registration fails critically.
+ */
+export declare function registerObsidianGlobalSearchTool(server: McpServer, obsidianService: ObsidianRestApiService, vaultCacheService: VaultCacheService): Promise<void>;

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

@@ -0,0 +1,69 @@
+/**
+ * @module ObsidianGlobalSearchToolRegistration
+ * @description Registers the 'obsidian_global_search' tool with the MCP server.
+ * This tool allows searching the Obsidian vault using text/regex queries with optional date filters.
+ */
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
+import { ObsidianGlobalSearchInputSchemaShape, processObsidianGlobalSearch, } from "./logic.js"; // Ensure '.js' extension
+/**
+ * Registers the 'obsidian_global_search' tool with the MCP server instance.
+ *
+ * @param {McpServer} server - The MCP server instance.
+ * @param {ObsidianRestApiService} obsidianService - The instance of the Obsidian REST API service.
+ * @param {VaultCacheService} vaultCacheService - The instance of the Vault Cache service.
+ * @returns {Promise<void>} A promise that resolves when the tool is registered.
+ * @throws {McpError} If registration fails critically.
+ */
+export async function registerObsidianGlobalSearchTool(server, obsidianService, vaultCacheService) {
+    const toolName = "obsidian_global_search";
+    const toolDescription = `Performs search across the Obsidian vault using text or regex, primarily relying on the Obsidian REST API's simple search. Supports filtering by modification date, optionally restricting search to a specific directory path (recursively), pagination (page, pageSize), and limiting matches shown per file (maxMatchesPerFile). Returns a JSON object containing success status, a message, pagination details (currentPage, pageSize, totalPages), total file/match counts (before pagination), and an array of results. Each result includes the file path, filename, creation timestamp (ctime), modification timestamp (mtime), and an array of match context snippets (limited by maxMatchesPerFile). If there are multiple pages of results, it also includes an 'alsoFoundInFiles' array listing filenames found on other pages.`;
+    const registrationContext = requestContextService.createRequestContext({
+        operation: "RegisterObsidianGlobalSearchTool",
+        toolName: toolName,
+        module: "ObsidianGlobalSearchRegistration",
+    });
+    logger.info(`Attempting to register tool: ${toolName}`, registrationContext);
+    await ErrorHandler.tryCatch(async () => {
+        server.tool(toolName, toolDescription, ObsidianGlobalSearchInputSchemaShape, async (params, handlerInvocationContext) => {
+            const handlerContext = requestContextService.createRequestContext({
+                operation: "HandleObsidianGlobalSearchRequest",
+                toolName: toolName,
+                paramsSummary: {
+                    useRegex: params.useRegex,
+                    caseSensitive: params.caseSensitive,
+                    pageSize: params.pageSize,
+                    page: params.page,
+                    maxMatchesPerFile: params.maxMatchesPerFile,
+                    searchInPath: params.searchInPath,
+                    hasDateFilter: !!(params.modified_since || params.modified_until),
+                },
+            });
+            logger.debug(`Handling '${toolName}' request`, handlerContext);
+            return await ErrorHandler.tryCatch(async () => {
+                const response = await processObsidianGlobalSearch(params, handlerContext, obsidianService, vaultCacheService);
+                logger.debug(`'${toolName}' processed successfully`, handlerContext);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(response, null, 2),
+                        },
+                    ],
+                    isError: false,
+                };
+            }, {
+                operation: `executing tool ${toolName}`,
+                context: handlerContext,
+                errorCode: BaseErrorCode.INTERNAL_ERROR,
+            });
+        });
+        logger.info(`Tool registered successfully: ${toolName}`, registrationContext);
+    }, {
+        operation: `registering tool ${toolName}`,
+        context: registrationContext,
+        errorCode: BaseErrorCode.INTERNAL_ERROR,
+        errorMapper: (error) => new McpError(error instanceof McpError ? error.code : BaseErrorCode.INTERNAL_ERROR, `Failed to register tool '${toolName}': ${error instanceof Error ? error.message : "Unknown error"}`, { ...registrationContext }),
+        critical: true,
+    });
+}

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

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Barrel file for the 'obsidian_list_files' MCP tool.
+ *
+ * This file serves as the public entry point for the obsidian_list_files tool module.
+ * It re-exports the primary registration function (`registerObsidianListFilesTool`)
+ * from the './registration.js' module. This pattern simplifies imports for consumers
+ * of the tool, allowing them to import necessary components from a single location.
+ *
+ * Consumers (like the main server setup) should import the registration function
+ * from this file to integrate the tool into the MCP server instance.
+ */
+export { registerObsidianListFilesTool } from "./registration.js";

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

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Barrel file for the 'obsidian_list_files' MCP tool.
+ *
+ * This file serves as the public entry point for the obsidian_list_files tool module.
+ * It re-exports the primary registration function (`registerObsidianListFilesTool`)
+ * from the './registration.js' module. This pattern simplifies imports for consumers
+ * of the tool, allowing them to import necessary components from a single location.
+ *
+ * Consumers (like the main server setup) should import the registration function
+ * from this file to integrate the tool into the MCP server instance.
+ */
+export { registerObsidianListFilesTool } from "./registration.js";

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

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { ObsidianRestApiService } from "../../../services/obsidianRestAPI/index.js";
+import { RequestContext } from "../../../utils/index.js";
+/**
+ * Zod schema for validating the input parameters of the 'obsidian_list_files' tool.
+ */
+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"]
+     */
+    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>>;
+}, "strip", z.ZodTypeAny, {
+    dirPath: string;
+    fileExtensionFilter?: string[] | undefined;
+    nameRegexFilter?: string | null | undefined;
+}, {
+    dirPath: string;
+    fileExtensionFilter?: string[] | undefined;
+    nameRegexFilter?: string | null | 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.
+ */
+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.
+ *
+ * @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.
+ */
+export declare const processObsidianListFiles: (params: ObsidianListFilesInput, context: RequestContext, obsidianService: ObsidianRestApiService) => Promise<ObsidianListFilesResponse>;