# Advanced MCP Text Editor Server

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)
![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)

## Overview

A comprehensive **Model Context Protocol (MCP) Text Editor Server** that provides advanced file editing capabilities with enhanced security, backup management, and session isolation. Designed for AI assistants like Claude Code, Cursor Agent CLI, and other development environments.

### Key Features

- 🔒 **Enhanced Security**: Path validation, directory traversal prevention, system file protection
- 💾 **Automatic Backup Management**: Up to 10 backups per file with timestamp tracking
- 📁 **Comprehensive File Operations**: View, create, edit, insert, replace, and undo
- 🚫 **Smart Error Handling**: Detailed error messages and validation
- 📊 **File Information**: Detailed file stats and metadata
- ⚡ **High Performance**: Optimized for large files with configurable limits
- 🔄 **Undo Capability**: Revert recent changes with full backup restoration

## Quick Start

### Prerequisites

- Node.js 18.0 or higher
- TypeScript 5.0 or higher

### Installation

```bash
# Clone and setup
git clone https://github.com/stat-guy/text-editor.git
cd text-editor

# Install dependencies
npm install

# Build the server (REQUIRED - compiles TypeScript to JavaScript)
npm run build

# Test the installation
npm test
```

### Important: Build Process

This project is written in **TypeScript** but runs as **JavaScript**:

- **Source Code**: `src/index.ts` (human-readable TypeScript)
- **Executable**: `dist/index.js` (compiled JavaScript - this is what Node.js runs)
- **Build Command**: `npm run build` compiles `src/` → `dist/`

⚠️ **Critical**: Always use `dist/index.js` as the entry point, not `src/index.ts`

### Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "text-editor": {
      "command": "node",
      "args": ["/absolute/path/to/text-editor/dist/index.js"]
    }
  }
}
```

**Note**: The path points to `dist/index.js` (compiled), not `src/index.ts` (source).

## Tools Available

### 1. `view` - View Files and Directories

View file contents or list directory contents with optional line range and character limits.

**Parameters:**
- `path` (string): File or directory path
- `view_range` (optional): Array of [start_line, end_line] for partial viewing
- `max_characters` (optional): Maximum characters to return (default: 100,000)

**Examples:**
```typescript
// View entire file
{ "path": "src/index.ts" }

// View specific lines
{ "path": "src/index.ts", "view_range": [10, 50] }

// Limit output size
{ "path": "large-file.txt", "max_characters": 5000 }
```

### 2. `str_replace` - Replace Text

Replace specific text in a file with new content. Ensures exactly one match for safety.

**Parameters:**
- `path` (string): File path to modify
- `old_str` (string): Exact text to replace
- `new_str` (string): Replacement text

**Example:**
```typescript
{
  "path": "config.json",
  "old_str": "\"debug\": false",
  "new_str": "\"debug\": true"
}
```

### 3. `create` - Create Files

Create new files with specified content. Automatically creates parent directories.

**Parameters:**
- `path` (string): Path for new file
- `file_text` (string): File content

**Example:**
```typescript
{
  "path": "docs/new-feature.md",
  "file_text": "# New Feature\n\nThis is a new feature documentation."
}
```

### 4. `insert` - Insert Text

Insert text at specific line numbers in existing files.

**Parameters:**
- `path` (string): File path to modify
- `insert_line` (number): Line number to insert after (0 for beginning)
- `new_str` (string): Text to insert

**Example:**
```typescript
{
  "path": "src/utils.ts",
  "insert_line": 5,
  "new_str": "// New utility function\nexport function newUtil() { return true; }"
}
```

### 5. `undo_edit` - Revert Changes

Revert the last edit made to a file using automatic backups.

**Parameters:**
- `path` (string): File path to revert

**Example:**
```typescript
{ "path": "src/index.ts" }
```

### 6. `file_info` - File Information

Get detailed information about files and directories including size, permissions, and backup status.

**Parameters:**
- `path` (string): File or directory path

**Example:**
```typescript
{ "path": "src/index.ts" }
```

## Security Features

### Path Validation
- Prevents directory traversal attacks (`../` patterns)
- Blocks access to system directories (`/etc`, `/bin`, `/proc`, etc.)
- Validates all file paths before operations

### File Size Limits
- Maximum file size: 50MB (configurable)
- Character output limits to prevent memory issues
- Early validation to prevent resource exhaustion

### Backup Management
- Automatic backups before any modification
- Up to 10 backups per file with rotation
- Timestamped backup tracking
- Safe undo operations

## Performance Characteristics

- **File Operations**: 0.01-0.1 seconds for typical files
- **Large Files**: Optimized handling up to 50MB
- **Memory Usage**: Efficient streaming for large content
- **Backup Storage**: In-memory with automatic cleanup

## Error Handling

The server provides detailed error messages for:
- Invalid file paths or access denied
- File not found or permission errors
- Multiple matches in str_replace operations
- Invalid line numbers for insert operations
- Missing backups for undo operations

## Development

### Building

```bash
npm run build    # Build TypeScript to JavaScript
npm run dev      # Watch mode for development
npm run clean    # Clean build artifacts
```

### Testing

```bash
npm test         # Run basic functionality test
npm start        # Start server directly
```

## Architecture

### Core Components

- **Server Setup**: MCP server with STDIO transport
- **Tool Registration**: Zod-based parameter validation
- **File Operations**: Promise-based async file handling
- **Backup System**: In-memory backup store with rotation
- **Security Layer**: Path validation and access control

### Project Structure

```
/Users/kairi/text-editor/
├── src/
│   └── index.ts           # TypeScript source code (development)
├── dist/                  # Build output (what actually runs)
│   └── index.js           # ← Compiled JavaScript entry point
├── package.json           # Dependencies and build scripts
├── tsconfig.json          # TypeScript compiler configuration
├── README.md             # This documentation
├── LICENSE               # MIT license
├── examples/             # Usage examples and config
└── node_modules/         # Dependencies (after npm install)
```

**Key Points:**
- **Development**: Edit `src/index.ts`
- **Execution**: Node.js runs `dist/index.js`
- **Build Process**: `npm run build` compiles TypeScript → JavaScript
- **Entry Point**: Always use `dist/index.js` for MCP configuration

## Comparison with Anthropic's Text Editor Tool

| Feature | Anthropic Tool | This MCP Server |
|---------|---------------|-----------------|
| Basic file operations | ✅ | ✅ |
| Undo functionality | Limited | ✅ Enhanced |
| Backup management | None | ✅ Automatic |
| Security validation | Basic | ✅ Advanced |
| File size limits | None | ✅ Configurable |
| Error handling | Basic | ✅ Comprehensive |
| File information | None | ✅ Detailed stats |

## Contributing

1. Fork the repository
2. Create a feature branch
3. Implement your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

- GitHub Issues: [Report bugs or request features](https://github.com/stat-guy/text-editor/issues)
- Documentation: Full API documentation in `/docs`
- Examples: Usage examples in `/examples`

## Roadmap

- [ ] File watching capabilities
- [ ] Multi-file operations
- [ ] Advanced search and replace with regex
- [ ] File encryption support
- [ ] Integration with version control systems