feat: add optional line numbering to read_text_file tool

Implements #60 - Add line numbering flag for read_text_file

Changes:
- Added `with_line_numbers` optional parameter to ReadTextFile struct
- Updated read_text_file service method to format output with line numbers
- Line numbers are right-aligned (6 digits) with pipe separator format
- Uses 1-based indexing for line numbers
- Maintains backward compatibility (defaults to false)
- Added comprehensive unit tests for various scenarios
- Updated CHANGELOG.md with feature description

This feature enables AI agents to obtain file content with line numbers
in a single tool invocation, improving efficiency for code modification
tasks that require precise line-based targeting.

[agent commit]

Author: Abderraouf Belalia

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [Unreleased]
+
+### 🚀 Features
+
+* Add optional line numbering to read_text_file tool ([#60](https://github.com/rust-mcp-stack/rust-mcp-filesystem/issues/60))
+  - Added `with_line_numbers` optional parameter to `read_text_file` tool
+  - When enabled, prefixes each line with right-aligned line numbers and pipe separator
+  - Useful for AI agents that need to target specific lines for code patches
+  - Maintains backward compatibility with existing usage
+
 ## [0.3.6](https://github.com/rust-mcp-stack/rust-mcp-filesystem/compare/v0.3.5...v0.3.6) (2025-10-15)
 
 

src/fs_service.rs

@@ -575,11 +575,21 @@ impl FileSystemService {
         Ok(base64_string)
     }
 
-    pub async fn read_text_file(&self, file_path: &Path) -> ServiceResult<String> {
+    pub async fn read_text_file(&self, file_path: &Path, with_line_numbers: bool) -> ServiceResult<String> {
         let allowed_directories = self.allowed_directories().await;
         let valid_path = self.validate_path(file_path, allowed_directories)?;
         let content = tokio::fs::read_to_string(valid_path).await?;
-        Ok(content)
+
+        if with_line_numbers {
+            Ok(content
+                .lines()
+                .enumerate()
+                .map(|(i, line)| format!("{:>6} | {}", i + 1, line))
+                .collect::<Vec<_>>()
+                .join("\n"))
+        } else {
+            Ok(content)
+        }
     }
 
     pub async fn create_directory(&self, file_path: &Path) -> ServiceResult<()> {

src/tools/read_multiple_text_files.rs

@@ -35,7 +35,7 @@ impl ReadMultipleTextFiles {
             .map(|path| async move {
                 {
                     let content = context
-                        .read_text_file(Path::new(&path))
+                        .read_text_file(Path::new(&path), false)
                         .await
                         .map_err(CallToolError::new);
 

src/tools/read_text_file.rs

@@ -12,7 +12,8 @@ use crate::fs_service::FileSystemService;
     description = concat!("Read the complete contents of a text file from the file system as text. ",
     "Handles various text encodings and provides detailed error messages if the ",
     "file cannot be read. Use this tool when you need to examine the contents of ",
-    "a single file. Only works within allowed directories."),
+    "a single file. Optionally include line numbers for precise code targeting. ",
+    "Only works within allowed directories."),
     destructive_hint = false,
     idempotent_hint = false,
     open_world_hint = false,
@@ -22,6 +23,11 @@ use crate::fs_service::FileSystemService;
 pub struct ReadTextFile {
     /// The path of the file to read.
     pub path: String,
+    /// Optional: Include line numbers in output (default: false).
+    /// When enabled, each line is prefixed with its line number (1-based).
+    /// Useful for AI agents that need to target specific lines for code patches.
+    #[serde(default)]
+    pub with_line_numbers: Option<bool>,
 }
 
 impl ReadTextFile {
@@ -30,7 +36,10 @@ impl ReadTextFile {
         context: &FileSystemService,
     ) -> std::result::Result<CallToolResult, CallToolError> {
         let content = context
-            .read_text_file(Path::new(&params.path))
+            .read_text_file(
+                Path::new(&params.path),
+                params.with_line_numbers.unwrap_or(false),
+            )
             .await
             .map_err(CallToolError::new)?;
 

tests/test_fs_service.rs

@@ -230,10 +230,86 @@ async fn test_unzip_file_non_existent() {
 async fn test_read_file() {
     let (temp_dir, service, _allowed_dirs) = setup_service(vec!["dir1".to_string()]);
     let file_path = create_temp_file(temp_dir.join("dir1").as_path(), "test.txt", "content");
-    let content = service.read_text_file(&file_path).await.unwrap();
+    let content = service.read_text_file(&file_path, false).await.unwrap();
     assert_eq!(content, "content");
 }
 
+#[tokio::test]
+async fn test_read_text_file_with_line_numbers() {
+    let (temp_dir, service, _allowed_dirs) = setup_service(vec!["dir1".to_string()]);
+    let file_path = create_temp_file(
+        temp_dir.join("dir1").as_path(),
+        "test.txt",
+        "line1\nline2\nline3"
+    );
+    let content = service.read_text_file(&file_path, true).await.unwrap();
+    assert_eq!(content, "     1 | line1\n     2 | line2\n     3 | line3");
+}
+
+#[tokio::test]
+async fn test_read_text_file_without_line_numbers() {
+    let (temp_dir, service, _allowed_dirs) = setup_service(vec!["dir1".to_string()]);
+    let file_path = create_temp_file(
+        temp_dir.join("dir1").as_path(),
+        "test.txt",
+        "line1\nline2\nline3"
+    );
+    let content = service.read_text_file(&file_path, false).await.unwrap();
+    assert_eq!(content, "line1\nline2\nline3");
+}
+
+#[tokio::test]
+async fn test_read_text_file_with_line_numbers_empty_file() {
+    let (temp_dir, service, _allowed_dirs) = setup_service(vec!["dir1".to_string()]);
+    let file_path = create_temp_file(temp_dir.join("dir1").as_path(), "empty.txt", "");
+    let content = service.read_text_file(&file_path, true).await.unwrap();
+    assert_eq!(content, "");
+}
+
+#[tokio::test]
+async fn test_read_text_file_with_line_numbers_single_line() {
+    let (temp_dir, service, _allowed_dirs) = setup_service(vec!["dir1".to_string()]);
+    let file_path = create_temp_file(temp_dir.join("dir1").as_path(), "single.txt", "single line");
+    let content = service.read_text_file(&file_path, true).await.unwrap();
+    assert_eq!(content, "     1 | single line");
+}
+
+#[tokio::test]
+async fn test_read_text_file_with_line_numbers_no_trailing_newline() {
+    let (temp_dir, service, _allowed_dirs) = setup_service(vec!["dir1".to_string()]);
+    let file_path = create_temp_file(
+        temp_dir.join("dir1").as_path(),
+        "no_newline.txt",
+        "line1\nline2"
+    );
+    let content = service.read_text_file(&file_path, true).await.unwrap();
+    assert_eq!(content, "     1 | line1\n     2 | line2");
+}
+
+#[tokio::test]
+async fn test_read_text_file_with_line_numbers_large_file() {
+    let (temp_dir, service, _allowed_dirs) = setup_service(vec!["dir1".to_string()]);
+    // Create a file with more than 999 lines to test padding
+    let mut lines = Vec::new();
+    for i in 1..=1000 {
+        lines.push(format!("line{}", i));
+    }
+    let file_content = lines.join("\n");
+    let file_path = create_temp_file(
+        temp_dir.join("dir1").as_path(),
+        "large.txt",
+        &file_content
+    );
+    let content = service.read_text_file(&file_path, true).await.unwrap();
+
+    // Check first line
+    assert!(content.starts_with("     1 | line1\n"));
+    // Check line 999
+    assert!(content.contains("   999 | line999\n"));
+    // Check line 1000 (6 digits with right padding)
+    assert!(content.contains("  1000 | line1000"));
+}
+
 #[tokio::test]
 async fn test_create_directory() {
     let (temp_dir, service, _allowed_dirs) = setup_service(vec!["dir1".to_string()]);