fileditor-mcp 1.0.0

package/docs/README.cn.md

@@ -0,0 +1,128 @@
+# FileEditor MCP Server
+
+[📖 English Interface Doc](./MCP-INTERFACE.en.md) | [📖 中文接口文档](./MCP-INTERFACE.cn.md) | [📋 English README](../README.md)
+
+**专为 AI 编程助手优化的文件操作服务器** - 基于 Model Context Protocol 构建，针对代码编辑、重构、批量修改等AI编程场景深度优化，提供高精度、高效率的文件系统操作能力。
+
+## 🎯 设计理念
+
+**为 AI 编程而生** - 本项目专门针对 AI 模型的代码编辑需求进行设计，提供精确的块级操作、智能匹配算法和批量处理能力，让 AI 能够安全、高效地执行复杂的代码修改任务。
+
+## 🚀 核心特性
+
+### 📁 专业文件操作工具 (7个)
+- **`set_workspace`** - 安全工作区管理 (强制隔离，防止误操作)
+- **`read_files`** - 智能批量读取 (支持多文件、行范围、带行号定位)
+- **`write_files`** - 高效文件创建 (批量写入、原子性保证)
+- **`list_files`** - 完整目录遍历 (递归扫描、结构化输出)
+- **`insert_contents`** - 精确内容插入 (多点插入、负索引、末尾追加)
+- **`apply_diffs`** - **AI友好的差异应用** (智能空格处理、批量原子操作、容错匹配)
+- **`search_and_replace`** - 强大模式替换 (正则支持、范围限定、大小写控制)
+
+### 🛡️ 企业级安全保障
+- **工作区强隔离**: 严格边界控制，防止目录穿透和文件泄露
+- **路径智能解析**: 自动验证和标准化文件路径
+- **原子事务**: 批量操作要么全部成功，要么完全回滚
+
+### ⚡ AI 优化功能
+- **批量处理引擎**: 单次 API 调用处理大量文件操作
+- **智能匹配算法**: `trim` 模式处理代码格式差异，容错性强
+- **详细操作反馈**: 完整的成功/失败信息，便于 AI 调试和决策
+- **非阻塞错误处理**: 部分失败不影响其他操作继续执行
+
+## 🛠️ 快速开始
+
+```bash
+# 安装依赖 (推荐使用 pnpm)
+pnpm install
+
+# 启动生产服务器
+pnpm start
+
+# 开发模式 (文件变更自动重启)
+pnpm dev
+
+# 运行完整测试套件
+pnpm test
+```
+
+**环境要求**: Node.js ≥18, pnpm 包管理器
+
+## 💡 典型使用场景
+
+```json
+// 场景1: 工作区初始化 (必须首先执行)
+{
+  "name": "set_workspace",
+  "arguments": { "path": "/path/to/your/project" }
+}
+
+// 场景2: 批量代码文件分析
+{
+  "name": "read_files",
+  "arguments": { 
+    "path": ["src/main.js", "src/utils.js", "package.json"],
+    "line_range": "1-50"  // 可选：仅读取前50行
+  }
+}
+
+// 场景3: 智能代码重构 (容错空格差异)
+{
+  "name": "apply_diffs",
+  "arguments": {
+    "path": "src/config.js",
+    "search_content": [
+      "const API_URL = 'localhost';",
+      "const PORT = 3000;"
+    ],
+    "replace_content": [
+      "const API_URL = process.env.API_URL || 'localhost';",
+      "const PORT = process.env.PORT || 3000;"
+    ],
+    "start_line": [5, 7],
+    "atomic": true,      // 原子模式：全部成功或全部回滚
+    "trim": true         // 智能模式：忽略空格差异
+  }
+}
+```
+
+## 🏗️ 架构设计
+
+```
+src/
+├── index.js              # 服务启动入口
+├── server.js              # MCP 协议服务器
+├── tools/
+│   └── toolDefinitions.js # 工具定义和 JSON Schema
+├── handlers/              # 核心处理器 (7个)
+│   ├── applyDiff.js       # 差异应用 (支持批量+原子+智能匹配)
+│   ├── readFile.js        # 文件读取器
+│   ├── writeFile.js       # 文件写入器
+│   ├── listFiles.js       # 目录扫描器
+│   ├── insertContent.js   # 内容插入器
+│   ├── searchAndReplace.js # 模式替换器
+│   └── setWorkspace.js    # 工作区管理器
+└── utils/
+    └── fileUtils.js       # 通用文件操作库
+```
+
+**架构优势**: 高度模块化、职责明确、易于维护、便于 AI 理解和调用
+
+## 📊 质量保证
+
+- ✅ **100% 测试覆盖率** - 7个完整的处理器测试套件
+- ✅ **边界条件验证** - 异常输入和错误状态处理
+- ✅ **批量操作验证** - 原子性和一致性保证
+- ✅ **安全性测试** - 路径注入和权限验证
+
+## 🎉 为什么选择 FileEditor MCP
+
+1. **AI 原生设计** - 专门为 AI 编程助手的工作模式优化
+2. **高性能批处理** - 减少 API 调用次数，提升处理效率  
+3. **智能容错** - 处理现实代码中的格式和空格差异
+4. **企业级安全** - 严格的工作区隔离和权限控制
+5. **完整测试覆盖** - 可靠性和稳定性保证
+
+## 📄 开源协议
+
+MIT License - 欢迎贡献和使用

package/package.json

@@ -0,0 +1,27 @@
+{
+    "name": "fileditor-mcp",
+    "version": "1.0.0",
+    "description": "MCP server for file operations",
+    "main": "src/index.js",
+    "type": "module",
+    "scripts": {
+        "start": "node src/index.js",
+        "dev": "node --watch src/index.js",
+        "test": "node test/runAllTests.js"
+    },
+    "keywords": [
+        "mcp",
+        "file-operations",
+        "server"
+    ],
+    "author": "lansya",
+    "license": "MIT",
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^0.5.0",
+        "path-is-inside": "^1.0.2"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "packageManager": "pnpm@10.12.1+sha512.f0dda8580f0ee9481c5c79a1d927b9164f2c478e90992ad268bbb2465a736984391d6333d2c327913578b2804af33474ca554ba29c04a8b13060a717675ae3ac"
+}

package/src/handlers/applyDiff.js

@@ -0,0 +1,298 @@
+import { FileUtils } from '../utils/fileUtils.js';
+
+/**
+ * apply_diffs tool handler
+ */
+export class ApplyDiffHandler {
+
+    /**
+     * Format content with line numbers for error display
+     * @param {string} content - Content to format
+     * @param {number} startLine - Starting line number
+     * @returns {string} Formatted content with line numbers
+     */
+    static formatContentWithLineNumbers(content, startLine) {
+        const lines = content.split('\n');
+        return lines.map((line, index) => `${startLine + index} | ${line}`).join('\n');
+    }
+
+    /**
+     * Validate a single diff operation
+     * @param {Object} diff - Diff operation to validate
+     * @param {Array} lines - File lines
+     * @param {number} lineOffset - Current line offset
+     * @param {boolean} trim - Whether to trim whitespace when comparing
+     * @returns {Object} Validation result
+     */
+    static validateDiff(diff, lines, lineOffset, trim = false) {
+        const { search_content: searchContent, start_line: originalStartLine, originalIndex } = diff;
+
+        try {
+            // Calculate actual start line with offset
+            const actualStartLine = originalStartLine + lineOffset;
+
+            // Check if start line number exceeds current file range
+            if (actualStartLine > lines.length) {
+                throw new Error(`start_line (${originalStartLine} -> ${actualStartLine}) exceeds file length (${lines.length} lines)`);
+            }
+
+            // Split search content into line arrays
+            const searchLines = searchContent.split('\n');
+
+            // Determine the end line number for search
+            const endLine = actualStartLine + searchLines.length - 1;
+
+            // Check if search range exceeds file range
+            if (endLine > lines.length) {
+                throw new Error(`Search content extends beyond file length. Start line: ${originalStartLine} (actual: ${actualStartLine}), search lines: ${searchLines.length}, file lines: ${lines.length}`);
+            }
+
+            // Extract content to match
+            const targetLines = lines.slice(actualStartLine - 1, endLine);
+            const targetContent = targetLines.join('\n');
+
+            // Prepare content for comparison based on trim setting
+            let searchForComparison = searchContent;
+            let targetForComparison = targetContent;
+
+            if (trim) {
+                // Apply trim to each line and rejoin
+                const searchLinesForComparison = searchContent.split('\n').map(line => line.trim());
+                const targetLinesForComparison = targetLines.map(line => line.trim());
+
+                searchForComparison = searchLinesForComparison.join('\n');
+                targetForComparison = targetLinesForComparison.join('\n');
+            }
+
+            // Exact match check (using trimmed or original content based on trim setting)
+            if (targetForComparison !== searchForComparison) {
+                // Always show original content in error messages for debugging
+                const expectedFormatted = this.formatContentWithLineNumbers(searchContent, actualStartLine);
+                const actualFormatted = this.formatContentWithLineNumbers(targetContent, actualStartLine);
+                const detailedError = `Content mismatch at line ${originalStartLine} (actual: ${actualStartLine}).\n\nExpected content:\n${expectedFormatted}\n\nActual content:\n${actualFormatted}\n\nThis is diff #${originalIndex + 1} in the batch.`;
+                throw new Error(detailedError);
+            }
+
+            return {
+                success: true,
+                actualStartLine,
+                endLine,
+                searchLines
+            };
+        } catch (error) {
+            return {
+                success: false,
+                error: error.message,
+                originalIndex,
+                originalStartLine
+            };
+        }
+    }
+
+
+
+    /**
+     * Handle apply_diffs request (supports both single diff and batch diffs)
+     * @param {Object} args - Request parameters
+     * @returns {Promise<Object>} Response result
+     */
+    static async handle(args) {
+        const { path, search_content, replace_content, start_line, atomic = true, trim = false } = args;
+
+        // Check if file exists
+        if (!FileUtils.fileExists(path)) {
+            throw new Error(`File not found: ${path}`);
+        }
+
+        // Normalize all parameters to arrays
+        let searchArray, replaceArray, startLineArray;
+
+        if (Array.isArray(search_content)) {
+            searchArray = search_content;
+            replaceArray = Array.isArray(replace_content) ? replace_content : [replace_content];
+            startLineArray = Array.isArray(start_line) ? start_line : [start_line];
+        } else {
+            searchArray = [search_content];
+            replaceArray = Array.isArray(replace_content) ? replace_content : [replace_content];
+            startLineArray = Array.isArray(start_line) ? start_line : [start_line];
+        }
+
+        // Validate array lengths match
+        if (searchArray.length !== replaceArray.length || searchArray.length !== startLineArray.length) {
+            throw new Error("Array lengths for search_content, replace_content, and start_line must match");
+        }
+
+        const diffCount = searchArray.length;
+
+        // Validate all start_line values
+        for (let i = 0; i < diffCount; i++) {
+            if (startLineArray[i] < 1) {
+                throw new Error(`Invalid start_line: ${startLineArray[i]} at index ${i}. Line numbers start from 1.`);
+            }
+        }
+
+        // Create diff objects and sort by start_line
+        const diffs = searchArray.map((searchContent, index) => ({
+            search_content: searchContent,
+            replace_content: replaceArray[index],
+            start_line: startLineArray[index],
+            originalIndex: index
+        })).sort((a, b) => a.start_line - b.start_line);
+
+        // Read file content
+        const content = await FileUtils.readFile(path);
+        let lines = content.split('\n');
+        if (atomic && diffCount > 1) {
+            // Atomic mode: validate all diffs first
+            let lineOffset = 0;
+            const validationErrors = [];
+            let tempLines = [...lines]; // Work with a copy for validation
+
+            for (const diff of diffs) {
+                const validation = this.validateDiff(diff, tempLines, lineOffset, trim);
+
+                if (!validation.success) {
+                    validationErrors.push({
+                        index: validation.originalIndex,
+                        start_line: validation.originalStartLine,
+                        status: "fail",
+                        message: validation.error
+                    });
+                    break; // Stop validation on first error
+                } else {
+                    // Simulate the replacement to update tempLines and lineOffset
+                    const replaceLines = diff.replace_content.split('\n');
+                    const actualStartLine = diff.start_line + lineOffset;
+                    const endLine = actualStartLine + validation.searchLines.length - 1;
+
+                    const beforeLines = tempLines.slice(0, actualStartLine - 1);
+                    const afterLines = tempLines.slice(endLine);
+                    tempLines = [...beforeLines, ...replaceLines, ...afterLines];
+
+                    // Update line offset for next validation
+                    const lineDiff = replaceLines.length - validation.searchLines.length;
+                    lineOffset += lineDiff;
+                }
+            }
+
+            if (validationErrors.length > 0) {
+                // In atomic mode, if any diff fails, abort the entire operation
+                const results = new Array(diffCount);
+                validationErrors.forEach(error => {
+                    results[error.index] = error;
+                });
+
+                // Fill in success placeholders for non-failed diffs
+                for (let i = 0; i < diffCount; i++) {
+                    if (!results[i]) {
+                        results[i] = {
+                            index: i,
+                            start_line: startLineArray[i],
+                            status: "aborted",
+                            message: "Operation aborted due to validation failures in atomic mode"
+                        };
+                    }
+                }
+
+                // Create detailed error message with formatted content
+                let detailedMessage = `Atomic operation failed: ${validationErrors.length}/${diffCount} diffs would fail. No changes applied.\n\n`;
+                detailedMessage += "Detailed results:\n";
+                results.forEach((result, index) => {
+                    detailedMessage += `\nDiff ${index + 1}:\n`;
+                    detailedMessage += `  Status: ${result.status}\n`;
+                    detailedMessage += `  Start Line: ${result.start_line}\n`;
+                    detailedMessage += `  Message: ${result.message}\n`;
+                });
+
+                throw new Error(detailedMessage);
+            }
+        }
+
+        // Track results for each diff
+        const results = new Array(diffCount);
+        let lineOffset = 0; // Track cumulative line offset
+        let appliedCount = 0;
+
+        // Process each diff in order
+        for (const diff of diffs) {
+            const { search_content: searchContent, replace_content: replaceContent, start_line: originalStartLine, originalIndex } = diff;
+
+            if (!atomic || diffCount === 1) {
+                // Non-atomic mode or single diff: validate and apply one by one
+                const validation = this.validateDiff(diff, lines, lineOffset, trim);
+
+                if (!validation.success) {
+                    results[originalIndex] = {
+                        index: originalIndex,
+                        start_line: originalStartLine,
+                        status: "fail",
+                        message: validation.error
+                    };
+                    continue;
+                }
+            }
+
+            // Apply the diff
+            const actualStartLine = originalStartLine + lineOffset;
+            const searchLines = searchContent.split('\n');
+            const replaceLines = replaceContent.split('\n');
+            const endLine = actualStartLine + searchLines.length - 1;
+
+            // Perform replacement
+            const beforeLines = lines.slice(0, actualStartLine - 1);
+            const afterLines = lines.slice(endLine);
+            lines = [...beforeLines, ...replaceLines, ...afterLines];
+
+            // Update line offset for subsequent diffs
+            const lineDiff = replaceLines.length - searchLines.length;
+            lineOffset += lineDiff;
+            appliedCount++;
+
+            // Record success
+            results[originalIndex] = {
+                index: originalIndex,
+                start_line: originalStartLine,
+                status: "success",
+                message: `Replaced ${searchLines.length} line(s) at line ${originalStartLine}${lineDiff !== 0 ? ` (${lineDiff > 0 ? 'added' : 'removed'} ${Math.abs(lineDiff)} line(s))` : ''}`
+            };
+        }
+
+        // Write back to file
+        const newContent = lines.join('\n');
+        await FileUtils.writeFile(path, newContent);
+
+        // Build response
+        const failedCount = diffCount - appliedCount;
+        const isBatchMode = diffCount > 1;
+
+        let message;
+        if (isBatchMode) {
+            const mode = atomic ? "atomic" : "non-atomic";
+            message = `Batch diff operation (${mode}) completed: ${appliedCount}/${diffCount} diffs applied successfully to ${path}`;
+            if (failedCount > 0) {
+                message += ` (${failedCount} failed)`;
+            }
+            message += `. File now has ${lines.length} lines.\n\n`;
+
+            // Add detailed results for batch mode
+            message += "Detailed results:\n";
+            results.forEach((result, index) => {
+                message += `\nDiff ${index + 1}:\n`;
+                message += `  Status: ${result.status}\n`;
+                message += `  Start Line: ${result.start_line}\n`;
+                message += `  Message: ${result.message}\n`;
+            });
+        } else {
+            // Single mode - maintain original message format
+            const result = results[0];
+            if (result.status === "success") {
+                message = `Successfully applied diff to ${path}: ${result.message}. File now has ${lines.length} lines.`;
+            } else {
+                throw new Error(`Single diff failed:\n\n${result.message}`);
+            }
+        }
+
+        // Create success response using FileUtils
+        return FileUtils.createResponse(message);
+    }
+}

package/src/handlers/insertContent.js

@@ -0,0 +1,179 @@
+import fs from 'fs/promises';
+import { resolve } from 'path';
+import { FileUtils } from '../utils/fileUtils.js';
+
+/**
+ * insert_content tool handler
+ */
+export class InsertContentHandler {
+
+    /**
+     * Handle insert_content request
+     * @param {Object} args - Request parameters
+     * @returns {Promise<Object>} Response result
+     */
+    static async handle(args) {
+        const { path, line, content } = args;
+
+        try {
+            // Check if single file or multiple files
+            if (Array.isArray(path)) {
+                // Insert into multiple files
+                return await InsertContentHandler.insertContentMultipleFiles(path, line, content);
+            } else {
+                // Insert into single file
+                return await InsertContentHandler.insertContentSingleFile(path, line, content);
+            }
+        } catch (error) {
+            throw new Error(`Failed to insert content: ${error.message}`);
+        }
+    }
+
+    /**
+     * Insert content into a single file
+     * @param {string} filePath - File path
+     * @param {number} line - Line number
+     * @param {string} content - Content
+     * @returns {Promise<Object>} Response result
+     */
+    static async insertContentSingleFile(filePath, line, content) {
+        const fullPath = FileUtils.getSecurePath(filePath);
+
+        // Check if file exists
+        if (!FileUtils.fileExists(filePath)) {
+            throw new Error(`File not found: ${filePath}`);
+        }
+
+        // Read existing content
+        const existingContent = await FileUtils.readFile(filePath);
+        const lines = existingContent.split('\n');
+
+        // Handle insert position
+        let insertPosition;
+        if (line === 0) {
+            // 0 means end of file
+            insertPosition = lines.length;
+        } else if (line > 0) {
+            // Positive: 1-based index
+            insertPosition = line - 1; // Convert to 0-based index
+
+            // Check if insert position is valid
+            if (insertPosition > lines.length) {
+                throw new Error(`Line number ${line} exceeds file length (${lines.length} lines)`);
+            }
+        } else {
+            // Negative: calculate insert position from end
+            // -1 means before last line, -2 means before second last line, etc.
+            insertPosition = lines.length + line;
+
+            if (insertPosition < 0) {
+                throw new Error(`Negative line number ${line} is out of range for file with ${lines.length} lines`);
+            }
+        }
+
+        // Handle content to insert (may contain multiple lines)
+        const newLines = content.split('\n');
+
+        // Insert new content (both negative and positive are insert operations)
+        lines.splice(insertPosition, 0, ...newLines);
+
+        // Write back to file
+        await fs.writeFile(fullPath, lines.join('\n'), 'utf8');
+
+        // Build response message
+        let positionDesc;
+        if (line === 0) {
+            positionDesc = 'end of file';
+        } else if (line > 0) {
+            positionDesc = `line ${line}`;
+        } else {
+            positionDesc = `line ${Math.abs(line)} from end (before current line ${insertPosition + 1})`;
+        }
+
+        const message = `Successfully inserted ${newLines.length} line(s) at ${positionDesc} in ${filePath}. File now has ${lines.length} lines.`;
+        return FileUtils.createResponse(message);
+    }
+
+    /**
+     * Insert content into multiple files
+     * @param {string[]} filePaths - Array of file paths
+     * @param {number|number[]} lines - Line number or array of line numbers
+     * @param {string|string[]} contents - Content or array of contents
+     * @returns {Promise<Object>} Response result
+     */
+    static async insertContentMultipleFiles(filePaths, lines, contents) {
+        const results = [];
+        const errors = [];
+
+        // Parameter validation
+        const fileCount = filePaths.length;
+
+        // Handle line parameter (can be a single number or array)
+        let lineArray;
+        if (Array.isArray(lines)) {
+            if (lines.length !== fileCount) {
+                throw new Error(`Line array length (${lines.length}) must match file count (${fileCount})`);
+            }
+            lineArray = lines;
+        } else {
+            // If single number, apply to all files
+            lineArray = new Array(fileCount).fill(lines);
+        }
+
+        // Handle content parameter (can be a single string or array)
+        let contentArray;
+        if (Array.isArray(contents)) {
+            if (contents.length !== fileCount) {
+                throw new Error(`Content array length (${contents.length}) must match file count (${fileCount})`);
+            }
+            contentArray = contents;
+        } else {
+            // If single string, apply to all files
+            contentArray = new Array(fileCount).fill(contents);
+        }
+
+        // Perform insert operation for each file
+        for (let i = 0; i < fileCount; i++) {
+            const filePath = filePaths[i];
+            const line = lineArray[i];
+            const content = contentArray[i];
+
+            try {
+                const result = await InsertContentHandler.insertContentSingleFile(filePath, line, content);
+                results.push({
+                    file: filePath,
+                    success: true,
+                    message: result.content[0].text
+                });
+            } catch (error) {
+                errors.push({
+                    file: filePath,
+                    error: error.message
+                });
+            }
+        }
+
+        // Build return message
+        let responseText = '';
+
+        if (results.length > 0) {
+            responseText += `Successfully processed ${results.length} file(s):\n\n`;
+            for (const result of results) {
+                responseText += `✅ ${result.file}: ${result.message}\n`;
+            }
+        }
+
+        if (errors.length > 0) {
+            responseText += `\nErrors encountered:\n`;
+            for (const error of errors) {
+                responseText += `❌ ${error.file}: ${error.error}\n`;
+            }
+        }
+
+        if (results.length === 0 && errors.length > 0) {
+            throw new Error(`Failed to insert content in any files: ${errors.map(e => e.error).join(', ')}`);
+        }
+
+        return FileUtils.createResponse(responseText.trim());
+    }
+}