MCP Server Filesystem

🚀 MCP File System Server

The MCP File System Server offers a set of MCP tools for efficient file operations, which can be easily integrated into development environments such as VSCode.

🚀 Quick Start

Setting up the Development Environment on Windows

REM Clone the repository
git clone https://github.com/MarcusJellinghaus/mcp_server_filesystem.git
cd mcp-server-filesystem

REM Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate

REM Install dependencies
pip install -e .

REM Install development dependencies
pip install -e ".[dev]"

Configuration Instructions

To integrate this server with VSCode or other Cline - supported tools, follow these configuration steps:

1. VSCode Integration:
   • Open VSCode and install the Cline extension.
   • Create a mcp-config.json file in the project root directory and add the following content:

{
  "mcp": {
    "servers": [
      {
        "id": "filesystem",
        "class": "mcp_server_filesystem.FileSystemServer",
        "args": {
          "project_dir": "."
        }
      }
    ]
  }
}

2. Start the Server:
   • In VSCode, open the terminal and run the following command:

python src/server.py

✨ Features

Available Tools

The server provides the following MCP tools:

Tool Details

List Directory

• Returns a list of file and directory names.
• By default, the results are filtered according to the .gitignore pattern, and the .git folder is excluded.

Read File

• Parameters: file_path (string): The path of the file to read (relative to the project directory).
• Returns the file content as a string.

Save File

• Parameters:
  • file_path (string): The path of the file to write.
  • content (string): The content to write.
• Returns a boolean indicating whether the operation was successful.

Append File

• Parameters:
  • file_path (string): The path of the file to append to.
  • content (string): The content to append.
• Returns a boolean indicating whether the operation was successful.
• Note: The file must already exist; use save_file to create a new file.

Delete File

• Parameters: file_path (string): The path of the file to delete.
• Returns a boolean indicating whether the operation was successful.
• Note: This operation is irreversible and will permanently delete the file.

Edit File

• Parameters:
  • file_path (string): The file to edit.
  • edits (array): A list of edit operations, each containing:
    • old_text (string): The text to be replaced.
    • new_text (string): The new replacement text.
  • dry_run (boolean, optional): Preview changes without applying them.
  • options (object, optional): Formatting settings.
• Features:
  • Supports pattern matching for line ranges and file paths.
  • Supports multiple replacements simultaneously.

🔧 Technical Details

Security Features

• File Access Control:
  • Only read, write, and append operations are allowed, and deletion operations are strictly prohibited.
  • All changes require explicit confirmation to avoid accidental modifications.
• Directory Structure Protection:
  • The structure of the root directory and its sub - directories is protected to prevent accidental deletion or renaming.

Development Instructions

• Code Structure:
  • The project is organized based on the standard Python package structure.
  • The main modules include server.py and filesystem_server.py.
• Logging and Debugging:
  • The server provides detailed log output for easy debugging and monitoring of the running status.
  • The log level and output format can be adjusted through the configuration file.

💻 Usage Examples

Basic Testing

1. Start the server:

python src/server.py

2. Use the Cline tool in VSCode for interactive testing:
   • Open the Cline tool.
   • Select the filesystem server and start a session.

Advanced Testing

• Unit Testing:
  • Run the following command in the project root directory:

python -m pytest tests/

📄 License

This project is licensed under the MIT License, which allows for free use, modification, and distribution. Please refer to the LICENSE file for detailed licensing information.