feat: add optional line numbering to read_text_file tool

CHANGELOG.md

@@ -1,25 +1,5 @@
 # Changelog
 
-## [0.3.8](https://github.com/rust-mcp-stack/rust-mcp-filesystem/compare/v0.3.7...v0.3.8) (2025-10-31)
-
-
-### ⚙️ Miscellaneous Chores
-
-* Release 0.3.8 ([38f2919](https://github.com/rust-mcp-stack/rust-mcp-filesystem/commit/38f29190b167bc36de4f33edae3bd63f61567aa7))
-* Release 0.3.8 ([9030cbb](https://github.com/rust-mcp-stack/rust-mcp-filesystem/commit/9030cbbabca1bca1992a93a63a9d01b367e0d83e))
-
-## [0.3.7](https://github.com/rust-mcp-stack/rust-mcp-filesystem/compare/v0.3.6...v0.3.7) (2025-10-31)
-
-
-### 🚀 Features
-
-* Update document and installers with npm support ([#68](https://github.com/rust-mcp-stack/rust-mcp-filesystem/issues/68)) ([5b78516](https://github.com/rust-mcp-stack/rust-mcp-filesystem/commit/5b785169e5522cf28097f4b9781462ddfb73aeb2))
-
-
-### 🐛 Bug Fixes
-
-* Ignore client root change notification when it is not enabled by server ([#65](https://github.com/rust-mcp-stack/rust-mcp-filesystem/issues/65)) ([3ca810a](https://github.com/rust-mcp-stack/rust-mcp-filesystem/commit/3ca810ade142d91d14d1d138e9cc8f5680b35ec5))
-
 ## [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/io/read.rs

@@ -20,11 +20,25 @@ use tokio::{
 const MAX_CONCURRENT_FILE_READ: usize = 5;
 
 impl FileSystemService {
-    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)
+        }
     }
 
     /// Reads the first n lines from a text file, preserving line endings.

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 a right-aligned, 1-based line number
+    /// Followed by a space, a vertical bar (`|`), and another space in the format: `   123 | <original line content>`
+    #[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,118 @@ 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_read_text_file_with_line_numbers_windows_line_endings() {
+    let (temp_dir, service, _allowed_dirs) = setup_service(vec!["dir1".to_string()]);
+    let file_path = create_temp_file(
+        temp_dir.join("dir1").as_path(),
+        "windows.txt",
+        "line1\r\nline2\r\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_with_line_numbers_single_newline_unix() {
+    let (temp_dir, service, _allowed_dirs) = setup_service(vec!["dir1".to_string()]);
+    // A file with just "\n" is treated by lines() as having one empty line before the newline
+    // To get two empty lines, we need "\n\n"
+    let file_path = create_temp_file(temp_dir.join("dir1").as_path(), "newline_unix.txt", "\n\n");
+    let content = service.read_text_file(&file_path, true).await.unwrap();
+    assert_eq!(content, "     1 | \n     2 | ");
+}
+
+#[tokio::test]
+async fn test_read_text_file_with_line_numbers_single_newline_windows() {
+    let (temp_dir, service, _allowed_dirs) = setup_service(vec!["dir1".to_string()]);
+    // A file with just "\r\n" is treated by lines() as having one empty line
+    // To get two empty lines, we need "\r\n\r\n"
+    let file_path = create_temp_file(
+        temp_dir.join("dir1").as_path(),
+        "newline_windows.txt",
+        "\r\n\r\n",
+    );
+    let content = service.read_text_file(&file_path, true).await.unwrap();
+    assert_eq!(content, "     1 | \n     2 | ");
+}
+
 #[tokio::test]
 async fn test_create_directory() {
     let (temp_dir, service, _allowed_dirs) = setup_service(vec!["dir1".to_string()]);