Jalalkhan912/File_MCP_Server

Minimal File-System MCP Server

fs_server.py is a simple yet powerful server that exposes file system operations (create, read, write, edit, move, copy, delete) as an MCP (Message-based Communication Protocol) service. It's designed with a strong emphasis on safety through workspace sandboxing, ensuring all operations are confined to a designated root directory.

This server also includes a direct HTTP endpoint for serving static files from the workspace, making it convenient for scenarios where direct file access (e.g., for serving web assets or reviewing generated files) is needed.

Features

• Workspace Sandboxing: All file system operations are strictly confined to a configurable root directory, preventing unauthorized access to other parts of your system.
• Interactive Workspace Selection: Upon startup, the server intelligently determines the workspace root:
  1. Prioritizes the FS_WORKSPACE environment variable.
  2. Attempts to use a graphical folder picker (Tkinter) for a user-friendly selection.
  3. Falls back to a console prompt for interactive text-based selection.
  4. Uses the current working directory as a default if no other option is chosen interactively.
• Comprehensive File System Tools: Exposes a rich set of operations via the MCP interface:
  • workspace_root(): Returns the absolute path of the current workspace root.
  • make_dir(path, parents, exist_ok): Creates a new directory.
  • list_dir(path, recursive, pattern): Lists contents of a directory, with options for recursion and glob patterns.
  • read_text(path, encoding, max_bytes): Reads the content of a text file, with a truncation limit.
  • write_text(path, content, overwrite, create_dirs, encoding): Writes content to a text file, with options for overwriting and creating parent directories.
  • append_text(path, content, create_dirs, encoding): Appends content to an existing file (or creates it if missing).
  • replace_text(path, pattern, replacement, regex, count, encoding): Performs search and replace within a text file, supporting literal and regex patterns.
  • move_path(src, dest, overwrite): Moves or renames a file or directory.
  • copy_path(src, dest, overwrite): Copies a file or directory.
  • delete_path(path, recursive): Deletes a file or an entire directory (if recursive is true).
  • read_json(path): Reads and parses a JSON file.
  • write_json(path, data, overwrite, create_dirs, indent): Writes a Python dictionary as JSON to a file.
• Direct File Access HTTP Endpoint: Files within the workspace can be served directly via http://0.0.0.0:8765/files/{path:path}, allowing for easy access to static assets or generated content.
• Built on Modern Python Web Stack: Utilizes Starlette for the web application and Uvicorn as the ASGI server, ensuring high performance and robustness.

Setup and Installation

1. Prerequisites:

   • Python 3.7+
   • (Optional for GUI selection) tkinter (usually included with Python or installable via sudo apt-get install python3-tk on Debian/Ubuntu).

2. Clone the repository (if applicable):

   git clone <Jalalkhan912/File_MCP_Server>
   cd <File_MCP_Server>
   

3. Install Dependencies:

   pip install fastmcp starlette uvicorn
   

Usage

1. Run the Server: Execute the Python script directly.

   python fs_server.py
   

2. Workspace Selection: Upon running, the server will prompt you to select a workspace directory if the FS_WORKSPACE environment variable is not set.

   • Environment Variable: Set FS_WORKSPACE to your desired root path before running the script:

     export FS_WORKSPACE="/path/to/your/workspace"
     python fs_server.py
     

   • GUI Selection: If tkinter is available, a file dialog will appear to let you choose a directory.
   • Console Prompt: If GUI selection is not possible or cancelled, you can type the path in the console.

3. Accessing the Server: Once started, the server will be listening on http://0.0.0.0:8765.

   • Health Check: You can check the server's health at http://0.0.0.0:8765/healthz. It should return "ok".

   • MCP Tools: The MCP tools are accessible via the SSE (Server-Sent Events) endpoint, typically used by an MCP client. The base SSE endpoint is http://0.0.0.0:8765/sse. (Note: Interaction with MCP tools requires an MCP client library or a compatible system.)

   • Direct File Access: To access files directly from your chosen workspace, use the /files/ endpoint. For example, if your workspace is /home/user/my_project and you have a file /home/user/my_project/data/report.txt, you can access it at: http://0.0.0.0:8765/files/data/report.txt

Development / Advanced Usage

You can also run the server using uvicorn directly for more control, including hot-reloading for development:

uvicorn --app-dir . fs_server:app --host 0.0.0.0 --port 8765 --reload --log-level debug

(Note: If you renamed your file from fs_server_n8n.py to fs_server.py, adjust the command accordingly.)

Security Considerations

The primary security mechanism is workspace sandboxing. It's crucial that the FS_WORKSPACE directory is chosen carefully, as any operation performed via the MCP tools will be restricted to this directory. Users interacting with this server should understand that its capabilities are limited to the designated workspace.