# MCP Local Filesystem Server

An MCP (Model Context Protocol) server that provides secure access to local file system operations.

## Features

- **Read Files**: Read file contents with configurable encoding
- **Write Files**: Create or overwrite files
- **List Directories**: Browse directory contents
- **Create Directories**: Create new directories (with recursive option)
- **Delete Files/Directories**: Remove files or directories (with recursive option)
- **Move/Rename**: Move or rename files and directories
- **File Stats**: Get detailed file/directory metadata
- **Search Files**: Search for files matching patterns

## Security

The server implements directory-level access control. Only directories specified at startup are accessible, preventing unauthorized access to the rest of the filesystem.

## Installation

```bash
npm install
npm run build
```

## Usage

Start the server with one or more allowed directories:

```bash
node build/index.js /path/to/allowed/dir1 /path/to/allowed/dir2
```

Or using the binary:

```bash
mcp-local-filesystem /path/to/allowed/dir1 /path/to/allowed/dir2
```

## Configuration for Cursor

Add to your MCP settings configuration:

```json
{
  "mcpServers": {
    "local-filesystem": {
      "command": "node",
      "args": [
        "d:\\FILE_SYSTEM_MCP\\build\\index.js",
        "C:\\Users\\YourUsername\\Documents",
        "D:\\Projects"
      ]
    }
  }
}
```

## Available Tools

### read_file
Reads a file from the filesystem.

**Parameters:**
- `path` (string, required): Path to the file
- `encoding` (string, optional): Encoding to use (utf-8, ascii, base64)

### write_file
Writes content to a file (creates or overwrites).

**Parameters:**
- `path` (string, required): Path to the file
- `content` (string, required): Content to write
- `encoding` (string, optional): Encoding to use

### list_directory
Lists all files and directories in a directory.

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

### create_directory
Creates a new directory.

**Parameters:**
- `path` (string, required): Path for the new directory
- `recursive` (boolean, optional): Create parent directories if needed

### delete_path
Deletes a file or directory.

**Parameters:**
- `path` (string, required): Path to delete
- `recursive` (boolean, optional): Required for non-empty directories

### move_path
Moves or renames a file or directory.

**Parameters:**
- `source` (string, required): Source path
- `destination` (string, required): Destination path

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

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

### search_files
Searches for files matching a pattern.

**Parameters:**
- `directory` (string, required): Directory to search in
- `pattern` (string, required): Filename pattern (supports * and ?)
- `maxResults` (number, optional): Maximum results (default: 100)

## Resources

The server exposes each allowed directory as a resource with a `file://` URI scheme. You can use the `ReadResource` MCP operation to browse directories and read files.

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode for development
npm run watch
```

## License

MIT