feat: Add insert_text_file_contents function

Add ability to insert text before or after a specific line in a file.
- Add InsertTextFileContentsRequest model
- Implement insert_text_file_contents in TextEditor
- Add comprehensive tests
- Export function in __init__.py

Author: Yoshihiro Takahara

src/mcp_text_editor/__init__.py

@@ -1,10 +1,37 @@
 """MCP Text Editor Server package."""
 
 import asyncio
+from typing import Any, Dict, List
 
 from .server import main
+from .text_editor import TextEditor
+
+# Create a global text editor instance
+_text_editor = TextEditor()
 
 
 def run() -> None:
     """Run the MCP Text Editor Server."""
     asyncio.run(main())
+
+
+# Export functions
+async def get_text_file_contents(
+    request: Dict[str, List[Dict[str, Any]]]
+) -> Dict[str, Any]:
+    """Get text file contents with line range specification."""
+    return await _text_editor.read_multiple_ranges(
+        ranges=request["files"],
+        encoding="utf-8",
+    )
+
+
+async def insert_text_file_contents(request: Dict[str, Any]) -> Dict[str, Any]:
+    """Insert text content before or after a specific line in a file."""
+    return await _text_editor.insert_text_file_contents(
+        file_path=request["path"],
+        file_hash=request["file_hash"],
+        after=request.get("after"),
+        before=request.get("before"),
+        contents=request["contents"],
+    )

src/mcp_text_editor/models.py

@@ -2,7 +2,7 @@
 
 from typing import Dict, List, Optional
 
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, Field, field_validator, model_validator
 
 
 class GetTextFileContentsRequest(BaseModel):
@@ -120,3 +120,49 @@ class FileRanges(BaseModel):
     ranges: List[FileRange] = Field(
         ..., description="List of line ranges to read from the file"
     )
+
+
+class InsertTextFileContentsRequest(BaseModel):
+    """Request model for inserting text into a file.
+
+    Example:
+    {
+        "path": "/path/to/file",
+        "file_hash": "abc123...",
+        "after": 5,  # Insert after line 5
+        "contents": "new content"
+    }
+    or
+    {
+        "path": "/path/to/file",
+        "file_hash": "abc123...",
+        "before": 5,  # Insert before line 5
+        "contents": "new content"
+    }
+    """
+
+    path: str = Field(..., description="Path to the text file")
+    file_hash: str = Field(..., description="Hash of original contents")
+    after: Optional[int] = Field(
+        None, description="Line number after which to insert content"
+    )
+    before: Optional[int] = Field(
+        None, description="Line number before which to insert content"
+    )
+    contents: str = Field(..., description="Content to insert")
+
+    @model_validator(mode="after")
+    def validate_position(self) -> "InsertTextFileContentsRequest":
+        """Validate that exactly one of after or before is specified."""
+        if (self.after is None and self.before is None) or (
+            self.after is not None and self.before is not None
+        ):
+            raise ValueError("Exactly one of 'after' or 'before' must be specified")
+        return self
+
+    @field_validator("after", "before")
+    def validate_line_number(cls, v) -> Optional[int]:
+        """Validate that line numbers are positive."""
+        if v is not None and v < 1:
+            raise ValueError("Line numbers must be positive")
+        return v

src/mcp_text_editor/text_editor.py

@@ -431,3 +431,108 @@ async def edit_file_contents(
                 "reason": "Unexpected error occurred",
                 "content": None,
             }
+
+    async def insert_text_file_contents(
+        self,
+        file_path: str,
+        file_hash: str,
+        contents: str,
+        after: Optional[int] = None,
+        before: Optional[int] = None,
+        encoding: str = "utf-8",
+    ) -> Dict[str, Any]:
+        """Insert text content before or after a specific line in a file.
+
+        Args:
+            file_path (str): Path to the file to edit
+            file_hash (str): Expected hash of the file before editing
+            contents (str): Content to insert
+            after (Optional[int]): Line number after which to insert content
+            before (Optional[int]): Line number before which to insert content
+            encoding (str, optional): File encoding. Defaults to "utf-8"
+
+        Returns:
+            Dict[str, Any]: Results containing:
+                - result: "ok" or "error"
+                - hash: New file hash if successful
+                - reason: Error message if result is "error"
+        """
+        if (after is None and before is None) or (
+            after is not None and before is not None
+        ):
+            return {
+                "result": "error",
+                "reason": "Exactly one of 'after' or 'before' must be specified",
+                "hash": None,
+            }
+
+        try:
+            current_content, _, _, current_hash, total_lines, _ = (
+                await self.read_file_contents(
+                    file_path,
+                    encoding=encoding,
+                )
+            )
+
+            if current_hash != file_hash:
+                return {
+                    "result": "error",
+                    "reason": "File hash mismatch - Please use get_text_file_contents tool to get current content and hash",
+                    "hash": None,
+                }
+
+            # Split into lines, preserving line endings
+            lines = current_content.splitlines(keepends=True)
+
+            # Determine insertion point
+            if after is not None:
+                if after > total_lines:
+                    return {
+                        "result": "error",
+                        "reason": f"Line number {after} is beyond end of file (total lines: {total_lines})",
+                        "hash": None,
+                    }
+                insert_pos = after
+            else:  # before must be set due to earlier validation
+                assert before is not None
+                if before > total_lines + 1:
+                    return {
+                        "result": "error",
+                        "reason": f"Line number {before} is beyond end of file (total lines: {total_lines})",
+                        "hash": None,
+                    }
+                insert_pos = before - 1
+
+            # Ensure content ends with newline
+            if not contents.endswith("\n"):
+                contents += "\n"
+
+            # Insert the content
+            lines.insert(insert_pos, contents)
+
+            # Join lines and write back to file
+            final_content = "".join(lines)
+            with open(file_path, "w", encoding=encoding) as f:
+                f.write(final_content)
+
+            # Calculate new hash
+            new_hash = self.calculate_hash(final_content)
+
+            return {
+                "result": "ok",
+                "hash": new_hash,
+                "reason": None,
+            }
+
+        except FileNotFoundError:
+            return {
+                "result": "error",
+                "reason": f"File not found: {file_path}",
+                "hash": None,
+            }
+        except Exception as e:
+            return {
+                "result": "error",
+                "reason": str(e),
+                "hash": None,
+            }

tests/test_insert_text_file.py

@@ -0,0 +1,134 @@
+"""Test insert_text_file_contents function."""
+
+from pathlib import Path
+
+import pytest
+
+from mcp_text_editor import get_text_file_contents, insert_text_file_contents
+
+
+@pytest.mark.asyncio
+async def test_insert_after_line(tmp_path: Path) -> None:
+    """Test inserting text after a specific line."""
+    # Create a test file
+    test_file = tmp_path / "test.txt"
+    test_file.write_text("line1\nline2\nline3\n")
+
+    # Get the current hash
+    result = await get_text_file_contents(
+        {"files": [{"file_path": str(test_file), "ranges": [{"start": 1}]}]}
+    )
+    file_hash = result[str(test_file)]["file_hash"]
+
+    # Insert text after line 2
+    result = await insert_text_file_contents(
+        {
+            "path": str(test_file),
+            "file_hash": file_hash,
+            "after": 2,
+            "contents": "new_line\n",
+        }
+    )
+
+    assert result["result"] == "ok"
+    assert result["hash"] is not None
+
+    # Verify the content
+    content = test_file.read_text()
+    assert content == "line1\nline2\nnew_line\nline3\n"
+
+
+@pytest.mark.asyncio
+async def test_insert_before_line(tmp_path: Path) -> None:
+    """Test inserting text before a specific line."""
+    # Create a test file
+    test_file = tmp_path / "test.txt"
+    test_file.write_text("line1\nline2\nline3\n")
+
+    # Get the current hash
+    result = await get_text_file_contents(
+        {"files": [{"file_path": str(test_file), "ranges": [{"start": 1}]}]}
+    )
+    file_hash = result[str(test_file)]["file_hash"]
+
+    # Insert text before line 2
+    result = await insert_text_file_contents(
+        {
+            "path": str(test_file),
+            "file_hash": file_hash,
+            "before": 2,
+            "contents": "new_line\n",
+        }
+    )
+
+    assert result["result"] == "ok"
+    assert result["hash"] is not None
+
+    # Verify the content
+    content = test_file.read_text()
+    assert content == "line1\nnew_line\nline2\nline3\n"
+
+
+@pytest.mark.asyncio
+async def test_insert_beyond_file_end(tmp_path: Path) -> None:
+    """Test inserting text beyond the end of file."""
+    # Create a test file
+    test_file = tmp_path / "test.txt"
+    test_file.write_text("line1\nline2\nline3\n")
+
+    # Get the current hash
+    result = await get_text_file_contents(
+        {"files": [{"file_path": str(test_file), "ranges": [{"start": 1}]}]}
+    )
+    file_hash = result[str(test_file)]["file_hash"]
+
+    # Try to insert text after line 10 (file has only 3 lines)
+    result = await insert_text_file_contents(
+        {
+            "path": str(test_file),
+            "file_hash": file_hash,
+            "after": 10,
+            "contents": "new_line\n",
+        }
+    )
+
+    assert result["result"] == "error"
+    assert "beyond end of file" in result["reason"]
+
+
+@pytest.mark.asyncio
+async def test_file_not_found(tmp_path: Path) -> None:
+    """Test inserting text into a non-existent file."""
+    # Try to insert text into a non-existent file
+    result = await insert_text_file_contents(
+        {
+            "path": str(tmp_path / "nonexistent.txt"),
+            "file_hash": "any_hash",
+            "after": 1,
+            "contents": "new_line\n",
+        }
+    )
+
+    assert result["result"] == "error"
+    assert "File not found" in result["reason"]
+
+
+@pytest.mark.asyncio
+async def test_hash_mismatch(tmp_path: Path) -> None:
+    """Test inserting text with incorrect file hash."""
+    # Create a test file
+    test_file = tmp_path / "test.txt"
+    test_file.write_text("line1\nline2\nline3\n")
+
+    # Try to insert text with incorrect hash
+    result = await insert_text_file_contents(
+        {
+            "path": str(test_file),
+            "file_hash": "incorrect_hash",
+            "after": 1,
+            "contents": "new_line\n",
+        }
+    )
+
+    assert result["result"] == "error"
+    assert "hash mismatch" in result["reason"]

tests/test_patch_text_file.py

@@ -0,0 +1,50 @@
+"""Test module for patch_text_file."""
+
+import os
+
+import pytest
+
+from mcp_text_editor.text_editor import TextEditor
+
+
+@pytest.mark.asyncio
+async def test_patch_text_file_middle(tmp_path):
+    """Test patching text in the middle of the file."""
+    # Create a test file
+    file_path = os.path.join(tmp_path, "test.txt")
+    editor = TextEditor()
+
+    # Create initial content
+    content = "line1\nline2\nline3\nline4\nline5\n"
+    with open(file_path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+    # Get file hash and range hash
+    file_info = await editor.read_multiple_ranges(
+        [{"file_path": str(file_path), "ranges": [{"start": 2, "end": 3}]}]
+    )
+
+    # Extract file and range hashes
+    file_content = file_info[str(file_path)]
+    file_hash = file_content["file_hash"]
+    range_hash = file_content["ranges"][0]["range_hash"]
+
+    # Patch the file
+    new_content = "new line2\nnew line3\n"
+    patch = {
+        "start": 2,
+        "end": 3,  # changed from 4 to 3 since we only want to replace lines 2-3
+        "contents": new_content,
+        "range_hash": range_hash,
+    }
+    result = await editor.edit_file_contents(
+        str(file_path),
+        file_hash,
+        [patch],
+    )
+
+    # Verify the patch was successful
+    assert result["result"] == "ok"
+    with open(file_path, "r", encoding="utf-8") as f:
+        updated_content = f.read()
+    assert updated_content == "line1\nnew line2\nnew line3\nline4\nline5\n"