Filesys

🚀 File System MCP Project Documentation

The filesys project is a lightweight MCP server built on Python and the mcp library. It securely exposes file content and metadata from pre - configured directories. Leveraging FastMCP, it offers functionalities like listing files in a specified directory and reading file content and metadata.

✨ Features

• List all files in a specified directory.
• Read the content and metadata of a specific file.
• New Feature: Integrated with Anthropic's Claude AI, allowing users to interact with the file system through natural - language conversations. It uses Claude Tools to securely access defined MCP resources.

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

🎉 Feature Preview

• Chat with Claude to list and read files in the safe_folder:

🔧 How It Works

The core functionality is divided into the following parts:

• Resources: In src/resources.py, two functions handle file operations:

  • list_files(): Scans the specified directory and returns a list of all files.
  • read_file(): Reads the content of a file based on its name and returns the content.

• Server: In run.py, a simple MCP server is defined. After starting, it listens on a port and processes requests from clients. The server calls functions in the resource module to respond to requests.

• Claude Tool Client: In claude_tool_client.py, utility functions for interacting with the MCP server are defined. These functions can be used to test the server's functionality and provide an interface for Claude to send requests.

• Testing: If there are unit - test files in the tests/ directory (e.g., tests/test_resources.py), you can run the tests with the following command:

  python -m unittest discover tests
  

📦 Installation

1. Clone the repository:

   git clone [Repository URL]
   

2. Create a virtual environment and install dependencies:

   python -m venv venv
   source venv/bin/activate  # Use `venv\Scripts\activate` on Windows
   pip install mcp
   

3. Configure API keys:
   • Modify the config/config.json file to set the server's configuration (e.g., port).
   • Create a .env.local file and add Anthropic's API key.

💻 Usage Examples

Basic Usage

1. Start the MCP server:

   python run.py
   

2. Chat with Claude:

   python interact_with_claude.py
   

3. Send MCP requests directly (optional):
   • List files: Send the request files://list.
   • Read a file: Send the request files://read/{filename} (replace {filename} with the actual file name).

🤝 Contribution Guidelines

Contributions are welcome! To contribute to the project, follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or fix.
3. Commit your changes with detailed commit messages.
4. Push the branch and open a Pull Request on GitHub.

📄 Other Notes

• Customize the configuration files (config/config.json and .env.local) as needed.

• ⚠️ Important Note

  The interact_with_claude.py script requires the run.py server to be running in another process.

• The project implements basic security measures to restrict access to the configured directories and prevent directory traversal attacks.
• Update this documentation if you add new features or make changes.