DirectoryResource listing uses OS path separators and unstable order #3589

Activity

1. tasnemawawde-afk

   added a commit that references this issue on Sep 27, 2026

   Make DirectoryResource listing stable and cross-platform

   ...

   06f76b5
2. claude

   added

   v2Affects the v2 line (2.x on main)Affects the v2 line (2.x on main)

   v1Affects the v1.x maintenance lineAffects the v1.x maintenance line

   on Sep 27, 2026
3. Ben-Home commented on Sep 29, 2026

   

   Ben-Home

   on Sep 29, 2026

   More actions

   Good catch. as_posix() is the right fix at the wire level, and there is a stronger reason than cosmetic consistency: clients take these listing values and construct child resource URIs from them, and the RFC 3986 path grammar allows only / as a separator. A \ in a URI path is non-conformant and breaks resolution on any non-Windows client, so normalizing before serialization is the correct place.

   On ordering: stability matters because clients that hash or diff resource listings for caching will churn on every read when glob() order varies by filesystem. sorted() over the posix-form strings is deterministic (codepoint order), so sorting after conversion is the right pairing; sort the final wire values rather than the OS paths.

   One edge worth covering in the test: filenames that differ only in case on a case-insensitive filesystem (a.txt and A.txt on NTFS). sorted() gives deterministic codepoint order, which is fine, but it is worth asserting so nobody later "fixes" the sort back to filesystem enumeration order.

   We hit this exact inconsistency in a gateway that aggregates multiple business APIs (corpusiq.io) where directory listings get compared across Windows and Linux workers, so making the wire format platform-neutral matters well beyond cosmetics.
4. 0xamlab commented on Oct 1, 2026

   

   0xamlab

   on Oct 1, 2026

   More actions

   Confirmed the nondeterminism on current main.

   Minimal repro (macOS, but the separator problem is the same path on Windows):

   import anyio, json, tempfile
   from pathlib import Path
   from mcp.server.mcpserver.resources import DirectoryResource
   
   root = Path(tempfile.mkdtemp())
   (root / "sub").mkdir()
   (root / "c.txt").write_text("c", encoding="utf-8")
   (root / "a.txt").write_text("a", encoding="utf-8")
   (root / "b.txt").write_text("b", encoding="utf-8")
   (root / "sub" / "z.txt").write_text("z", encoding="utf-8")
   
   r = DirectoryResource(uri="dir://x", name="x", path=root, recursive=True)
   print(json.loads(anyio.run(r.read))["files"])

   Output I got:

   ['c.txt', 'b.txt', 'a.txt', 'sub/z.txt']
   

   That is neither insertion order (c, a, b, sub/z) nor alphabetical; it follows the raw filesystem order returned by rglob().

   Mechanism is in src/mcp/server/mcpserver/resources/types.py:

   • list_files() at line 215 calls self.path.glob() / self.path.rglob() — those return directory entries in filesystem (readdir) order, which varies by FS and platform.
   • read() at line 229 builds the returned strings with str(f.relative_to(self.path)), which uses the OS-native path separator (os.sep). On Windows that produces sub\c.txt; on Linux/macOS it produces sub/c.txt.

   Fix direction: sort the file list and posix-normalize the paths so the JSON listing is identical across platforms:

   file_list = sorted(
       (f.relative_to(self.path)).as_posix()
       for f in files
       if f.is_file()
   )

   The reporter already has a tested fix on their fork; I'm happy to open a PR with the same approach plus coverage for both v2 (main) and v1.x if a maintainer assigns this or marks it help wanted.

   Disclosure: I contribute to thyn-ai/Algenta (open-source agent tooling).
5. claude

   added

   bugSomething isn't workingSomething isn't working

   on Oct 8, 2026