Optimized File System Proxy (MCP-FS)

A high-throughput Model Context Protocol server engineered for intelligent orchestration of filesystem tasks. This tool prioritizes efficiency when engaging with extensive file repositories by offering fine-grained context scoping, superior search mechanisms that minimize token consumption, and streamlined batch processing for complex modifications.

Core Rationale: Maximizing AI Interaction with Data

This utility overcomes the limitations of standard file access tools by implementing several key optimizations:

• Context Pruning: Employing partial data retrieval and exact boundary specification to ensure only germane information enters the model context window.
• Token Economy: Search operations leverage techniques (like ripgrep integration) to provide token-efficient results with integrated result set segmentation (pagination).
• Request Consolidation: Facilitating compound file operations within a single server call to decrease communication latency.

Advanced File Manipulation Capabilities

This server extends basic CRUD operations with intelligence suited for codebases and large datasets:

• Precision Reading: Line-level reading capabilities, allowing configuration of surrounding context lines (windows) around specified points.
• Verified Modification: Advanced atomic editing procedures featuring pre-edit content validation to guarantee transactional integrity against concurrent modifications.
• Superior Discovery: Search utilities offering regex support and context mirroring options analogous to grep -A/-B/-C.
• Relativity Support: Operations can utilize line numbers relative to a specified start point for complex regional refactoring.

Feature Set

• Absolute Security Boundary: Operations are strictly confined to a whitelist of pre-approved, fully qualified directory paths.
• Feature Completeness: Supports all conventional filesystem actions (read, write, list, move, delete).
• Augmented Discovery: Includes recursive structure mapping (tree_visualization) and content-based file duplication identification.
• Accelerated Search: Default integration with ripgrep (rg) for speed; falls back gracefully to Python alternatives.
• High Reliability: Backed by an extensive test suite (>75 tests) developed using behavior-driven methodologies.
• Environment Agnostic: Compatible across major operating systems (Windows, macOS, Linux).

Deployment and Integration (Quick Guide)

Prerequisites & Setup

Install the uv package manager first:

bash

Installation via shell script

curl -fsSL https://raw.githubusercontent.com/astral-sh/uv/main/install.sh | bash

Clone the source and install dependencies:

bash

Checkout

git clone https://github.com/safurrier/mcp-filesystem.git cd mcp-filesystem

Dependency resolution

uv pip sync requirements.txt requirements-dev.txt

Path Preparation

Obtain the absolute directory paths that the server should expose to the MCP consumer:

bash

Example for obtaining repository path

REPO_ROOT=$(pwd)

Example for target data directories

realpath /data/logs

Configuration for Desktop Clients (e.g., Claude)

Modify the client configuration file (e.g., claude_desktop_config.json) to register this server. Ensure all paths are absolute:

{ "mcpServers": { "mcp-filesystem-manager": { "command": "uv", "args": [ "--directory", "/absolute/path/to/mcp-filesystem", "run", "run_server.py", "/absolute/path/to/accessible/dir1", "/absolute/path/to/accessible/dir2" ] } } }

Crucially: Restart the client application after updating the configuration.

Operational Commands

Server Execution

Invoke the server, specifying the root directories authorized for access:

bash

Recommended execution via uv

uv run run_server.py /target/folder/A /target/folder/B

Standard Python execution

python run_server.py /target/folder/A

Monitoring Activity

To observe server communication and debug requests:

bash

Linux/macOS log tailing

tail -f ~/Library/Logs/Claude/mcp-server-mcp-filesystem.log

Tool Interface Definitions

Data Ingestion & Retrieval

• read_file: Fetching complete file contents.
• read_multiple_files: Batch retrieval of documents.
• write_file: Atomic content replacement or creation.
• list_directory: Detailed metadata listing.
• get_file_info: Metadata retrieval.

Granular Content Access

• read_file_lines: Fetching a specific segment of lines using offset (start index) and limit (count).
• head_file: Quick access to file preamble.
• tail_file: Quick access to file conclusion.

Content Modification

• edit_file_at_line: Performs transactional updates based on exact line numbers. Includes an expected_content safeguard field to prevent applying changes if the underlying data has drifted.

System Discovery & Analysis

• grep_files: Pattern matching utilizing regex, context windows, and result pagination.
• directory_tree: Generates a recursive map of the permitted structure.
• find_duplicate_files: Content-based deduplication scanning (configurable minimum size).
• calculate_directory_size: Summing up disk usage.

Workflow Example: Context-Aware Refactoring

When updating a specific function signature across a large codebase:

1. Locate: Use grep_files targeting the function name, setting context_after: 3 to capture related imports and calls. Use results_limit to manage the initial scope.
2. Verify Context: Examine the results, focusing on the precise matches returned.
3. Refine Edit: Use edit_file_at_line targeting the function definition line. Provide the old signature as the expected_content argument, and the new signature as the content argument, setting action: "replace".
4. Iterate: Repeat for subsequent matches, potentially using relative line numbering if edits affect the line counts of downstream matches.

This methodology minimizes the volume of text processed per AI iteration, dramatically improving operational speed and reducing potential context window overflow errors.