huseyinkaracif/file-operations-mcp

File Operations MCP Server

A Model Context Protocol (MCP) server that provides secure file operation tools for AI assistants. This server allows safe reading, writing, and listing of files within configured directories.

Features

• Read Files: Read file contents with customizable encoding
• Write Files: Write content to files with encoding options
• List Directories: Browse directory contents with optional hidden file inclusion
• File Existence Check: Verify if files or directories exist
• Security: Path validation to prevent directory traversal attacks
• TypeScript: Fully typed for better development experience

Available Tools

read_file

Read the contents of a file.

Parameters:

• path (string, required): Path to the file to read
• encoding (string, optional): File encoding (default: 'utf8')

write_file

Write content to a file.

Parameters:

• path (string, required): Path to the file to write
• content (string, required): Content to write to the file
• encoding (string, optional): File encoding (default: 'utf8')

list_directory

List files and directories in a given path.

Parameters:

• path (string, required): Path to the directory to list
• includeHidden (boolean, optional): Include hidden files (default: false)

file_exists

Check if a file or directory exists.

Parameters:

• path (string, required): Path to check for existence

Installation

1. Clone or download this project
2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

Usage

Running the Server Directly

npm start

Development Mode

npm run dev

Adding to Cursor

To use this MCP server with Cursor, add the following configuration to your MCP settings:

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Go to "Features" → "Model Context Protocol"
3. Add a new server configuration:

{
  "file-operations": {
    "command": "node",
    "args": ["/absolute/path/to/file-operations-mcp/build/index.js"],
    "env": {}
  }
}

Or add to your ~/.cursor/mcp.json file:

{
  "mcpServers": {
    "file-operations": {
      "command": "node",
      "args": ["/absolute/path/to/file-operations-mcp/build/index.js"]
    }
  }
}

Security

This server implements several security measures:

• Path Validation: All file paths are validated to prevent directory traversal attacks
• Allowed Directories: Only files within the current working directory are accessible by default
• Safe Path Resolution: Uses Node.js path utilities to safely resolve file paths

Customizing Allowed Directories

To modify which directories the server can access, edit the ALLOWED_DIRECTORIES array in src/tools/file-tools.ts:

const ALLOWED_DIRECTORIES = [
  process.cwd(), // Current working directory
  '/path/to/your/safe/directory',
  // Add more allowed directories as needed
];

Example Responses

Successful File Read

{
  "success": true,
  "message": "File read successfully: /path/to/file.txt",
  "data": {
    "content": "Hello, World!",
    "path": "/path/to/file.txt"
  }
}

Directory Listing

{
  "success": true,
  "message": "Directory listed successfully: /path/to/directory",
  "data": {
    "files": [
      {
        "name": "example.txt",
        "path": "/path/to/directory/example.txt",
        "isDirectory": false,
        "isFile": true,
        "size": 1024,
        "lastModified": "2024-01-15T10:30:00.000Z"
      }
    ],
    "count": 1
  }
}

Error Response

{
  "success": false,
  "message": "Failed to read file: ENOENT: no such file or directory",
  "data": null
}

Development

Scripts

• npm run build: Compile TypeScript to JavaScript
• npm start: Run the compiled server
• npm run dev: Build and run in one command
• npm run watch: Watch for changes and recompile

Project Structure

file-operations-mcp/
├── src/
│   ├── index.ts              # Main server implementation
│   ├── tools/
│   │   └── file-tools.ts     # File operation implementations
│   └── types/
│       └── index.ts          # TypeScript type definitions
├── build/                    # Compiled JavaScript (after build)
├── package.json
├── tsconfig.json
└── README.md

Requirements

• Node.js >= 18.0.0
• npm or yarn package manager

License

MIT License - see package.json for details. by Hüseyin Karacif

Contributing

Feel free to open issues or submit pull requests to improve this MCP server!