@mrxkun/mcfast-mcp 3.4.0 → 3.4.2

package/README.md

@@ -22,14 +22,47 @@ Standard AI agents often struggle with multi-file edits, broken syntax, and "hal
 
 ---
 
-## 🚀 Key Features (v3.3)
+## 🚀 Key Features (v3.4)
+
+### 1. **Batch Read Mode** 🆕 NEW in v3.4
+Read multiple files in parallel with a single request:
+- **Parallel Processing**: Up to 50 files read simultaneously
+- **Line Range Support**: Read specific line ranges to save tokens
+- **Smart Truncation**: Auto-truncate large files in batch mode
+- **Progress Tracking**: Real-time progress for batch operations
+
+### 2. **Parallel Edit with Dependencies** 🆕 NEW in v3.4
+Execute complex multi-file edits with intelligent parallelization:
+- **Dependency Graph**: Specify which edits depend on others
+- **Automatic Parallelization**: Independent edits run in parallel
+- **Sequential Dependencies**: Dependent edits wait for prerequisites
+- **Atomic Operations**: All-or-nothing execution with rollback
+
+Example:
+```javascript
+{
+  operations: [
+    { id: "1", path: "A.js", instruction: "...", depends_on: [] },
+    { id: "2", path: "B.js", instruction: "...", depends_on: ["1"] },
+    { id: "3", path: "C.js", instruction: "...", depends_on: [] }
+  ]
+}
+// 1 and 3 run in parallel, 2 waits for 1
+```
 
-### 1. **AST-Aware Refactoring**
+### 3. **Smart Caching Layer** 🆕 NEW in v3.4
+Intelligent caching for improved performance:
+- **Content Caching**: Cache file reads (30 min TTL)
+- **Edit Result Caching**: Cache successful edits (1 hour TTL)
+- **Batch Operation Caching**: Cache batch results (15 min TTL)
+- **Automatic Invalidation**: Cache clears on file changes
+
+### 4. **AST-Aware Refactoring**
 mcfast doesn't just "search and replace" text. It parses your code into a Tree-sitter AST to perform:
 - **Scope-Aware Rename**: Rename functions, variables, or classes safely across your entire project.
 - **Smart Symbol Search**: Find true references, ignoring comments and strings.
 
-### 2. **Hybrid Fuzzy Patching** ⚡ NEW in v3.3
+### 5. **Hybrid Fuzzy Patching** ⚡ NEW in v3.3
 Multi-layered matching strategy with intelligent fallback:
 1. **Exact Line Match** (Hash Map) - O(1) lookup for identical code blocks
 2. **Myers Diff Algorithm** - Shortest Edit Script in O((M+N)D) time
@@ -37,19 +70,19 @@ Multi-layered matching strategy with intelligent fallback:
 
 This hybrid approach significantly improves accuracy and reduces false matches for complex refactoring tasks.
 
-### 3. **Context-Aware Search** 🆕 NEW in v3.3
+### 6. **Context-Aware Search** 🆕 NEW in v3.3
 Automatic junk directory exclusion powered by intelligent pattern matching:
 - Automatically filters `node_modules`, `.git`, `dist`, `build`, `.next`, `coverage`, `__pycache__`, and more
 - No manual configuration required
 - Respects `.gitignore` patterns automatically
 
-### 4. **Advanced Fuzzy Patching**
+### 7. **Advanced Fuzzy Patching**
 Tired of "Line number mismatch" errors? mcfast uses a multi-layered matching strategy:
 - **Levenshtein Distance**: Measures text similarity with early termination.
 - **Token Analysis**: Matches code based on logic even if whitespace or formatting differs.
 - **Structural Matching**: Validates that the patch "fits" the code structure.
 
-### 5. **Auto-Rollback (Auto-Healing)**
+### 8. **Auto-Rollback (Auto-Healing)**
 mcfast integrates language-specific linters to ensure your build stays green:
 - **JS/TS**: `node --check`
 - **Go**: `gofmt -e`
@@ -57,7 +90,7 @@ mcfast integrates language-specific linters to ensure your build stays green:
 - **Python/PHP/Ruby**: Syntax validation.
 *If validation fails, mcfast automatically restores from a hidden backup.*
 
-### 6. **Organize Imports**
+### 9. **Organize Imports**
 Supports JS, TS, Go, Python, and more. Automatically sorts and cleans up your import blocks using high-speed S-expression queries.
 
 ---
@@ -102,15 +135,51 @@ Add the following to your `claude_desktop_config.json`:
 
 ---
 
-## 🧰 Available Tools
-
-mcfast exposes a unified set of tools to your AI agent:
-
-*   **`edit`**: The primary tool. It decides whether to use `ast_refactor`, `fuzzy_patch`, or `search_replace` based on the task complexity.
-*   **`search`**: Fast grep-style search with in-memory AST indexing.
-*   **`read`**: Smart reader that returns code chunks with line numbers, optimized for token savings.
-*   **`list_files`**: High-performance globbing with `.gitignore` support and context-aware filtering.
-*   **`reapply`**: If an edit fails validation, the AI can use this to retry with a different strategy.
+## 🧰 5 Unified Tools
+
+mcfast exposes a complete set of 5 tools to your AI agent, each optimized for specific use cases:
+
+| Tool | Purpose | Best For |
+|------|---------|----------|
+| **`edit`** | Multi-file code editing | Complex refactoring, renaming, multi-file updates |
+| **`parallel_edit`** | Multi-file edits with dependencies | Complex workflows requiring ordered execution |
+| **`search`** | Fast pattern search | Finding code patterns, symbols, references |
+| **`read`** | Read file content | Viewing specific files with line ranges |
+| **`list_files`** | Directory exploration | Discovering project structure, finding files |
+| **`reapply`** | Retry failed edits | Auto-recovery with enhanced context |
+
+### Tool Details
+
+**`edit`** (aliases: `apply_fast`, `edit_file`, `apply_search_replace`)
+- Primary editing tool with auto-strategy detection
+- Supports: AST refactoring, fuzzy patching, search-replace
+- Handles single-file and multi-file edits seamlessly
+
+**`parallel_edit`** (NEW in v3.4)
+- Multi-file coordination with dependency resolution
+- Execute operations in parallel when possible
+- Automatic rollback on failure
+- Perfect for complex refactoring workflows
+
+**`search`** (aliases: `search_code`, `search_code_ai`)
+- Fast pattern matching with regex support
+- In-memory AST indexing for symbol-aware searches
+- Automatic junk directory filtering (node_modules, .git, dist, etc.)
+
+**`read`** (alias: `read_file`)
+- Read file content with optional line ranges
+- Optimized for token efficiency (read only what you need)
+- Supports all 10 language parsers
+
+**`list_files`** (alias: `list_files_fast`)
+- Recursive directory listing with depth control
+- Respects `.gitignore` automatically
+- Perfect for exploring codebase structure
+
+**`reapply`**
+- Smart retry mechanism for failed edits
+- Enhanced context and error analysis
+- Max 3 automatic retries with strategy adjustment
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mrxkun/mcfast-mcp",
-  "version": "3.4.0",
-  "description": "Ultra-fast code editing with fuzzy patching, auto-rollback, and 7 unified tools.",
+  "version": "3.4.2",
+  "description": "Ultra-fast code editing with fuzzy patching, auto-rollback, and 5 unified tools.",
   "type": "module",
   "bin": {
     "mcfast-mcp": "src/index.js"

package/src/index.js

@@ -263,15 +263,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             // CORE TOOL 3: read
             {
                 name: "read",
-                description: "Read file contents. CRITICAL: Use `start_line` and `end_line` for large files to reduce token usage and latency.",
+                description: "Read file contents. CRITICAL: Use `start_line` and `end_line` for large files to reduce token usage and latency. Supports both single file and batch mode.",
                 inputSchema: {
                     type: "object",
                     properties: {
-                        filePath: { type: "string", description: "Absolute path to the file" },
+                        filePath: { type: "string", description: "Absolute path to a single file (use this OR filePaths, not both)" },
+                        filePaths: { type: "array", items: { type: "string" }, description: "Array of file paths for batch read mode (use this OR filePath, not both)" },
                         start_line: { type: "number", description: "Start line (1-indexed, inclusive)" },
-                        end_line: { type: "number", description: "End line (1-indexed, inclusive)" }
-                    },
-                    required: ["filePath"]
+                        end_line: { type: "number", description: "End line (1-indexed, inclusive)" },
+                        max_lines_per_file: { type: "number", description: "Max lines per file in batch mode (default: 100)" }
+                    }
                 }
             },
             // CORE TOOL 4: list_files
@@ -880,190 +881,184 @@ async function handleSearch({ query, files, path, mode = 'auto', regex = false,
 /**
  * UNIFIED HANDLER 3: handleRead (v2.0)
  * Renamed from handleReadFile for consistency
+ * Now supports both single file and batch read modes
  */
-async function handleRead({ filePath, start_line, end_line }) {
-    return await handleReadFile({ path: filePath, start_line, end_line });
-}
-
-// Local search implementation (no API required)
-async function reportAudit(params) {
-    if (!TOKEN) return;
-    try {
-        await fetch(`${API_URL}/logs/audit`, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                "Authorization": `Bearer ${TOKEN}`,
-            },
-            body: JSON.stringify(params),
-        });
-    } catch (e) {
-        console.error("Failed to report audit:", e.message);
+async function handleRead({ filePath, filePaths, start_line, end_line, max_lines_per_file = 100 }) {
+    // Batch mode: read multiple files in parallel
+    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 });
 }
 
-// Unified Search Implementation (v4.0 - Early Termination with Stream)
-async function handleSearchFilesystem({ query, path: searchPath = process.cwd(), include = "**/*", exclude = [], isRegex = false, caseSensitive = false }) {
+/**
+ * BATCH READ HANDLER: Read multiple files in parallel
+ */
+async function handleBatchRead(filePaths, start_line, end_line, max_lines_per_file) {
     const start = Date.now();
-    const MAX_RESULTS = 100;
-    const results = [];
-    let strategy = 'unknown';
-
-    try {
-        const { spawn } = await import('child_process');
-        const { promisify } = await import('util');
-        const sleep = promisify(setTimeout);
-
-        const escapedQuery = query.replace(/"/g, '\\"');
-        const caseFlag = caseSensitive ? '' : '-i';
-        const regexFlag = isRegex ? '-e' : '-F';
-
-        // Try ripgrep first with streaming and early termination
-        try {
-            strategy = 'ripgrep';
-            const rgProcess = spawn('rg', [
-                '-n', '--no-heading', '--with-filename',
-                caseFlag, regexFlag,
-                escapedQuery,
-                searchPath
-            ], {
-                stdio: ['ignore', 'pipe', 'pipe']
-            });
-
-            const readline = (await import('readline')).createInterface({
-                input: rgProcess.stdout,
-                crlfDelay: Infinity
-            });
-
-            for await (const line of readline) {
-                if (results.length >= MAX_RESULTS) {
-                    rgProcess.kill();
-                    break;
-                }
-                results.push(line);
-            }
-
-            rgProcess.stderr.on('data', () => { });
-            await new Promise(resolve => rgProcess.on('close', resolve));
-
-            if (results.length > 0 || rgProcess.exitCode === 0) {
-                return formatSearchResults(query, strategy, results, start, MAX_RESULTS);
-            }
-        } catch (rgErr) {
-            // Try git grep
+    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 {
-                strategy = 'git_grep';
-                const gitProcess = spawn('git', [
-                    'grep', '-n', '-I',
-                    caseFlag ? '' : '-i',
-                    regexFlag ? '-E' : '-F',
-                    escapedQuery
-                ], {
-                    cwd: searchPath,
-                    stdio: ['ignore', 'pipe', 'pipe']
+                const result = await handleReadFileInternal({ 
+                    path: filePath, 
+                    start_line, 
+                    end_line,
+                    max_lines: max_lines_per_file 
                 });
+                return { path: filePath, ...result, success: true };
+            } catch (error) {
+                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`;
+    output += `========================================\n\n`;
+    
+    // Add each file's content
+    results.forEach((result, index) => {
+        output += `[${index + 1}/${filePaths.length}] `;
+        if (result.success) {
+            output += `✅ ${result.path} (${result.lines} lines)\n`;
+            output += `----------------------------------------\n`;
+            // Truncate content if too long
+            const contentPreview = result.content?.substring(0, 5000);
+            output += contentPreview;
+            if (result.content?.length > 5000) {
+                output += `\n... (${result.content.length - 5000} more chars)`;
+            }
+        } else {
+            output += `❌ ${result.path}\n`;
+            output += `Error: ${result.error}\n`;
+        }
+        output += `\n\n`;
+    });
+    
+    // Report audit for batch operation
+    reportAudit({
+        tool: 'read_file',
+        instruction: `Batch read: ${filePaths.join(', ').substring(0, 200)}`,
+        status: failed === 0 ? 'success' : 'partial',
+        latency_ms: Date.now() - start,
+        files_count: filePaths.length,
+        input_tokens: Math.ceil(filePaths.join(',').length / 4),
+        output_tokens: Math.ceil(output.length / 4)
+    });
+    
+    return {
+        content: [{ type: "text", text: output }]
+    };
+}
 
-                const readline = (await import('readline')).createInterface({
-                    input: gitProcess.stdout,
-                    crlfDelay: Infinity
-                });
+/**
+ * INTERNAL: Handle single file read with line range and max_lines limit
+ */
+async function handleReadFileInternal({ path: filePath, start_line, end_line, max_lines }) {
+    const absolutePath = path.resolve(filePath);
+    const stats = await fs.stat(absolutePath);
 
-                for await (const line of readline) {
-                    if (results.length >= MAX_RESULTS) {
-                        gitProcess.kill();
-                        break;
-                    }
-                    results.push(line);
-                }
+    if (!stats.isFile()) {
+        throw new Error(`Path is not a file: ${absolutePath}`);
+    }
 
-                gitProcess.stderr.on('data', () => { });
-                await new Promise(resolve => gitProcess.on('close', resolve));
-
-                return formatSearchResults(query, strategy, results, start, MAX_RESULTS);
-            } catch (gitErr) {
-                // Fallback to native grep
-                strategy = 'native_grep';
-                const grepProcess = spawn('grep', [
-                    '-r', '-n', '-I',
-                    caseFlag ? '' : '-i',
-                    regexFlag ? '-E' : '-F',
-                    '--exclude-dir=node_modules', '--exclude-dir=.git',
-                    '--exclude-dir=.next', '--exclude-dir=dist', '--exclude-dir=build',
-                    escapedQuery,
-                    searchPath
-                ], {
-                    stdio: ['ignore', 'pipe', 'pipe']
-                });
+    const STREAM_THRESHOLD = 1024 * 1024; // 1MB
+    
+    let startLine = start_line ? parseInt(start_line) : 1;
+    let endLine = end_line ? parseInt(end_line) : -1;
+    let outputContent;
+    let totalLines;
 
-                const readline = (await import('readline')).createInterface({
-                    input: grepProcess.stdout,
-                    crlfDelay: Infinity
-                });
+    if ((stats.size > STREAM_THRESHOLD && (start_line || end_line)) || stats.size > 10 * 1024 * 1024) {
+        const { Readable } = await import('stream');
+        const { createInterface } = await import('readline');
 
-                for await (const line of readline) {
-                    if (results.length >= MAX_RESULTS) {
-                        grepProcess.kill();
-                        break;
-                    }
-                    results.push(line);
-                }
+        let currentLine = 0;
+        const lines = [];
 
-                grepProcess.stderr.on('data', () => { });
-                await new Promise(resolve => grepProcess.on('close', resolve));
+        const stream = (await import('fs')).createReadStream(absolutePath, { encoding: 'utf8' });
+        const rl = createInterface({ input: stream, crlfDelay: Infinity });
 
-                return formatSearchResults(query, strategy, results, start, MAX_RESULTS);
+        for await (const line of rl) {
+            currentLine++;
+            if (startLine && endLine) {
+                if (currentLine >= startLine && currentLine <= endLine) {
+                    lines.push(line);
+                }
+                if (currentLine >= endLine) break;
+            } else if (startLine && currentLine >= startLine) {
+                lines.push(line);
+                if (max_lines && lines.length >= max_lines) break;
+            } else if (lines.length < (max_lines || 2000)) {
+                lines.push(line);
+            } else {
+                break;
             }
         }
 
-        return formatSearchResults(query, strategy, results, start, MAX_RESULTS);
-
-    } catch (error) {
-        reportAudit({
-            tool: 'search_filesystem',
-            instruction: query,
-            status: 'error',
-            error_message: error.message,
-            latency_ms: Date.now() - start,
-            input_tokens: Math.ceil(query.length / 4),
-            output_tokens: 0
-        });
-        return {
-            content: [{ type: "text", text: `❌ search_filesystem error: ${error.message}` }],
-            isError: true
-        };
-    }
-}
-
-function formatSearchResults(query, strategy, results, start, maxResults) {
-    let output = `⚡ search_filesystem (${strategy}) found ${results.length} results for "${query}"\n\n`;
-
-    if (results.length === 0) {
-        output += "No matches found.";
+        stream.destroy();
+        outputContent = lines.join('\n');
+        totalLines = currentLine;
     } else {
-        output += results.join('\n');
-        if (results.length >= maxResults) {
-            output += `\n... and more matches (early termination at ${maxResults}).`;
+        const content = await fs.readFile(absolutePath, 'utf8');
+        const lines = content.split('\n');
+        totalLines = lines.length;
+
+        if (startLine < 1) startLine = 1;
+        if (endLine < 1 || endLine > totalLines) endLine = totalLines;
+        if (startLine > endLine) {
+            throw new Error(`Invalid line range: start_line (${startLine}) > end_line (${endLine})`);
         }
-    }
 
-    const estimatedOutputTokens = Math.ceil(output.length / 4);
-
-    reportAudit({
-        tool: 'search_filesystem',
-        instruction: query,
-        strategy,
-        status: 'success',
-        latency_ms: Date.now() - start,
-        files_count: 0,
-        input_tokens: Math.ceil(query.length / 4),
-        output_tokens: estimatedOutputTokens,
-        result_summary: JSON.stringify(results.slice(0, maxResults))
-    });
+        if (start_line || end_line) {
+            outputContent = lines.slice(startLine - 1, endLine).join('\n');
+        } else if (max_lines && lines.length > max_lines) {
+            outputContent = lines.slice(0, max_lines).join('\n');
+        } else {
+            outputContent = content;
+        }
+    }
 
-    return { content: [{ type: "text", text: output }] };
+    return {
+        content: outputContent,
+        lines: outputContent.split('\n').length,
+        size: outputContent.length,
+        totalLines,
+        path: filePath
+    };
 }
 
-// Native high-performance search
+/**
+ * Native high-performance search
+ */
 async function handleWarpgrep({ query, include = ".", isRegex = false, caseSensitive = false }) {
     const start = Date.now();
     try {