add graceful shutdown, indexing mutex, structured logging, and error recovery hints

peteretelej · peteretelej · commit 78cb1b5a3bc6 · 2026-03-15T00:09:35.000+03:00
Adds SIGTERM/SIGINT handlers to close SQLite connections cleanly, per-directory
indexing mutex to prevent concurrent indexing of the same path, structured
JSON logging to stderr, MCP logging capability for client notifications, and
descriptive error messages with recovery guidance.
diff --git a/src/logger.ts b/src/logger.ts
@@ -0,0 +1,59 @@
+export type LogLevel = 'debug' | 'info' | 'warning' | 'error';
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warning: 2,
+  error: 3,
+};
+
+let currentLevel: LogLevel = 'info';
+
+/**
+ * Set the minimum log level. Messages below this level are discarded.
+ */
+export function setLogLevel(level: LogLevel): void {
+  currentLevel = level;
+}
+
+/**
+ * Get the current log level.
+ */
+export function getLogLevel(): LogLevel {
+  return currentLevel;
+}
+
+/**
+ * Initialize the log level from the LOG_LEVEL environment variable.
+ * Invalid values default to 'info' with a warning on stderr.
+ */
+export function initLogLevel(): void {
+  const envLevel = process.env.LOG_LEVEL?.toLowerCase();
+  if (!envLevel) return;
+
+  if (envLevel in LEVEL_ORDER) {
+    currentLevel = envLevel as LogLevel;
+  } else {
+    process.stderr.write(
+      `Warning: invalid LOG_LEVEL "${process.env.LOG_LEVEL}", defaulting to "info"\n`
+    );
+    currentLevel = 'info';
+  }
+}
+
+/**
+ * Write a structured JSON log line to stderr.
+ * Never writes to stdout (reserved for the MCP protocol channel).
+ */
+export function log(level: LogLevel, message: string, data?: Record<string, unknown>): void {
+  if (LEVEL_ORDER[level] < LEVEL_ORDER[currentLevel]) return;
+
+  const entry: Record<string, unknown> = {
+    timestamp: new Date().toISOString(),
+    level,
+    message,
+    ...data,
+  };
+
+  process.stderr.write(JSON.stringify(entry) + '\n');
+}
diff --git a/src/mcp-handlers.ts b/src/mcp-handlers.ts
@@ -4,7 +4,23 @@ import { searchContent, findSimilarFiles, getFileContent, getChunkContent } from
 import { getIndexStatus, SQLiteStorage, initializeStorage } from './storage.js';
 import { validateIndexPrerequisites, validateSearchPrerequisites } from './prerequisites.js';
 import { validatePathWithinIndexedDirs, resolveIndexedDirectories } from './path-validation.js';
+import { log } from './logger.js';
 import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+// MCP server reference for sending client-visible log notifications
+let mcpServer: Server | null = null;
+
+/**
+ * Set the MCP server reference for logging notifications.
+ * Called from startMcpServer() after server creation.
+ */
+export function setMcpServer(server: Server): void {
+  mcpServer = server;
+}
+
+// Workspace-level indexing mutex: keyed by normalized directory path
+const indexingMutex = new Map<string, Promise<void>>();
 
 // Cached set of resolved indexed directory paths for path validation
 let indexedDirsCache: Set<string> = new Set();
@@ -94,34 +110,71 @@ export async function handleIndexTool(args: unknown, config: Config): Promise<Ca
   await validateIndexPrerequisites(config);
 
   const paths = args.directory_paths.map((p: string) => p.trim());
-  const result = await indexDirectories(paths, config);
 
-  // Refresh the indexed directories cache after successful indexing
-  const { sqlite } = await initializeStorage(config);
+  log('info', 'Index start', { directories: paths });
+  mcpServer?.sendLoggingMessage({ level: 'info', data: { event: 'index_start', directories: paths } });
+
+  // Per-directory mutex: serialize concurrent calls targeting the same directory
+  for (const dirPath of paths) {
+    const existing = indexingMutex.get(dirPath);
+    if (existing) {
+      log('info', 'Waiting for ongoing indexing', { directory: dirPath });
+      await existing;
+    }
+  }
+
+  // Create a deferred promise for this indexing operation
+  let resolveIndexing: () => void;
+  const indexingPromise = new Promise<void>((resolve) => { resolveIndexing = resolve; });
+  for (const dirPath of paths) {
+    indexingMutex.set(dirPath, indexingPromise);
+  }
+
   try {
-    refreshIndexedDirsCache(sqlite);
+    const result = await indexDirectories(paths, config);
+
+    // Refresh the indexed directories cache after successful indexing
+    const { sqlite } = await initializeStorage(config);
+    try {
+      refreshIndexedDirsCache(sqlite);
+    } finally {
+      sqlite.close();
+    }
+
+    log('info', 'Index complete', { result });
+    mcpServer?.sendLoggingMessage({ level: 'info', data: { event: 'index_complete', result } });
+
+    let responseText = `Indexed ${result.indexed} files, skipped ${result.skipped} files, cleaned up ${result.deleted} deleted files, ${result.failed} failed`;
+
+    if (result.errors.length > 0) {
+      responseText += `\nErrors: [\n`;
+      result.errors.forEach(error => {
+        responseText += `  '${error}'\n`;
+      });
+      responseText += `]`;
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: responseText
+        }
+      ]
+    };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    log('error', 'Index error', { error: errorMessage, directories: paths });
+    mcpServer?.sendLoggingMessage({ level: 'error', data: { event: 'index_error', error: errorMessage } });
+    throw new Error(
+      `Indexing failed for ${paths.join(', ')}. Verify the directory exists and is readable. Use 'server_info' to check current status.`
+    );
   } finally {
-    sqlite.close();
-  }
-  
-  let responseText = `Indexed ${result.indexed} files, skipped ${result.skipped} files, cleaned up ${result.deleted} deleted files, ${result.failed} failed`;
-  
-  if (result.errors.length > 0) {
-    responseText += `\nErrors: [\n`;
-    result.errors.forEach(error => {
-      responseText += `  '${error}'\n`;
-    });
-    responseText += `]`;
+    resolveIndexing!();
+    for (const dirPath of paths) {
+      indexingMutex.delete(dirPath);
+    }
   }
-  
-  return {
-    content: [
-      {
-        type: 'text',
-        text: responseText
-      }
-    ]
-  };
 }
 
 async function validateWorkspace(workspace?: string): Promise<{ workspace?: string; message?: string }> {
@@ -195,16 +248,26 @@ export async function handleGetContentTool(args: unknown, config?: Config): Prom
   await ensureIndexedDirsCache(resolvedConfig);
   validatePathWithinIndexedDirs(args.file_path, indexedDirsCache);
 
-  const content = await getFileContent(args.file_path, args.chunks);
-  
-  return {
-    content: [
-      {
-        type: 'text',
-        text: content
-      }
-    ]
-  };
+  try {
+    const content = await getFileContent(args.file_path, args.chunks);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: content
+        }
+      ]
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (msg.includes('ENOENT') || msg.toLowerCase().includes('not found') || msg.toLowerCase().includes('no such file')) {
+      throw new Error(
+        `File not found: ${args.file_path}. The file may have been moved or deleted. Use 'search' to find similar content.`
+      );
+    }
+    throw error;
+  }
 }
 
 export async function handleGetChunkTool(args: unknown, config?: Config): Promise<CallToolResult> {
@@ -217,16 +280,26 @@ export async function handleGetChunkTool(args: unknown, config?: Config): Promis
   await ensureIndexedDirsCache(resolvedConfig);
   validatePathWithinIndexedDirs(args.file_path, indexedDirsCache);
 
-  const content = await getChunkContent(args.file_path, args.chunk_id);
-  
-  return {
-    content: [
-      {
-        type: 'text',
-        text: content
-      }
-    ]
-  };
+  try {
+    const content = await getChunkContent(args.file_path, args.chunk_id);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: content
+        }
+      ]
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (msg.includes('ENOENT') || msg.toLowerCase().includes('not found') || msg.toLowerCase().includes('no such file')) {
+      throw new Error(
+        `File not found: ${args.file_path}. The file may have been moved or deleted. Use 'search' to find similar content.`
+      );
+    }
+    throw error;
+  }
 }
 
 export async function handleServerInfoTool(version: string): Promise<CallToolResult> {
@@ -248,6 +321,7 @@ export async function handleServerInfoTool(version: string): Promise<CallToolRes
 
 export function formatErrorResponse(error: unknown): CallToolResult {
   const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+  log('error', 'Tool error', { error: errorMessage });
   return {
     content: [
       {
diff --git a/src/mcp.ts b/src/mcp.ts
@@ -9,14 +9,17 @@ import { readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { Config } from './config.js';
-import { 
-  handleIndexTool, 
-  handleSearchTool, 
-  handleSimilarFilesTool, 
-  handleGetContentTool, 
-  handleGetChunkTool, 
+import { closeAllStorage } from './storage.js';
+import { initLogLevel, log } from './logger.js';
+import {
+  handleIndexTool,
+  handleSearchTool,
+  handleSimilarFilesTool,
+  handleGetContentTool,
+  handleGetChunkTool,
   handleServerInfoTool,
-  formatErrorResponse
+  formatErrorResponse,
+  setMcpServer
 } from './mcp-handlers.js';
 
 // Read version from package.json
@@ -296,18 +299,23 @@ Returns server version, indexing statistics, directory list, workspace informati
 ];
 
 export async function startMcpServer(config: Config): Promise<void> {
+  initLogLevel();
+
   const server = new Server(
     {
       name: 'directory-indexer',
       version: VERSION
     },
     {
       capabilities: {
-        tools: {}
+        tools: {},
+        logging: {}
       }
     }
   );
 
+  setMcpServer(server);
+
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
       tools: MCP_TOOLS
@@ -347,8 +355,19 @@ export async function startMcpServer(config: Config): Promise<void> {
 
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  
+
+  // Graceful shutdown: close all SQLite connections before exiting
+  const cleanup = () => {
+    log('info', 'Shutting down MCP server');
+    closeAllStorage();
+    process.exit(0);
+  };
+  process.on('SIGTERM', cleanup);
+  process.on('SIGINT', cleanup);
+
   if (config.verbose) {
     console.error('MCP server started successfully');
   }
+
+  log('info', 'MCP server started', { version: VERSION });
 }
diff --git a/src/storage.ts b/src/storage.ts
@@ -3,6 +3,22 @@ import { Config } from './config.js';
 import { FileInfo, ChunkInfo, ensureDirectory } from './utils.js';
 import { dirname } from 'path';
 
+// Registry of all open SQLiteStorage instances for graceful shutdown
+const openStorageInstances = new Set<SQLiteStorage>();
+
+/**
+ * Close all open SQLiteStorage instances. Called during graceful shutdown.
+ */
+export function closeAllStorage(): void {
+  for (const instance of openStorageInstances) {
+    try {
+      instance.close();
+    } catch {
+      // Ignore errors during shutdown cleanup
+    }
+  }
+}
+
 export interface DirectoryRecord {
   id: number;
   path: string;
@@ -291,6 +307,7 @@ export class SQLiteStorage {
 
   constructor(private config: Config) {
     this.db = this.initializeDatabase();
+    openStorageInstances.add(this);
   }
 
   private initializeDatabase(): Database.Database {
@@ -441,6 +458,7 @@ export class SQLiteStorage {
   }
 
   close(): void {
+    openStorageInstances.delete(this);
     this.db.close();
   }
 }
diff --git a/tests/mcp-handlers.test.ts b/tests/mcp-handlers.test.ts
diff --git a/tests/path-validation.unit.test.ts b/tests/path-validation.unit.test.ts
