feat: add optional line numbering to read_text_file tool (#61)

* 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]

* style: fix formatting and clippy warnings

[agent commit]

* docs: update capabilities with line numbering parameter

[agent commit]

* refactor: address PR review feedback for line numbering feature

- Remove manual CHANGELOG.md entry (auto-generated at release)
- Revert docs/capabilities.md changes (auto-generated via mcp-discovery)
- Improve documentation clarity for with_line_numbers parameter format
- Add test for Windows line endings (\r\n)
- Add edge case tests for newline-only content

Addresses review comments on PR #61

[agent commit]

* fix: correct fs_service.rs module structure after rebase

[agent commit]

---------

Co-authored-by: Abderraouf Belalia <abderraoufbelalia@symplectic.link>

Author: 0xErgod

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()]);