Filesystem Model Context Protocol Server

Overview

Filesys is a lightweight MCP server built with Python and the MCP library that securely exposes file contents and metadata from a preconfigured directory. The project leverages FastMCP to provide a set of endpoints that allow:

• Listing all files in a specified directory.
• Reading the contents and metadata of a specified file.

The project ensures safe file access by validating paths and preventing directory traversal attacks.

Preview

Finding and reading the content of the test.txt file in the safe-folder:

How It Works

The core functionality is divided into two main components:

Resources

In src/resources.py, two functions are responsible for file operations:

• list_files(): Scans the base directory (configured in config/config.json) to return a list of visible files.
• read_file(filename): Reads the content of the specified file and returns it along with metadata (size and last modified timestamp), while ensuring that the file access is safe.

Server

In src/server.py, a FastMCP server is initialized and registers two resource endpoints:

• files://list: Invokes list_files_resource(), which returns the list of files.
• files://read/{filename}: Invokes read_file_resource(filename), which returns the file's content and metadata.

The server is started via run.py, and it utilizes the MCP library to handle resource requests.

Client & Testing

An example client in example_client.py demonstrates how to connect to the server, list resources, and read file contents using the MCP protocol. Unit tests in tests/test_resources.py ensure that the file listing and reading functionalities work as expected.

Installation

1. Clone the Repository:

   shell git clone https://github.com/iBz-04/Filesys.git

2. Navigate to the Project Directory:

   shell cd Filesys

3. Create a Virtual Environment (Optional but Recommended):

   shell python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

4. Install Dependencies:

   shell pip install -r requirements.txt

Configuration

The file server reads its configuration from config/config.json. By default, the server operates on the directory specified below:

{
  "directory": "./safe_folder"
}

You can modify this file to point to a different directory if needed.

Usage

1. Start the Server:

   shell python run.py

   This command will initialize the FastMCP server and register the file listing and reading endpoints.

2. Interact with the Server:

   • Using the Example Client:
     You can run the provided example client to interact with the server:

     shell python example_client.py

   • Direct Requests:
     Use any MCP-compatible client to access the endpoints:

     • List Files: Request files://list to get the list of files.
     • Read a File: Request files://read/{filename} (replace {filename} with the actual file name) to retrieve the file's content and metadata.

Testing

Run the unit tests to verify the functionality:

python -m unittest discover tests

This command will execute the tests in tests/test_resources.py to ensure that file operations perform correctly.

Contributing

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Commit your changes with detailed messages.
4. Push your branch and open a pull request.

Additional Notes

• Customize the configuration as needed.
• This project implements basic security measures to restrict file access to the configured directory.
• Update this documentation as new features are added or changes are made.

About

This is a Filesystem model context protocol server that could allow an LLM to read and list files from a specified directory on your local machine.

Topics

python
filesystem
mcp
ai-agents
llm
llm-agent
model-context-protocol
mcp-server
model-context-protocol-servers
mcp-sdk
python-mcp

Resources

Readme
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks

Report repository

Releases

No releases published

Packages 0

No packages published

Languages

• Python 100.0%