Merge branch 'develop'

Author: tumf

Makefile

@@ -24,4 +24,4 @@ typecheck:
 # Run all checks required before pushing
 check:  lint typecheck test
 fix: check format
-all: format check
+all: format check coverage

README.md

@@ -47,6 +47,7 @@ MCP Text Editor Server is designed to facilitate safe and efficient line-based t
 - Read multiple ranges from multiple files in a single operation
 - Line-based patch application with correct handling of line number shifts
 - Edit text file contents with conflict detection
+- Flexible character encoding support (utf-8, shift_jis, latin1, etc.)
 - Support for multiple file operations
 - Proper handling of concurrent edits with hash-based validation
 - Memory-efficient processing of large files
@@ -143,6 +144,7 @@ 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)
+- `encoding`: File encoding (default: "utf-8"). Specify the encoding of the text file (e.g., "shift_jis", "latin1")
 
 **Single Range Response:**
 
@@ -238,6 +240,7 @@ Important Notes:
 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
+6. File encoding must match the encoding used in get_text_file_contents
 
 **Success Response:**
 
@@ -295,6 +298,7 @@ result = await edit_text_file_contents({
         {
             "path": "file.txt",
             "hash": contents["file.txt"][0]["hash"],
+            "encoding": "utf-8",  # Optional, defaults to "utf-8"
             "patches": [
                 {
                     "line_start": 5,
@@ -325,6 +329,7 @@ The server handles various error cases:
 - Hash mismatches (concurrent edit detection)
 - Invalid patch ranges
 - Overlapping patches
+- Encoding errors (when file cannot be decoded with specified encoding)
 - Line number out of bounds
 
 ## Security Considerations

pyproject.toml

@@ -7,7 +7,8 @@ authors = [
 ]
 dependencies = [
     "asyncio>=3.4.3",
-    "mcp>=1.1.0",
+    "mcp>=1.1.2",
+    "chardet>=5.2.0",
 ]
 requires-python = ">=3.11"
 readme = "README.md"

src/mcp_text_editor/models.py

@@ -28,6 +28,9 @@ class EditPatch(BaseModel):
     line_start: int = Field(1, description="Starting line for edit")
     line_end: Optional[int] = Field(None, description="Ending line for edit")
     contents: str = Field(..., description="New content to insert")
+    range_hash: Optional[str] = Field(
+        None, description="Hash of content being replaced. None for insertions"
+    )
 
 
 class EditFileOperation(BaseModel):
@@ -80,3 +83,21 @@ class EditTextFileContentsRequest(BaseModel):
     """
 
     files: List[EditFileOperation] = Field(..., description="List of file operations")
+
+
+class FileRange(BaseModel):
+    """Represents a line range in a file."""
+
+    start: int = Field(..., description="Starting line number (1-based)")
+    end: Optional[int] = Field(
+        None, description="Ending line number (null for end of file)"
+    )
+
+
+class FileRanges(BaseModel):
+    """Represents a file and its line ranges."""
+
+    file_path: str = Field(..., description="Path to the text file")
+    ranges: List[FileRange] = Field(
+        ..., description="List of line ranges to read from the file"
+    )

src/mcp_text_editor/server.py

@@ -24,7 +24,7 @@ class GetTextFileContentsHandler:
     """Handler for getting text file contents."""
 
     name = "get_text_file_contents"
-    description = "Read text file contents from multiple files and line ranges. Returns file contents with hashes for concurrency control and line numbers for reference. The hashes are used to detect conflicts when editing the files."
+    description = "Read text file contents from multiple files and line ranges. Returns file contents with hashes for concurrency control and line numbers for reference. The hashes are used to detect conflicts when editing the files. File paths must be absolute."
 
     def __init__(self):
         self.editor = TextEditor()
@@ -45,7 +45,7 @@ def get_tool_description(self) -> Tool:
                             "properties": {
                                 "file_path": {
                                     "type": "string",
-                                    "description": "Path to the text file",
+                                    "description": "Path to the text file. File path must be absolute.",
                                 },
                                 "ranges": {
                                     "type": "array",
@@ -68,7 +68,12 @@ def get_tool_description(self) -> Tool:
                             },
                             "required": ["file_path", "ranges"],
                         },
-                    }
+                    },
+                    "encoding": {
+                        "type": "string",
+                        "description": "Text encoding (default: 'utf-8')",
+                        "default": "utf-8",
+                    },
                 },
                 "required": ["files"],
             },
@@ -78,40 +83,24 @@ async def run_tool(self, arguments: Dict[str, Any]) -> Sequence[TextContent]:
         """Execute the tool with given arguments."""
         try:
             if "files" not in arguments:
-                # Handle legacy single file request
-                if "file_path" in arguments:
-                    file_path = arguments["file_path"]
-                    line_start = arguments.get("line_start", 1)
-                    line_end = arguments.get("line_end")
-
-                    content, start, end, content_hash, file_lines, file_size = (
-                        await self.editor.read_file_contents(
-                            file_path, line_start, line_end
-                        )
-                    )
+                raise RuntimeError("Missing required argument: 'files'")
 
-                    response = {
-                        "contents": content,
-                        "line_start": start,
-                        "line_end": end,
-                        "hash": content_hash,
-                        "file_path": file_path,
-                        "file_lines": file_lines,
-                        "file_size": file_size,
-                    }
+            for file_info in arguments["files"]:
+                if not os.path.isabs(file_info["file_path"]):
+                    raise RuntimeError(
+                        f"File path must be absolute: {file_info['file_path']}"
+                    )
 
-                    return [
-                        TextContent(type="text", text=json.dumps(response, indent=2))
-                    ]
-                else:
-                    raise RuntimeError("Missing required argument: files")
+            encoding = arguments.get("encoding", "utf-8")
+            result = await self.editor.read_multiple_ranges(
+                arguments["files"], encoding=encoding
+            )
+            response = result
 
-            # Handle multi-file request
-            result = await self.editor.read_multiple_ranges(arguments["files"])
-            return [TextContent(type="text", text=json.dumps(result, indent=2))]
+            return [TextContent(type="text", text=json.dumps(response, indent=2))]
 
         except KeyError as e:
-            raise RuntimeError(f"Missing required argument: {e}") from e
+            raise RuntimeError(f"Missing required argument: '{e}'") from e
         except Exception as e:
             raise RuntimeError(f"Error processing request: {str(e)}") from e
 
@@ -120,7 +109,7 @@ class EditTextFileContentsHandler:
     """Handler for editing text file contents."""
 
     name = "edit_text_file_contents"
-    description = "A line editor that supports editing text file contents by specifying line ranges and content. It handles multiple patches in a single operation with hash-based conflict detection. IMPORTANT: (1) Before using this tool, you must first get the file's current hash using get_text_file_contents. (2) To avoid line number shifts affecting your patches, use get_text_file_contents to read the same ranges you plan to edit before making changes. (3) Patches must be specified from bottom to top to handle line number shifts correctly, as edits to lower lines don't affect the line numbers of higher lines."
+    description = "A line editor that supports editing text file contents by specifying line ranges and content. It handles multiple patches in a single operation with hash-based conflict detection. File paths must be absolute. IMPORTANT: (1) Before using this tool, you must first get the file's current hash and range hashes and line numbers using get_text_file_contents. (2) To avoid line number shifts affecting your patches, use get_text_file_contents to read the SAME ranges you plan to edit before making changes. different line numbers have different rangehashes.(3) Patches must be specified from bottom to top to handle line number shifts correctly, as edits to lower lines don't affect the line numbers of higher lines. (4) To append content to a file, first get the total number of lines with get_text_file_contents, then specify a patch with line_start = total_lines + 1 and line_end = total_lines. This indicates an append operation and range_hash is not required. Similarly, range_hash is not required for new file creation."
 
     def __init__(self):
         self.editor = TextEditor()
@@ -138,8 +127,14 @@ def get_tool_description(self) -> Tool:
                         "items": {
                             "type": "object",
                             "properties": {
-                                "path": {"type": "string"},
-                                "hash": {"type": "string"},
+                                "path": {
+                                    "type": "string",
+                                    "description": "Path to the text file. File path must be absolute.",
+                                },
+                                "file_hash": {
+                                    "type": "string",
+                                    "description": "Hash of the file contents when get_text_file_contents is called.",
+                                },
                                 "patches": {
                                     "type": "array",
                                     "items": {
@@ -148,20 +143,31 @@ def get_tool_description(self) -> Tool:
                                             "line_start": {
                                                 "type": "integer",
                                                 "default": 1,
+                                                "description": "Starting line number (1-based). it should be matched with the start line number when get_text_file_contents is called.",
                                             },
                                             "line_end": {
                                                 "type": ["integer", "null"],
                                                 "default": None,
+                                                "description": "Ending line number (null for end of file). it should be matched with the end line number when get_text_file_contents is called.",
                                             },
                                             "contents": {"type": "string"},
+                                            "range_hash": {
+                                                "type": "string",
+                                                "description": "Hash of the content being replaced from line_start to line_end (required except for new files and append operations)",
+                                            },
                                         },
                                         "required": ["contents"],
                                     },
                                 },
                             },
-                            "required": ["path", "hash", "patches"],
+                            "required": ["path", "file_hash", "patches"],
                         },
-                    }
+                    },
+                    "encoding": {
+                        "type": "string",
+                        "description": "Text encoding (default: 'utf-8')",
+                        "default": "utf-8",
+                    },
                 },
                 "required": ["files"],
             },
@@ -176,61 +182,58 @@ async def run_tool(self, arguments: Dict[str, Any]) -> Sequence[TextContent]:
             files = arguments["files"]
             results: Dict[str, Dict] = {}
 
-            for file_operation in files:
-                file_path = None
-                try:
-                    try:
-                        file_path = file_operation["path"]
-                    except KeyError as e:
-                        raise RuntimeError(
-                            "Missing required field: path in file operation"
-                        ) from e
+            if len(files) == 0:
+                return [TextContent(type="text", text=json.dumps(results, indent=2))]
 
-                    # Ensure the file exists
-                    if not os.path.exists(file_path):
-                        results[file_path] = {
-                            "result": "error",
-                            "reason": "File not found",
-                            "hash": None,
-                        }
-                        continue
+            for file_operation in files:
+                # First check if required fields exist
+                if "path" not in file_operation:
+                    raise RuntimeError("Missing required field: path")
+                if "file_hash" not in file_operation:
+                    raise RuntimeError("Missing required field: file_hash")
+                if "patches" not in file_operation:
+                    raise RuntimeError("Missing required field: patches")
+
+                # Then check if path is absolute
+                if not os.path.isabs(file_operation["path"]):
+                    raise RuntimeError(
+                        f"File path must be absolute: {file_operation['path']}"
+                    )
 
-                    try:
-                        file_hash = file_operation["hash"]
-                    except KeyError as e:
-                        raise RuntimeError(
-                            f"Missing required field: hash for file {file_path}"
-                        ) from e
-
-                    # Ensure patches list is not empty
-                    try:
-                        patches = file_operation["patches"]
-                    except KeyError as e:
-                        raise RuntimeError(
-                            f"Missing required field: patches for file {file_path}"
-                        ) from e
+                try:
+                    file_path = file_operation["path"]
+                    file_hash = file_operation["file_hash"]
+                    patches = file_operation["patches"]
 
                     if not patches:
                         results[file_path] = {
                             "result": "error",
                             "reason": "Empty patches list",
-                            "hash": None,
+                            "file_hash": file_hash,
                         }
                         continue
 
+                    encoding = arguments.get("encoding", "utf-8")
                     result = await self.editor.edit_file_contents(
-                        file_path, file_hash, patches
+                        file_path, file_hash, patches, encoding=encoding
                     )
                     results[file_path] = result
                 except Exception as e:
-                    if file_path:
-                        results[file_path] = {
-                            "result": "error",
-                            "reason": str(e),
-                            "hash": None,
-                        }
-                    else:
-                        raise
+                    current_hash = None
+                    if "path" in file_operation:
+                        file_path = file_operation["path"]
+                        try:
+                            _, _, _, current_hash, _, _ = (
+                                await self.editor.read_file_contents(file_path)
+                            )
+                        except Exception:
+                            current_hash = None
+
+                    results[file_path if "path" in file_operation else "unknown"] = {
+                        "result": "error",
+                        "reason": str(e),
+                        "file_hash": current_hash,
+                    }
 
             return [TextContent(type="text", text=json.dumps(results, indent=2))]
         except Exception as e:

src/mcp_text_editor/service.py

@@ -120,7 +120,7 @@ def edit_file_contents(
                 file_path: EditResult(
                     result="error",
                     reason=str(e),
-                    hash=current_hash,
+                    hash=None,  # Don't return the current hash on error
                     content=None,
                 )
             }