# 🚀 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! 🚀