MCP Text Editor

🚀 MCP Text Editor

MCP Text Editor is a text-based collaborative tool that allows users to read, write, and update files via the HTTP API. Designed for real-time collaborative scenarios, this tool supports multiple users editing the same file simultaneously and provides conflict detection and resolution mechanisms.

🚀 Quick Start

Core Functional Modules

1. Retrieve File Content
   • Read file content from a specified path.
   • Support retrieving partial file content by range (line numbers).
2. Edit File Content
   • Insert or overwrite file content at a specified position.
   • Support submitting multiple modifications at once.
   • Provide a conflict detection mechanism to avoid data inconsistencies caused by concurrent editing.
3. Error Handling and Recovery
   • Detect file status changes (e.g., modified by other processes).
   • Provide detailed error information when conflicts are detected, facilitating user retries or repairs.

Common Use Cases

1. Get Current Content

contents = await get_text_file_contents({
    "files": [
        {
            "file_path": "file.txt",
            "ranges": [{"start": 1, "end": null}]  # Read the entire file
        }
    ]
})

2. Edit File Content

result = await edit_text_file_contents({
    "files": [
        {
            "path": "file.txt",
            "hash": contents["file.txt"][0]["hash"],
            "encoding": "utf-8",  # Optional, default is "utf-8"
            "patches": [
                {
                    "line_start": 5,
                    "line_end": 8,
                    "contents": "New content\n"
                }
            ]
        }
    ]
})

3. Handle Conflicts

if result["file.txt"]["result"] == "error":
    if "hash mismatch" in result["file.txt"]["reason"]:
        # The file was modified by another process. Get the latest content and retry.
        pass

💻 Usage Examples

Basic Usage

The above code snippets demonstrate the basic operations of retrieving, editing, and handling conflicts in the MCP Text Editor.

Advanced Usage

In complex scenarios, you can combine multiple operations to achieve more functions, such as batch editing multiple files or handling concurrent editing conflicts in a more sophisticated way.

📚 Documentation

Error Handling

The server handles various error conditions:

• File not found: Validate all file paths to prevent directory traversal attacks.
• Permission denied: Check file and directory permission settings.
• Hash mismatch (Concurrent editing detection): The content was modified by another process.
• Invalid patch range: Overlapping or out-of-bounds line numbers.
• Encoding error: The specified file cannot be decoded using the specified encoding.

Security Considerations

• File path validation: The server strictly validates all file paths to prevent directory traversal attacks.
• Access control: Ensure that file system permissions are set correctly to restrict unauthorized access.
• Hash verification: All file modifications are verified using SHA-256 hash values to avoid race condition issues.
• Input sanitization: All user input is strictly sanitized and validated.
• Error handling: Error messages never expose any sensitive data.

Troubleshooting

Common Issues

1. Permission denied
   • Check file and directory permission settings.
   • Ensure that the running process has sufficient permissions to access the target file.
2. Hash mismatch
   • Retry the editing operation after getting the latest content.
   • Check the error message for specific reasons.
3. Encoding issues
   • Ensure that the specified encoding matches the actual encoding of the file.
   • Try reloading the file using a different encoding format.

Development Setup

Install Dependencies

pip install requests

Run Tests

python tests.py

Project Structure

mcp-text-editor/
├── README.md               # Project documentation
├── requirements.txt       # Project dependencies
├── src/
│   ├── __init__.py
│   ├── client.py          # HTTP client implementation
│   └── server.py          # HTTP server implementation
└── tests/
    └── test_*.py         # Test cases

License

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

Contribution Guidelines

Submit Code

git clone https://github.com/yourusername/mcp-text-editor.git
cd mcp-text-editor
git branch -b feature/new-feature
git add .
git commit -m "Add new feature"
git push origin feature/new-feature

Report Issues

• Please submit bugs or feature requests via GitHub Issues.

Code Quality Tools

black .  # Format code
flake8 .  # Check code style
mypy .  # Static type checking

Testing

Unit Testing

import unittest
from src.client import MCPClient

class TestMCPClient(unittest.TestCase):
    def setUp(self):
        self.client = MCPClient('http://localhost:8000')

    def test_get_file_contents(self):
        result = self.client.get_file_contents('file.txt')
        self.assertIsInstance(result, dict)

if __name__ == '__main__':
    unittest.main()

Integration Testing

import pytest
from src.server import MCPServer

def test_server_response():
    server = MCPServer()
    server.start()
    assert 200 in server.responses

🔧 Technical Details

Project Structure

The project is structured as follows:

• README.md: Project documentation.
• requirements.txt: Project dependencies.
• src/: Source code directory.
  • client.py: HTTP client implementation.
  • server.py: HTTP server implementation.
• tests/: Test cases directory.

Code Quality Tools

• black: Used for code formatting.
• flake8: Used for code style checking.
• mypy: Used for static type checking.

📄 License

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