filesystem.md

Filesystem Tool

The filesystem tool provides secure file and directory operations with strict access controls. This tool is disabled by default and must be explicitly enabled.

Security Notice

⚠️ IMPORTANT: This tool provides direct filesystem access and is disabled by default. Only enable it if you understand the security implications and trust the AI agent with filesystem operations.

Configuration

Environment Variables

• ENABLE_ADDITIONAL_TOOLS (required): Add filesystem to enable the tool (disabled by default)
• FILESYSTEM_TOOL_ALLOWED_DIRS (optional): Colon-separated (Unix) list of allowed directory paths

Custom Allowed Directories

By default, the tool allows access to:

• Current working directory
• User home directory

To restrict access to specific directories only:

Unix/Linux/macOS:

export FILESYSTEM_TOOL_ALLOWED_DIRS="/home/user/projects:/tmp:/home/user/documents"

MCP Configuration Example

{
  "mcpServers": {
    "dev-tools": {
      "type": "stdio",
      "command": "/path/to/mcp-devtools",
      "env": {
        "FILESYSTEM_TOOL_ENABLE": "true",
        "FILESYSTEM_TOOL_ALLOWED_DIRS": "/home/user/projects:/tmp"
      }
    }
  }
}

Features

• File Operations: Read, write, and edit files with atomic operations
• Directory Operations: Create, list, and navigate directories
• File Search: Recursively search for files with pattern matching
• File Metadata: Get detailed file information including size, permissions, and timestamps
• Security: Strict directory access control prevents operations outside allowed directories
• Advanced Features: Head/tail file reading, directory trees, file moving
• Configurable Access: Customisable allowed directories via environment variables

Functions

File Operations

read_file

Read complete contents of a file or specific lines.

Parameters:

• path (required): File path to read
• head (optional): Read only first N lines
• tail (optional): Read only last N lines

Example:

{
  "function": "read_file",
  "options": {
    "path": "/path/to/file.txt",
    "head": 10
  }
}

read_multiple_files

Read multiple files simultaneously for efficient batch operations.

Parameters:

• paths (required): Array of file paths

Example:

{
  "function": "read_multiple_files",
  "options": {
    "paths": ["/path/to/file1.txt", "/path/to/file2.txt"]
  }
}

write_file

Create new file or overwrite existing file with content.

Parameters:

• path (required): File path to write
• content (required): Content to write

Example:

{
  "function": "write_file",
  "options": {
    "path": "/path/to/file.txt",
    "content": "Hello, World!"
  }
}

edit_file

Make selective edits to files with diff preview.

Parameters:

• path (required): File path to edit
• edits (required): Array of edit operations with oldText and newText
• dryRun (optional): Preview changes without applying (default: false)

Example:

{
  "function": "edit_file",
  "options": {
    "path": "/path/to/file.txt",
    "edits": [
      {
        "oldText": "old content",
        "newText": "new content"
      }
    ],
    "dryRun": true
  }
}

Directory Operations

create_directory

Create directory with parent directories as needed.

Parameters:

• path (required): Directory path to create

Example:

{
  "function": "create_directory",
  "options": {
    "path": "/path/to/new/directory"
  }
}

list_directory

List directory contents with file/directory indicators.

Parameters:

• path (required): Directory path to list

Example:

{
  "function": "list_directory",
  "options": {
    "path": "/path/to/directory"
  }
}

list_directory_with_sizes

List directory contents with file sizes and sorting options.

Parameters:

• path (required): Directory path to list
• sortBy (optional): Sort by "name" or "size" (default: "name")

Example:

{
  "function": "list_directory_with_sizes",
  "options": {
    "path": "/path/to/directory",
    "sortBy": "size"
  }
}

directory_tree

Get recursive tree view of directory structure as JSON.

Parameters:

• path (required): Root directory path

Example:

{
  "function": "directory_tree",
  "options": {
    "path": "/path/to/directory"
  }
}

File Management

move_file

Move or rename files and directories.

Parameters:

• source (required): Source path
• destination (required): Destination path

Example:

{
  "function": "move_file",
  "options": {
    "source": "/path/to/old/location",
    "destination": "/path/to/new/location"
  }
}

search_files

Recursively search for files matching a pattern.

Parameters:

• path (required): Starting directory path
• pattern (required): Search pattern (case-insensitive)
• excludePatterns (optional): Array of patterns to exclude

Example:

{
  "function": "search_files",
  "options": {
    "path": "/path/to/search",
    "pattern": "*.txt",
    "excludePatterns": ["*.tmp", "node_modules"]
  }
}

get_file_info

Get detailed metadata about a file or directory.

Parameters:

• path (required): File or directory path

Example:

{
  "function": "get_file_info",
  "options": {
    "path": "/path/to/file.txt"
  }
}

Security

list_allowed_directories

List all directories the tool is allowed to access.

Parameters: None

Example:

{
  "function": "list_allowed_directories",
  "options": {}
}

Security Features

Directory Access Control

• All operations are restricted to allowed directories
• Symlink validation prevents directory traversal attacks
• Atomic file operations prevent race conditions
• Path normalisation prevents bypass attempts

Default Allowed Directories

• Current working directory
• User home directory
• Can be configured via MCP Roots protocol

Safe Operations

• Atomic writes using temporary files
• Symlink resolution and validation
• Parent directory validation for new files
• Comprehensive error handling

Usage Examples

Basic File Operations

// Write a configuration file
{
  "function": "write_file",
  "options": {
    "path": "./config.json",
    "content": "{\"debug\": true}"
  }
}

// Read the file back
{
  "function": "read_file",
  "options": {
    "path": "./config.json"
  }
}

Directory Management

// Create project structure
{
  "function": "create_directory",
  "options": {
    "path": "./src/components"
  }
}

// List contents with sizes
{
  "function": "list_directory_with_sizes",
  "options": {
    "path": "./src",
    "sortBy": "size"
  }
}

File Search and Analysis

// Find all TypeScript files
{
  "function": "search_files",
  "options": {
    "path": "./src",
    "pattern": ".ts",
    "excludePatterns": ["node_modules", "*.d.ts"]
  }
}

// Get file information
{
  "function": "get_file_info",
  "options": {
    "path": "./package.json"
  }
}

Advanced File Reading

// Read last 50 lines of log file
{
  "function": "read_file",
  "options": {
    "path": "./app.log",
    "tail": 50
  }
}

// Preview file edits
{
  "function": "edit_file",
  "options": {
    "path": "./config.js",
    "edits": [
      {
        "oldText": "debug: false",
        "newText": "debug: true"
      }
    ],
    "dryRun": true
  }
}

Error Handling

The tool provides comprehensive error handling for:

• Access Denied: Operations outside allowed directories
• File Not Found: Missing files or directories
• Permission Errors: Insufficient file system permissions
• Invalid Parameters: Missing or malformed parameters
• Symlink Security: Symlinks pointing outside allowed directories

Best Practices

1. Use dryRun for edits: Always preview file edits before applying
2. Validate paths: Check allowed directories before operations
3. Handle errors gracefully: All operations can fail, handle errors appropriately
4. Use atomic operations: The tool uses atomic writes for safety
5. Respect security boundaries: Don't attempt to bypass directory restrictions

Dependencies

• None: Pure Go implementation with standard library
• Cross-platform: Works on macOS and Linux
• Secure by default: Directory access control enabled by default