{"id":26538869,"url":"https://github.com/ibz-04/filesys","last_synced_at":"2025-03-21T23:30:21.936Z","repository":{"id":282791169,"uuid":"949665449","full_name":"iBz-04/Filesys","owner":"iBz-04","description":"This is a Filesystem MCP server that could allow an LLM to read and list files from a specified directory on your local machine.","archived":false,"fork":false,"pushed_at":"2025-03-16T23:54:25.000Z","size":0,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-17T00:29:24.463Z","etag":null,"topics":["filesystem","llm-agent","mcp","mcp-sdk","mcp-server","model-context-protocol","model-context-protocol-servers","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iBz-04.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-16T23:50:15.000Z","updated_at":"2025-03-16T23:59:26.000Z","dependencies_parsed_at":"2025-03-17T00:39:30.218Z","dependency_job_id":null,"html_url":"https://github.com/iBz-04/Filesys","commit_stats":null,"previous_names":["ibz-04/filesys"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iBz-04%2FFilesys","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iBz-04%2FFilesys/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iBz-04%2FFilesys/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iBz-04%2FFilesys/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iBz-04","download_url":"https://codeload.github.com/iBz-04/Filesys/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244884558,"owners_count":20526252,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["filesystem","llm-agent","mcp","mcp-sdk","mcp-server","model-context-protocol","model-context-protocol-servers","python"],"created_at":"2025-03-21T23:30:21.378Z","updated_at":"2025-03-21T23:30:21.922Z","avatar_url":"https://github.com/iBz-04.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# File system MCP\n\n## Overview\nfilesys 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:\n- Listing all files in a specified directory.\n- Reading the contents and metadata of a specified file.\n\nThe project ensures safe file access by validating paths and preventing directory traversal attacks.\n\n## Preview\n- finding  and reading the the content of the test.txt file in the safe-folder\n\n\u003cimg src=\"https://res.cloudinary.com/diekemzs9/image/upload/v1742201934/Screenshot_2025-03-16_233952_fhr4m8.png\" alt=\"My Image\" width=\"950\"/\u003e\n\n## How It Works\nThe core functionality is divided into two main components:\n\n- **Resources:**  \n  In `src/resources.py`, two functions are responsible for file operations:\n  - `list_files()`: Scans the base directory (configured in `config/config.json`) to return a list of visible files.\n  - `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.\n\n- **Server:**  \n  In `src/server.py`, a FastMCP server is initialized and registers two resource endpoints:\n  - `files://list`: Invokes `list_files_resource()`, which returns the list of files.\n  - `files://read/{filename}`: Invokes `read_file_resource(filename)`, which returns the file's content and metadata.\n  \nThe server is started via `run.py`, and it utilizes the mcp library to handle resource requests.\n\n- **Client \u0026 Testing:**  \n  An example client in `example_client.py` demonstrates how to connect to the server, list resources, and read file contents using the MCP protocol.  \n  Unit tests in `tests/test_resources.py` ensure that the file listing and reading functionalities work as expected.\n\n## Installation\n1. **Clone the Repository:**\n   ```bash\n   git clone https://github.com/iBz-04/Filesys.git\n   ```\n2. **Navigate to the Project Directory:**\n   ```bash\n   cd Filesys\n   ```\n3. **Create a Virtual Environment (Optional but Recommended):**\n   ```bash\n   python -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n4. **Install Dependencies:**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n## Configuration\nThe file server reads its configuration from `config/config.json`. By default, the server operates on the directory specified below:\n```json\n{\n  \"directory\": \"./safe_folder\"\n}\n```\nYou can modify this file to point to a different directory if needed.\n\n## Usage\n1. **Start the Server:**\n   ```bash\n   python run.py\n   ```\n   This command will initialize the FastMCP server and register the file listing and reading endpoints.\n\n2. **Interact with the Server:**\n   - **Using the Example Client:**  \n     You can run the provided example client to interact with the server:\n     ```bash\n     python example_client.py\n     ```\n   - **Direct Requests:**  \n     Use any MCP-compatible client to access the endpoints:  \n     - **List Files:** Request `files://list` to get the list of files.\n     - **Read a File:** Request `files://read/{filename}` (replace `{filename}` with the actual file name) to retrieve the file's content and metadata.\n\n## Testing\nRun the unit tests to verify the functionality:\n```bash\npython -m unittest discover tests\n```\nThis command will execute the tests in `tests/test_resources.py` to ensure that file operations perform correctly.\n\n## Contributing\nContributions are welcome! To contribute:\n1. Fork the repository.\n2. Create a new branch for your feature or bugfix.\n3. Commit your changes with detailed messages.\n4. Push your branch and open a pull request.\n\n\n\n## Additional Notes\n- Customize the configuration as needed.\n- This project implements basic security measures to restrict file access to the configured directory.\n- Update this documentation as new features are added or changes are made. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibz-04%2Ffilesys","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibz-04%2Ffilesys","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibz-04%2Ffilesys/lists"}