Tafa MCP Server

# 🚀 Tafa MCP Server **Tafa** (meaning "quick" in several African languages) is a production-ready Model Context Protocol (MCP) server that provides comprehensive file system management capabilities for seamless integration with Claude Desktop. ## ✨ Features ### 🗂️ File Operations - **read_file** - Read complete file contents with UTF-8 encoding - **write_file** - Create new files or overwrite existing ones (with backup) - **append_file** - Add content to existing files - **copy_file** - Copy files to new locations - **move_file** - Move/rename files - **delete_file** - Remove files with confirmation and backup - **get_file_info** - Get detailed file metadata (size, dates, permissions, hash) ### 📁 Directory Operations - **create_directory** - Create directories with parent creation - **list_directory** - List contents with file/directory indicators (recursive option) - **delete_directory** - Remove directories with confirmation and backup - **get_directory_info** - Get directory metadata and statistics ### 🔍 Search Operations - **search_files** - Recursive file search with pattern matching - **search_content** - Search within file contents (grep-like functionality) - **find_duplicates** - Find duplicate files by content hash ### 🔒 Security Features - **Sandboxed Operations** - Only allow operations within specified directories - **Automatic Backups** - Creates backups before destructive operations - **Path Validation** - Prevents directory traversal attacks - **File Size Limits** - Prevents operations on extremely large files - **Permission Checks** - Validates read/write permissions before operations ## 🛠️ Installation ### Quick Install (NPM) ```bash npm install -g tafa-mcp ``` ### Manual Installation ```bash git clone https://github.com/your-org/tafa-mcp.git cd tafa-mcp npm install npm run install-global ``` ## ⚙️ Configuration ### Claude Desktop Configuration Add to your Claude Desktop configuration file: **macOS/Linux**: `~/.config/claude/claude_desktop_config.json` **Windows**: `%APPDATA%\claude\claude_desktop_config.json` ```json { "mcpServers": { "tafa-mcp": { "command": "tafa-mcp", "args": [ "/Users/username/Documents", "/Users/username/Desktop", "/Users/username/Downloads" ] } } } ``` ### Docker Configuration ```json { "mcpServers": { "tafa-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "--mount", "type=bind,src=/Users/username/Documents,dst=/workspace/Documents", "--mount", "type=bind,src=/Users/username/Desktop,dst=/workspace/Desktop", "tafa-mcp", "/workspace" ] } } } ``` ## 🚀 Usage ### Starting the Server ```bash tafa-mcp /path/to/directory1 /path/to/directory2 ``` ### Example Usage with Claude Once configured, you can use Claude to perform file operations: ``` "Can you read the contents of my README.md file?" "Please create a new file called notes.txt with some sample content" "Search for all JavaScript files in my project directory" "Find duplicate files in my Downloads folder" ``` ## 🔧 Available Tools ### File Operations - `read_file(path)` - Read file contents - `write_file(path, content, backup=true)` - Write file with optional backup - `append_file(path, content)` - Append content to file - `copy_file(source, destination)` - Copy file - `move_file(source, destination)` - Move/rename file - `delete_file(path, backup=true)` - Delete file with optional backup - `get_file_info(path)` - Get file metadata ### Directory Operations - `create_directory(path)` - Create directory - `list_directory(path, recursive=false, showHidden=false)` - List directory contents - `delete_directory(path, backup=true)` - Delete directory with backup ### Search Operations - `search_files(directory, pattern, recursive=true)` - Search files by name pattern - `search_content(directory, searchTerm, filePattern="*", recursive=true)` - Search file contents ### Utility - `get_server_info()` - Get server information and available tools ## 🔐 Security Tafa MCP implements several security measures: 1. **Directory Sandboxing**: Operations are restricted to specified directories 2. **Path Validation**: Prevents directory traversal attacks 3. **Permission Checks**: Validates file system permissions 4. **File Size Limits**: Prevents operations on extremely large files (100MB default) 5. **Automatic Backups**: Creates backups before destructive operations ## 🗂️ Project Structure ``` tafa-mcp/ ├── package.json ├── README.md ├── src/ │ ├── index.js # Main server entry point │ └── tools/ │ ├── fileOperations.js # File operation handlers │ ├── directoryOperations.js # Directory operation handlers │ ├── searchOperations.js # Search operation handlers │ └── securityManager.js # Security and validation ├── config/ │ └── claude_desktop_config.example.json └── tests/ └── basic-tests.js ``` ## 🧪 Testing Run basic tests: ```bash npm test ``` ## 🤝 Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests for new functionality 5. Submit a pull request ## 📄 License MIT License - see LICENSE file for details. ## 🆘 Support For issues and support: - GitHub Issues: [Report a bug](https://github.com/your-org/tafa-mcp/issues) - Documentation: [Full documentation](https://github.com/your-org/tafa-mcp/wiki) ## 🚀 Roadmap - [ ] Archive operations (ZIP/TAR) - [ ] File synchronization - [ ] Batch operations - [ ] File organization tools - [ ] Git integration - [ ] Extended search capabilities --- **Tafa MCP** - Making file system operations fast and efficient for Claude Desktop! 🚀