ceciliomichael/mcp-filesystem-server

MCP Batch Read Server

An MCP (Model Context Protocol) server that provides a batch_read tool for reading multiple files efficiently in a single batch operation.

Features

• Batch File Reading: Read multiple files concurrently using absolute paths
• Error Resilience: Continues reading other files even if some fail
• Format Detection: Automatically handles both text and binary files
• Detailed Results: Provides comprehensive feedback on success/failure status
• Cross-Platform: Works on Windows, macOS, and Linux

Installation

1. Install dependencies:

npm install

2. Build the server:

npm run build

3. Test the server:

npm start

Usage

Tool: batch_read

Reads multiple files from absolute paths in a single operation with flexible parameter handling.

Parameters:

• paths: Array of absolute file paths to read (supports flexible input formats)

Response:

• Summary of successful and failed reads
• File contents (UTF-8 text or base64 for binary)
• File size and encoding information
• Detailed error messages for failed reads

Example

// Tool call example (named parameter)
{
  "paths": [
    "C:\\Users\\Administrator\\Desktop\\file1.txt",
    "C:\\Users\\Administrator\\Desktop\\file2.json",
    "/absolute/path/to/file3.md"
  ]
}

// Also works with direct array input (flexible)
[
  "C:\\Users\\Administrator\\Desktop\\file1.txt",
  "C:\\Users\\Administrator\\Desktop\\file2.json"
]

Response Format:

Read 3 file(s): 2 successful, 1 failed

File 1: C:\Users\Administrator\Desktop\file1.txt
✓ Success (utf-8, 1024 bytes)
Content:
[file content here]

---

File 2: C:\Users\Administrator\Desktop\file2.json
✓ Success (utf-8, 512 bytes)
Content:
[JSON content here]

---

File 3: /absolute/path/to/file3.md
✗ Error: ENOENT: no such file or directory

---

Configuration

Cursor AI Configuration

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "batch-read": {
      "command": "node",
      "args": [
        "C:/absolute/path/to/dist/index.js"
      ],
      "env": {}
    }
  }
}

Development

• Build: npm run build
• Start: npm start
• Dev: npm run dev (builds and starts)

Error Handling

The tool gracefully handles various error scenarios:

• File Not Found: Returns specific error message
• Permission Denied: Reports access issues
• Binary Files: Automatically converts to base64
• Partial Failures: Continues processing other files
• Network Paths: Supports UNC paths on Windows

Technical Details

• Concurrent Reading: Uses Promise.allSettled() for parallel file operations
• Encoding Detection: Attempts UTF-8 first, falls back to base64 for binary
• Cross-Platform: Proper path handling for Windows and Unix systems
• Memory Efficient: Streams large files appropriately
• MCP Compliant: Follows MCP protocol specifications

License

MIT License