obsidian-mcp-server 2.0.7 → 3.1.0

package/dist/services/obsidianRestAPI/vaultCache/service.js

@@ -1,299 +0,0 @@
-/**
- * @module VaultCacheService
- * @description Service for building and managing an in-memory cache of Obsidian vault content.
- */
-import path from "node:path";
-import { config } from "../../../config/index.js";
-import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
-import { logger, requestContextService, retryWithDelay, } from "../../../utils/index.js";
-/**
- * Manages an in-memory cache of the Obsidian vault's file structure and metadata.
- *
- * __Is the cache safe and secure?__
- * Yes, the cache is safe and secure for its purpose within this application. Here's why:
- * 1. __In-Memory Storage:__ The cache exists only in the server's memory. It is not written to disk or transmitted over the network, so its attack surface is limited to the server process itself.
- * 2. __Local Data Source:__ The data populating the cache comes directly from your own Obsidian vault via the local REST API. It is not fetching data from external, untrusted sources.
- *
- * __Warning: High Memory Usage__
- * This service stores the entire content of every markdown file in the vault in memory. For users with very large vaults (e.g., many gigabytes of markdown files), this can lead to significant RAM consumption. If you experience high memory usage, consider disabling the cache via the `OBSIDIAN_ENABLE_CACHE` environment variable.
- */
-export class VaultCacheService {
-    constructor(obsidianService) {
-        this.vaultContentCache = new Map();
-        this.isCacheReady = false;
-        this.isBuilding = false;
-        this.refreshIntervalId = null;
-        this.obsidianService = obsidianService;
-        logger.info("VaultCacheService initialized.", requestContextService.createRequestContext({
-            operation: "VaultCacheServiceInit",
-        }));
-    }
-    /**
-     * Starts the periodic cache refresh mechanism.
-     * The interval is controlled by the `OBSIDIAN_CACHE_REFRESH_INTERVAL_MIN` config setting.
-     */
-    startPeriodicRefresh() {
-        const refreshIntervalMs = config.obsidianCacheRefreshIntervalMin * 60 * 1000;
-        if (this.refreshIntervalId) {
-            logger.warning("Periodic refresh is already running.", requestContextService.createRequestContext({
-                operation: "startPeriodicRefresh",
-            }));
-            return;
-        }
-        this.refreshIntervalId = setInterval(() => this.refreshCache(), refreshIntervalMs);
-        logger.info(`Vault cache periodic refresh scheduled every ${config.obsidianCacheRefreshIntervalMin} minutes.`, requestContextService.createRequestContext({
-            operation: "startPeriodicRefresh",
-        }));
-    }
-    /**
-     * Stops the periodic cache refresh mechanism.
-     * Should be called during graceful shutdown.
-     */
-    stopPeriodicRefresh() {
-        const context = requestContextService.createRequestContext({
-            operation: "stopPeriodicRefresh",
-        });
-        if (this.refreshIntervalId) {
-            clearInterval(this.refreshIntervalId);
-            this.refreshIntervalId = null;
-            logger.info("Stopped periodic cache refresh.", context);
-        }
-        else {
-            logger.info("Periodic cache refresh was not running.", context);
-        }
-    }
-    /**
-     * Checks if the cache has been successfully built.
-     * @returns {boolean} True if the cache is ready, false otherwise.
-     */
-    isReady() {
-        return this.isCacheReady;
-    }
-    /**
-     * Checks if the cache is currently being built.
-     * @returns {boolean} True if the cache build is in progress, false otherwise.
-     */
-    getIsBuilding() {
-        return this.isBuilding;
-    }
-    /**
-     * Returns the entire vault content cache.
-     * Use with caution for large vaults due to potential memory usage.
-     * @returns {ReadonlyMap<string, CacheEntry>} The cache map.
-     */
-    getCache() {
-        // Return a readonly view or copy if mutation is a concern
-        return this.vaultContentCache;
-    }
-    /**
-     * Retrieves a specific entry from the cache.
-     * @param {string} filePath - The vault-relative path of the file.
-     * @returns {CacheEntry | undefined} The cache entry or undefined if not found.
-     */
-    getEntry(filePath) {
-        return this.vaultContentCache.get(filePath);
-    }
-    /**
-     * Immediately fetches the latest data for a single file and updates its entry in the cache.
-     * This is useful for ensuring cache consistency immediately after a file modification.
-     * @param {string} filePath - The vault-relative path of the file to update.
-     * @param {RequestContext} context - The request context for logging.
-     */
-    async updateCacheForFile(filePath, context) {
-        const opContext = { ...context, operation: "updateCacheForFile", filePath };
-        logger.debug(`Proactively updating cache for file: ${filePath}`, opContext);
-        try {
-            const noteJson = await retryWithDelay(() => this.obsidianService.getFileContent(filePath, "json", opContext), {
-                operationName: "proactiveCacheUpdate",
-                context: opContext,
-                maxRetries: 3,
-                delayMs: 300,
-                shouldRetry: (err) => err instanceof McpError &&
-                    (err.code === BaseErrorCode.NOT_FOUND ||
-                        err.code === BaseErrorCode.SERVICE_UNAVAILABLE),
-            });
-            if (noteJson && noteJson.content && noteJson.stat) {
-                this.vaultContentCache.set(filePath, {
-                    content: noteJson.content,
-                    mtime: noteJson.stat.mtime,
-                });
-                logger.info(`Proactively updated cache for: ${filePath}`, opContext);
-            }
-            else {
-                logger.warning(`Proactive cache update for ${filePath} received invalid data, skipping update.`, opContext);
-            }
-        }
-        catch (error) {
-            // If the file was deleted, a NOT_FOUND error is expected. We should remove it from the cache.
-            if (error instanceof McpError && error.code === BaseErrorCode.NOT_FOUND) {
-                if (this.vaultContentCache.has(filePath)) {
-                    this.vaultContentCache.delete(filePath);
-                    logger.info(`Proactively removed deleted file from cache: ${filePath}`, opContext);
-                }
-            }
-            else {
-                logger.error(`Failed to proactively update cache for ${filePath}. Error: ${error instanceof Error ? error.message : String(error)}`, opContext);
-            }
-        }
-    }
-    /**
-     * Builds the in-memory cache by fetching all markdown files and their content.
-     * This is intended to be run once at startup. Subsequent updates are handled by `refreshCache`.
-     */
-    async buildVaultCache() {
-        const initialBuildContext = requestContextService.createRequestContext({
-            operation: "buildVaultCache.initialCheck",
-        });
-        if (this.isBuilding) {
-            logger.warning("Cache build already in progress. Skipping.", initialBuildContext);
-            return;
-        }
-        if (this.isCacheReady) {
-            logger.info("Cache already built. Skipping.", initialBuildContext);
-            return;
-        }
-        await this.refreshCache(true); // Perform an initial, full build
-    }
-    /**
-     * Refreshes the cache by comparing remote file modification times with cached ones.
-     * Only fetches content for new or updated files.
-     * @param isInitialBuild - If true, forces a full build and sets the cache readiness flag.
-     */
-    async refreshCache(isInitialBuild = false) {
-        const context = requestContextService.createRequestContext({
-            operation: "refreshCache",
-            isInitialBuild,
-        });
-        if (this.isBuilding) {
-            logger.warning("Cache refresh already in progress. Skipping.", context);
-            return;
-        }
-        this.isBuilding = true;
-        if (isInitialBuild) {
-            this.isCacheReady = false;
-        }
-        logger.info("Starting vault cache refresh process...", context);
-        try {
-            const startTime = Date.now();
-            const remoteFiles = await this.listAllMarkdownFiles("/", context);
-            const remoteFileSet = new Set(remoteFiles);
-            const cachedFileSet = new Set(this.vaultContentCache.keys());
-            let filesAdded = 0;
-            let filesUpdated = 0;
-            let filesRemoved = 0;
-            // 1. Remove deleted files from cache
-            for (const cachedFile of cachedFileSet) {
-                if (!remoteFileSet.has(cachedFile)) {
-                    this.vaultContentCache.delete(cachedFile);
-                    filesRemoved++;
-                    logger.debug(`Removed deleted file from cache: ${cachedFile}`, {
-                        ...context,
-                        filePath: cachedFile,
-                    });
-                }
-            }
-            // 2. Check for new or updated files
-            for (const filePath of remoteFiles) {
-                try {
-                    const fileMetadata = await this.obsidianService.getFileMetadata(filePath, context);
-                    if (!fileMetadata) {
-                        logger.warning(`Skipping file during cache refresh due to missing or invalid metadata: ${filePath}`, { ...context, filePath });
-                        continue;
-                    }
-                    const remoteMtime = fileMetadata.mtime;
-                    const cachedEntry = this.vaultContentCache.get(filePath);
-                    if (!cachedEntry || cachedEntry.mtime < remoteMtime) {
-                        const noteJson = (await this.obsidianService.getFileContent(filePath, "json", context));
-                        this.vaultContentCache.set(filePath, {
-                            content: noteJson.content,
-                            mtime: noteJson.stat.mtime,
-                        });
-                        if (!cachedEntry) {
-                            filesAdded++;
-                            logger.debug(`Added new file to cache: ${filePath}`, {
-                                ...context,
-                                filePath,
-                            });
-                        }
-                        else {
-                            filesUpdated++;
-                            logger.debug(`Updated modified file in cache: ${filePath}`, {
-                                ...context,
-                                filePath,
-                            });
-                        }
-                    }
-                }
-                catch (error) {
-                    logger.error(`Failed to process file during cache refresh: ${filePath}. Skipping. Error: ${error instanceof Error ? error.message : String(error)}`, { ...context, filePath });
-                }
-            }
-            const duration = (Date.now() - startTime) / 1000;
-            if (isInitialBuild) {
-                this.isCacheReady = true;
-                logger.info(`Initial vault cache build completed in ${duration.toFixed(2)}s. Cached ${this.vaultContentCache.size} files.`, context);
-            }
-            else {
-                logger.info(`Vault cache refresh completed in ${duration.toFixed(2)}s. Added: ${filesAdded}, Updated: ${filesUpdated}, Removed: ${filesRemoved}. Total cached: ${this.vaultContentCache.size}.`, context);
-            }
-        }
-        catch (error) {
-            logger.error(`Critical error during vault cache refresh. Cache may be incomplete. Error: ${error instanceof Error ? error.message : String(error)}`, context);
-            if (isInitialBuild) {
-                this.isCacheReady = false;
-            }
-        }
-        finally {
-            this.isBuilding = false;
-        }
-    }
-    /**
-     * Helper to recursively list all markdown files. Similar to the one in search logic.
-     * @param dirPath - Starting directory path.
-     * @param context - Request context.
-     * @param visitedDirs - Set to track visited directories.
-     * @returns Array of file paths.
-     */
-    async listAllMarkdownFiles(dirPath, context, visitedDirs = new Set()) {
-        const operation = "listAllMarkdownFiles";
-        const opContext = { ...context, operation, dirPath };
-        const normalizedPath = path.posix.normalize(dirPath === "" ? "/" : dirPath);
-        if (visitedDirs.has(normalizedPath)) {
-            logger.warning(`Cycle detected or directory already visited during cache build: ${normalizedPath}. Skipping.`, opContext);
-            return [];
-        }
-        visitedDirs.add(normalizedPath);
-        let markdownFiles = [];
-        try {
-            const entries = await this.obsidianService.listFiles(normalizedPath, opContext);
-            for (const entry of entries) {
-                const fullPath = path.posix.join(normalizedPath, entry);
-                if (entry.endsWith("/")) {
-                    const subDirFiles = await this.listAllMarkdownFiles(fullPath, opContext, visitedDirs);
-                    markdownFiles = markdownFiles.concat(subDirFiles);
-                }
-                else if (entry.toLowerCase().endsWith(".md")) {
-                    markdownFiles.push(fullPath);
-                }
-            }
-            return markdownFiles;
-        }
-        catch (error) {
-            const errMsg = `Failed to list directory during cache build scan: ${normalizedPath}`;
-            const err = error; // Type assertion
-            if (err instanceof McpError && err.code === BaseErrorCode.NOT_FOUND) {
-                logger.warning(`${errMsg} - Directory not found, skipping.`, opContext);
-                return [];
-            }
-            // Log and re-throw critical listing errors
-            if (err instanceof Error) {
-                logger.error(errMsg, err, opContext);
-            }
-            else {
-                logger.error(errMsg, opContext);
-            }
-            const errorCode = err instanceof McpError ? err.code : BaseErrorCode.INTERNAL_ERROR;
-            throw new McpError(errorCode, `${errMsg}: ${err instanceof Error ? err.message : String(err)}`, opContext);
-        }
-    }
-}

package/dist/types-global/errors.d.ts

@@ -1,73 +0,0 @@
-import { z } from "zod";
-/**
- * Defines a set of standardized error codes for common issues within MCP servers or tools.
- * These codes help clients understand the nature of an error programmatically.
- */
-export declare enum BaseErrorCode {
-    /** Access denied due to invalid credentials or lack of authentication. */
-    UNAUTHORIZED = "UNAUTHORIZED",
-    /** Access denied despite valid authentication, due to insufficient permissions. */
-    FORBIDDEN = "FORBIDDEN",
-    /** The requested resource or entity could not be found. */
-    NOT_FOUND = "NOT_FOUND",
-    /** The request could not be completed due to a conflict with the current state of the resource. */
-    CONFLICT = "CONFLICT",
-    /** The request failed due to invalid input parameters or data. */
-    VALIDATION_ERROR = "VALIDATION_ERROR",
-    /** An error occurred while parsing input data (e.g., date string, JSON). */
-    PARSING_ERROR = "PARSING_ERROR",
-    /** The request was rejected because the client has exceeded rate limits. */
-    RATE_LIMITED = "RATE_LIMITED",
-    /** The request timed out before a response could be generated. */
-    TIMEOUT = "TIMEOUT",
-    /** The service is temporarily unavailable, possibly due to maintenance or overload. */
-    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
-    /** An unexpected error occurred on the server side. */
-    INTERNAL_ERROR = "INTERNAL_ERROR",
-    /** An error occurred, but the specific cause is unknown or cannot be categorized. */
-    UNKNOWN_ERROR = "UNKNOWN_ERROR",
-    /** An error occurred during the loading or validation of configuration data. */
-    CONFIGURATION_ERROR = "CONFIGURATION_ERROR"
-}
-/**
- * Custom error class for MCP-specific errors.
- * Encapsulates a `BaseErrorCode`, a descriptive message, and optional details.
- * Provides a method to format the error into a standard MCP tool response.
- */
-export declare class McpError extends Error {
-    code: BaseErrorCode;
-    details?: Record<string, unknown> | undefined;
-    /**
-     * Creates an instance of McpError.
-     * @param {BaseErrorCode} code - The standardized error code.
-     * @param {string} message - A human-readable description of the error.
-     * @param {Record<string, unknown>} [details] - Optional additional details about the error.
-     */
-    constructor(code: BaseErrorCode, message: string, details?: Record<string, unknown> | undefined);
-}
-/**
- * Zod schema for validating error objects, potentially used for parsing
- * error responses or validating error structures internally.
- */
-export declare const ErrorSchema: z.ZodObject<{
-    /** The error code, corresponding to BaseErrorCode enum values. */
-    code: z.ZodNativeEnum<typeof BaseErrorCode>;
-    /** A human-readable description of the error. */
-    message: z.ZodString;
-    /** Optional additional details or context about the error. */
-    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, "strip", z.ZodTypeAny, {
-    code: BaseErrorCode;
-    message: string;
-    details?: Record<string, unknown> | undefined;
-}, {
-    code: BaseErrorCode;
-    message: string;
-    details?: Record<string, unknown> | undefined;
-}>;
-/**
- * TypeScript type inferred from `ErrorSchema`.
- * Represents a validated error object structure.
- * @typedef {z.infer<typeof ErrorSchema>} ErrorResponse
- */
-export type ErrorResponse = z.infer<typeof ErrorSchema>;

package/dist/types-global/errors.js

@@ -1,71 +0,0 @@
-import { z } from "zod";
-/**
- * Defines a set of standardized error codes for common issues within MCP servers or tools.
- * These codes help clients understand the nature of an error programmatically.
- */
-export var BaseErrorCode;
-(function (BaseErrorCode) {
-    /** Access denied due to invalid credentials or lack of authentication. */
-    BaseErrorCode["UNAUTHORIZED"] = "UNAUTHORIZED";
-    /** Access denied despite valid authentication, due to insufficient permissions. */
-    BaseErrorCode["FORBIDDEN"] = "FORBIDDEN";
-    /** The requested resource or entity could not be found. */
-    BaseErrorCode["NOT_FOUND"] = "NOT_FOUND";
-    /** The request could not be completed due to a conflict with the current state of the resource. */
-    BaseErrorCode["CONFLICT"] = "CONFLICT";
-    /** The request failed due to invalid input parameters or data. */
-    BaseErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
-    /** An error occurred while parsing input data (e.g., date string, JSON). */
-    BaseErrorCode["PARSING_ERROR"] = "PARSING_ERROR";
-    /** The request was rejected because the client has exceeded rate limits. */
-    BaseErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
-    /** The request timed out before a response could be generated. */
-    BaseErrorCode["TIMEOUT"] = "TIMEOUT";
-    /** The service is temporarily unavailable, possibly due to maintenance or overload. */
-    BaseErrorCode["SERVICE_UNAVAILABLE"] = "SERVICE_UNAVAILABLE";
-    /** An unexpected error occurred on the server side. */
-    BaseErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
-    /** An error occurred, but the specific cause is unknown or cannot be categorized. */
-    BaseErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
-    /** An error occurred during the loading or validation of configuration data. */
-    BaseErrorCode["CONFIGURATION_ERROR"] = "CONFIGURATION_ERROR";
-})(BaseErrorCode || (BaseErrorCode = {}));
-/**
- * Custom error class for MCP-specific errors.
- * Encapsulates a `BaseErrorCode`, a descriptive message, and optional details.
- * Provides a method to format the error into a standard MCP tool response.
- */
-export class McpError extends Error {
-    /**
-     * Creates an instance of McpError.
-     * @param {BaseErrorCode} code - The standardized error code.
-     * @param {string} message - A human-readable description of the error.
-     * @param {Record<string, unknown>} [details] - Optional additional details about the error.
-     */
-    constructor(code, message, details) {
-        super(message);
-        this.code = code;
-        this.details = details;
-        // Set the error name for identification
-        this.name = "McpError";
-        // Ensure the prototype chain is correct
-        Object.setPrototypeOf(this, McpError.prototype);
-    }
-}
-/**
- * Zod schema for validating error objects, potentially used for parsing
- * error responses or validating error structures internally.
- */
-export const ErrorSchema = z
-    .object({
-    /** The error code, corresponding to BaseErrorCode enum values. */
-    code: z.nativeEnum(BaseErrorCode).describe("Standardized error code"),
-    /** A human-readable description of the error. */
-    message: z.string().describe("Detailed error message"),
-    /** Optional additional details or context about the error. */
-    details: z
-        .record(z.unknown())
-        .optional()
-        .describe("Optional structured error details"),
-})
-    .describe("Schema for validating structured error objects.");

package/dist/utils/index.d.ts

@@ -1,5 +0,0 @@
-export * from "./internal/index.js";
-export * from "./parsing/index.js";
-export * from "./security/index.js";
-export * from "./metrics/index.js";
-export * from "./obsidian/index.js";

package/dist/utils/index.js

@@ -1,13 +0,0 @@
-// Re-export all utilities from their categorized subdirectories
-export * from "./internal/index.js";
-export * from "./parsing/index.js";
-export * from "./security/index.js";
-export * from "./metrics/index.js";
-export * from "./obsidian/index.js"; // Added export for obsidian utils
-// It's good practice to have index.ts files in each subdirectory
-// that export the contents of that directory.
-// Assuming those will be created or already exist.
-// If not, this might need adjustment to export specific files, e.g.:
-// export * from './internal/errorHandler.js';
-// export * from './internal/logger.js';
-// ... etc.

package/dist/utils/internal/asyncUtils.d.ts

@@ -1,54 +0,0 @@
-import { RequestContext } from "./requestContext.js";
-/**
- * Configuration for the {@link retryWithDelay} function, defining how retries are handled.
- */
-export interface RetryConfig<T> {
-    /**
-     * A descriptive name for the operation being retried. Used in logging.
-     * Example: "FetchUserData", "ProcessPayment".
-     */
-    operationName: string;
-    /**
-     * The request context associated with the operation, for logging and tracing.
-     */
-    context: RequestContext;
-    /**
-     * The maximum number of retry attempts before failing.
-     */
-    maxRetries: number;
-    /**
-     * The delay in milliseconds between retry attempts.
-     */
-    delayMs: number;
-    /**
-     * An optional function to determine if a retry should be attempted based on the error.
-     * If not provided, retries will be attempted for any error.
-     * @param error - The error that occurred during the operation.
-     * @returns `true` if a retry should be attempted, `false` otherwise.
-     */
-    shouldRetry?: (error: unknown) => boolean;
-    /**
-     * An optional function to execute before each retry attempt.
-     * Useful for custom logging or cleanup actions.
-     * @param attempt - The current retry attempt number.
-     * @param error - The error that triggered the retry.
-     */
-    onRetry?: (attempt: number, error: unknown) => void;
-}
-/**
- * Executes an asynchronous operation with a configurable retry mechanism.
- * This function will attempt the operation up to `maxRetries` times, with a specified
- * `delayMs` between attempts. It allows for custom logic to decide if an error
- * warrants a retry and for actions to be taken before each retry.
- *
- * @template T The expected return type of the asynchronous operation.
- * @param {() => Promise<T>} operation - The asynchronous function to execute.
- *   This function should return a Promise resolving to type `T`.
- * @param {RetryConfig<T>} config - Configuration options for the retry behavior,
- *   including operation name, context, retry limits, delay, and custom handlers.
- * @returns {Promise<T>} A promise that resolves with the result of the operation if successful.
- * @throws {McpError} Throws an `McpError` if the operation fails after all retry attempts,
- *   or if an unexpected error occurs during the retry logic. The error will contain details
- *   about the operation name, context, and the last encountered error.
- */
-export declare function retryWithDelay<T>(operation: () => Promise<T>, config: RetryConfig<T>): Promise<T>;

package/dist/utils/internal/asyncUtils.js

@@ -1,101 +0,0 @@
-/**
- * @fileoverview Provides utilities for handling asynchronous operations,
- * such as retrying operations with delays.
- * @module src/utils/internal/asyncUtils
- */
-import { McpError, BaseErrorCode } from "../../types-global/errors.js";
-import { logger } from "./logger.js";
-/**
- * Executes an asynchronous operation with a configurable retry mechanism.
- * This function will attempt the operation up to `maxRetries` times, with a specified
- * `delayMs` between attempts. It allows for custom logic to decide if an error
- * warrants a retry and for actions to be taken before each retry.
- *
- * @template T The expected return type of the asynchronous operation.
- * @param {() => Promise<T>} operation - The asynchronous function to execute.
- *   This function should return a Promise resolving to type `T`.
- * @param {RetryConfig<T>} config - Configuration options for the retry behavior,
- *   including operation name, context, retry limits, delay, and custom handlers.
- * @returns {Promise<T>} A promise that resolves with the result of the operation if successful.
- * @throws {McpError} Throws an `McpError` if the operation fails after all retry attempts,
- *   or if an unexpected error occurs during the retry logic. The error will contain details
- *   about the operation name, context, and the last encountered error.
- */
-export async function retryWithDelay(operation, config) {
-    const { operationName, context, maxRetries, delayMs, shouldRetry = () => true, // Default: retry on any error
-    onRetry, } = config;
-    let lastError;
-    for (let attempt = 1; attempt <= maxRetries; attempt++) {
-        try {
-            return await operation();
-        }
-        catch (error) {
-            lastError = error;
-            // Ensure the context for logging includes attempt details
-            const retryAttemptContext = {
-                ...context, // Spread existing context
-                operation: operationName, // Ensure operationName is part of the context for logger
-                attempt,
-                maxRetries,
-                lastError: error instanceof Error ? error.message : String(error),
-            };
-            if (attempt < maxRetries && shouldRetry(error)) {
-                if (onRetry) {
-                    onRetry(attempt, error); // Custom onRetry logic
-                }
-                else {
-                    // Default logging for retry attempt
-                    logger.warning(`Operation '${operationName}' failed on attempt ${attempt} of ${maxRetries}. Retrying in ${delayMs}ms...`, retryAttemptContext);
-                }
-                await new Promise((resolve) => setTimeout(resolve, delayMs));
-            }
-            else {
-                // Max retries reached or shouldRetry returned false
-                const finalErrorMsg = `Operation '${operationName}' failed definitively after ${attempt} attempt(s).`;
-                // Log the final failure with the enriched context
-                logger.error(finalErrorMsg, error instanceof Error ? error : undefined, retryAttemptContext);
-                if (error instanceof McpError) {
-                    // If the last error was already an McpError, re-throw it but ensure its details are preserved/updated.
-                    error.details = {
-                        ...(typeof error.details === "object" && error.details !== null
-                            ? error.details
-                            : {}),
-                        ...retryAttemptContext, // Add retry context to existing details
-                        finalAttempt: true,
-                    };
-                    throw error;
-                }
-                // For other errors, wrap in a new McpError
-                throw new McpError(BaseErrorCode.SERVICE_UNAVAILABLE, // Default to SERVICE_UNAVAILABLE, consider making this configurable or smarter
-                `${finalErrorMsg} Last error: ${error instanceof Error ? error.message : String(error)}`, {
-                    ...retryAttemptContext, // Include all retry context
-                    originalErrorName: error instanceof Error ? error.name : typeof error,
-                    originalErrorStack: error instanceof Error ? error.stack : undefined,
-                    finalAttempt: true,
-                });
-            }
-        }
-    }
-    // Fallback: This part should ideally not be reached if the loop logic is correct.
-    // If it is, it implies an issue with the loop or maxRetries logic.
-    const fallbackErrorContext = {
-        ...context,
-        operation: operationName,
-        maxRetries,
-        reason: "Fallback_Error_Path_Reached_In_Retry_Logic",
-    };
-    logger.crit(
-    // Log as critical because this path indicates a logic flaw
-    `Operation '${operationName}' failed unexpectedly after all retries (fallback path). This may indicate a logic error in retryWithDelay.`, lastError instanceof Error ? lastError : undefined, fallbackErrorContext);
-    throw new McpError(BaseErrorCode.INTERNAL_ERROR, // Indicates an issue with the retry utility itself
-    `Operation '${operationName}' failed unexpectedly after all retries (fallback path). Last error: ${lastError instanceof Error ? lastError.message : String(lastError)}`, {
-        ...fallbackErrorContext,
-        originalError: lastError instanceof Error
-            ? {
-                message: lastError.message,
-                name: lastError.name,
-                stack: lastError.stack,
-            }
-            : String(lastError),
-    });
-}