refactor: rename line_start/line_end to start/end

Author: Yoshihiro Takahara

src/mcp_text_editor/models.py

@@ -9,24 +9,24 @@ class GetTextFileContentsRequest(BaseModel):
     """Request model for getting text file contents."""
 
     file_path: str = Field(..., description="Path to the text file")
-    line_start: int = Field(1, description="Starting line number (1-based)")
-    line_end: Optional[int] = Field(None, description="Ending line number (inclusive)")
+    start: int = Field(1, description="Starting line number (1-based)")
+    end: Optional[int] = Field(None, description="Ending line number (inclusive)")
 
 
 class GetTextFileContentsResponse(BaseModel):
     """Response model for getting text file contents."""
 
     contents: str = Field(..., description="File contents")
-    line_start: int = Field(..., description="Starting line number")
-    line_end: int = Field(..., description="Ending line number")
+    start: int = Field(..., description="Starting line number")
+    end: int = Field(..., description="Ending line number")
     hash: str = Field(..., description="Hash of the contents")
 
 
 class EditPatch(BaseModel):
     """Model for a single edit patch operation."""
 
-    line_start: int = Field(1, description="Starting line for edit")
-    line_end: Optional[int] = Field(None, description="Ending line for edit")
+    start: int = Field(1, description="Starting line for edit")
+    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"
@@ -70,8 +70,8 @@ class EditTextFileContentsRequest(BaseModel):
                 "hash": "abc123...",
                 "patches": [
                     {
-                        "line_start": 1,  # default: 1 (top of file)
-                        "line_end": null,  # default: null (end of file)
+                        "start": 1,  # default: 1 (top of file)
+                        "end": null,  # default: null (end of file)
                         "contents": "new content"
                     }
                 ]

src/mcp_text_editor/server.py

@@ -109,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. 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."
+    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 start = total_lines + 1 and 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()
@@ -140,20 +140,20 @@ def get_tool_description(self) -> Tool:
                                     "items": {
                                         "type": "object",
                                         "properties": {
-                                            "line_start": {
+                                            "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": {
+                                            "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)",
+                                                "description": "Hash of the content being replaced from start to end (required except for new files and append operations)",
                                             },
                                         },
                                         "required": ["contents"],

src/mcp_text_editor/service.py

@@ -16,32 +16,32 @@ def calculate_hash(content: str) -> str:
 
     @staticmethod
     def read_file_contents(
-        file_path: str, line_start: int = 1, line_end: Optional[int] = None
+        file_path: str, start: int = 1, end: Optional[int] = None
     ) -> Tuple[str, int, int]:
         """Read file contents within specified line range."""
         with open(file_path, "r", encoding="utf-8") as f:
             lines = f.readlines()
 
         # Adjust line numbers to 0-based index
-        line_start = max(1, line_start) - 1
-        line_end = len(lines) if line_end is None else min(line_end, len(lines))
+        start = max(1, start) - 1
+        end = len(lines) if end is None else min(end, len(lines))
 
-        selected_lines = lines[line_start:line_end]
+        selected_lines = lines[start:end]
         content = "".join(selected_lines)
 
-        return content, line_start + 1, line_end
+        return content, start + 1, end
 
     @staticmethod
     def validate_patches(patches: List[EditPatch], total_lines: int) -> bool:
         """Validate patches for overlaps and bounds."""
-        # Sort patches by line_start
-        sorted_patches = sorted(patches, key=lambda x: x.line_start)
+        # Sort patches by start
+        sorted_patches = sorted(patches, key=lambda x: x.start)
 
         prev_end = 0
         for patch in sorted_patches:
-            if patch.line_start <= prev_end:
+            if patch.start <= prev_end:
                 return False
-            patch_end = patch.line_end or total_lines
+            patch_end = patch.end or total_lines
             if patch_end > total_lines:
                 return False
             prev_end = patch_end
@@ -84,8 +84,8 @@ def edit_file_contents(
             # Apply patches
             new_lines = lines.copy()
             for patch in operation.patches:
-                start_idx = patch.line_start - 1
-                end_idx = patch.line_end if patch.line_end else len(lines)
+                start_idx = patch.start - 1
+                end_idx = patch.end if patch.end else len(lines)
                 patch_lines = patch.contents.splitlines(keepends=True)
                 new_lines[start_idx:end_idx] = patch_lines
 

src/mcp_text_editor/text_editor.py

@@ -100,37 +100,37 @@ async def read_multiple_ranges(
             result[file_path] = {"ranges": [], "file_hash": file_hash}
 
             for range_spec in file_range.ranges:
-                line_start = max(1, range_spec.start) - 1
+                start = max(1, range_spec.start) - 1
                 end_value = range_spec.end
-                line_end = (
+                end = (
                     min(total_lines, end_value)
                     if end_value is not None
                     else total_lines
                 )
 
-                if line_start >= total_lines:
+                if start >= total_lines:
                     empty_content = ""
                     result[file_path]["ranges"].append(
                         {
                             "content": empty_content,
-                            "start_line": line_start + 1,
-                            "end_line": line_start + 1,
+                            "start": start + 1,
+                            "end": start + 1,
                             "range_hash": self.calculate_hash(empty_content),
                             "total_lines": total_lines,
                             "content_size": 0,
                         }
                     )
                     continue
 
-                selected_lines = lines[line_start:line_end]
+                selected_lines = lines[start:end]
                 content = "".join(selected_lines)
                 range_hash = self.calculate_hash(content)
 
                 result[file_path]["ranges"].append(
                     {
                         "content": content,
-                        "start_line": line_start + 1,
-                        "end_line": line_end,
+                        "start": start + 1,
+                        "end": end,
                         "range_hash": range_hash,
                         "total_lines": total_lines,
                         "content_size": len(content),
@@ -142,36 +142,36 @@ async def read_multiple_ranges(
     async def read_file_contents(
         self,
         file_path: str,
-        line_start: int = 1,
-        line_end: Optional[int] = None,
+        start: int = 1,
+        end: Optional[int] = None,
         encoding: str = "utf-8",
     ) -> Tuple[str, int, int, str, int, int]:
         lines, file_content, total_lines = await self._read_file(
             file_path, encoding=encoding
         )
 
-        if line_end is not None and line_end < line_start:
+        if end is not None and end < start:
             raise ValueError("End line must be greater than or equal to start line")
 
-        line_start = max(1, line_start) - 1
-        line_end = total_lines if line_end is None else min(line_end, total_lines)
+        start = max(1, start) - 1
+        end = total_lines if end is None else min(end, total_lines)
 
-        if line_start >= total_lines:
+        if start >= total_lines:
             empty_content = ""
             empty_hash = self.calculate_hash(empty_content)
-            return empty_content, line_start, line_start, empty_hash, total_lines, 0
-        if line_end < line_start:
+            return empty_content, start, start, empty_hash, total_lines, 0
+        if end < start:
             raise ValueError("End line must be greater than or equal to start line")
 
-        selected_lines = lines[line_start:line_end]
+        selected_lines = lines[start:end]
         content = "".join(selected_lines)
         content_hash = self.calculate_hash(content)
         content_size = len(content.encode(encoding))
 
         return (
             content,
-            line_start + 1,
-            line_end,
+            start + 1,
+            end,
             content_hash,
             total_lines,
             content_size,
@@ -191,17 +191,17 @@ async def edit_file_contents(
             file_path (str): Path to the file to edit
             expected_hash (str): Expected hash of the file before editing
             patches (List[EditPatch]): List of patches to apply
-                - line_start (int): Starting line number (1-based, optional, default: 1)
-                - line_end (Optional[int]): Ending line number (inclusive)
+                - start (int): Starting line number (1-based, optional, default: 1)
+                - end (Optional[int]): Ending line number (inclusive)
                 - contents (str): New content to insert
         Edit file contents with hash-based conflict detection and multiple patches (supporting new file creation).
 
         Args:
             file_path (str): Path to the file to edit (parent directories are created automatically)
             expected_hash (str): Expected hash of the file before editing (empty string for new files)
             patches (List[Dict[str, Any]]): List of patches to apply, each containing:
-                - line_start (int): Starting line number (1-based)
-                - line_end (Optional[int]): Ending line number (inclusive)
+                - start (int): Starting line number (1-based)
+                - end (Optional[int]): Ending line number (inclusive)
                 - contents (str): New content to insert
                 - range_hash (str): Expected hash of the content being replaced
 
@@ -277,8 +277,8 @@ async def edit_file_contents(
             sorted_patches = sorted(
                 patch_objects,
                 key=lambda x: (
-                    -(x.line_start),
-                    -(x.line_end or x.line_start or float("inf")),
+                    -(x.start),
+                    -(x.end or x.start or float("inf")),
                 ),
             )
 
@@ -287,10 +287,10 @@ async def edit_file_contents(
                 for j in range(i + 1, len(sorted_patches)):
                     patch1 = sorted_patches[i]
                     patch2 = sorted_patches[j]
-                    start1 = patch1.line_start
-                    end1 = patch1.line_end or start1
-                    start2 = patch2.line_start
-                    end2 = patch2.line_end or start2
+                    start1 = patch1.start
+                    end1 = patch1.end or start1
+                    start2 = patch2.start
+                    end2 = patch2.end or start2
 
                     if (start1 <= end2 and end1 >= start2) or (
                         start2 <= end1 and end2 >= start1
@@ -305,17 +305,17 @@ async def edit_file_contents(
             # Apply patches
             for patch in sorted_patches:
                 # Get line numbers (1-based)
-                line_start: int
-                line_end: Optional[int]
+                start: int
+                end: Optional[int]
                 if isinstance(patch, EditPatch):
-                    line_start = patch.line_start
-                    line_end = patch.line_end
+                    start = patch.start
+                    end = patch.end
                 else:
-                    line_start = patch["line_start"] if "line_start" in patch else 1
-                    line_end = patch["line_end"] if "line_end" in patch else line_start
+                    start = patch["start"] if "start" in patch else 1
+                    end = patch["end"] if "end" in patch else start
 
                 # Check for invalid line range
-                if line_end is not None and line_end < line_start:
+                if end is not None and end < start:
                     return {
                         "result": "error",
                         "reason": "End line must be greater than or equal to start line",
@@ -337,11 +337,9 @@ async def edit_file_contents(
                     }
 
                 # Calculate line ranges for zero-based indexing
-                line_start_zero = line_start - 1
-                line_end_zero = (
-                    len(lines) - 1
-                    if line_end is None
-                    else min(line_end - 1, len(lines) - 1)
+                start_zero = start - 1
+                end_zero = (
+                    len(lines) - 1 if end is None else min(end - 1, len(lines) - 1)
                 )
 
                 # Get expected hash for validation
@@ -356,8 +354,8 @@ async def edit_file_contents(
                 if not os.path.exists(file_path) or not current_content:
                     # New file or empty file - treat as insertion
                     is_insertion = True
-                elif line_start_zero >= len(lines):
-                    # Append mode - line_start exceeds total lines
+                elif start_zero >= len(lines):
+                    # Append mode - start exceeds total lines
                     is_insertion = True
                 else:
                     # For existing files:
@@ -371,7 +369,7 @@ async def edit_file_contents(
                         }
 
                     # Hash provided - verify content
-                    target_lines = lines[line_start_zero : line_end_zero + 1]
+                    target_lines = lines[start_zero : end_zero + 1]
                     target_content = "".join(target_lines)
                     actual_range_hash = self.calculate_hash(target_content)
 
@@ -381,7 +379,7 @@ async def edit_file_contents(
                         f"\nExpected: {expected_range_hash}"
                         f"\nActual: {actual_range_hash}"
                         f"\nContent: {target_content!r}"
-                        f"\nRange: {line_start_zero}:{line_end_zero + 1}"
+                        f"\nRange: {start_zero}:{end_zero + 1}"
                     )
 
                     # Compare hashes
@@ -396,7 +394,7 @@ async def edit_file_contents(
                         if actual_range_hash != expected_range_hash:
                             return {
                                 "result": "error",
-                                "reason": f"Content hash mismatch - Please use get_text_file_contents tool with lines {line_start}-{line_end} to get current content and hashes, then retry with the updated hashes. If you want to append content, set line_start to {len(lines)+1}.",
+                                "reason": f"Content hash mismatch - Please use get_text_file_contents tool with lines {start}-{end} to get current content and hashes, then retry with the updated hashes. If you want to append content, set start to {len(lines)+1}.",
                                 "file_hash": None,
                                 "content": current_content,
                             }
@@ -414,14 +412,14 @@ async def edit_file_contents(
                 # Apply changes - line ranges were calculated earlier
                 if is_insertion:
                     # Insert at the specified line
-                    lines[line_start_zero:line_start_zero] = new_lines
+                    lines[start_zero:start_zero] = new_lines
                 else:
                     # Replace the specified range
-                    lines[line_start_zero : line_end_zero + 1] = new_lines
+                    lines[start_zero : end_zero + 1] = new_lines
 
                 # Debug output - shows the operation type
                 print(
-                    f"Applied patch: line_start={line_start} line_end={line_end} is_insertion={is_insertion} contents={patch.contents!r}"
+                    f"Applied patch: start={start} end={end} is_insertion={is_insertion} contents={patch.contents!r}"
                 )
 
             # Write the final content back to file