# Local Files MCP Server

A Model Context Protocol (MCP) server for managing local files. Provides tools for reading, writing, analyzing, searching, and organizing files with built-in safety protections.

## Features

- 📖 **Read/Write files** - UTF-8 and base64 support
- 📂 **Directory operations** - List, organize, search
- 🔍 **Content search** - Regex pattern matching
- 🔎 **Find duplicates** - MD5 hash comparison
- 📊 **File analysis** - Size, MIME type, line counts
- 🛡️ **Safety protections** - Configurable allowed/protected paths
- 🖥️ **Cross-platform** - macOS, Linux, Windows

## Installation

### NPX

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

**Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "local-files": {
      "command": "npx",
      "args": ["-y", "fsorg"]
    }
  }
}
```

That's it! Claude Desktop will automatically download and run the MCP server via npx.

### Alternative: Install from source

```bash
git clone https://github.com/argtobias/fsorg.git
cd fsorg
pnpm install
pnpm build
```

Then configure Claude Desktop:

```json
{
  "mcpServers": {
    "local-files": {
      "command": "node",
      "args": ["/path/to/fsorg/dist/index.js"]
    }
  }
}
```

### Safety Configuration

Create a config file at:

-- **macOS/Linux**: `~/.config/localfiles-org/config.json`

-- **Windows**: `%LOCALAPPDATA%\localfiles-org\config.json`

```json
{
  "allowedPaths": [
    "~/projects",
    "~/Development",
    "~/workspace",
    "/tmp"
  ],
  "additionalProtectedPaths": [
    "~/my-important-folder"
  ],
  "additionalProtectedPatterns": [
    "^backup",
    "\\.bak$"
  ]
}
```

#### Configuration Options

| Option | Description | Default |
|--------|-------------|---------|
| `allowedPaths` | Paths where delete operations are permitted | `~/projects`, `~/dev`, etc. |
| `additionalProtectedPaths` | Extra paths to protect from deletion | `[]` |
| `additionalProtectedPatterns` | Regex patterns for protected file names | `[]` |

#### Always Protected (cannot be overridden)

- **System paths**: `/`, `/etc`, `/usr`, `/bin`, `/System`, etc.
- **User paths**: `~`, `~/Documents`, `~/Desktop`, `~/Downloads`, `~/.ssh`
- **Patterns**: `.git`, `.env`, `.ssh`, credentials, secrets

## Available Tools

### File Operations

| Tool | Description |
|------|-------------|
| `read_file` | Read file contents (UTF-8 or base64) |
| `write_file` | Write content to file (UTF-8 or base64) |
| `delete_file` | Safely delete a file with protection checks |
| `move_file` | Move file with optional empty directory cleanup |
| `analyze_file` | Get file stats (size, MIME, lines, words) |

### Directory Operations

| Tool | Description |
|------|-------------|
| `list_directory` | List files with optional recursion and glob patterns |
| `delete_directory` | Safely delete directory (requires confirmation for recursive) |
| `organize_by_type` | Organize files into folders by extension/date/size |

### Search Operations

| Tool | Description |
|------|-------------|
| `search_content` | Search for regex patterns in file contents |
| `find_duplicates` | Find duplicate files by MD5 hash |
| `sort_file_content` | Sort lines in a file |

### Batch Operations

| Tool | Description |
|------|-------------|
| `rename_files` | Batch rename files using regex patterns |

## Usage Examples

### Read a file
```json
{
  "tool": "read_file",
  "arguments": {
    "path": "~/projects/myfile.txt"
  }
}
```

### Find and delete duplicates
```json
{
  "tool": "find_duplicates",
  "arguments": {
    "path": "~/projects/images",
    "recursive": true
  }
}
```

### Safely delete with preview
```json
{
  "tool": "delete_file",
  "arguments": {
    "path": "~/projects/temp/old-file.txt",
    "preview": true
  }
}
```

### Organize files by extension
```json
{
  "tool": "organize_by_type",
  # Local Files MCP Server

  Simple MCP server for safe local file operations: read, write, search, organize and protected delete.

  ## Quick install

  Run via npx (recommended for Claude Desktop):

  ```json
  {
    "mcpServers": {
      "local-files": {
        "command": "npx",
        "args": ["-y", "fsorg"]
      }
    }
  }
  ```

  From source:

  ```bash
  git clone https://github.com/argtobias/fsorg.git
  cd fsorg
  pnpm install
  pnpm build
  ```

  ## Configuration

  Create user config at:

  - macOS/Linux: `~/.config/localfiles-org/config.json`
    
  - Windows: `%LOCALAPPDATA%\\localfiles-org\\config.json`

  Minimal config example:

  ```json
  {
    "allowedPaths": ["~/projects", "~/Development"],
    "additionalProtectedPaths": [],
    "additionalProtectedPatterns": []
  }
  ```

  ## Safety

  - Only operations inside `allowedPaths` can delete files.
  - System and user-critical paths are always protected.
  - Pattern-based protection (e.g. `.git`, `.env`) is enforced.

  ## Usage examples

  Read a file:

  ```json
  { "tool": "read_file", "arguments": { "path": "~/projects/myfile.txt" } }
  ```

  Find duplicates:

  ```json
  { "tool": "find_duplicates", "arguments": { "path": "~/projects/images", "recursive": true } }
  ```

  Delete with preview (safe):

  ```json
  { "tool": "delete_file", "arguments": { "path": "~/projects/temp/old.txt", "preview": true } }
  ```

  ## Development

  ```bash
  pnpm install
  pnpm build
  pnpm dev
  ```

  ## License

  ISC