🚀 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)

npm install -g tafa-mcp

Manual Installation

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

{
  "mcpServers": {
    "tafa-mcp": {
      "command": "tafa-mcp",
      "args": [
        "/Users/username/Documents",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

Docker Configuration

{
  "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

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:

Directory Sandboxing: Operations are restricted to specified directories
Path Validation: Prevents directory traversal attacks
Permission Checks: Validates file system permissions
File Size Limits: Prevents operations on extremely large files (100MB default)
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:

npm test

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

For issues and support:

GitHub Issues: Report a bug
Documentation: Full documentation

🚀 Roadmap

Tafa MCP - Making file system operations fast and efficient for Claude Desktop! 🚀