🐛 MCP Filesystem: macOS Screenshot Files Fail with Unicode Characters (ENOENT Error)

[jagansanikommu]

🐛 Bug Report: MCP Filesystem Operations Fail with macOS Screenshot Files

Issue Summary

MCP filesystem operations (move, read, access) fail on macOS system-generated screenshot files despite files being visible in directory listings. This affects file organization workflows and creates inconsistent behavior between file listing and file manipulation operations.

Environment

• OS: macOS (multiple versions affected)
• MCP Server: @modelcontextprotocol/server-filesystem
• Node.js: (applicable versions)
• Files Affected: System-generated screenshot files specifically

Bug Description

Expected Behavior

• Files visible in list_directory operations should be accessible for move_file, read_file, and other filesystem operations
• All files with standard characters (including spaces) should be movable

Actual Behavior

• Screenshot files appear in directory listings but throw ENOENT: no such file or directory errors during move/access operations
• Regular files with spaces work perfectly when created manually
• Only affects macOS system-generated screenshots

Reproduction Steps

1. Take screenshots on macOS (creates files like Screenshot 2025-04-23 at 2.40.40 PM.png)
2. Use MCP list_directory tool - files appear normally
3. Attempt to use move_file or read_file on these screenshots
4. Operations fail with ENOENT errors
5. Create a test file with similar naming manually - it works fine

Root Cause Analysis

macOS screenshot files contain non-standard Unicode characters:

• Non-breaking spaces (U+00A0) instead of regular spaces (U+0020)
• Special Unicode characters in timestamps and punctuation
• Extended file attributes that interfere with standard Node.js file operations

Evidence

# This works (manually created file)
touch "Screenshot 2025-04-23 at 2.40.40 PM copy.png"
# MCP can move this file successfully

# This fails (macOS system-generated)  
mv "Screenshot 2025-04-23 at 2.40.40 PM.png" ./Images/
# ENOENT error in MCP operations

Impact

• High: Affects common file organization workflows
• User Experience: Creates confusion when "visible" files can't be accessed
• Productivity: Forces manual workarounds for basic file management
• Cross-platform: Specifically impacts macOS users with no clear error messaging

Workarounds Currently Available

For Users:

1. Manual drag-and-drop in Finder
2. Rename files to simpler names first
3. Use Terminal with shell globbing: mv Screenshot*.png ./Images/

For Developers:

// Unicode normalization before file operations
function normalizeFilename(filename) {
    return filename
        .normalize('NFC')
        .replace(/\u00A0/g, ' ')  // Replace non-breaking spaces
        .replace(/[\u2000-\u206F]/g, ' '); // Replace Unicode spaces
}

Proposed Solutions

1. Unicode Normalization (Recommended)

• Implement filename normalization before all file operations
• Handle common Unicode edge cases in filesystem operations
• Add this to the core MCP filesystem server

2. Better Error Handling

• Distinguish between "file not found" vs "file access encoding issues"
• Provide more descriptive error messages for Unicode-related failures
• Suggest normalization when Unicode issues are detected

3. Alternative Access Methods

• Use native OS APIs that handle Unicode edge cases better
• Implement fallback mechanisms for problematic filenames

4. Documentation & Warning

• Document known limitations with macOS screenshot files
• Provide clear workarounds in the README
• Add warning in error messages about potential Unicode issues

Technical Implementation Suggestion

// Add to filesystem operations
function sanitizeFilePath(filePath: string): string {
    return filePath
        .normalize('NFC')
        .replace(/\u00A0/g, ' ')
        .replace(/[\u2000-\u206F\u2E00-\u2E7F]/g, ' ');
}

// Apply before all file operations
export async function moveFile(source: string, destination: string) {
    const normalizedSource = sanitizeFilePath(source);
    const normalizedDest = sanitizeFilePath(destination);
    // ... existing move logic
}

Testing Files

I can provide test screenshot files demonstrating this issue if needed for reproduction.

Related Issues

This may affect other MCP filesystem implementations:

• mark3labs/mcp-filesystem-server
• bsmi021/mcp-filesystem-server
• Other Node.js based filesystem MCPs

---

Request: This impacts daily productivity for macOS users. Unicode normalization would solve this elegantly while maintaining backward compatibility.

Let me know if you need additional details, test files, or are interested in a PR implementing the Unicode normalization solution.