refactor: improve error messages for file hash validation

Author: tumf

src/mcp_text_editor/handlers/append_text_file_contents.py

@@ -87,7 +87,7 @@ async def run_tool(self, arguments: Dict[str, Any]) -> Sequence[TextContent]:
             # Create patch for append operation
             result = await self.editor.edit_file_contents(
                 file_path,
-                expected_hash=arguments["file_hash"],
+                expected_file_hash=arguments["file_hash"],
                 patches=[
                     {
                         "start": total_lines + 1,

src/mcp_text_editor/handlers/create_text_file.py

@@ -68,7 +68,7 @@ async def run_tool(self, arguments: Dict[str, Any]) -> Sequence[TextContent]:
             # Create new file using edit_file_contents with empty expected_hash
             result = await self.editor.edit_file_contents(
                 file_path,
-                expected_hash="",  # Empty hash for new file
+                expected_file_hash="",  # Empty hash for new file
                 patches=[
                     {
                         "start": 1,

src/mcp_text_editor/handlers/patch_text_file_contents.py

@@ -94,7 +94,7 @@ async def run_tool(self, arguments: Dict[str, Any]) -> Sequence[TextContent]:
             # Apply patches using editor.edit_file_contents
             result = await self.editor.edit_file_contents(
                 file_path=file_path,
-                expected_hash=arguments["file_hash"],
+                expected_file_hash=arguments["file_hash"],
                 patches=arguments["patches"],
                 encoding=encoding,
             )

src/mcp_text_editor/text_editor.py

@@ -223,7 +223,7 @@ async def read_file_contents(
     async def edit_file_contents(
         self,
         file_path: str,
-        expected_hash: str,
+        expected_file_hash: str,
         patches: List[Dict[str, Any]],
         encoding: str = "utf-8",
     ) -> Dict[str, Any]:
@@ -252,7 +252,7 @@ async def edit_file_contents(
         self._validate_file_path(file_path)
         try:
             if not os.path.exists(file_path):
-                if expected_hash not in ["", None]:  # Allow null hash
+                if expected_file_hash not in ["", None]:  # Allow null hash
                     return self.create_error_response(
                         "File not found and non-empty hash provided",
                         suggestion="append",
@@ -270,31 +270,31 @@ async def edit_file_contents(
                             hint="Please check file permissions and try again",
                         )
                 # Initialize empty state for new file
-                current_content = ""
-                current_hash = ""
+                current_file_content = ""
+                current_file_hash = ""
                 lines: List[str] = []
                 encoding = "utf-8"
             else:
                 # Read current file content and verify hash
                 (
-                    current_content,
+                    current_file_content,
                     _,
                     _,
-                    current_hash,
+                    current_file_hash,
                     total_lines,
                     _,
                 ) = await self.read_file_contents(file_path, encoding=encoding)
 
                 # Treat empty file as new file
-                if not current_content:
-                    current_content = ""
-                    current_hash = ""
+                if not current_file_content:
+                    current_file_content = ""
+                    current_file_hash = ""
                     lines = []
-                elif current_content and expected_hash == "":
+                elif current_file_content and expected_file_hash == "":
                     return self.create_error_response(
                         "Unexpected error - Cannot treat existing file as new",
                     )
-                elif current_hash != expected_hash:
+                elif current_file_hash != expected_file_hash:
                     suggestion = "patch"
                     hint = "Please use get_text_file_contents tool to get the current content and hash"
 
@@ -304,8 +304,8 @@ async def edit_file_contents(
                         hint=hint,
                     )
                 else:
-                    lines = current_content.splitlines(keepends=True)
-                    lines = current_content.splitlines(keepends=True)
+                    lines = current_file_content.splitlines(keepends=True)
+                    lines = current_file_content.splitlines(keepends=True)
 
             # Convert patches to EditPatch objects
             patch_objects = [EditPatch.model_validate(p) for p in patches]
@@ -356,16 +356,26 @@ async def edit_file_contents(
                         "result": "error",
                         "reason": "End line must be greater than or equal to start line",
                         "file_hash": None,
-                        "content": current_content,
+                        "content": current_file_content,
                     }
 
                 # Handle unexpected empty hash for existing file
                 if (
                     os.path.exists(file_path)
-                    and current_content
-                    and expected_hash == ""
+                    and current_file_content
+                    and expected_file_hash == ""
                 ):
-                    return {"result": "error", "reason": "Unexpected error"}
+                    return {
+                        "result": "error",
+                        "reason": "File hash validation required: Empty hash provided for existing file",
+                        "details": {
+                            "file_path": file_path,
+                            "current_file_hash": self.calculate_hash(
+                                current_file_content
+                            ),
+                            "expected_file_hash": expected_file_hash,
+                        },
+                    }
 
                 # Calculate line ranges for zero-based indexing
                 start_zero = start - 1
@@ -379,7 +389,7 @@ async def edit_file_contents(
                     expected_range_hash = patch.range_hash
 
                 # Determine operation type and validate hash requirements
-                if not os.path.exists(file_path) or not current_content:
+                if not os.path.exists(file_path) or not current_file_content:
                     # New file or empty file - treat as insertion
                     is_insertion = True
                 elif start_zero >= len(lines):
@@ -418,15 +428,15 @@ async def edit_file_contents(
                 if not contents.strip():
                     return {
                         "result": "ok",
-                        "file_hash": current_hash,  # Return current hash since no changes made
+                        "file_hash": current_file_hash,  # Return current hash since no changes made
                         "hint": "For content deletion, please consider using delete_text_file_contents instead of patch with empty content",
                         "suggestion": "delete",
                     }
 
                 # Set suggestions for alternative tools
                 suggestion_text: Optional[str] = None
                 hint_text: Optional[str] = None
-                if not os.path.exists(file_path) or not current_content:
+                if not os.path.exists(file_path) or not current_file_content:
                     suggestion_text = "append"
                     hint_text = "For new or empty files, please consider using append_text_file_contents instead"
                 elif is_insertion: