# MCP Filesystem Server

An MCP (Model Context Protocol) server for filesystem operations with built-in security features.

## Features

- **File Reading**: Read text file contents
- **File Writing**: Create or overwrite files
- **Directory Listing**: List contents with details (name, type, size, modified date)
- **File Search**: Search for files using regex patterns
- **File Information**: Get detailed metadata for files/directories
- **Directory Creation**: Create new directories
- **File Deletion**: Delete files and directories (Downloads folder only for safety)

## Security

The server implements the following security measures:

1. **Allowed Directories**: Only allows access to specific directories:
   - `~/Documents`
   - `~/Downloads`

2. **Delete Restrictions**: Delete operations are only allowed in `~/Downloads` folder for safety
3. **Path Validation**: Prevents path traversal attacks
4. **Size Limits**: Files limited to 10MB for read operations
5. **Depth Limits**: Searches limited to 5 levels deep by default

## Installation

```bash
# Install dependencies
npm install

# Compile TypeScript
npm run build
```

## Usage

### As a standalone MCP server

```bash
npm start
```

### Integration with Claude Desktop

1. Build the project:
```bash
npm run build
```

2. Update your Claude Desktop configuration at:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   - Linux: `~/.config/Claude/claude_desktop_config.json`

3. Add the server configuration:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["/absolute/path/to/MCP-test/dist/index.js"]
    }
  }
}
```

4. Restart Claude Desktop

## Available Tools

### read_file
Reads the contents of a file.

**Parameters:**
- `path` (string): Path to the file to read

**Example:**
```json
{
  "path": "~/Documents/test.txt"
}
```

### write_file
Writes content to a file.

**Parameters:**
- `path` (string): Path to the file
- `content` (string): Content to write

**Example:**
```json
{
  "path": "~/Documents/test.txt",
  "content": "Hello, World!"
}
```

### list_directory
Lists directory contents with details.

**Parameters:**
- `path` (string): Path to the directory

**Example:**
```json
{
  "path": "~/Documents"
}
```

### search_files
Searches for files matching a regex pattern.

**Parameters:**
- `directory` (string): Directory to search in (must be within allowed directories)
- `pattern` (string): Regex pattern to match file names
- `maxDepth` (number, optional): Maximum search depth (default: 5)

**Example:**
```json
{
  "directory": "~/Documents",
  "pattern": "\\.txt$",
  "maxDepth": 3
}
```

### get_file_info
Gets detailed information about a file or directory.

**Parameters:**
- `path` (string): Path to the file or directory

**Example:**
```json
{
  "path": "~/Documents/test.txt"
}
```

### create_directory
Creates a new directory.

**Parameters:**
- `path` (string): Path to the directory to create

**Example:**
```json
{
  "path": "~/Documents/new-folder"
}
```

### delete_file
Deletes a file or directory. **Only works in Downloads folder for safety.**

**Parameters:**
- `path` (string): Path to the file or directory to delete (must be in Downloads)
- `recursive` (boolean, optional): If true, delete directories and their contents recursively (default: false)

**Examples:**

Delete a file:
```json
{
  "path": "~/Downloads/old-file.txt"
}
```

Delete a directory and its contents:
```json
{
  "path": "~/Downloads/temp-folder",
  "recursive": true
}
```

**Important Notes:**
- Delete operations are **only allowed in the Downloads folder**
- Attempting to delete files in Documents or other locations will be denied
- Directories require `recursive: true` parameter to be deleted
- Deleted files cannot be recovered

## Development

```bash
# Compile in watch mode
npm run watch

# Compile once
npm run build

# Run after compiling
npm start
```

## Project Structure

```
MCP-test/
├── src/
│   └── index.ts          # Main MCP server
├── dist/                 # Compiled files (generated)
├── package.json
├── tsconfig.json
├── config.example.json   # Configuration example
└── README.md
```

## Customization

To change allowed directories, edit the `ALLOWED_DIRECTORIES` constant in `src/index.ts`:

```typescript
const ALLOWED_DIRECTORIES = [
  path.join(os.homedir(), "Documents"),
  path.join(os.homedir(), "Downloads"),
  // Add more directories here
];
```

To change the file size limit:

```typescript
const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
```

## Troubleshooting

### Server doesn't start
- Verify you've compiled the project with `npm run build`
- Verify the path in the configuration is absolute and correct

### "Access denied" when trying to access a file
- Verify the file is within `~/Documents` or `~/Downloads`
- Check file permissions

### "File too large"
- Files are limited to 10MB by default
- Modify `MAX_FILE_SIZE` if you need larger files

## License

MIT