INSTALL.md•5.09 kB
# 🚀 Tafa MCP Installation Guide
## Quick Start (5 minutes)
### 1. Install Node.js
Make sure you have Node.js 18+ installed:
```bash
# Check Node.js version
node --version
# If you need to install Node.js:
# Visit https://nodejs.org/ or use a package manager
```
### 2. Install Tafa MCP globally
```bash
npm install -g tafa-mcp
```
### 3. Test the installation
```bash
# Create a test directory
mkdir ~/tafa-test
echo "Hello Tafa!" > ~/tafa-test/test.txt
# Start the server (in another terminal)
tafa-mcp ~/tafa-test
# The server should output:
# 🚀 Tafa MCP Server initialized with directories:
# 📁 /Users/username/tafa-test
# 🎯 Tafa MCP Server connected and ready!
```
### 4. Configure Claude Desktop
**macOS/Linux**: Edit `~/.config/claude/claude_desktop_config.json`
**Windows**: Edit `%APPDATA%\claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"tafa-mcp": {
"command": "tafa-mcp",
"args": [
"/Users/username/Documents",
"/Users/username/Desktop",
"/Users/username/Downloads"
]
}
}
}
```
### 5. Restart Claude Desktop
Close and reopen Claude Desktop. You should now be able to use file system operations!
## Example Usage
Once configured, you can ask Claude:
```
"Please read the contents of my README.md file"
"Create a new file called notes.txt with today's tasks"
"Search for all Python files in my project directory"
"Organize my Downloads folder by file type"
"Find and remove duplicate files in my Documents"
```
## Available Commands
### File Operations
- `read_file(path)` - Read file contents
- `write_file(path, content, backup=true)` - Write file with backup
- `append_file(path, content)` - Append to file
- `copy_file(source, destination)` - Copy file
- `move_file(source, destination)` - Move/rename file
- `delete_file(path, backup=true)` - Delete file with backup
- `get_file_info(path)` - Get file metadata
### Directory Operations
- `create_directory(path)` - Create directory
- `list_directory(path, recursive=false, showHidden=false)` - List contents
- `delete_directory(path, backup=true)` - Delete directory with backup
### Search Operations
- `search_files(directory, pattern, recursive=true)` - Search files by pattern
- `search_content(directory, searchTerm, filePattern="*", recursive=true)` - Search content
- `find_duplicates(directory, minSize=0)` - Find duplicate files
### Advanced Operations
- `compress_files(sourcePaths, destinationPath, format="zip")` - Create archive
- `extract_archive(archivePath, destinationPath)` - Extract archive
- `batch_rename(directory, pattern, replacement)` - Batch rename files
- `organize_files(directory, organizationType="extension")` - Auto-organize files
## Security Features
🔒 **Safe by Design**
- Only operates within specified directories
- Automatic backups before destructive operations
- Path validation prevents directory traversal
- File size limits prevent system overload
- Permission checks before operations
## Troubleshooting
### Common Issues
**1. "Command not found: tafa-mcp"**
```bash
# Check if globally installed
npm list -g tafa-mcp
# If not installed:
npm install -g tafa-mcp
```
**2. "Access denied" errors**
- Ensure the directory is included in your Claude Desktop config
- Check file/directory permissions
- Verify the path exists and is accessible
**3. Claude Desktop not recognizing the server**
- Restart Claude Desktop after configuration changes
- Check the config file syntax (must be valid JSON)
- Verify the command path is correct
**4. Server startup issues**
```bash
# Test manually
tafa-mcp ~/Documents
# Check for error messages
# Ensure Node.js 18+ is installed
```
### Getting Help
- **Documentation**: [GitHub Wiki](https://github.com/your-org/tafa-mcp/wiki)
- **Issues**: [Report a Bug](https://github.com/your-org/tafa-mcp/issues)
- **Community**: [Discussions](https://github.com/your-org/tafa-mcp/discussions)
## Advanced Configuration
### Custom Backup Directory
```bash
# Set custom backup location
export TAFA_BACKUP_DIR="/path/to/backups"
tafa-mcp ~/Documents
```
### Docker Usage
```bash
# Build Docker image
docker build -t tafa-mcp .
# Run with volume mounts
docker run -i --rm \
-v /Users/username/Documents:/workspace/Documents \
-v /Users/username/Desktop:/workspace/Desktop \
tafa-mcp /workspace
```
### Development Setup
```bash
# Clone repository
git clone https://github.com/your-org/tafa-mcp.git
cd tafa-mcp
# Install dependencies
npm install
# Run tests
npm test
# Start development server
npm run dev
```
## Performance Tips
- **Large Directories**: Use `recursive=false` for faster listing
- **File Searches**: Use specific patterns to limit search scope
- **Backups**: Disable backups for non-critical operations
- **Memory**: Monitor memory usage with large file operations
## Updates
```bash
# Check current version
tafa-mcp --version
# Update to latest version
npm update -g tafa-mcp
```
---
**Need help?** Open an issue or check our [documentation](https://github.com/your-org/tafa-mcp/wiki) for more detailed guides!