Filesys

Filesys exposes a small API over MCP to securely access the contents and metadata of a configured directory. The server reads its base directory from config/config.json (by default ./safe_folder) and provides two resource endpoints: files://list, which returns the list of visible files, and files://read/{filename}, which returns the contents and basic metadata (size and last modified timestamp) for a given file. A new Claude AI integration is included, enabling natural language queries via Claude Tools that can list files or read specific files by translating your questions into MCP calls. The Claude client functions act as a bridge, calling the MCP endpoints and returning structured results for consumption in conversations. To use the Claude integration, you need an Anthropic API key configured in .env.local as ANTHROPIC_API_KEY. Start the MCP server, then run the Claude interaction script to begin a chat that can ask things like “What files are available?” or “Read test.txt for me.”

Prerequisites:

• Python 3.8+ installed on your system
• Git installed
• Optional: a virtual environment tool (venv) is available

Step-by-step:

1. Clone the repository

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

2. Navigate into the project directory

cd Filesys

3. Create and activate a virtual environment (optional but recommended)

python -m venv venv
# macOS/Linux
source venv/bin/activate
# Windows
venv\Scripts\activate

4. Install dependencies

pip install -r requirements.txt

5. Configure Anthropic API key for Claude integration

• Create a file named .env.local in the project root
• Add your API key:

ANTHROPIC_API_KEY=your_api_key_here

• Ensure .gitignore prevents committing this file

6. Configure the server directory (optional)

• Edit config/config.json to set the base directory, if needed:

{
  "directory": "./safe_folder"
}

7. Start the MCP server

python run.py

8. (Optional) Run the Claude integration script in a separate terminal

python interact_with_claude.py

Notes:

• The Claude integration relies on Claude Tools defined in claude_tool_client.py and interact_with_claude.py. Ensure the Anthropic API key is available in the environment as described above.
• The server exposes two MCP endpoints: files://list and files://read/{filename}.

Common issues and tips:

• If you change the base directory in config/config.json, restart the MCP server to apply changes.
• Ensure the safe_folder permissions allow read access for the user running the server.
• The Claude integration depends on the Claude Tools defined in the project; if Claude cannot access the MCP endpoints, verify the server is reachable and that the tools are correctly configured.
• For testing, you can directly query the MCP endpoints with any MCP-compatible client using files://list and files://read/{filename}.
• Keep the ANTHROPIC_API_KEY secret; it should reside only in .env.local and be ignored by git.