stat-guy/text-editor

Advanced MCP Text Editor Server

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

# 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:

{
  "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:

// 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:

{
  "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:

{
  "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:

{
  "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:

{ "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:

{ "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

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

Testing

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

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
• 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