MCP 服务器

Advanced MCP Text Editor Server

Enables AI assistants to perform advanced file editing operations with enhanced security, automatic backups, and undo functionality.

README

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

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