@mrxkun/mcfast-mcp 4.1.11 → 4.1.13

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mrxkun/mcfast-mcp",
-  "version": "4.1.11",
-  "description": "Ultra-fast code editing with WASM acceleration, fuzzy patching, multi-layer caching, and 8 unified tools. v4.1.11: Suppress console output to prevent JSON-RPC stream corruption.",
+  "version": "4.1.13",
+  "description": "Ultra-fast code editing with WASM acceleration, fuzzy patching, multi-layer caching, and 8 unified tools. v4.1.12: Implement proper MCP stdio transport lifecycle and cleanup to prevent zombie processes.",
   "type": "module",
   "bin": {
     "mcfast-mcp": "src/index.js"

package/src/index.js

@@ -25,13 +25,13 @@ const colors = {
 
 // Override console.log - suppress in MCP mode
 const originalConsoleLog = console.log;
-console.log = function(...args) {
+console.log = function (...args) {
     // Suppressed in MCP mode
 };
 
 // Override console.error - suppress in MCP mode  
 const originalConsoleError = console.error;
-console.error = function(...args) {
+console.error = function (...args) {
     // Suppressed in MCP mode
 };
 
@@ -86,70 +86,70 @@ const LOCK_FILE_PATH = path.join(process.cwd(), '.mcfast', '.mcp-instance.lock')
 let lockFileHandle = null;
 
 async function acquireLock() {
-  try {
-    const lockDir = path.dirname(LOCK_FILE_PATH);
-    await fs.mkdir(lockDir, { recursive: true });
-    
-    lockFileHandle = await fs.open(LOCK_FILE_PATH, 'wx');
-    
-    // Write current PID
-    await lockFileHandle.write(`${process.pid}\n${Date.now()}\n`, 0);
-    await lockFileHandle.sync();
-    
-    // Cleanup on exit
-    process.on('beforeExit', releaseLock);
-    process.on('SIGINT', releaseLock);
-    process.on('SIGTERM', releaseLock);
-    process.on('uncaughtException', releaseLock);
-    
-    console.error(`${colors.cyan}[Lock]${colors.reset} Acquired lock file: ${LOCK_FILE_PATH}`);
-    return true;
-  } catch (error) {
-    if (error.code === 'EEXIST') {
-      // Lock file exists, check if it's stale
-      try {
-        const lockContent = await fs.readFile(LOCK_FILE_PATH, 'utf-8');
-        const [pid, timestamp] = lockContent.trim().split('\n');
-        const lockAge = Date.now() - parseInt(timestamp);
-        
-        // Check if process is still running (stale lock if > 5 minutes)
-        if (lockAge > 5 * 60 * 1000) {
-          console.error(`${colors.yellow}[Lock]${colors.reset} Stale lock detected (age: ${Math.round(lockAge / 1000)}s), removing...`);
-          await fs.unlink(LOCK_FILE_PATH);
-          return acquireLock(); // Retry
-        }
-        
-        console.error(`${colors.red}[Lock]${colors.reset} Another instance is already running (PID: ${pid})`);
-        console.error(`${colors.yellow}[Lock]${colors.reset} To force start, delete: ${LOCK_FILE_PATH}`);
-        return false;
-      } catch (readError) {
-        console.error(`${colors.red}[Lock]${colors.reset} Failed to read lock file: ${readError.message}`);
+    try {
+        const lockDir = path.dirname(LOCK_FILE_PATH);
+        await fs.mkdir(lockDir, { recursive: true });
+
+        lockFileHandle = await fs.open(LOCK_FILE_PATH, 'wx');
+
+        // Write current PID
+        await lockFileHandle.write(`${process.pid}\n${Date.now()}\n`, 0);
+        await lockFileHandle.sync();
+
+        // Cleanup on exit
+        process.on('beforeExit', releaseLock);
+        process.on('SIGINT', releaseLock);
+        process.on('SIGTERM', releaseLock);
+        process.on('uncaughtException', releaseLock);
+
+        console.error(`${colors.cyan}[Lock]${colors.reset} Acquired lock file: ${LOCK_FILE_PATH}`);
+        return true;
+    } catch (error) {
+        if (error.code === 'EEXIST') {
+            // Lock file exists, check if it's stale
+            try {
+                const lockContent = await fs.readFile(LOCK_FILE_PATH, 'utf-8');
+                const [pid, timestamp] = lockContent.trim().split('\n');
+                const lockAge = Date.now() - parseInt(timestamp);
+
+                // Check if process is still running (stale lock if > 5 minutes)
+                if (lockAge > 5 * 60 * 1000) {
+                    console.error(`${colors.yellow}[Lock]${colors.reset} Stale lock detected (age: ${Math.round(lockAge / 1000)}s), removing...`);
+                    await fs.unlink(LOCK_FILE_PATH);
+                    return acquireLock(); // Retry
+                }
+
+                console.error(`${colors.red}[Lock]${colors.reset} Another instance is already running (PID: ${pid})`);
+                console.error(`${colors.yellow}[Lock]${colors.reset} To force start, delete: ${LOCK_FILE_PATH}`);
+                return false;
+            } catch (readError) {
+                console.error(`${colors.red}[Lock]${colors.reset} Failed to read lock file: ${readError.message}`);
+                return false;
+            }
+        }
+        console.error(`${colors.red}[Lock]${colors.reset} Failed to acquire lock: ${error.message}`);
         return false;
-      }
     }
-    console.error(`${colors.red}[Lock]${colors.reset} Failed to acquire lock: ${error.message}`);
-    return false;
-  }
 }
 
 async function releaseLock() {
-  if (lockFileHandle) {
+    if (lockFileHandle) {
+        try {
+            await lockFileHandle.close();
+            lockFileHandle = null;
+        } catch (e) {
+            // Ignore close errors
+        }
+    }
+
     try {
-      await lockFileHandle.close();
-      lockFileHandle = null;
-    } catch (e) {
-      // Ignore close errors
-    }
-  }
-  
-  try {
-    await fs.unlink(LOCK_FILE_PATH);
-    console.error(`${colors.cyan}[Lock]${colors.reset} Released lock file`);
-  } catch (error) {
-    if (error.code !== 'ENOENT') {
-      console.error(`${colors.yellow}[Lock]${colors.reset} Failed to release lock: ${error.message}`);
-    }
-  }
+        await fs.unlink(LOCK_FILE_PATH);
+        console.error(`${colors.cyan}[Lock]${colors.reset} Released lock file`);
+    } catch (error) {
+        if (error.code !== 'ENOENT') {
+            console.error(`${colors.yellow}[Lock]${colors.reset} Failed to release lock: ${error.message}`);
+        }
+    }
 }
 
 // ============================================================================
@@ -171,36 +171,36 @@ let memoryEngineReady = false;
  */
 async function backgroundInitializeMemoryEngine() {
     if (memoryEngineInitPromise) return memoryEngineInitPromise;
-    
+
     memoryEngineInitPromise = (async () => {
         const maxRetries = 2;
         let lastError = null;
-        
+
         for (let attempt = 1; attempt <= maxRetries; attempt++) {
             try {
                 memoryEngine = new MemoryEngine({
                     apiKey: TOKEN,
                     enableSync: true
                 });
-                
+
                 // Use timeout for initialization
                 const initTimeout = new Promise((_, reject) => {
                     setTimeout(() => reject(new Error('Memory engine init timeout')), 25000);
                 });
-                
+
                 await Promise.race([
                     memoryEngine.initialize(process.cwd()),
                     initTimeout
                 ]);
-                
+
                 memoryEngineReady = true;
                 console.error(`${colors.cyan}[Memory]${colors.reset} Engine initialized successfully`);
                 return memoryEngine;
-                
+
             } catch (error) {
                 lastError = error;
                 console.error(`${colors.yellow}[Memory]${colors.reset} Initialization attempt ${attempt}/${maxRetries} failed: ${error.message}`);
-                
+
                 if (attempt < maxRetries) {
                     // Exponential backoff before retry
                     const backoffMs = 1000 * Math.pow(2, attempt - 1);
@@ -209,7 +209,7 @@ async function backgroundInitializeMemoryEngine() {
                 }
             }
         }
-        
+
         // All retries failed - graceful degradation
         console.error(`${colors.yellow}[Memory]${colors.reset} All initialization attempts failed. Running in degraded mode.`);
         console.error(`${colors.yellow}[Memory]${colors.reset} Error: ${lastError?.message || 'Unknown error'}`);
@@ -217,7 +217,7 @@ async function backgroundInitializeMemoryEngine() {
         memoryEngineReady = false;
         return null;
     })();
-    
+
     return memoryEngineInitPromise;
 }
 
@@ -228,7 +228,7 @@ async function getMemoryEngine() {
     if (memoryEngine && memoryEngineReady) {
         return memoryEngine;
     }
-    
+
     // Wait for initialization with timeout
     if (memoryEngineInitPromise) {
         try {
@@ -240,12 +240,12 @@ async function getMemoryEngine() {
             console.error(`${colors.yellow}[Memory]${colors.reset} Waiting for engine: ${error.message}`);
         }
     }
-    
+
     // If still not ready, try to initialize now
     if (!memoryEngine) {
         await backgroundInitializeMemoryEngine();
     }
-    
+
     return memoryEngine;
 }
 
@@ -255,18 +255,18 @@ async function getMemoryEngine() {
 async function searchMemoryContext(instruction, maxResults = 5) {
     try {
         const engine = await getMemoryEngine();
-        
+
         // Use intelligent search for best context
-        const searchResult = await engine.intelligentSearch(instruction, { 
-            limit: maxResults 
+        const searchResult = await engine.intelligentSearch(instruction, {
+            limit: maxResults
         });
-        
+
         if (!searchResult.results || searchResult.results.length === 0) {
             return '';
         }
 
         let context = '';
-        
+
         // Add code context from search results
         context += '\n\n--- MEMORY CONTEXT (Relevant Code) ---\n';
         searchResult.results.forEach((result, idx) => {
@@ -277,7 +277,7 @@ async function searchMemoryContext(instruction, maxResults = 5) {
                 context += `${result.code.substring(0, 300)}${result.code.length > 300 ? '...' : ''}\n`;
             }
         });
-        
+
         // Add facts if available
         const facts = await engine.searchFacts(instruction, 5);
         if (facts && facts.length > 0) {
@@ -286,7 +286,7 @@ async function searchMemoryContext(instruction, maxResults = 5) {
                 context += `• ${fact.type}: ${fact.name} (${fact.file_id})\n`;
             });
         }
-        
+
         return context;
     } catch (error) {
         console.error(`${colors.yellow}[Memory]${colors.reset} Context search failed: ${error.message}`);
@@ -304,44 +304,44 @@ async function autoTriggerIntelligence(filePath, instruction) {
         if (process.env.MCFAST_INTELLIGENCE_AUTO !== 'true') {
             return;
         }
-        
+
         const engine = await getMemoryEngine();
         const cache = getIntelligenceCache();
-        
+
         // 1. Detect patterns (cached for 5 minutes)
         const patternCacheKey = { file: filePath, type: 'patterns' };
         let patterns = cache.get('patterns', patternCacheKey);
-        
+
         if (!patterns) {
             patterns = await engine.detectPatterns();
             if (patterns && patterns.length > 0) {
                 cache.set('patterns', patternCacheKey, patterns);
                 console.error(`${colors.cyan}[Intelligence]${colors.reset} 💡 Detected ${patterns.length} patterns`);
-                
+
                 // Log high-confidence patterns
                 patterns.filter(p => p.confidence > 0.8).forEach(p => {
                     console.error(`${colors.yellow}[Pattern]${colors.reset} ${p.type}: ${p.message}`);
                 });
             }
         }
-        
+
         // 2. Get suggestions (cached for 5 minutes)
         const suggestionCacheKey = { file: filePath, type: 'suggestions' };
         let suggestions = cache.get('suggestions', suggestionCacheKey);
-        
+
         if (!suggestions) {
             suggestions = await engine.getSuggestions({ currentFile: filePath });
             if (suggestions && suggestions.length > 0) {
                 cache.set('suggestions', suggestionCacheKey, suggestions);
                 console.error(`${colors.cyan}[Intelligence]${colors.reset} 💡 ${suggestions.length} suggestions available`);
-                
+
                 // Show top suggestions
                 suggestions.slice(0, 3).forEach(s => {
                     console.error(`${colors.yellow}[Suggestion]${colors.reset} ${s.type}: ${s.message}`);
                 });
             }
         }
-        
+
     } catch (error) {
         // Silent fail - intelligence should not break the tool
         if (VERBOSE) {
@@ -357,7 +357,7 @@ async function logEditToMemory({ instruction, files, strategy, success, errorMes
     try {
         const engine = await getMemoryEngine();
         const diffSize = Object.keys(files).reduce((total, fp) => total + (files[fp]?.length || 0), 0);
-        
+
         engine.logEditToMemory({
             instruction: instruction.substring(0, 500),
             files: Object.keys(files),
@@ -367,7 +367,7 @@ async function logEditToMemory({ instruction, files, strategy, success, errorMes
             durationMs,
             errorMessage
         });
-        
+
         console.error(`${colors.cyan}[Memory]${colors.reset} Edit logged to history`);
     } catch (error) {
         console.error(`${colors.yellow}[Memory]${colors.reset} Log failed: ${error.message}`);
@@ -380,13 +380,13 @@ async function logEditToMemory({ instruction, files, strategy, success, errorMes
 async function analyzeRenameImpact(symbolName, currentFile = null) {
     try {
         const engine = await getMemoryEngine();
-        
+
         // Search for symbol references across codebase
-        const searchResult = await engine.intelligentSearch(symbolName, { 
+        const searchResult = await engine.intelligentSearch(symbolName, {
             limit: 20,
             currentFile
         });
-        
+
         const impactedFiles = new Set();
         const references = [];
 
@@ -757,6 +757,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     },
                     required: []
                 }
+            },
+            // HEALTH CHECK TOOL
+            {
+                name: "health_check",
+                description: "💚 Check MCP server health status and resource usage. Returns: process status, memory engine state, uptime, and system metrics.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: []
+                }
             }
         ],
     };
@@ -964,6 +974,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             result = await projectAnalyzeExecute(args);
             summary = 'Project analyzed';
         }
+        // HEALTH CHECK TOOL
+        else if (name === "health_check") {
+            result = await handleHealthCheck();
+            summary = 'Health check completed';
+        }
         else {
             throw new Error(`Tool not found: ${name}`);
         }
@@ -1041,9 +1056,9 @@ async function reportAudit(data) {
             flushInterval: 5000,
             verbose: VERBOSE
         });
-        
+
         queue.add(auditData);
-        
+
         if (VERBOSE) {
             const stats = queue.getStats();
             console.error(`${colors.dim}[Audit] Queued for batching. Queue size: ${stats.queued}${colors.reset}`);
@@ -1082,9 +1097,9 @@ async function handleRegexSearch({ query, path: searchPath, caseSensitive = fals
         if (!validation.valid) {
             const latency = Date.now() - start;
             return {
-                content: [{ 
-                    type: "text", 
-                    text: `⚠️  Invalid regex pattern: ${validation.error}\n\nQuery: "${query}"\n\n💡 Tips:\n• Basic regex works: \\bword\\b, [a-z]+, (foo|bar)\n• Avoid lookbehind (?<=...) and lookahead (?=...) - not supported by grep\n• Use word boundaries \\b instead of lookarounds\n• Escape special chars: \\\\, \\+, \\*` 
+                content: [{
+                    type: "text",
+                    text: `⚠️  Invalid regex pattern: ${validation.error}\n\nQuery: "${query}"\n\n💡 Tips:\n• Basic regex works: \\bword\\b, [a-z]+, (foo|bar)\n• Avoid lookbehind (?<=...) and lookahead (?=...) - not supported by grep\n• Use word boundaries \\b instead of lookarounds\n• Escape special chars: \\\\, \\+, \\*`
                 }],
                 isError: true
             };
@@ -1120,12 +1135,12 @@ async function handleRegexSearch({ query, path: searchPath, caseSensitive = fals
 
         try {
             const { stdout, stderr } = await execAsync(command, { maxBuffer: 10 * 1024 * 1024 }); // 10MB buffer
-            
+
             // Check for grep regex errors in stderr
             if (stderr && stderr.includes('Invalid regular expression')) {
                 throw new Error(`grep: ${stderr}`);
             }
-            
+
             const results = stdout.trim().split('\n').filter(Boolean);
 
             const latency = Date.now() - start;
@@ -1190,12 +1205,12 @@ async function handleRegexSearch({ query, path: searchPath, caseSensitive = fals
                     content: [{ type: "text", text: `🔍 Regex Search: No matches found for "${query}" in ${searchPath} (${latency}ms)` }]
                 };
             }
-            
+
             // Handle regex syntax errors
             if (execErr.stderr && execErr.stderr.includes('Invalid')) {
                 throw new Error(`Invalid regex syntax: ${execErr.stderr}. Try simplifying your pattern.`);
             }
-            
+
             throw execErr;
         }
     } catch (error) {
@@ -1222,14 +1237,14 @@ async function handleRegexSearch({ query, path: searchPath, caseSensitive = fals
  */
 function validateRegex(pattern) {
     const warnings = [];
-    
+
     try {
         // Test if it's valid JavaScript regex
         new RegExp(pattern);
     } catch (e) {
         return { valid: false, error: e.message, warnings };
     }
-    
+
     // Check for patterns not supported by basic grep (PCRE-only features)
     const unsupportedPatterns = [
         { regex: /\(\?<[=!]/, name: 'Lookbehind (?<=...) or negative lookbehind (?<!...)' },
@@ -1241,18 +1256,18 @@ function validateRegex(pattern) {
         { regex: /\(\?\d*\)/, name: 'Subroutine calls (?1)' },
         { regex: /\(\?&\w+\)/, name: 'Subroutine calls (?&name)' }
     ];
-    
+
     for (const { regex, name } of unsupportedPatterns) {
         if (regex.test(pattern)) {
             warnings.push(`Pattern uses ${name} which may not be supported by grep. Results may be incomplete.`);
         }
     }
-    
+
     // Check for potentially dangerous patterns (catastrophic backtracking)
     if (/\(\w+\+\+?\)|\(\w+\*\*?\)\*\*?/.test(pattern)) {
         warnings.push('Pattern may cause performance issues (nested quantifiers)');
     }
-    
+
     return { valid: true, warnings };
 }
 
@@ -1282,7 +1297,7 @@ async function handleSearchFilesystem({ query, path: searchPath, isRegex = false
             // Convert literal query to glob pattern for file search
             pattern = `**/*${query}*`;
         }
-        
+
         // Use fast-glob to find files
         const files = await fg([pattern], {
             cwd,
@@ -1294,7 +1309,7 @@ async function handleSearchFilesystem({ query, path: searchPath, isRegex = false
 
         // Also search file contents if it's not a file pattern
         const contentMatches = [];
-        
+
         // For simple queries, also search in common code files
         if (!isRegex && query.length > 1) {
             const codeFiles = await fg(['**/*.{js,ts,jsx,tsx,py,go,rs,java,rb,php}'], {
@@ -1302,7 +1317,7 @@ async function handleSearchFilesystem({ query, path: searchPath, isRegex = false
                 ignore: ['node_modules/**', '.git/**'],
                 absolute: false
             });
-            
+
             // Search in first 50 files to avoid performance issues
             for (const file of codeFiles.slice(0, 50)) {
                 try {
@@ -1310,7 +1325,7 @@ async function handleSearchFilesystem({ query, path: searchPath, isRegex = false
                     if (content.includes(query)) {
                         const lines = content.split('\n');
                         const matches = [];
-                        
+
                         lines.forEach((line, idx) => {
                             if (line.includes(query)) {
                                 matches.push({
@@ -1320,7 +1335,7 @@ async function handleSearchFilesystem({ query, path: searchPath, isRegex = false
                                 });
                             }
                         });
-                        
+
                         if (matches.length > 0) {
                             contentMatches.push({
                                 file,
@@ -1335,7 +1350,7 @@ async function handleSearchFilesystem({ query, path: searchPath, isRegex = false
         }
 
         const latency = Date.now() - start;
-        
+
         // Format output
         let output = `${colors.bold}Filesystem Search Results${colors.reset}\n\n`;
         output += `Query: "${query}"\n`;
@@ -1381,7 +1396,7 @@ async function handleSearchFilesystem({ query, path: searchPath, isRegex = false
         };
     } catch (error) {
         const latency = Date.now() - start;
-        
+
         reportAudit({
             tool: 'search_filesystem',
             instruction: `Search: ${query}`,
@@ -1441,7 +1456,7 @@ async function handleReapply({ instruction, files, errorContext = "", attempt =
  */
 async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
     const editStartTime = Date.now();
-    
+
     // Validate required parameters
     if (!instruction) {
         return {
@@ -1449,16 +1464,16 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
             isError: true
         };
     }
-    
+
     if (!files || Object.keys(files).length === 0) {
         return {
             content: [{ type: "text", text: "❌ Error: 'files' parameter is required and must contain at least one file" }],
             isError: true
         };
     }
-    
+
     const firstFile = Object.keys(files)[0];
-    
+
     // 1. Retrieve memory context for enhanced understanding
     let memoryContext = '';
     try {
@@ -1469,7 +1484,7 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
     } catch (error) {
         console.error(`${colors.yellow}[Memory]${colors.reset} Context retrieval failed: ${error.message}`);
     }
-    
+
     // 2. Analyze impact for rename operations
     let impactAnalysis = null;
     const renamePattern = instruction.match(/(?:rename|change)\s+(?:function|class|const|let|var|method)\s+(\w+)\s+to\s+(\w+)/i);
@@ -1484,7 +1499,7 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
             console.error(`${colors.yellow}[IMPACT]${colors.reset} Analysis failed: ${error.message}`);
         }
     }
-    
+
     // Check for multi-file edits first
     const multiFileEdit = detectCrossFileEdit(instruction, files);
 
@@ -1518,7 +1533,7 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
                     errorMessage: result.message || result.error,
                     durationMs: Date.now() - editStartTime
                 });
-                
+
                 return {
                     content: [{
                         type: "text",
@@ -1556,7 +1571,7 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
                 errorMessage: error.message,
                 durationMs: Date.now() - editStartTime
             });
-            
+
             return {
                 content: [{
                     type: "text",
@@ -1661,7 +1676,7 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
                 errorMessage: error.message,
                 durationMs: Date.now() - editStartTime
             });
-            
+
             return {
                 content: [{
                     type: "text",
@@ -1792,7 +1807,7 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
 
             // Include impact analysis in result if available
             let resultText = `✅ AST Refactor Applied Successfully\n\nOperation: ${pattern.type}\nChanges: ${transformResult.count || transformResult.replacements || 0} locations\n\nBackup: ${editResult.backupPath}`;
-            
+
             if (impactAnalysis && impactAnalysis.suggestion) {
                 resultText += `\n\n${impactAnalysis.suggestion}`;
                 if (impactAnalysis.impactedFiles.length > 0) {
@@ -1823,7 +1838,7 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
                 errorMessage: error.message,
                 durationMs: Date.now() - editStartTime
             });
-            
+
             return {
                 content: [{
                     type: "text",
@@ -1846,7 +1861,7 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
                 dryRun,
                 toolName: 'edit'
             });
-            
+
             // Log to memory
             await logEditToMemory({
                 instruction,
@@ -1856,7 +1871,7 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
                 errorMessage: result.isError ? result.content?.[0]?.text : null,
                 durationMs: Date.now() - editStartTime
             });
-            
+
             return result;
         }
     }
@@ -1869,7 +1884,7 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
             dryRun,
             toolName: 'edit'
         });
-        
+
         // Log to memory
         await logEditToMemory({
             instruction,
@@ -1879,7 +1894,7 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
             errorMessage: result.isError ? result.content?.[0]?.text : null,
             durationMs: Date.now() - editStartTime
         });
-        
+
         return result;
     }
 
@@ -1889,14 +1904,14 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
     if (memoryContext) {
         enhancedInstruction = `${instruction}\n\n--- CONTEXT FROM CODEBASE ---${memoryContext}`;
     }
-    
+
     const result = await handleApplyFast({
         instruction: enhancedInstruction,
         files,
         dryRun,
         toolName: 'edit'
     });
-    
+
     // Log to memory
     await logEditToMemory({
         instruction,
@@ -1906,13 +1921,13 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
         errorMessage: result.isError ? result.content?.[0]?.text : null,
         durationMs: Date.now() - editStartTime
     });
-    
+
     // Auto-trigger intelligence tools in background (non-blocking)
     if (!result.isError) {
         const firstFile = Object.keys(files)[0];
-        autoTriggerIntelligence(firstFile, instruction).catch(() => {});
+        autoTriggerIntelligence(firstFile, instruction).catch(() => { });
     }
-    
+
     return result;
 }
 
@@ -1924,7 +1939,7 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
  */
 async function handleSearch({ query, files, path, mode = 'auto', regex = false, caseSensitive = false, contextLines = 2, maxResults = 10 }) {
     const searchStartTime = Date.now();
-    
+
     // For regex mode without files, we need to do content-based regex search
     // since fast-glob doesn't support full regex patterns
     if (regex && !files && mode === 'auto') {
@@ -1939,9 +1954,9 @@ async function handleSearch({ query, files, path, mode = 'auto', regex = false,
     if ((detectedMode === 'auto' || detectedMode === 'local') && !regex) {
         try {
             const engine = await getMemoryEngine();
-            
+
             // Use intelligent search (UltraHybrid + Smart Routing)
-            const searchResult = await engine.intelligentSearch(query, { 
+            const searchResult = await engine.intelligentSearch(query, {
                 limit: maxResults,
                 currentFile: files ? Object.keys(files)[0] : null
             });
@@ -2017,7 +2032,7 @@ async function handleRead({ filePath, filePaths, start_line, end_line, max_lines
     if (filePaths && Array.isArray(filePaths) && filePaths.length > 0) {
         return await handleBatchRead(filePaths, start_line, end_line, max_lines_per_file);
     }
-    
+
     // Single file mode (backward compatible)
     return await handleReadFile({ path: filePath, start_line, end_line });
 }
@@ -2028,50 +2043,50 @@ async function handleRead({ filePath, filePaths, start_line, end_line, max_lines
 async function handleBatchRead(filePaths, start_line, end_line, max_lines_per_file) {
     const start = Date.now();
     const MAX_BATCH_SIZE = 50;
-    
+
     if (filePaths.length > MAX_BATCH_SIZE) {
         return {
             content: [{ type: "text", text: `❌ Batch read limit exceeded: ${filePaths.length} files (max ${MAX_BATCH_SIZE})` }],
             isError: true
         };
     }
-    
+
     console.error(`${colors.cyan}[BATCH READ]${colors.reset} ${filePaths.length} files`);
-    
+
     // Read all files in parallel with Promise.all
     const results = await Promise.all(
         filePaths.map(async (filePath) => {
             try {
-                const result = await handleReadFileInternal({ 
-                    path: filePath, 
-                    start_line, 
+                const result = await handleReadFileInternal({
+                    path: filePath,
+                    start_line,
                     end_line,
-                    max_lines: max_lines_per_file 
+                    max_lines: max_lines_per_file
                 });
                 return { path: filePath, ...result, success: true };
             } catch (error) {
-                return { 
-                    path: filePath, 
-                    success: false, 
+                return {
+                    path: filePath,
+                    success: false,
                     error: error.message,
                     content: `❌ Error reading ${filePath}: ${error.message}`
                 };
             }
         })
     );
-    
+
     // Calculate stats
     const successful = results.filter(r => r.success).length;
     const failed = results.filter(r => !r.success).length;
     const totalLines = results.reduce((sum, r) => sum + (r.lines || 0), 0);
     const totalSize = results.reduce((sum, r) => sum + (r.size || 0), 0);
-    
+
     // Format output
     let output = `📚 Batch Read Complete (${filePaths.length} files)\n`;
     output += `✅ Successful: ${successful}  ❌ Failed: ${failed}\n`;
     output += `📊 Total: ${totalLines} lines, ${(totalSize / 1024).toFixed(1)} KB\n`;
     output += `⏱️ Latency: ${Date.now() - start}ms\n\n`;
-    
+
     // Add each file's content
     results.forEach((result, index) => {
         output += `[${index + 1}/${filePaths.length}] `;
@@ -2090,7 +2105,7 @@ async function handleBatchRead(filePaths, start_line, end_line, max_lines_per_fi
         }
         output += `\n\n`;
     });
-    
+
     // Report audit for batch operation
     reportAudit({
         tool: 'read_file',
@@ -2101,7 +2116,7 @@ async function handleBatchRead(filePaths, start_line, end_line, max_lines_per_fi
         input_tokens: Math.ceil(filePaths.join(',').length / 4),
         output_tokens: Math.ceil(output.length / 4)
     });
-    
+
     return {
         content: [{ type: "text", text: output }]
     };
@@ -2119,7 +2134,7 @@ async function handleReadFileInternal({ path: filePath, start_line, end_line, ma
     }
 
     const STREAM_THRESHOLD = 1024 * 1024; // 1MB
-    
+
     let startLine = start_line ? parseInt(start_line) : 1;
     let endLine = end_line ? parseInt(end_line) : -1;
     let outputContent;
@@ -2247,12 +2262,12 @@ async function handleWarpgrep({ query, include = ".", isRegex = false, caseSensi
                 });
                 return { content: [{ type: "text", text: msg }] };
             }
-            
+
             // Handle regex syntax errors
             if (execErr.stderr && execErr.stderr.includes('Invalid')) {
                 throw new Error(`Invalid regex syntax: ${execErr.stderr}. Try simplifying your pattern.`);
             }
-            
+
             throw execErr;
         }
     } catch (error) {
@@ -3078,18 +3093,18 @@ async function handleMemorySearch({ query, type = 'all', maxResults = 6, minScor
  */
 async function handleMemoryGet({ type }) {
     const start = Date.now();
-    
+
     // Early return if memory engine not ready
     if (!memoryEngineReady) {
         return {
-            content: [{ 
-                type: "text", 
-                text: `⏳ Memory engine is still initializing. Please try again in a few seconds.` 
+            content: [{
+                type: "text",
+                text: `⏳ Memory engine is still initializing. Please try again in a few seconds.`
             }],
             isError: true
         };
     }
-    
+
     try {
         const engine = await getMemoryEngine();
         let output = '';
@@ -3123,12 +3138,12 @@ async function handleMemoryGet({ type }) {
         } else if (type === 'reindex') {
             output = `🔄 Re-indexing Codebase\n\n`;
             output += `Starting re-index in background...\n`;
-            
+
             // Trigger re-index in background
             engine.performInitialScan().catch(err => {
                 console.error('[Reindex] Error:', err.message);
             });
-            
+
             output += `✅ Re-index started. Check stats in a few seconds.\n`;
             output += `Use 'memory_get stats' to check progress.`;
         } else if (type === 'intelligence') {
@@ -3176,18 +3191,18 @@ async function handleMemoryGet({ type }) {
  */
 async function handleDetectPatterns() {
     const start = Date.now();
-    
+
     // Early return if memory engine not ready
     if (!memoryEngineReady) {
         return {
-            content: [{ 
-                type: "text", 
-                text: `⏳ Memory engine is still initializing. Please try again in a few seconds.` 
+            content: [{
+                type: "text",
+                text: `⏳ Memory engine is still initializing. Please try again in a few seconds.`
             }],
             isError: true
         };
     }
-    
+
     try {
         const engine = await getMemoryEngine();
         const patterns = await engine.detectPatterns();
@@ -3235,18 +3250,18 @@ async function handleDetectPatterns() {
  */
 async function handleGetSuggestions({ currentFile, currentLine }) {
     const start = Date.now();
-    
+
     // Early return if memory engine not ready
     if (!memoryEngineReady) {
         return {
-            content: [{ 
-                type: "text", 
-                text: `⏳ Memory engine is still initializing. Please try again in a few seconds.` 
+            content: [{
+                type: "text",
+                text: `⏳ Memory engine is still initializing. Please try again in a few seconds.`
             }],
             isError: true
         };
     }
-    
+
     try {
         const engine = await getMemoryEngine();
         const suggestions = await engine.getSuggestions({
@@ -3300,18 +3315,18 @@ async function handleGetSuggestions({ currentFile, currentLine }) {
  */
 async function handleSelectStrategy({ instruction, files = [] }) {
     const start = Date.now();
-    
+
     // Early return if memory engine not ready
     if (!memoryEngineReady) {
         return {
-            content: [{ 
-                type: "text", 
-                text: `⏳ Memory engine is still initializing. Please try again in a few seconds.` 
+            content: [{
+                type: "text",
+                text: `⏳ Memory engine is still initializing. Please try again in a few seconds.`
             }],
             isError: true
         };
     }
-    
+
     try {
         const engine = await getMemoryEngine();
         const result = await engine.selectStrategy(instruction, { files });
@@ -3352,6 +3367,74 @@ async function handleSelectStrategy({ instruction, files = [] }) {
     }
 }
 
+/**
+ * HEALTH CHECK HANDLER
+ */
+async function handleHealthCheck() {
+    const start = Date.now();
+
+    try {
+        const memoryStats = memoryEngine ? await memoryEngine.getStats() : null;
+        const watcherStats = memoryEngine?.watcher ? memoryEngine.watcher.getStats() : null;
+
+        const health = {
+            status: 'healthy',
+            timestamp: Date.now(),
+            pid: process.pid,
+            uptime: process.uptime(),
+            memoryUsage: {
+                rss: Math.round(process.memoryUsage().rss / 1024 / 1024) + ' MB',
+                heapTotal: Math.round(process.memoryUsage().heapTotal / 1024 / 1024) + ' MB',
+                heapUsed: Math.round(process.memoryUsage().heapUsed / 1024 / 1024) + ' MB',
+                external: Math.round(process.memoryUsage().external / 1024 / 1024) + ' MB'
+            },
+            memoryEngine: {
+                ready: memoryEngineReady,
+                initialized: memoryEngine?.isInitialized || false,
+                stats: memoryStats
+            },
+            fileWatcher: watcherStats || {
+                enabled: process.env.MCFAST_FILE_WATCHER !== 'false',
+                status: 'not_running'
+            },
+            latencyMs: Date.now() - start
+        };
+
+        reportAudit({
+            tool: 'health_check',
+            status: 'success',
+            latency_ms: health.latencyMs
+        });
+
+        return {
+            content: [{
+                type: 'text',
+                text: JSON.stringify(health, null, 2)
+            }]
+        };
+
+    } catch (error) {
+        reportAudit({
+            tool: 'health_check',
+            status: 'error',
+            error_message: error.message,
+            latency_ms: Date.now() - start
+        });
+
+        return {
+            content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    status: 'error',
+                    error: error.message,
+                    timestamp: Date.now()
+                })
+            }],
+            isError: true
+        };
+    }
+}
+
 /**
  * Start Server
  */
@@ -3359,13 +3442,28 @@ async function handleSelectStrategy({ instruction, files = [] }) {
 // Acquire lock before starting - prevents multiple instances
 const lockAcquired = await acquireLock();
 if (!lockAcquired) {
-  console.error(`${colors.red}[ERROR]${colors.reset} Failed to acquire lock. Another mcfast-mcp instance may be running.`);
-  console.error(`${colors.yellow}[HINT]${colors.reset} Delete ${LOCK_FILE_PATH} if you're sure no other instance is running.`);
-  process.exit(1);
+    console.error(`${colors.red}[ERROR]${colors.reset} Failed to acquire lock. Another mcfast-mcp instance may be running.`);
+    console.error(`${colors.yellow}[HINT]${colors.reset} Delete ${LOCK_FILE_PATH} if you're sure no other instance is running.`);
+    process.exit(1);
 }
 
 const transport = new StdioServerTransport();
 
+// NOTE: Do NOT add process.stdin.on('end') handler here.
+// VSCode and some MCP clients send ephemeral EOF / half-close signals during
+// the initialize handshake, which would cause premature gracefulShutdown
+// before the server has a chance to respond, resulting in the
+// "Error: calling 'initialize': EOF" error.
+//
+// The MCP SDK's StdioServerTransport already manages transport lifecycle.
+// Only handle unrecoverable stdout errors.
+process.stdout.on('error', (err) => {
+    if (err.code === 'EPIPE' || err.code === 'ERR_STREAM_DESTROYED') {
+        console.error('[MCP] stdout closed, shutting down:', err.code);
+        gracefulShutdown('stdout.error');
+    }
+});
+
 // Pre-initialize memory engine in background
 backgroundInitializeMemoryEngine().catch(err => {
     console.error(`${colors.yellow}[Memory]${colors.reset} Background init error: ${err.message}`);
@@ -3374,31 +3472,50 @@ backgroundInitializeMemoryEngine().catch(err => {
 
 // Graceful shutdown handler
 async function gracefulShutdown(signal) {
-  console.error(`${colors.yellow}[Shutdown]${colors.reset} Received ${signal}, cleaning up...`);
-  
-  try {
-    // Stop memory engine
-    if (memoryEngine && memoryEngineReady) {
-      await memoryEngine.cleanup();
-    }
-    
-    // Flush audit queue
-    const auditQ = getAuditQueue();
-    await auditQ.destroy();
-    
-    // Release lock
-    await releaseLock();
-    
-    console.error(`${colors.green}[Shutdown]${colors.reset} Cleanup complete`);
-  } catch (error) {
-    console.error(`${colors.red}[Shutdown]${colors.reset} Error during cleanup: ${error.message}`);
-  }
-  
-  process.exit(0);
+    console.error(`${colors.yellow}[Shutdown]${colors.reset} Received ${signal}, cleaning up...`);
+
+    const SHUTDOWN_TIMEOUT = 5000; // 5 seconds per MCP best practices
+
+    try {
+        await Promise.race([
+            (async () => {
+                // Stop memory engine
+                if (memoryEngine && memoryEngineReady) {
+                    await memoryEngine.cleanup();
+                }
+
+                // Flush audit queue
+                const auditQ = getAuditQueue();
+                await auditQ.destroy();
+
+                // Release lock
+                await releaseLock();
+            })(),
+            new Promise(resolve => setTimeout(resolve, SHUTDOWN_TIMEOUT))
+        ]);
+
+        console.error(`${colors.green}[Shutdown]${colors.reset} Cleanup complete`);
+    } catch (error) {
+        console.error(`${colors.red}[Shutdown]${colors.reset} Error during cleanup: ${error.message}`);
+    }
+
+    // Always exit (even if cleanup fails) to prevent zombie processes
+    process.exit(0);
 }
 
 process.on('SIGINT', () => gracefulShutdown('SIGINT'));
 process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
 
+// Protect against zombie processes - handle unexpected errors
+process.on('uncaughtException', (err) => {
+    console.error('[MCP] Uncaught exception:', err);
+    gracefulShutdown('uncaughtException');
+});
+
+process.on('unhandledRejection', (reason, promise) => {
+    console.error('[MCP] Unhandled rejection:', reason);
+    gracefulShutdown('unhandledRejection');
+});
+
 await server.connect(transport);
 console.error("mcfast MCP v1.0.0 running on stdio");

package/src/memory/memory-engine.js

@@ -225,23 +225,30 @@ export class MemoryEngine {
       });
     }
     
-    // Initialize file watcher
-    this.watcher = new FileWatcher(projectPath, this, {
-      debounceMs: 1500,
-      ignored: [
-        '**/node_modules/**',
-        '**/.git/**',
-        '**/dist/**',
-        '**/build/**',
-        '**/.mcfast/**',
-        '**/*.log'
-      ]
-    });
-    
-    try {
-      await this.watcher.start();
-    } catch (watcherError) {
-      console.error('[MemoryEngine] ⚠️ File watcher failed to start (continuing without file watching):', watcherError.message);
+    // Initialize file watcher (configurable via MCFAST_FILE_WATCHER env)
+    const ENABLE_FILE_WATCHER = process.env.MCFAST_FILE_WATCHER !== 'false';
+    
+    if (ENABLE_FILE_WATCHER) {
+      this.watcher = new FileWatcher(projectPath, this, {
+        debounceMs: 1500,
+        ignored: [
+          '**/node_modules/**',
+          '**/.git/**',
+          '**/dist/**',
+          '**/build/**',
+          '**/.mcfast/**',
+          '**/*.log'
+        ]
+      });
+      
+      try {
+        await this.watcher.start();
+      } catch (watcherError) {
+        console.error('[MemoryEngine] ⚠️ File watcher failed to start (continuing without file watching):', watcherError.message);
+        this.watcher = null;
+      }
+    } else {
+      console.error('[MemoryEngine] File watcher disabled (MCFAST_FILE_WATCHER=false)');
       this.watcher = null;
     }
     

package/src/memory/watchers/file-watcher.js

@@ -453,19 +453,21 @@ export class FileWatcher {
     
     console.error('[FileWatcher] Stopping...');
     
-    // Stop cleanup interval
+    // 1. Stop cleanup interval
     if (this.cleanupInterval) {
       clearInterval(this.cleanupInterval);
       this.cleanupInterval = null;
     }
     
-    // Process remaining updates
-    if (this.pendingUpdates.size > 0) {
-      console.error(`[FileWatcher] Processing remaining ${this.pendingUpdates.size} updates...`);
-      await this.processQueue();
+    // 2. Clear pending updates map (free memory)
+    this.pendingUpdates.clear();
+    
+    // 3. Cancel debounce timeout if exists
+    if (this.flushQueue && this.flushQueue.cancel) {
+      this.flushQueue.cancel();
     }
     
-    // Close watcher
+    // 4. Close chokidar watcher (critical - prevents persistent file watching)
     if (this.watcher) {
       await this.watcher.close();
       this.watcher = null;