# MCP File Editor Server

A comprehensive Model Context Protocol (MCP) server that provides advanced file operations for reading, writing, searching, and editing files. This server offers 10 powerful tools for file manipulation with robust error handling and comprehensive test coverage.

## Features

### Core Tools

1. **`read_file`** - Read file contents with flexible options
   - Full file reading or specific line ranges
   - Optional line number prefixes
   - Support for partial file reading

2. **`replace_in_file`** - Regex-based string replacement
   - Single or multiple occurrence replacement
   - Complex regex pattern support
   - Safe replacement with occurrence limits

3. **`delete_from_file`** - Remove content between line numbers
   - Line content verification for safety
   - Single or multi-line deletion
   - Precise line range targeting

4. **`insert_into_file`** - Insert content at specific positions
   - Before/after line placement
   - End-of-file appending
   - Line content verification

5. **`replace_lines_in_file`** - Replace content between lines
   - Multi-line content replacement
   - Line content verification
   - Flexible content insertion

6. **`multireplace_lines_in_file`** - Multiple line replacements with automatic adjustment

   - Perform multiple edits in a single operation
   - Automatic line number adjustment after each edit
   - Detailed success/failure reporting for each edit
   - Handles complex line shifting scenarios

7. **`search_file`** - Search within individual files
   - Regex pattern matching
   - Context lines (before/after)
   - Detailed match reporting

8. **`list_files`** - Directory content listing
   - File and directory enumeration
   - File size information
   - Recursive directory support

9. **`search_directory`** - Search across multiple files
   - Directory-wide regex search
   - Include/exclude pattern filtering
   - Recursive subdirectory searching

10. **`create_file`** - Create new files with automatic directory creation
   - Safe file creation with overwrite protection
   - Automatic directory structure creation
   - Comprehensive error handling for file system operations

### Key Features

- **Robust Error Handling**: User-friendly error messages with actionable guidance
- **Path Validation**: Absolute path enforcement with helpful error messages
- **Content Verification**: Line content verification to prevent accidental edits
- **Comprehensive Testing**: 80 test cases covering all functionality
- **TypeScript Implementation**: Full type safety and modern JavaScript features
- **FastMCP Framework**: Built on the FastMCP library for optimal performance

## Installation

### Prerequisites

- Node.js 16.x or later
- npm or yarn package manager

### Install Dependencies

```bash
npm install
```

### Build the Project

```bash
npm run build
```

## Usage

### Cursor-compatible MCP server config

```json
"mcpServers": {
   "file-edit": {
      "command": "npx",
      "args": ["mcp-file-editor@latest"]
   }
}
```

[![Add MCP Server file-edit to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=file-edit&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJtY3AtZmlsZS1lZGl0b3JAbGF0ZXN0Il19)

### Starting the Server

```bash
node build/index.js
```

The server will start and listen for MCP client connections via stdio transport.

### MCP Client Integration

This server is designed to work with MCP-compatible clients. The server communicates via stdio and supports the following MCP tools:

#### Example Tool Usage

```javascript
// Read a file
const result = await client.callTool({
  name: 'read_file',
  arguments: {
    file_path: '/absolute/path/to/file.txt',
    show_line_numbers: true,
    start_line: 1,
    end_line: 10
  }
});

// Search for patterns
const searchResult = await client.callTool({
  name: 'search_directory',
  arguments: {
    directory_path: '/path/to/search',
    regexp: 'TODO|FIXME',
    recursive: true
  }
});

// Multiple line replacements with automatic adjustment
const multiEditResult = await client.callTool({
  name: 'multireplace_lines_in_file',
  arguments: {
    file_path: '/path/to/file.txt',
    edits: [
      {
        line_start: 10,
        line_end: 15,
        line_start_contents: 'Line 10: Tenth line',
        contents: 'REPLACED LINES 10-15\nWith new content'
      },
      {
        line_start: 25,
        line_end: 30,
        line_start_contents: 'Line 25: Twenty-fifth line',
        contents: 'REPLACED LINES 25-30\nWith different content'
      }
    ]
  }
});

// Create a new file
const createResult = await client.callTool({
  name: 'create_file',
  arguments: {
    file_path: '/absolute/path/to/new-file.txt',
    contents: 'This is the content of the new file.\nIt can span multiple lines.'
  }
});
```

## Testing

Run the comprehensive test suite:

```bash
npm test
```

The test suite includes:

- **80 total tests** across 5 test files
- Unit tests for all 10 tools
- Error handling validation
- Edge case coverage
- Integration testing with MCP client

### Test Coverage

- `read-file.test.ts` - 16 tests for file reading operations
- `editing-tools.test.ts` - 26 tests for file modification tools (including multireplace_lines_in_file)
- `search-tools.test.ts` - 22 tests for search and directory operations
- `utils.test.ts` - 16 tests for utility functions
- `create_file.test.ts` - 7 tests for file creation operations

## API Reference

### Tool Parameters

#### read_file

- `file_path` (string, required): Absolute path to the file
- `show_line_numbers` (boolean, optional): Prefix lines with numbers
- `start_line` (number, optional): Starting line number (1-based)
- `end_line` (number, optional): Ending line number (1-based)
- `full` (boolean, optional): Read entire file (mutually exclusive with line ranges)

#### replace_in_file

- `file_path` (string, required): Absolute path to the file
- `regex_source` (string, required): Regular expression pattern
- `target` (string, required): Replacement string
- `multiple` (boolean, optional): Allow multiple replacements

#### delete_from_file

- `file_path` (string, required): Absolute path to the file
- `line_start` (number, required): Starting line number
- `line_end` (number, required): Ending line number
- `line_start_contents` (string, required): Expected content of starting line

#### insert_into_file

- `file_path` (string, required): Absolute path to the file
- `line_number` (number, required): Target line number (0 for end)
- `line_contents` (string, required): Expected content of target line
- `where` (enum, required): 'before' or 'after'
- `contents` (string, required): Content to insert

#### replace_lines_in_file

- `file_path` (string, required): Absolute path to the file
- `line_start` (number, required): Starting line number
- `line_end` (number, required): Ending line number
- `line_start_contents` (string, required): Expected content of starting line
- `contents` (string, required): Replacement content

#### multireplace_lines_in_file

- `file_path` (string, required): Absolute path to the file
- `edits` (array, required): Array of edit operations
  - `line_start` (number, required): Starting line number (1-based)
  - `line_end` (number, required): Ending line number (1-based)
  - `line_start_contents` (string, required): Expected content of starting line
  - `contents` (string, required): New content to replace the lines with

#### search_file

- `file_path` (string, required): Absolute path to the file
- `regexp` (string, required): Regular expression pattern
- `lines_before` (number, optional): Context lines before matches
- `lines_after` (number, optional): Context lines after matches

#### list_files

- `directory_path` (string, required): Absolute path to the directory

#### search_directory

- `directory_path` (string, required): Absolute path to the directory
- `regexp` (string, required): Regular expression pattern
- `recursive` (boolean, optional): Search subdirectories
- `lines_before` (number, optional): Context lines before matches
- `lines_after` (number, optional): Context lines after matches
- `include` (string, optional): File pattern to include
- `exclude` (string, optional): File/directory pattern to exclude

#### create_file

- `file_path` (string, required): Absolute path to the file to be created
- `contents` (string, required): Content to write into the new file

## Error Handling

The server provides detailed error messages for common issues:

- **Path validation**: Clear messages for relative paths and non-existent files
- **Content verification**: Helpful guidance when line content doesn't match
- **File operations**: Descriptive errors for read/write failures
- **Parameter validation**: Specific guidance for invalid parameters

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

## License

This project is licensed under the MIT License. See LICENSE file for details.

## Version History

- **v1.1.0** – Added `create_file` tool for creating files with automatic directory creation and safe‑overwrite protection.

## Architecture

The server is built with:

- **TypeScript** for type safety and modern JavaScript features
- **FastMCP** framework for MCP protocol implementation
- **Zod** for schema validation
- **Vitest** for comprehensive testing
- **fs-extra** for enhanced file system operations

The architecture follows clean separation of concerns with:

- Main server implementation in `src/index.ts`
- Utility functions in `src/utils.ts`
- Comprehensive test suite with proper MCP client integration
- Modular tool implementations with consistent error handling