Fix/unicode normalization clean

[muthub-ai]

Title:
fix: Unicode normalization for macOS screenshot files and Unicode filenames

Summary

• All file operations now normalize Unicode in file paths (NFC, non-breaking space, special Unicode punctuation)
• Fixes ENOENT errors for macOS screenshot files and similar Unicode edge cases
• Adds excellent comments explaining rationale and edge cases
• Documents change and test results in README and PR_TEST_RESULTS.md
• All tests (create, move, read, list) pass for both normal and non-breaking space filenames
• See PR_TEST_RESULTS.md for full test evidence.

Description

See PR_TEST_RESULTS.md for full test evidence.

Unicode Normalization for File Operations

Added a sanitizeFilePath utility in index.ts that:
Normalizes all file paths to Unicode NFC form.
Replaces non-breaking spaces (U+00A0) with regular spaces.
Replaces a range of special Unicode spaces and punctuation that can appear in macOS screenshot filenames and other OS-generated files.
Integrated this normalization into all file operations by calling sanitizeFilePath in the validatePath function, ensuring every file operation (move, read, etc.) is robust against Unicode edge cases.

Server Details

Server: filesystem

Changes to:

1. Core file path handling logic (Unicode normalization in all file operations)
2. Documentation (README.md, new PR_TEST_RESULTS.md)
3. Code comments (improved clarity and rationale in index.ts)

Motivation and Context

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

How Has This Been Tested?

Test results attached in results.md. tested with Claude and Gemini

Breaking Changes

No

Types of changes

• [ x] Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• [ x] Documentation update

Checklist

• [ x] I have read the MCP Protocol Documentation
• [ x] My changes follows MCP security best practices
• [ x] I have updated the server's README accordingly
• [x ] I have tested this with an LLM client
• [x ] My code follows the repository's style guidelines
• [ x] New and existing tests pass locally
• [x ] I have added appropriate error handling
• [x ] I have documented all environment variables and configuration options

Additional context

[muthub-ai]

Everything is good to go, please review and approve.

[olaservo]

Closing this PR — it has merge conflicts due to the major architecture refactoring (Nov 2025) and would need a rewrite for the current codebase.

The Unicode normalization use case is valid. PR #3238 addresses Unicode handling more comprehensively (including umlauts and symlinks) against the current architecture, so we'll focus review efforts there.

One concern with this approach: the replacement range [\u2000-\u206F\u2E00-\u2E7F] is overly broad and would replace legitimate punctuation characters (em dashes, ellipses, etc.) in filenames with spaces. A targeted NFC normalization + non-breaking space fix would be safer.

Thank you for identifying the macOS screenshot filename issue.

This comment was posted by Claude Code on behalf of @olaservo.