test(filesystem): add regression tests for Docker Linux path handling

[majiayu000]

Fixes #3628

Description

Adds regression tests for the Docker/Linux path normalization bug where paths like /h/username/MCP_Development/data got wrongly converted to H:\username\MCP_Development\data. The code fix already landed on main (commit c9b0135 added platform detection to normalizePath and convertToWindowsPath), but there were no tests covering the exact scenario from the issue.

New tests mock process.platform to 'linux' (simulating Docker Alpine) and verify that single-letter root directories (/h/, /u/, /d/) aren't mistaken for Windows drive letters. Uses the same mocking pattern already in the WSL test block.

Note: Docker image 1.0.2 still has the bug. It needs rebuilding from current main to pick up the fix.

Server Details

• Server: filesystem
• Changes to: tests only (path-utils.test.ts)

Motivation and Context

Issue #3628 reports that the filesystem server running in Docker Alpine Linux converts valid Linux paths to Windows-style paths. The fix exists but had no dedicated test coverage for the Docker scenario.

How Has This Been Tested?

cd src/filesystem && npm test — all 149 tests pass (7 test files), including the new regression tests.

Breaking Changes

None. Test-only change.

Types of changes

• 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)
• Documentation update

Checklist

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

[cliffhall]

@claude review

[claude]

Claude finished @cliffhall's task in 1m 34s —— View job

---

PR Review

• Read changed files and gather context
• Review test quality and correctness
• Check against existing patterns and style guidelines
• Post review findings

---

Summary: This is a test-only PR adding regression tests for issue #3628 (Docker Alpine Linux wrongly converting /h/username/... to H:\username\...). The implementation fix already landed in main. The tests are well-written overall with a few minor notes.

---

What the PR adds

A new describe('Linux Docker path handling (issue #3628 fix)') block in src/filesystem/__tests__/path-utils.test.ts with 3 test cases:

1. Exact reproduction of the issue Docker Image 1.0.2 Breaks Linux Users with Letter at Start of Path #3628 scenario (/h/username/MCP_Development/data)
2. A broader set of single-letter root paths on Linux (/u/, /d/, /s/, /e/)
3. Direct test of convertToWindowsPath with Linux platform mocked

---

Correctness

The tests align with the implementation in path-utils.ts. The key code paths:

normalizePath (path-utils.ts:46-53):

const isUnixPath = p.startsWith('/') && (
  p.match(/^\/mnt\/[a-z]\//i) ||
  (process.platform !== 'win32') ||   // <-- on Linux, all /x/ paths bypass conversion
  (process.platform === 'win32' && !p.match(/^\/[a-zA-Z]\//))
);

convertToWindowsPath (path-utils.ts:19):

if (p.match(/^\/[a-zA-Z]\//) && process.platform === 'win32') {

Both guards require platform === 'win32' before converting single-letter roots, so the new tests correctly verify the expected behavior.

---

Observations

Good:

• Uses the same Object.defineProperty(process, 'platform', ...) mocking pattern as the existing WSL block (lines 248–253) — consistent and already reviewed in main.
• afterEach correctly restores originalPlatform after each test.
• Both normalizePath (end-to-end) and convertToWindowsPath (unit) are tested directly — good layered coverage.
• Negative assertions (not.toContain('H:'), not.toContain('\\')) complement the positive ones, clearly documenting what the bug was.

Minor observations (non-blocking):

1. Redundancy with the WSL block. The test at line 411 (preserves single-letter root directories on Linux) overlaps significantly with the existing test at line 295 (should NOT convert Unix-style paths (/c/) when running inside WSL (linux)), which already covers /c/ and /d/ on Linux with platform mocked to 'linux'. The new tests add /u/, /s/, /e/, and the /h/ case specifically — the overlap is acceptable and the extra letters add value.

2. originalPlatform declared twice at describe-scope. Lines 232 and 384 each declare const originalPlatform = process.platform; inside their respective describe blocks. These are in separate scopes so there's no runtime conflict, but a reader scanning the file might find it briefly confusing. Not worth changing.

3. No darwin / macOS coverage. The fix uses process.platform !== 'win32', which means 'darwin' also benefits. A test mocking darwin would be pedantically complete but is entirely optional — linux is the reported scenario and the logic is the same.

4. PR description checkbox: "Bug fix" is checked, but this is a test-only change. Minor description inaccuracy, no impact on the code.

---

Verdict

Looks good. The tests are correctly written, follow the established mocking pattern, cover the exact regression scenario from the issue, and provide good direct coverage of both the public normalizePath and helper convertToWindowsPath functions. No changes required.