@mrxkun/mcfast-mcp 4.0.0 → 4.0.3

package/src/index.js

@@ -40,6 +40,7 @@ import {
 } from './strategies/tree-sitter/refactor.js';
 import { safeEdit } from './utils/backup.js';
 import { formatError } from './utils/error-formatter.js';
+import { MemoryEngine } from './memory/index.js';
 
 const execAsync = promisify(exec);
 
@@ -47,6 +48,132 @@ const API_URL = "https://mcfast.vercel.app/api/v1";
 const TOKEN = process.env.MCFAST_TOKEN;
 const VERBOSE = process.env.MCFAST_VERBOSE !== 'false'; // Default: true
 
+// Memory Engine (initialized lazily)
+let memoryEngine = null;
+
+async function getMemoryEngine() {
+    if (!memoryEngine) {
+        memoryEngine = new MemoryEngine({
+            apiKey: TOKEN,
+            enableSync: true
+        });
+        await memoryEngine.initialize(process.cwd());
+        console.error(`${colors.cyan}[Memory]${colors.reset} Engine initialized`);
+    }
+    return memoryEngine;
+}
+
+/**
+ * Search memory for context related to instruction using UltraHybrid search
+ */
+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 
+        });
+        
+        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) => {
+            const fileName = result.filePath || result.path || 'unknown';
+            const score = result.finalScore || result.score || 0;
+            context += `\n[${idx + 1}] ${fileName} (score: ${score.toFixed(2)})\n`;
+            if (result.code) {
+                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) {
+            context += '\n--- MEMORY CONTEXT (Facts) ---\n';
+            facts.forEach(fact => {
+                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}`);
+        return '';
+    }
+}
+
+/**
+ * Log edit to memory after successful edit
+ */
+async function logEditToMemory({ instruction, files, strategy, success, errorMessage, durationMs }) {
+    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),
+            strategy,
+            success,
+            diffSize,
+            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}`);
+    }
+}
+
+/**
+ * Impact Analysis for rename operations using semantic search
+ */
+async function analyzeRenameImpact(symbolName, currentFile = null) {
+    try {
+        const engine = await getMemoryEngine();
+        
+        // Search for symbol references across codebase
+        const searchResult = await engine.intelligentSearch(symbolName, { 
+            limit: 20,
+            currentFile
+        });
+        
+        const impactedFiles = new Set();
+        const references = [];
+
+        searchResult.results.forEach(result => {
+            const filePath = result.filePath || result.path;
+            if (filePath && filePath !== currentFile) {
+                impactedFiles.add(filePath);
+                references.push({
+                    file: filePath,
+                    score: result.finalScore || result.score,
+                    context: result.code?.substring(0, 150)
+                });
+            }
+        });
+
+        return {
+            impactedFiles: Array.from(impactedFiles),
+            references: references.slice(0, 10),
+            totalReferences: searchResult.results.length,
+            suggestion: impactedFiles.size > 0
+                ? `⚠️  Rename will affect ${impactedFiles.size} file(s) with ${references.length} reference(s). Consider using multi-file edit.`
+                : null
+        };
+    } catch (error) {
+        console.error(`${colors.yellow}[Memory]${colors.reset} Impact analysis failed: ${error.message}`);
+        return { impactedFiles: [], references: [], totalReferences: 0, suggestion: null };
+    }
+}
+
 // ANSI Color Codes for Terminal Output
 const colors = {
     reset: '\x1b[0m',
@@ -69,6 +196,8 @@ const toolIcons = {
     read: '📖',
     list_files: '📁',
     reapply: '🔁',
+    memory_search: '🧠',
+    memory_get: '📚',
     // Legacy aliases (backward compatibility)
     apply_fast: '⚡',
     apply_search_replace: '🔄',
@@ -957,11 +1086,41 @@ async function handleReapply({ instruction, files, errorContext = "", attempt =
 }
 
 /**
- * UNIFIED HANDLER 1: handleEdit (v2.0)
+ * UNIFIED HANDLER 1: handleEdit (v3.0 - Enhanced with Memory)
  * Consolidates: apply_fast + edit_file + apply_search_replace
  * Auto-detects best strategy based on input
+ * NEW: Context retrieval, impact analysis, auto-fix references
  */
 async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
+    const editStartTime = Date.now();
+    const firstFile = Object.keys(files)[0];
+    
+    // 1. Retrieve memory context for enhanced understanding
+    let memoryContext = '';
+    try {
+        memoryContext = await searchMemoryContext(instruction, 5);
+        if (memoryContext) {
+            console.error(`${colors.cyan}[MEMORY]${colors.reset} Retrieved context for edit`);
+        }
+    } 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);
+    if (renamePattern) {
+        const symbolName = renamePattern[1];
+        try {
+            impactAnalysis = await analyzeRenameImpact(symbolName, firstFile);
+            if (impactAnalysis.suggestion) {
+                console.error(`${colors.yellow}[IMPACT]${colors.reset} ${impactAnalysis.suggestion}`);
+            }
+        } catch (error) {
+            console.error(`${colors.yellow}[IMPACT]${colors.reset} Analysis failed: ${error.message}`);
+        }
+    }
+    
     // Check for multi-file edits first
     const multiFileEdit = detectCrossFileEdit(instruction, files);
 
@@ -986,6 +1145,16 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
             }
 
             if (!result.success) {
+                // Log failed edit to memory
+                await logEditToMemory({
+                    instruction,
+                    files,
+                    strategy: multiFileEdit.type,
+                    success: false,
+                    errorMessage: result.message || result.error,
+                    durationMs: Date.now() - editStartTime
+                });
+                
                 return {
                     content: [{
                         type: "text",
@@ -997,6 +1166,15 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
                 };
             }
 
+            // Log successful edit to memory
+            await logEditToMemory({
+                instruction,
+                files: result.files || Object.keys(files),
+                strategy: multiFileEdit.type,
+                success: true,
+                durationMs: Date.now() - editStartTime
+            });
+
             return {
                 content: [{
                     type: "text",
@@ -1005,6 +1183,16 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
             };
 
         } catch (error) {
+            // Log failed edit to memory
+            await logEditToMemory({
+                instruction,
+                files,
+                strategy: 'multi_file_error',
+                success: false,
+                errorMessage: error.message,
+                durationMs: Date.now() - editStartTime
+            });
+            
             return {
                 content: [{
                     type: "text",
@@ -1018,13 +1206,12 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
     }
 
     const strategy = detectEditStrategy({ instruction, code_edit, files });
-
     console.error(`${colors.cyan}[EDIT STRATEGY]${colors.reset} ${strategy}`);
 
     // Strategy 1: Fuzzy Patch (unified diff format)
     if (strategy === 'fuzzy_patch') {
         const diffText = code_edit || instruction;
-        const filePath = Object.keys(files)[0]; // Assume single file for now
+        const filePath = Object.keys(files)[0];
         const fileContent = files[filePath];
 
         try {
@@ -1056,6 +1243,16 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
                 await fs.writeFile(filePath, patchResult.content, 'utf8');
             });
 
+            // Log edit to memory
+            await logEditToMemory({
+                instruction,
+                files: { [filePath]: fileContent },
+                strategy: 'fuzzy_patch',
+                success: editResult.success,
+                errorMessage: editResult.error,
+                durationMs: Date.now() - editStartTime
+            });
+
             if (!editResult.success) {
                 // Determine error type based on result
                 let errorType = 'generic';
@@ -1091,6 +1288,16 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
             };
 
         } catch (error) {
+            // Log failed edit
+            await logEditToMemory({
+                instruction,
+                files,
+                strategy: 'fuzzy_patch',
+                success: false,
+                errorMessage: error.message,
+                durationMs: Date.now() - editStartTime
+            });
+            
             return {
                 content: [{
                     type: "text",
@@ -1191,6 +1398,15 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
                 await fs.writeFile(filePath, transformResult.code, 'utf8');
             });
 
+            // Log successful AST refactor
+            await logEditToMemory({
+                instruction,
+                files: { [filePath]: fileContent },
+                strategy: `ast_refactor:${pattern.type}`,
+                success: editResult.success,
+                durationMs: Date.now() - editStartTime
+            });
+
             if (!editResult.success) {
                 let errorType = 'generic';
                 if (editResult.error.includes('ENOENT')) errorType = 'file_not_found';
@@ -1210,14 +1426,40 @@ 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) {
+                    resultText += `\n\n📋 Affected files:`;
+                    impactAnalysis.impactedFiles.slice(0, 5).forEach(f => {
+                        resultText += `\n  • ${f}`;
+                    });
+                    if (impactAnalysis.impactedFiles.length > 5) {
+                        resultText += `\n  ... and ${impactAnalysis.impactedFiles.length - 5} more`;
+                    }
+                }
+            }
+
             return {
                 content: [{
                     type: "text",
-                    text: `✅ AST Refactor Applied Successfully\n\nOperation: ${pattern.type}\nChanges: ${transformResult.count || transformResult.replacements || 0} locations\n\nBackup: ${editResult.backupPath}`
+                    text: resultText
                 }]
             };
 
         } catch (error) {
+            // Log failed edit
+            await logEditToMemory({
+                instruction,
+                files,
+                strategy: `ast_refactor:${pattern?.type || 'unknown'}`,
+                success: false,
+                errorMessage: error.message,
+                durationMs: Date.now() - editStartTime
+            });
+            
             return {
                 content: [{
                     type: "text",
@@ -1234,40 +1476,85 @@ async function handleEdit({ instruction, files, code_edit, dryRun = false }) {
     if (strategy === 'search_replace') {
         const extracted = extractSearchReplace(instruction);
         if (extracted) {
-            return await handleApplyFast({
+            const result = await handleApplyFast({
                 instruction: `Replace checking for exact match:\nSEARCH:\n${extracted.search}\n\nREPLACE WITH:\n${extracted.replace}`,
                 files,
                 dryRun,
                 toolName: 'edit'
             });
+            
+            // Log to memory
+            await logEditToMemory({
+                instruction,
+                files,
+                strategy: 'search_replace',
+                success: !result.isError,
+                errorMessage: result.isError ? result.content?.[0]?.text : null,
+                durationMs: Date.now() - editStartTime
+            });
+            
+            return result;
         }
     }
 
     // Strategy 3: Placeholder Merge (token-efficient)
     if (strategy === 'placeholder_merge' && code_edit) {
-        return await handleApplyFast({
+        const result = await handleApplyFast({
             instruction: `${instruction}\n\nUSE PLACEHOLDER MERGE STRATEGY. Code snippet:\n${code_edit}`,
             files,
             dryRun,
             toolName: 'edit'
         });
+        
+        // Log to memory
+        await logEditToMemory({
+            instruction,
+            files,
+            strategy: 'placeholder_merge',
+            success: !result.isError,
+            errorMessage: result.isError ? result.content?.[0]?.text : null,
+            durationMs: Date.now() - editStartTime
+        });
+        
+        return result;
     }
 
     // Strategy 4: Mercury Intelligent (most flexible, default)
-    return await handleApplyFast({
-        instruction,
+    // Enhance instruction with memory context
+    let enhancedInstruction = instruction;
+    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,
+        files,
+        strategy: 'mercury_intelligent',
+        success: !result.isError,
+        errorMessage: result.isError ? result.content?.[0]?.text : null,
+        durationMs: Date.now() - editStartTime
+    });
+    
+    return result;
 }
 
 /**
- * UNIFIED HANDLER 2: handleSearch (v2.0)
+ * UNIFIED HANDLER 2: handleSearch (v3.0 - Enhanced with Memory)
  * Consolidates: search_code + search_code_ai + search_filesystem
  * Auto-detects best strategy based on input
+ * Memory System Integration: Intelligent local-first hybrid search
  */
-async function handleSearch({ query, files, path, mode = 'auto', regex = false, caseSensitive = false, contextLines = 2 }) {
+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') {
@@ -1278,6 +1565,50 @@ async function handleSearch({ query, files, path, mode = 'auto', regex = false,
 
     console.error(`${colors.cyan}[SEARCH STRATEGY]${colors.reset} ${detectedMode}`);
 
+    // Memory System Integration: Try intelligent search for auto/local modes
+    if ((detectedMode === 'auto' || detectedMode === 'local') && !regex) {
+        try {
+            const engine = await getMemoryEngine();
+            
+            // Use intelligent search (UltraHybrid + Smart Routing)
+            const searchResult = await engine.intelligentSearch(query, { 
+                limit: maxResults,
+                currentFile: files ? Object.keys(files)[0] : null
+            });
+
+            if (searchResult.results && searchResult.results.length > 0) {
+                console.error(`${colors.cyan}[MEMORY]${colors.reset} Found ${searchResult.results.length} results via intelligent search`);
+
+                // Format results
+                let output = `🔍 Intelligent Search Results for "${query}"\n`;
+                output += `${colors.dim}Method: ${searchResult.metadata?.method || 'intelligent'} | `;
+                output += `Accuracy: ${searchResult.metadata?.accuracy || '90%'} | `;
+                output += `Duration: ${searchResult.metadata?.totalDuration || 'N/A'}${colors.reset}\n\n`;
+
+                searchResult.results.slice(0, maxResults).forEach((result, i) => {
+                    const filePath = result.filePath || result.path || 'unknown';
+                    const score = result.finalScore || result.score || 0;
+                    output += `[${i + 1}] ${colors.yellow}${filePath}${colors.reset}\n`;
+                    if (result.code) {
+                        output += `    ${result.code.slice(0, 200)}${result.code.length > 200 ? '...' : ''}\n`;
+                    }
+                    output += `    ${colors.dim}Score: ${score.toFixed(2)}${colors.reset}\n\n`;
+                });
+
+                if (searchResult.results.length > maxResults) {
+                    output += `${colors.dim}... and ${searchResult.results.length - maxResults} more results${colors.reset}\n`;
+                }
+
+                return { content: [{ type: "text", text: output }] };
+            } else {
+                console.error(`${colors.yellow}[MEMORY]${colors.reset} No results from intelligent search, falling back...`);
+            }
+        } catch (memoryError) {
+            console.error(`${colors.yellow}[MEMORY]${colors.reset} Intelligent search failed: ${memoryError.message}`);
+            // Continue with normal search strategies
+        }
+    }
+
     // Strategy 1: Local search (if files provided)
     if (detectedMode === 'local' && files) {
         return await handleSearchCode({ query, files, regex, caseSensitive, contextLines });
@@ -1550,6 +1881,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) {
@@ -1569,6 +1906,11 @@ async function handleWarpgrep({ query, include = ".", isRegex = false, caseSensi
     }
 }
 
+/**
+ * UNIFIED HANDLER 4: handleSearchCode (v2.0)
+ * Renamed from handleSearchCode for consistency
+ * Now supports both single file and batch search modes
+ */
 async function handleSearchCode({ query, files, regex = false, caseSensitive = false, contextLines = 2 }) {
     const start = Date.now();
     try {
@@ -1730,104 +2072,161 @@ async function handleSearchCode({ query, files, regex = false, caseSensitive = f
     }
 }
 
-async function handleListFiles({ path: dirPath = process.cwd(), depth = 5, offset = 0, limit = 500 }) {
-    const start = Date.now();
+/**
+ * UNIFIED HANDLER 5: handleSearchCodeAI (v2.0)
+ * Renamed from handleSearchCodeAI for consistency
+ * Now supports both single file and batch search modes
+ */
+async function handleSearchCodeAI({ query, files, contextLines = 2 }) {
+    if (!TOKEN) {
+        return {
+            content: [{ type: "text", text: "❌ Error: MCFAST_TOKEN is missing. Please set it in your MCP config." }],
+            isError: true
+        };
+    }
     try {
-        const files = await getFiles(dirPath, depth);
-
-        // Apply pagination
-        const totalFiles = files.length;
-        const paginatedFiles = files.slice(offset, offset + limit);
-        const hasMore = offset + limit < totalFiles;
+        const response = await fetch(`${API_URL}/search-ai`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": `Bearer ${TOKEN}`,
+            },
+            body: JSON.stringify({ query, files, contextLines }),
+        });
 
-        // Build output with pagination info
-        let output = `📁 Files in ${dirPath} (depth: ${depth}):\n`;
-        output += `Showing ${offset + 1}-${Math.min(offset + limit, totalFiles)} of ${totalFiles} files`;
-        if (hasMore) {
-            output += `. Use offset: ${offset + limit} to see more.`;
+        if (!response.ok) {
+            const errorText = await response.text();
+            return {
+                content: [{ type: "text", text: `Search Error (${response.status}): ${errorText}` }],
+                isError: true,
+            };
         }
-        output += `\n\n${paginatedFiles.join('\n')}`;
 
-        // Check for large output and add helpful message
-        const outputLength = output.length;
-        if (outputLength > 50000) {
-            output += `\n\n💡 Tip: Output is large. Use depth parameter to limit depth (e.g., depth: 2 or 3) to limit the search scope.`;
+        const data = await response.json();
+
+        // Check for warning (empty file content)
+        if (data.warning) {
+            return {
+                content: [{ type: "text", text: `⚠️ ${data.warning}\n\nThis usually means the AI agent didn't load file contents before searching. The files parameter should contain actual file content, not empty strings.` }],
+            };
         }
 
-        reportAudit({
-            tool: 'list_files_fast',
-            instruction: dirPath,
-            status: 'success',
-            latency_ms: Date.now() - start,
-            files_count: totalFiles,
-            result_summary: JSON.stringify(paginatedFiles.slice(0, 500)),
-            input_tokens: Math.ceil(dirPath.length / 4),
-            output_tokens: Math.ceil(output.length / 4)
-        });
+        // Format results nicely
+        let output = `🔍 Found ${data.totalMatches} matches for "${query}"\n\n`;
+
+        if (data.results.length === 0) {
+            output += "No matches found.";
+        } else {
+            data.results.forEach((result, i) => {
+                output += `📄 ${result.file}:${result.lineNumber}\n`;
+                result.context.forEach(ctx => {
+                    const prefix = ctx.isMatch ? "→ " : "  ";
+                    output += `${prefix}${ctx.lineNumber}: ${ctx.content}\n`;
+                });
+                if (i < data.results.length - 1) output += "\n";
+            });
+        }
 
         return {
-            content: [{ type: "text", text: output }]
+            content: [{ type: "text", text: output }],
         };
 
     } catch (error) {
-        // Error recovery: suggest using depth parameter
-        let errorMessage = `❌ Error listing files: ${error.message}`;
-        if (error.message.includes('too many files') || error.message.includes('EMFILE') || error.message.includes('max')) {
-            errorMessage += `\n\n💡 Tip: Try reducing the depth (e.g., depth: 2 or 3) to limit the search scope.`;
-        }
-
-        reportAudit({
-            tool: 'list_files_fast',
-            instruction: dirPath,
-            status: 'error',
-            error_message: error.message,
-            latency_ms: Date.now() - start
-        });
         return {
-            content: [{ type: "text", text: errorMessage }],
-            isError: true
+            content: [{ type: "text", text: `Search Connection Error: ${error.message}` }],
+            isError: true,
         };
     }
 }
 
-async function handleEditFile({ path: filePath, content, instruction = "" }) {
-    const start = Date.now();
+/**
+ * UNIFIED HANDLER 6: handleGetDefinition (v2.0)
+ * Renamed from handleGetDefinition for consistency
+ * Now supports both single file and batch search modes
+ */
+async function handleGetDefinition({ path: filePath, symbol }) {
+    if (!filePath || !symbol) throw new Error("Missing path or symbol");
+
+    const absolutePath = path.resolve(filePath);
+
+    // Check if path is a directory - search across files in directory
+    let stats;
     try {
-        await fs.writeFile(filePath, content, 'utf8');
+        stats = await fs.stat(absolutePath);
+    } catch (e) {
+        throw new Error(`Path does not exist: ${filePath}`);
+    }
 
-        const estimatedTokens = Math.ceil(content.length / 4);
+    if (!stats.isFile()) {
+        // It's a directory - search for symbol definition using grep
+        return await handleDefinitionInDirectory({ path: absolutePath, symbol });
+    }
 
-        reportAudit({
-            tool: 'edit_file',
-            instruction: instruction || `Written ${filePath}`,
-            status: 'success',
-            latency_ms: Date.now() - start,
-            files_count: 1,
-            input_tokens: estimatedTokens,
-            output_tokens: 10 // Minimal output (success message)
-        });
+    // It's a file - use tree-sitter to find definition
+    const content = await fs.readFile(filePath, 'utf8');
+    const definitions = await findDefinition(content, filePath, symbol);
 
+    if (definitions.length === 0) {
         return {
-            content: [{ type: "text", text: `✅ File saved successfully: ${filePath}` }]
+            content: [{ type: "text", text: `No definition found for '${symbol}' in ${filePath}` }]
         };
-    } catch (error) {
-        reportAudit({
-            tool: 'edit_file',
-            instruction: instruction || `Failed write ${filePath}`,
-            status: 'error',
-            error_message: error.message,
-            latency_ms: Date.now() - start,
-            input_tokens: Math.ceil((content?.length || 0) / 4),
-            output_tokens: 0
-        });
+    }
+
+    const def = definitions[0]; // Take first
+
+    return {
+        content: [{ type: "text", text: `Definition of '${symbol}':\n${filePath}:${def.line}:${def.column} (${def.type || 'unknown'})` }]
+    };
+}
+
+/**
+ * UNIFIED HANDLER 7: handleFindReferences (v2.0)
+ * Renamed from handleFindReferences for consistency
+ * Now supports both single file and batch search modes
+ */
+async function handleFindReferences({ path: filePath, symbol }) {
+    if (!filePath || !symbol) throw new Error("Missing path or symbol");
+
+    const absolutePath = path.resolve(filePath);
+
+    // Check if path is a directory - search across files in directory
+    let stats;
+    try {
+        stats = await fs.stat(absolutePath);
+    } catch (e) {
+        throw new Error(`Path does not exist: ${filePath}`);
+    }
+
+    if (!stats.isFile()) {
+        // It's a directory - search for references using grep
+        return await handleReferencesInDirectory({ path: absolutePath, symbol });
+    }
+
+    // It's a file - use tree-sitter to find references
+    const content = await fs.readFile(filePath, 'utf8');
+    const references = await findReferences(content, filePath, symbol);
+
+    if (references.length === 0) {
         return {
-            content: [{ type: "text", text: `❌ Failed to write file: ${error.message}` }],
-            isError: true
+            content: [{ type: "text", text: `No references found for '${symbol}' in ${filePath}` }]
         };
     }
-}
 
+    let output = `References for '${symbol}' in ${filePath} (${references.length}):\n`;
+    references.forEach(ref => {
+        output += `${ref.line}:${ref.column}\n`;
+    });
+
+    return {
+        content: [{ type: "text", text: output }]
+    };
+}
 
+/**
+ * UNIFIED HANDLER 8: handleReadFile (v2.0)
+ * Renamed from handleReadFile for consistency
+ * Now supports both single file and batch search modes
+ */
 async function handleReadFile({ path: filePath, start_line, end_line }) {
     const start = Date.now();
     try {
@@ -1880,7 +2279,7 @@ async function handleReadFile({ path: filePath, start_line, end_line }) {
             if (startLine && endLine) {
                 lineRangeInfo = `(Lines ${startLine}-${endLine} of ${totalLines})`;
             } else if (startLine) {
-                lineRangeInfo = `(Lines ${startLine}-${currentLine} of ${totalLines})`;
+                lineRangeInfo = `(Lines ${startLine}-${currentLine} of ${totalLines} - truncated)`;
             } else {
                 lineRangeInfo = `(Lines 1-${lines.length} of ${totalLines} - truncated)`;
             }
@@ -1935,6 +2334,11 @@ async function handleReadFile({ path: filePath, start_line, end_line }) {
     }
 }
 
+/**
+ * UNIFIED HANDLER 9: handleApplyFast (v2.0)
+ * Renamed from handleApplyFast for consistency
+ * Now supports both single file and batch search modes
+ */
 async function handleApplyFast({ instruction, files, dryRun, toolName }) {
     if (!TOKEN) {
         return {
@@ -2008,103 +2412,76 @@ async function handleApplyFast({ instruction, files, dryRun, toolName }) {
     }
 }
 
-async function handleSearchCodeAI({ query, files, contextLines = 2 }) {
-    if (!TOKEN) {
-        return {
-            content: [{ type: "text", text: "❌ Error: MCFAST_TOKEN is missing. Please set it in your MCP config." }],
-            isError: true
-        };
-    }
+/**
+ * UNIFIED HANDLER 10: handleListFiles (v2.0)
+ * Renamed from handleListFiles for consistency
+ * Now supports both single file and batch search modes
+ */
+async function handleListFiles({ path: dirPath = process.cwd(), depth = 5, offset = 0, limit = 500 }) {
+    const start = Date.now();
     try {
-        const response = await fetch(`${API_URL}/search-ai`, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                "Authorization": `Bearer ${TOKEN}`,
-            },
-            body: JSON.stringify({ query, files, contextLines }),
-        });
-
-        if (!response.ok) {
-            const errorText = await response.text();
-            return {
-                content: [{ type: "text", text: `Search Error (${response.status}): ${errorText}` }],
-                isError: true,
-            };
-        }
+        const files = await getFiles(dirPath, depth);
 
-        const data = await response.json();
+        // Apply pagination
+        const totalFiles = files.length;
+        const paginatedFiles = files.slice(offset, offset + limit);
+        const hasMore = offset + limit < totalFiles;
 
-        // Check for warning (empty file content)
-        if (data.warning) {
-            return {
-                content: [{ type: "text", text: `⚠️ ${data.warning}\n\nThis usually means the AI agent didn't load file contents before searching. The files parameter should contain actual file content, not empty strings.` }],
-            };
+        // Build output with pagination info
+        let output = `📁 Files in ${dirPath} (depth: ${depth}):\n`;
+        output += `Showing ${offset + 1}-${Math.min(offset + limit, totalFiles)} of ${totalFiles} files`;
+        if (hasMore) {
+            output += `. Use offset: ${offset + limit} to see more.`;
         }
+        output += `\n\n${paginatedFiles.join('\n')}`;
 
-        // Format results nicely
-        let output = `🔍 Found ${data.totalMatches} matches for "${query}"\n\n`;
-
-        if (data.results.length === 0) {
-            output += "No matches found.";
-        } else {
-            data.results.forEach((result, i) => {
-                output += `📄 ${result.file}:${result.lineNumber}\n`;
-                result.context.forEach(ctx => {
-                    const prefix = ctx.isMatch ? "→ " : "  ";
-                    output += `${prefix}${ctx.lineNumber}: ${ctx.content}\n`;
-                });
-                if (i < data.results.length - 1) output += "\n";
-            });
+        // Check for large output and add helpful message
+        const outputLength = output.length;
+        if (outputLength > 50000) {
+            output += `\n\n💡 Tip: Output is large. Use depth parameter to limit depth (e.g., depth: 2 or 3) to limit the search scope.`;
         }
 
-        return {
-            content: [{ type: "text", text: output }],
-        };
+        reportAudit({
+            tool: 'list_files_fast',
+            instruction: dirPath,
+            status: 'success',
+            latency_ms: Date.now() - start,
+            files_count: totalFiles,
+            result_summary: JSON.stringify(paginatedFiles.slice(0, 500)),
+            input_tokens: Math.ceil(dirPath.length / 4),
+            output_tokens: Math.ceil(output.length / 4)
+        });
 
-    } catch (error) {
         return {
-            content: [{ type: "text", text: `Search Connection Error: ${error.message}` }],
-            isError: true,
+            content: [{ type: "text", text: output }]
         };
-    }
-}
-
-async function handleGetDefinition({ path: filePath, symbol }) {
-    if (!filePath || !symbol) throw new Error("Missing path or symbol");
-
-    const absolutePath = path.resolve(filePath);
-
-    // Check if path is a directory - search across files in directory
-    let stats;
-    try {
-        stats = await fs.stat(absolutePath);
-    } catch (e) {
-        throw new Error(`Path does not exist: ${filePath}`);
-    }
-
-    if (!stats.isFile()) {
-        // It's a directory - search for symbol definition using grep
-        return await handleDefinitionInDirectory({ path: absolutePath, symbol });
-    }
 
-    // It's a file - use tree-sitter to find definition
-    const content = await fs.readFile(filePath, 'utf8');
-    const definitions = await findDefinition(content, filePath, symbol);
+    } catch (error) {
+        // Error recovery: suggest using depth parameter
+        let errorMessage = `❌ Error listing files: ${error.message}`;
+        if (error.message.includes('too many files') || error.message.includes('EMFILE') || error.message.includes('max')) {
+            errorMessage += `\n\n💡 Tip: Try reducing the depth (e.g., depth: 2 or 3) to limit the search scope.`;
+        }
 
-    if (definitions.length === 0) {
+        reportAudit({
+            tool: 'list_files_fast',
+            instruction: dirPath,
+            status: 'error',
+            error_message: error.message,
+            latency_ms: Date.now() - start
+        });
         return {
-            content: [{ type: "text", text: `No definition found for '${symbol}' in ${filePath}` }]
+            content: [{ type: "text", text: errorMessage }],
+            isError: true
         };
     }
-
-    const def = definitions[0]; // Take first
-
-    return {
-        content: [{ type: "text", text: `Definition of '${symbol}':\n${filePath}:${def.line}:${def.column} (${def.type || 'unknown'})` }]
-    };
 }
 
+/**
+ * UNIFIED HANDLER 11: handleDefinitionInDirectory (v2.0)
+ * Renamed from handleDefinitionInDirectory for consistency
+ * Now supports both single file and batch search modes
+ */
 async function handleDefinitionInDirectory({ path: dirPath, symbol }) {
     // Search for symbol definition in directory using grep
     // Look for common definition patterns: const/let/var, function, class, interface, type, etc.
@@ -2168,44 +2545,11 @@ async function handleDefinitionInDirectory({ path: dirPath, symbol }) {
     };
 }
 
-async function handleFindReferences({ path: filePath, symbol }) {
-    if (!filePath || !symbol) throw new Error("Missing path or symbol");
-
-    const absolutePath = path.resolve(filePath);
-
-    // Check if path is a directory - search across files in directory
-    let stats;
-    try {
-        stats = await fs.stat(absolutePath);
-    } catch (e) {
-        throw new Error(`Path does not exist: ${filePath}`);
-    }
-
-    if (!stats.isFile()) {
-        // It's a directory - search for references using grep
-        return await handleReferencesInDirectory({ path: absolutePath, symbol });
-    }
-
-    // It's a file - use tree-sitter to find references
-    const content = await fs.readFile(filePath, 'utf8');
-    const references = await findReferences(content, filePath, symbol);
-
-    if (references.length === 0) {
-        return {
-            content: [{ type: "text", text: `No references found for '${symbol}' in ${filePath}` }]
-        };
-    }
-
-    let output = `References for '${symbol}' in ${filePath} (${references.length}):\n`;
-    references.forEach(ref => {
-        output += `${ref.line}:${ref.column}\n`;
-    });
-
-    return {
-        content: [{ type: "text", text: output }]
-    };
-}
-
+/**
+ * UNIFIED HANDLER 12: handleReferencesInDirectory (v2.0)
+ * Renamed from handleReferencesInDirectory for consistency
+ * Now supports both single file and batch search modes
+ */
 async function handleReferencesInDirectory({ path: dirPath, symbol }) {
     // Search for symbol references in directory using grep
     const flags = "-rn";