mcp-text-editor 1.0.0__tar.gz

mcp_text_editor-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,69 @@
+name: Publish
+on:
+  push:
+    tags:
+      - "v*"
+    strategy:
+      matrix:
+        python-version: ["3.11"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: |
+          python -m pip install --upgrade pip
+          pip install uv
+
+      - name: Install dev/test dependencies
+        run: |
+          pip install -e ".[dev]"
+          pip install -e ".[test]"
+
+      - name: Run tests
+        run: |
+          make check
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Update version from tag
+        run: |
+          # Strip 'v' prefix from tag and update version.py
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "__version__ = \"${VERSION}\"" > src/mcp_text_editor/version.py
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: |
+          python -m pip install --upgrade pip
+          pip install uv
+
+      - name: Build package
+        run: |
+          uv build
+
+      - name: Publish to PyPI
+        env:
+          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          uv publish --token $PYPI_TOKEN

mcp_text_editor-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,45 @@
+name: Test
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: |
+          python -m pip install --upgrade pip
+          pip install uv
+
+      - name: Install dev/test dependencies
+        run: |
+          pip install -e ".[dev]"
+          pip install -e ".[test]"
+
+      - name: Run lint and typecheck
+        run: |
+          make lint typecheck
+
+      - name: Run tests with coverage
+        run: |
+          pytest --cov --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

mcp_text_editor-1.0.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environment
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.coverage
+.coverage.*
+.pytest_cache/
+htmlcov/
+
+# Distribution
+*.tar.gz
+
+# Logs
+*.log
+prompt.md

mcp_text_editor-1.0.0/.python-version

@@ -0,0 +1 @@
+3.11

mcp_text_editor-1.0.0/Makefile

@@ -0,0 +1,27 @@
+.PHONY: test format lint typecheck check coverage
+.DEFAULT_GOAL := all
+
+test:
+	pytest
+
+coverage:
+	pytest --cov=mcp_text_editor --cov-report=term-missing
+
+format:
+	black src tests
+	isort src tests
+	ruff check --fix src tests
+
+
+lint:
+	black --check src tests
+	isort --check src tests
+	ruff check src tests
+
+typecheck:
+	mypy src tests
+
+# Run all checks required before pushing
+check:  lint typecheck test
+fix: check format
+all: format check

mcp_text_editor-1.0.0/PKG-INFO

@@ -0,0 +1,434 @@
+Metadata-Version: 2.3
+Name: mcp-text-editor
+Version: 1.0.0
+Summary: MCP Text Editor Server - Edit text files via MCP protocol
+Author: tumf
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: asyncio>=3.4.3
+Requires-Dist: mcp>=1.1.0
+Provides-Extra: dev
+Requires-Dist: black>=23.3.0; extra == 'dev'
+Requires-Dist: isort>=5.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.2.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.2.2; extra == 'dev'
+Requires-Dist: ruff>=0.0.262; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'test'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'test'
+Requires-Dist: pytest-env>=1.1.0; extra == 'test'
+Requires-Dist: pytest-mock>=3.12.0; extra == 'test'
+Requires-Dist: pytest>=8.3.4; extra == 'test'
+Description-Content-Type: text/markdown
+
+# MCP Text Editor Server
+
+[![codecov](https://codecov.io/gh/tumf/mcp-text-editor/graph/badge.svg?token=52D51U0ZUR)](https://codecov.io/gh/tumf/mcp-text-editor)
+
+A Model Context Protocol (MCP) server that provides text file editing capabilities through a standardized API.
+
+## Overview
+
+MCP Text Editor Server is designed to facilitate safe and efficient text file operations in a client-server architecture. It implements the Model Context Protocol, ensuring reliable file editing with robust conflict detection and resolution. This makes it ideal for applications requiring synchronized file access, such as collaborative editing tools, automated text processing systems, or any scenario where multiple processes need to modify text files safely.
+
+### Key Benefits
+
+- Safe concurrent editing with hash-based validation
+- Efficient partial file access with line-range specifications
+- Atomic multi-file operations
+- Robust error handling and recovery mechanisms
+
+
+## Features
+
+- Get text file contents with line range specification
+- Read multiple ranges from multiple files in a single operation
+- Edit text file contents with conflict detection
+- Support for multiple file operations
+- Proper handling of concurrent edits with hash-based validation
+- Line-based patch application with correct handling of line number shifts
+- Robust error handling and validation
+- Memory-efficient processing of large files
+
+
+## Requirements
+
+- Python 3.11 or higher
+- POSIX-compliant operating system (Linux, macOS, etc.) or Windows
+- Sufficient disk space for text file operations
+- File system permissions for read/write operations
+
+
+1. Install Python 3.11+
+
+```bash
+pyenv install 3.11.6
+pyenv local 3.11.6
+```
+
+2. Install uv (recommended) or pip
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+3. Create virtual environment and install dependencies
+
+```bash
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install -e ".[dev]"
+```
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+Start the server:
+
+```bash
+python -m mcp_text_editor
+```
+
+### MCP Tools
+
+The server provides two main tools:
+
+#### get_text_file_contents
+
+Get the contents of one or more text files with line range specification.
+
+**Single Range Request:**
+
+```json
+{
+  "file_path": "path/to/file.txt",
+  "line_start": 1,
+  "line_end": 10
+}
+```
+
+**Multiple Ranges Request:**
+
+```json
+{
+  "files": [
+    {
+      "file_path": "file1.txt",
+      "ranges": [
+        {"start": 1, "end": 10},
+        {"start": 20, "end": 30}
+      ]
+    },
+    {
+      "file_path": "file2.txt",
+      "ranges": [
+        {"start": 5, "end": 15}
+      ]
+    }
+  ]
+}
+```
+
+Parameters:
+- `file_path`: Path to the text file
+- `line_start`/`start`: Line number to start from (1-based)
+- `line_end`/`end`: Line number to end at (inclusive, null for end of file)
+
+**Single Range Response:**
+
+```json
+{
+  "contents": "File contents",
+  "line_start": 1,
+  "line_end": 10,
+  "hash": "sha256-hash-of-contents",
+  "file_lines": 50,
+  "file_size": 1024
+}
+```
+
+**Multiple Ranges Response:**
+
+```json
+{
+  "file1.txt": [
+    {
+      "content": "Lines 1-10 content",
+      "start_line": 1,
+      "end_line": 10,
+      "hash": "sha256-hash-1",
+      "total_lines": 50,
+      "content_size": 512
+    },
+    {
+      "content": "Lines 20-30 content",
+      "start_line": 20,
+      "end_line": 30,
+      "hash": "sha256-hash-2",
+      "total_lines": 50,
+      "content_size": 512
+    }
+  ],
+  "file2.txt": [
+    {
+      "content": "Lines 5-15 content",
+      "start_line": 5,
+      "end_line": 15,
+      "hash": "sha256-hash-3",
+      "total_lines": 30,
+      "content_size": 256
+    }
+  ]
+}
+```
+
+#### edit_text_file_contents
+
+Edit text file contents with conflict detection. Supports editing multiple files in a single operation.
+
+**Request Format:**
+
+```json
+{
+  "files": [
+    {
+      "path": "file1.txt",
+      "hash": "sha256-hash-from-get-contents",
+      "patches": [
+        {
+          "line_start": 5,
+          "line_end": 8,
+          "contents": "New content for lines 5-8\n"
+        },
+        {
+          "line_start": 15,
+          "line_end": 15,
+          "contents": "Single line replacement\n"
+        }
+      ]
+    },
+    {
+      "path": "file2.txt",
+      "hash": "sha256-hash-from-get-contents",
+      "patches": [
+        {
+          "line_start": 1,
+          "line_end": 3,
+          "contents": "Replace first three lines\n"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Important Notes:
+1. Always get the current hash using get_text_file_contents before editing
+2. Patches are applied from bottom to top to handle line number shifts correctly
+3. Patches must not overlap within the same file
+4. Line numbers are 1-based
+5. If original content ends with newline, ensure patch content also ends with newline
+
+**Success Response:**
+
+```json
+{
+  "file1.txt": {
+    "result": "ok",
+    "hash": "sha256-hash-of-new-contents"
+  },
+  "file2.txt": {
+    "result": "ok",
+    "hash": "sha256-hash-of-new-contents"
+  }
+}
+```
+
+**Error Response:**
+
+```json
+{
+  "file1.txt": {
+    "result": "error",
+    "reason": "File not found",
+    "hash": null
+  },
+  "file2.txt": {
+    "result": "error",
+    "reason": "Content hash mismatch - file was modified",
+    "hash": "current-hash",
+    "content": "Current file content"
+  }
+}
+```
+
+### Common Usage Pattern
+
+1. Get current content and hash:
+
+```python
+contents = await get_text_file_contents({
+    "files": [
+        {
+            "file_path": "file.txt",
+            "ranges": [{"start": 1, "end": null}]  # Read entire file
+        }
+    ]
+})
+```
+
+2. Edit file content:
+
+```python
+result = await edit_text_file_contents({
+    "files": [
+        {
+            "path": "file.txt",
+            "hash": contents["file.txt"][0]["hash"],
+            "patches": [
+                {
+                    "line_start": 5,
+                    "line_end": 8,
+                    "contents": "New content\n"
+                }
+            ]
+        }
+    ]
+})
+```
+
+3. Handle conflicts:
+
+```python
+if result["file.txt"]["result"] == "error":
+    if "hash mismatch" in result["file.txt"]["reason"]:
+        # File was modified by another process
+        # Get new content and retry
+        pass
+```
+
+### Error Handling
+
+The server handles various error cases:
+- File not found
+- Permission errors
+- Hash mismatches (concurrent edit detection)
+- Invalid patch ranges
+- Overlapping patches
+- Line number out of bounds
+
+## Security Considerations
+
+- File Path Validation: The server validates all file paths to prevent directory traversal attacks
+- Access Control: Proper file system permissions should be set to restrict access to authorized directories
+- Hash Validation: All file modifications are validated using SHA-256 hashes to prevent race conditions
+- Input Sanitization: All user inputs are properly sanitized and validated
+- Error Handling: Sensitive information is not exposed in error messages
+
+## Troubleshooting
+
+### Common Issues
+
+1. Permission Denied
+   - Check file and directory permissions
+   - Ensure the server process has necessary read/write access
+
+2. Hash Mismatch Errors
+   - The file was modified by another process
+   - Fetch latest content and retry the operation
+
+3. Connection Issues
+   - Verify the server is running and accessible
+   - Check network configuration and firewall settings
+
+4. Performance Issues
+   - Consider using smaller line ranges for large files
+   - Monitor system resources (memory, disk space)
+
+## Development
+
+### Setup
+
+1. Clone the repository
+2. Create and activate a Python virtual environment
+3. Install development dependencies: `pip install -e ".[dev]"`
+4. Run tests: `pytest`
+
+### Code Quality Tools
+
+- Ruff for linting
+- Black for code formatting
+- isort for import sorting
+- mypy for type checking
+- pytest-cov for test coverage
+
+### Testing
+
+Tests are located in the `tests` directory and can be run with pytest:
+
+```bash
+# Run all tests
+pytest
+
+# Run tests with coverage report
+pytest --cov=mcp_text_editor --cov-report=term-missing
+
+# Run specific test file
+pytest tests/test_text_editor.py -v
+```
+
+Current test coverage: 90%
+
+### Project Structure
+
+```
+mcp-text-editor/
+├── mcp_text_editor/
+│   ├── __init__.py
+│   ├── __main__.py      # Entry point
+│   ├── models.py        # Data models
+│   ├── server.py        # MCP Server implementation
+│   ├── service.py       # Core service logic
+│   └── text_editor.py   # Text editor functionality
+├── tests/               # Test files
+└── pyproject.toml       # Project configuration
+```
+
+## License
+
+MIT
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests and code quality checks
+5. Submit a pull request
+
+### Type Hints
+
+This project uses Python type hints throughout the codebase. Please ensure any contributions maintain this.
+
+### Error Handling
+
+All error cases should be handled appropriately and return meaningful error messages. The server should never crash due to invalid input or file operations.
+
+### Testing
+
+New features should include appropriate tests. Try to maintain or improve the current test coverage.
+
+### Code Style
+
+All code should be formatted with Black and pass Ruff linting. Import sorting should be handled by isort.