# MCP Duplicate File Manager Server

A Model Context Protocol (MCP) server that enables LLM-based AI agents to manage duplicate files efficiently. Designed for seamless integration with LLMs and AI agents using the MCP protocol with intelligent duplicate detection and safe deletion capabilities.

---

## Features

- Exposes file management tools for LLM agents via MCP:
  - `list_files`: List files in directories with optional filtering
  - `find_duplicates`: Find duplicate files based on content hash (MD5)
  - `delete_duplicates`: Safely delete duplicate files with intelligent copy detection
- Smart copy detection: Prioritizes deleting files with copy indicators ("copy", "(1)", "(2)", etc.)
- Content-based duplicate detection using MD5 hashing for accuracy
- Recursive directory scanning with optional pattern matching
- Dry-run mode for safe preview before actual deletion
- Simple integration with Claude, MCP clients, or other LLM-based agents

---

## Quickstart

### 1. Install & Run

Run the MCP Duplicate File Manager Server using [`uvx`](https://github.com/uvx-dev/uvx):

```bash
uvx --from git+https://github.com/deerajd/DuplicateFileRemover-MCP.git mcp-server
```

---

### 2. Integrate with Your LLM Agent

Add the following to your tool configuration (for Claude, MCP clients, etc.):

```json
{
  "mcpServers": {
    "DuplicateListor": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/deerajd/DuplicateFileRemover-MCP.git",
        "mcp-server"
      ]
    }
  }
}
```

This configuration launches the MCP Duplicate File Manager Server as a subprocess, exposing file management tools to your LLM agent.

---

### 3. Usage

From your LLM agent, you can call:

#### List Files in Directory
```
list_files(directory="./Documents", pattern="*.pdf")        # List PDF files
list_files(directory="/home/user", include_hidden=True)     # Include hidden files
list_files()                                                # List all files in current directory
```

#### Find Duplicate Files
```
find_duplicates(directory="./Downloads")                    # Find duplicates in Downloads
find_duplicates(directory="/Users/john/Desktop", recursive=False)  # Non-recursive search
find_duplicates()                                           # Find duplicates in current directory
```

#### Delete Duplicate Files
```
delete_duplicates(directory="./Documents", dry_run=True)    # Preview what would be deleted
delete_duplicates(directory="./Documents", dry_run=False)   # Actually delete duplicates
delete_duplicates(directory="./Pictures", recursive=True)   # Recursive deletion with preview
```

The server provides detailed responses including:
- List of files with metadata (name, size, type, path)
- Duplicate file groups organized by content hash
- Deletion results with preserved originals and deleted copies
- Error handling for inaccessible files or directories

---

## API Reference

### `list_files(directory=".", pattern="*", include_hidden=False)`
- **Parameters:**
  - `directory` (str): Directory path to list files from (default: current directory)
  - `pattern` (str): File pattern to match (e.g., "*.py", "*.txt") (default: "*")
  - `include_hidden` (bool): Whether to include hidden files (default: False)
- **Returns:** List of dictionaries containing file information (name, size, type, path, modified)

### `find_duplicates(directory=".", recursive=True)`
- **Parameters:**
  - `directory` (str): Directory path to search for duplicates (default: current directory)
  - `recursive` (bool): Whether to search recursively in subdirectories (default: True)
- **Returns:** Dictionary with hash as key and list of duplicate file paths as values

### `delete_duplicates(directory=".", recursive=True, dry_run=True)`
- **Parameters:**
  - `directory` (str): Directory path to search for duplicates (default: current directory)
  - `recursive` (bool): Whether to search recursively in subdirectories (default: True)
  - `dry_run` (bool): If True, only show what would be deleted without actually deleting (default: True)
- **Returns:** Dictionary with information about deleted files and preserved originals

#### Smart Copy Detection
The server intelligently identifies and prioritizes deletion of files with copy indicators:
- `copy` - Files containing "copy" in the filename
- `(1)`, `(2)`, etc. - Files with numbered suffixes
- `_copy`, `-copy` - Files with copy prefixes/suffixes
- `duplicate`, `dup` - Files marked as duplicates
- Multiple language variants (copie, kopia, copia)

---

## Development

### Requirements
- Python 3.8+
- [`hashlib`](https://docs.python.org/3/library/hashlib.html) for MD5 hashing
- [`pathlib`](https://docs.python.org/3/library/pathlib.html) for file path operations
- [`FastMCP`](https://github.com/modelcontext/fastmcp) for MCP server implementation

### Project Structure
```
DuplicateListor/
├── duplicatelist.py             # Main server implementation
├── main.py                      # Entry point
├── pyproject.toml               # Project configuration
└── README.md                    # This file
```

---

## Safety Features

- **Dry-run Mode**: Preview changes before actual deletion
- **Smart Original Detection**: Preserves files without copy indicators
- **Error Handling**: Graceful handling of inaccessible files
- **Content-based Matching**: Uses MD5 hashing for accurate duplicate detection
- **Detailed Reporting**: Comprehensive feedback on all operations

---

## License

MIT License

---