obsidian-mcp-server 1.5.8 → 2.0.2

package/dist/config/index.js

@@ -0,0 +1,191 @@
+import dotenv from "dotenv";
+import { existsSync, mkdirSync, readFileSync, statSync } from "fs";
+import path, { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { z } from "zod";
+dotenv.config();
+// --- Determine Project Root ---
+/**
+ * Finds the project root directory by searching upwards for package.json.
+ * @param startDir The directory to start searching from.
+ * @returns The absolute path to the project root, or throws an error if not found.
+ */
+const findProjectRoot = (startDir) => {
+    let currentDir = startDir;
+    while (true) {
+        const packageJsonPath = join(currentDir, "package.json");
+        if (existsSync(packageJsonPath)) {
+            return currentDir;
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            // Reached the root of the filesystem without finding package.json
+            throw new Error(`Could not find project root (package.json) starting from ${startDir}`);
+        }
+        currentDir = parentDir;
+    }
+};
+let projectRoot;
+try {
+    // For ESM, __dirname is not available directly.
+    const currentModuleDir = dirname(fileURLToPath(import.meta.url));
+    projectRoot = findProjectRoot(currentModuleDir);
+}
+catch (error) {
+    console.error(`FATAL: Error determining project root: ${error.message}`);
+    projectRoot = process.cwd();
+    console.warn(`Warning: Using process.cwd() (${projectRoot}) as fallback project root.`);
+}
+// --- End Determine Project Root ---
+const pkgPath = join(projectRoot, "package.json");
+let pkg = { name: "obsidian-mcp-server", version: "0.0.0" };
+try {
+    pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+}
+catch (error) {
+    if (process.stderr.isTTY) {
+        console.error("Warning: Could not read package.json for default config values. Using hardcoded defaults.", error);
+    }
+}
+/**
+ * Zod schema for validating environment variables.
+ * @private
+ */
+const EnvSchema = z.object({
+    MCP_SERVER_NAME: z.string().optional(),
+    MCP_SERVER_VERSION: z.string().optional(),
+    MCP_LOG_LEVEL: z.string().default("info"),
+    LOGS_DIR: z.string().default(path.join(projectRoot, "logs")),
+    NODE_ENV: z.string().default("development"),
+    MCP_TRANSPORT_TYPE: z.enum(["stdio", "http"]).default("stdio"),
+    MCP_HTTP_PORT: z.coerce.number().int().positive().default(3010),
+    MCP_HTTP_HOST: z.string().default("127.0.0.1"),
+    MCP_ALLOWED_ORIGINS: z.string().optional(),
+    MCP_AUTH_MODE: z.enum(["jwt", "oauth"]).optional(),
+    MCP_AUTH_SECRET_KEY: z
+        .string()
+        .min(32, "MCP_AUTH_SECRET_KEY must be at least 32 characters long for security")
+        .optional(),
+    OAUTH_ISSUER_URL: z.string().url().optional(),
+    OAUTH_AUDIENCE: z.string().optional(),
+    OAUTH_JWKS_URI: z.string().url().optional(),
+    // --- Obsidian Specific Config ---
+    OBSIDIAN_API_KEY: z.string().min(1, "OBSIDIAN_API_KEY cannot be empty"),
+    OBSIDIAN_BASE_URL: z.string().url().default("http://127.0.0.1:27123"),
+    OBSIDIAN_VERIFY_SSL: z
+        .string()
+        .transform((val) => val.toLowerCase() === "true")
+        .default("false"),
+    OBSIDIAN_CACHE_REFRESH_INTERVAL_MIN: z.coerce
+        .number()
+        .int()
+        .positive()
+        .default(10),
+    OBSIDIAN_ENABLE_CACHE: z
+        .string()
+        .transform((val) => val.toLowerCase() === "true")
+        .default("true"),
+    OBSIDIAN_API_SEARCH_TIMEOUT_MS: z.coerce
+        .number()
+        .int()
+        .positive()
+        .default(30000),
+});
+const parsedEnv = EnvSchema.safeParse(process.env);
+if (!parsedEnv.success) {
+    const errorDetails = parsedEnv.error.flatten().fieldErrors;
+    if (process.stderr.isTTY) {
+        console.error("❌ Invalid environment variables:", errorDetails);
+    }
+    throw new Error(`Invalid environment configuration. Please check your .env file or environment variables. Details: ${JSON.stringify(errorDetails)}`);
+}
+const env = parsedEnv.data;
+// --- Directory Ensurance Function ---
+const ensureDirectory = (dirPath, rootDir, dirName) => {
+    const resolvedDirPath = path.isAbsolute(dirPath)
+        ? dirPath
+        : path.resolve(rootDir, dirPath);
+    if (!resolvedDirPath.startsWith(rootDir + path.sep) &&
+        resolvedDirPath !== rootDir) {
+        if (process.stderr.isTTY) {
+            console.error(`Error: ${dirName} path "${dirPath}" resolves to "${resolvedDirPath}", which is outside the project boundary "${rootDir}".`);
+        }
+        return null;
+    }
+    if (!existsSync(resolvedDirPath)) {
+        try {
+            mkdirSync(resolvedDirPath, { recursive: true });
+        }
+        catch (err) {
+            if (process.stderr.isTTY) {
+                console.error(`Error creating ${dirName} directory at ${resolvedDirPath}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return null;
+        }
+    }
+    else {
+        try {
+            if (!statSync(resolvedDirPath).isDirectory()) {
+                if (process.stderr.isTTY) {
+                    console.error(`Error: ${dirName} path ${resolvedDirPath} exists but is not a directory.`);
+                }
+                return null;
+            }
+        }
+        catch (statError) {
+            if (process.stderr.isTTY) {
+                console.error(`Error accessing ${dirName} path ${resolvedDirPath}: ${statError.message}`);
+            }
+            return null;
+        }
+    }
+    return resolvedDirPath;
+};
+// --- End Directory Ensurance Function ---
+const validatedLogsPath = ensureDirectory(env.LOGS_DIR, projectRoot, "logs");
+if (!validatedLogsPath) {
+    if (process.stderr.isTTY) {
+        console.error("FATAL: Logs directory configuration is invalid or could not be created. Please check permissions and path. Exiting.");
+    }
+    process.exit(1);
+}
+/**
+ * Main application configuration object.
+ */
+export const config = {
+    pkg,
+    mcpServerName: env.MCP_SERVER_NAME || pkg.name,
+    mcpServerVersion: env.MCP_SERVER_VERSION || pkg.version,
+    logLevel: env.MCP_LOG_LEVEL,
+    logsPath: validatedLogsPath,
+    environment: env.NODE_ENV,
+    mcpTransportType: env.MCP_TRANSPORT_TYPE,
+    mcpHttpPort: env.MCP_HTTP_PORT,
+    mcpHttpHost: env.MCP_HTTP_HOST,
+    mcpAllowedOrigins: env.MCP_ALLOWED_ORIGINS?.split(",")
+        .map((origin) => origin.trim())
+        .filter(Boolean),
+    mcpAuthMode: env.MCP_AUTH_MODE,
+    mcpAuthSecretKey: env.MCP_AUTH_SECRET_KEY,
+    oauthIssuerUrl: env.OAUTH_ISSUER_URL,
+    oauthAudience: env.OAUTH_AUDIENCE,
+    oauthJwksUri: env.OAUTH_JWKS_URI,
+    obsidianApiKey: env.OBSIDIAN_API_KEY,
+    obsidianBaseUrl: env.OBSIDIAN_BASE_URL,
+    obsidianVerifySsl: env.OBSIDIAN_VERIFY_SSL,
+    obsidianCacheRefreshIntervalMin: env.OBSIDIAN_CACHE_REFRESH_INTERVAL_MIN,
+    obsidianEnableCache: env.OBSIDIAN_ENABLE_CACHE,
+    obsidianApiSearchTimeoutMs: env.OBSIDIAN_API_SEARCH_TIMEOUT_MS,
+};
+/**
+ * The configured logging level for the application.
+ * Exported separately for convenience (e.g., logger initialization).
+ * @type {string}
+ */
+export const logLevel = config.logLevel;
+/**
+ * The configured runtime environment for the application.
+ * Exported separately for convenience.
+ * @type {string}
+ */
+export const environment = config.environment;

package/dist/index.d.ts

@@ -1,6 +1,2 @@
 #!/usr/bin/env node
-export { run } from "./mcp/server.js";
-export * from "./obsidian/index.js";
-export * from "./resources/index.js";
-export * from "./tools/index.js";
-export * from "./utils/index.js";
+export {};

package/dist/index.js

@@ -1,20 +1,298 @@
 #!/usr/bin/env node
-import { run } from "./mcp/server.js";
-import { createLogger } from "./utils/logging.js";
-// Create a logger for the main entry point
-const logger = createLogger('Main');
-// Main entry point
-if (import.meta.url === `file://${process.argv[1]}`) {
-    logger.info("Starting Obsidian MCP Server");
-    run().catch((error) => {
-        logger.error("Failed to start server:", error);
-        process.exit(1);
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { config, environment } from "./config/index.js"; // This loads .env via dotenv.config()
+import { initializeAndStartServer } from "./mcp-server/server.js";
+import { requestContextService, retryWithDelay } from "./utils/index.js";
+import { logger } from "./utils/internal/logger.js"; // Import logger instance early
+// Import Services
+import { ObsidianRestApiService } from "./services/obsidianRestAPI/index.js";
+import { VaultCacheService } from "./services/obsidianRestAPI/vaultCache/index.js"; // Import VaultCacheService
+/**
+ * The main MCP server instance (only stored globally for stdio shutdown).
+ * @type {McpServer | undefined}
+ */
+let server;
+/**
+ * The main HTTP server instance (only stored globally for http shutdown).
+ * @type {ServerType | undefined}
+ */
+let httpServerInstance;
+/**
+ * Shared Obsidian REST API service instance.
+ * @type {ObsidianRestApiService | undefined}
+ */
+let obsidianService;
+/**
+ * Shared Vault Cache service instance.
+ * @type {VaultCacheService | undefined}
+ */
+let vaultCacheService;
+/**
+ * Gracefully shuts down the main MCP server.
+ * Handles process termination signals (SIGTERM, SIGINT) and critical errors.
+ *
+ * @param signal - The signal or event name that triggered the shutdown (e.g., "SIGTERM", "uncaughtException").
+ */
+const shutdown = async (signal) => {
+    // Define context for the shutdown operation
+    const shutdownContext = requestContextService.createRequestContext({
+        operation: "Shutdown",
+        signal,
+    });
+    logger.info(`Received ${signal}. Starting graceful shutdown...`, shutdownContext);
+    try {
+        // Stop cache refresh timer first
+        if (config.obsidianEnableCache && vaultCacheService) {
+            vaultCacheService.stopPeriodicRefresh();
+        }
+        // Close the main MCP server (only relevant for stdio)
+        if (server) {
+            logger.info("Closing main MCP server (stdio)...", shutdownContext);
+            await server.close();
+            logger.info("Main MCP server (stdio) closed successfully", shutdownContext);
+        }
+        // Close the main HTTP server instance (if it exists)
+        if (httpServerInstance) {
+            logger.info("Closing main HTTP server...", shutdownContext);
+            await new Promise((resolve, reject) => {
+                httpServerInstance.close((err) => {
+                    if (err) {
+                        logger.error("Error closing HTTP server", err, shutdownContext);
+                        reject(err);
+                        return;
+                    }
+                    logger.info("Main HTTP server closed successfully", shutdownContext);
+                    resolve();
+                });
+            });
+        }
+        if (!server && !httpServerInstance) {
+            logger.warning("No server instance (Stdio or HTTP) found to close during shutdown.", shutdownContext);
+        }
+        // Add any other necessary cleanup here (e.g., closing database connections if added later)
+        logger.info("Graceful shutdown completed successfully", shutdownContext);
+        process.exit(0);
+    }
+    catch (error) {
+        // Handle any errors during shutdown
+        logger.error("Critical error during shutdown", error instanceof Error ? error : undefined, {
+            ...shutdownContext, // Spread the existing RequestContext
+            // error field is handled by logger.error's second argument
+        });
+        process.exit(1); // Exit with error code if shutdown fails
+    }
+};
+/**
+ * Initializes and starts the main MCP server.
+ * Sets up request context, initializes the server instance, starts the transport,
+ * and registers signal handlers for graceful shutdown and error handling.
+ */
+const start = async () => {
+    // --- Logger Initialization (Moved here AFTER config/dotenv is loaded) ---
+    const validMcpLogLevels = [
+        "debug",
+        "info",
+        "notice",
+        "warning",
+        "error",
+        "crit",
+        "alert",
+        "emerg",
+    ];
+    // Read level from config (which read from env var or default)
+    const initialLogLevelConfig = config.logLevel;
+    // Validate the configured log level
+    let validatedMcpLogLevel = "info"; // Default to 'info'
+    if (validMcpLogLevels.includes(initialLogLevelConfig)) {
+        validatedMcpLogLevel = initialLogLevelConfig;
+    }
+    else {
+        // Use console.warn here as logger isn't initialized yet
+        console.warn(`Invalid MCP_LOG_LEVEL "${initialLogLevelConfig}" provided via config/env. Defaulting to "info".`);
+    }
+    // Initialize the logger with the validated MCP level and wait for it to complete.
+    await logger.initialize(validatedMcpLogLevel);
+    // Log initialization message using the logger itself (will go to file/console)
+    logger.info(`Logger initialized by start(). MCP logging level: ${validatedMcpLogLevel}`);
+    // --- End Logger Initialization ---
+    // Log that config is loaded (this was previously done earlier)
+    logger.debug("Configuration loaded successfully", requestContextService.createRequestContext({
+        configLoaded: true,
+        configSummary: {
+            serverName: config.mcpServerName,
+            transport: config.mcpTransportType,
+            logLevel: config.logLevel,
+        },
+    }));
+    // Create application-level request context using the service instance
+    // Use the validated transport type from the config object
+    const transportType = config.mcpTransportType;
+    const startupContext = requestContextService.createRequestContext({
+        operation: `ServerStartup_${transportType}`, // Include transport in operation name
+        appName: config.mcpServerName,
+        appVersion: config.mcpServerVersion,
+        environment: environment,
     });
-}
-// Export the run function and other important modules
-export { run } from "./mcp/server.js";
-export * from "./obsidian/index.js";
-export * from "./resources/index.js";
-export * from "./tools/index.js";
-export * from "./utils/index.js";
-//# sourceMappingURL=index.js.map
+    logger.info(`Starting ${config.mcpServerName} v${config.mcpServerVersion} (Transport: ${transportType})...`, startupContext);
+    try {
+        // --- Instantiate Shared Services ---
+        logger.debug("Instantiating shared services...", startupContext);
+        obsidianService = new ObsidianRestApiService(); // Instantiate Obsidian Service
+        // --- Perform Initial Obsidian API Status Check ---
+        try {
+            logger.info("Performing initial Obsidian API status check with retries...", startupContext);
+            const status = await retryWithDelay(async () => {
+                if (!obsidianService) {
+                    // This case should not happen in practice, but it satisfies the type checker.
+                    throw new Error("Obsidian service not initialized.");
+                }
+                const checkStatusContext = {
+                    ...startupContext,
+                    operation: "checkStatusAttempt",
+                };
+                const currentStatus = await obsidianService.checkStatus(checkStatusContext);
+                if (currentStatus?.service !== "Obsidian Local REST API" ||
+                    !currentStatus?.authenticated) {
+                    // Throw an error to trigger a retry
+                    throw new Error(`Obsidian API status check failed or indicates authentication issue. Status: ${JSON.stringify(currentStatus)}`);
+                }
+                return currentStatus;
+            }, {
+                operationName: "initialObsidianApiCheck",
+                context: startupContext,
+                maxRetries: 5, // Retry up to 5 times
+                delayMs: 3000, // Wait 3 seconds between retries
+            });
+            logger.info("Obsidian API status check successful.", {
+                ...startupContext,
+                obsidianVersion: status.versions.obsidian,
+                pluginVersion: status.versions.self,
+            });
+        }
+        catch (statusError) {
+            logger.error("Critical error during initial Obsidian API status check after multiple retries. Check OBSIDIAN_BASE_URL, OBSIDIAN_API_KEY, and plugin status.", {
+                ...startupContext,
+                error: statusError instanceof Error
+                    ? statusError.message
+                    : String(statusError),
+                stack: statusError instanceof Error ? statusError.stack : undefined,
+            });
+            // Re-throw the final error to be caught by the main startup catch block, which will exit the process.
+            throw statusError;
+        }
+        // --- End Status Check ---
+        if (config.obsidianEnableCache) {
+            vaultCacheService = new VaultCacheService(obsidianService); // Instantiate Cache Service, passing Obsidian Service
+            logger.info("Vault cache is enabled and service is instantiated.", startupContext);
+        }
+        else {
+            logger.info("Vault cache is disabled by configuration.", startupContext);
+        }
+        logger.info("Shared services instantiated.", startupContext);
+        // --- End Service Instantiation ---
+        // Initialize the server instance and start the selected transport
+        logger.debug("Initializing and starting MCP server transport", startupContext);
+        // Start the server transport. Services are instantiated here and passed down.
+        // For stdio, this returns the McpServer instance.
+        // For http, it returns the http.Server instance.
+        const serverOrHttpInstance = await initializeAndStartServer(obsidianService, vaultCacheService);
+        if (transportType === "stdio" &&
+            serverOrHttpInstance instanceof McpServer) {
+            server = serverOrHttpInstance; // Store McpServer for stdio
+            logger.debug("Stored McpServer instance for stdio transport.", startupContext);
+        }
+        else if (transportType === "http" && serverOrHttpInstance) {
+            // The instance is of ServerType (http.Server or https.Server)
+            httpServerInstance = serverOrHttpInstance; // Store ServerType for http transport
+            logger.debug("Stored http.Server instance for http transport.", startupContext);
+        }
+        else if (transportType === "http") {
+            // This case should ideally not be reached if startHttpTransport always returns an http.Server
+            logger.warning("HTTP transport selected, but initializeAndStartServer did not return an http.Server instance.", startupContext);
+        }
+        // If initializeAndStartServer failed, it would have thrown an error,
+        // and execution would jump to the outer catch block.
+        logger.info(`${config.mcpServerName} is running with ${transportType} transport`, {
+            ...startupContext,
+            startTime: new Date().toISOString(),
+        });
+        // --- Trigger Background Cache Build ---
+        if (config.obsidianEnableCache && vaultCacheService) {
+            // Start building the cache, but don't wait for it to finish.
+            // The server will be operational while the cache builds.
+            // Tools needing the cache should check its readiness state.
+            logger.info("Triggering background vault cache build...", startupContext);
+            // No 'await' here - run in background
+            vaultCacheService
+                .buildVaultCache()
+                .then(() => {
+                // Once the initial build is done, start the periodic refresh
+                vaultCacheService?.startPeriodicRefresh();
+            })
+                .catch((cacheBuildError) => {
+                // Log errors during the background build process
+                logger.error("Error occurred during background vault cache build", {
+                    ...startupContext, // Use startup context for correlation
+                    operation: "BackgroundCacheBuild",
+                    error: cacheBuildError instanceof Error
+                        ? cacheBuildError.message
+                        : String(cacheBuildError),
+                    stack: cacheBuildError instanceof Error
+                        ? cacheBuildError.stack
+                        : undefined,
+                });
+            });
+        }
+        // --- End Cache Build Trigger ---
+        // --- Signal and Error Handling Setup ---
+        // Handle process signals for graceful shutdown
+        process.on("SIGTERM", () => shutdown("SIGTERM"));
+        process.on("SIGINT", () => shutdown("SIGINT"));
+        // Handle uncaught exceptions
+        process.on("uncaughtException", async (error) => {
+            const errorContext = {
+                ...startupContext, // Include base context for correlation
+                event: "uncaughtException",
+                error: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack : undefined,
+            };
+            logger.error("Uncaught exception detected. Initiating shutdown...", errorContext);
+            // Attempt graceful shutdown; shutdown() handles its own errors.
+            await shutdown("uncaughtException");
+            // If shutdown fails internally, it will call process.exit(1).
+            // If shutdown succeeds, it calls process.exit(0).
+            // If shutdown itself throws unexpectedly *before* exiting, this process might terminate abruptly,
+            // but the core shutdown logic is handled within shutdown().
+        });
+        // Handle unhandled promise rejections
+        process.on("unhandledRejection", async (reason) => {
+            const rejectionContext = {
+                ...startupContext, // Include base context for correlation
+                event: "unhandledRejection",
+                reason: reason instanceof Error ? reason.message : String(reason),
+                stack: reason instanceof Error ? reason.stack : undefined,
+            };
+            logger.error("Unhandled promise rejection detected. Initiating shutdown...", rejectionContext);
+            // Attempt graceful shutdown; shutdown() handles its own errors.
+            await shutdown("unhandledRejection");
+            // Similar logic as uncaughtException: shutdown handles its exit codes.
+        });
+    }
+    catch (error) {
+        // Handle critical startup errors (already logged by ErrorHandler or caught above)
+        // Log the final failure context, including error details, before exiting
+        logger.error("Critical error during startup, exiting.", {
+            ...startupContext,
+            finalErrorContext: "Startup Failure",
+            error: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined,
+        });
+        process.exit(1);
+    }
+};
+// --- Async IIFE to allow top-level await ---
+// This remains necessary because start() is async
+(async () => {
+    // Start the application
+    await start();
+})(); // End async IIFE

package/dist/mcp-server/server.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Main entry point for the MCP (Model Context Protocol) server.
+ * This file orchestrates the server's lifecycle:
+ * 1. Initializes the core `McpServer` instance (from `@modelcontextprotocol/sdk`) with its identity and capabilities.
+ * 2. Registers available resources and tools, making them discoverable and usable by clients.
+ * 3. Selects and starts the appropriate communication transport (stdio or Streamable HTTP)
+ *    based on configuration.
+ * 4. Handles top-level error management during startup.
+ *
+ * MCP Specification References:
+ * - Lifecycle: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/lifecycle.mdx
+ * - Overview (Capabilities): https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/index.mdx
+ * - Transports: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx
+ * @module src/mcp-server/server
+ */
+import { ServerType } from "@hono/node-server";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ObsidianRestApiService } from "../services/obsidianRestAPI/index.js";
+import { VaultCacheService } from "../services/obsidianRestAPI/vaultCache/index.js";
+/**
+ * Main application entry point. Initializes services and starts the MCP server.
+ * Orchestrates server startup, transport selection, and top-level error handling.
+ *
+ * MCP Spec Relevance:
+ * - Manages server startup, leading to a server ready for MCP messages.
+ * - Handles critical startup failures, ensuring appropriate process exit.
+ *
+ * @param {ObsidianRestApiService} obsidianService - The shared Obsidian REST API service instance, instantiated by the caller (e.g., index.ts).
+ * @param {VaultCacheService | undefined} vaultCacheService - The shared Vault Cache service instance, instantiated by the caller (e.g., index.ts).
+ * @returns {Promise<void | McpServer>} For 'stdio', resolves with `McpServer`. For 'http', runs indefinitely.
+ *   Rejects on critical failure, leading to process exit.
+ */
+export declare function initializeAndStartServer(obsidianService: ObsidianRestApiService, vaultCacheService: VaultCacheService | undefined): Promise<void | McpServer | ServerType>;