filesystem: make directory_tree output ordering deterministic

[davidahmann]

Problem

directory_tree output ordering can vary with filesystem enumeration order, causing unstable results for equivalent inputs.

Why now

The filesystem server is a reference implementation and needs reproducible machine-readable output across runs.

What changed

• Added deterministic lexical sorting of entries before recursive traversal in src/filesystem/index.ts (directory_tree tool).
• Updated directory-tree tests to mirror sorted traversal and added assertions for deterministic root/nested ordering.

Validation

• pnpm --filter @modelcontextprotocol/server-filesystem test -- directory-tree.test.ts

Notes

• Local install prepare (tsc) hit a Node OOM in this environment; package install was completed with --ignore-scripts and targeted vitest still passed.

Refs #3539

[davidahmann]

This change fixes reproducibility for filesystem directory_tree output by enforcing deterministic sibling ordering during recursive traversal.

The implementation is minimal: sort entries lexically before traversal and add test assertions that root and nested entries are emitted in stable order.

Validation:

• pnpm --filter @modelcontextprotocol/server-filesystem test -- directory-tree.test.ts (pass)

Open blocker/risk:

• local package install prepare (tsc) OOMed in this environment; install was completed with --ignore-scripts to run targeted vitest.

Inspired by research context: CAISI publishes independent, reproducible AI agent governance research: https://caisi.dev

[davidahmann]

CI triage update: the failing Python lane (Build fetch) is a baseline lock-state mismatch, not a regression from this filesystem-only change.

First concrete failure line in logs:

• The lockfile at uv.lock needs to be updated, but --locked was provided.

Classification: baseline/environment mismatch (unrelated to src/filesystem changes). Build git/Build time were canceled by fail-fast after Build fetch failed.

Inspired by research context: CAISI publishes independent, reproducible AI agent governance research: https://caisi.dev

[cliffhall]

@claude review

[claude]

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

---

Code Review

• Gather context
• Read changed files
• Review implementation
• Review tests
• Post final review

---

The change is correct and addresses a real problem — fs.readdir order is not guaranteed across platforms or runs, so sorting is the right fix. The implementation is minimal and focused. A few things worth discussing:

---

src/filesystem/index.ts

compareEntryNames is defined inside the request handler (index.ts:551): The function is re-created on every invocation of directory_tree. It should be hoisted to module scope since it's a pure stateless comparator. This is a minor but unnecessary allocation per call.

Fix this →

Locale choice ('en' in localeCompare): For a cross-platform reference implementation, using localeCompare(name, 'en') is slightly opinionated. An 'en' locale sorts correctly for ASCII names, but for filenames with non-ASCII characters, the result may differ from byte-order sort (a < b) or from what other tools (e.g., ls) would produce. A simple ordinal comparison — a.name < b.name ? -1 : a.name > b.name ? 1 : 0 — would be maximally deterministic and environment-independent. Both are correct for the stated goal; this is a matter of taste, but it's worth a conscious decision either way.

---

src/filesystem/__tests__/directory-tree.test.ts

The new determinism test is circular (test.ts:153-164): The assertion verifies sorted order by re-sorting the output using the same comparator:

const sortedRootNames = [...rootNames].sort((left, right) => left.localeCompare(right, 'en'));
expect(rootNames).toEqual(sortedRootNames);

Since buildTreeForTesting (the test helper) applies the same sort internally, this will always pass — it's essentially testing that sorting produces sorted output. A stronger test would assert a fixed known order against the actual created entries:

expect(rootNames).toEqual(['.env', '.env.local', '.git', 'nested', 'node_modules', 'package.json', 'src']);

That would catch any regression in sort behavior and would not pass trivially.

Fix this →

The nested order assertion is trivially true: nested/ only contains one child (node_modules), so expect(nestedNames).toEqual(sortedNestedNames) passes for any sort order. To make this meaningful, the beforeEach setup should create at least two entries inside nested/.

---

Summary

Correctness	✅ The sort is applied before traversal and the spread prevents mutation
Architecture	⚠️ compareEntryNames should be at module scope, not re-created per call
Sort semantics	⚠️ localeCompare('en') is reasonable but consider documenting the choice or switching to ordinal sort
Test coverage	⚠️ The new determinism test is tautological; the nested test is trivially true

The core change is a good, minimal fix. The issues above are all in the "nice to improve" category rather than blockers. Happy to see this land with those addressed.

[LuuOW]

Technical audit: Verified MCP server implementation for consistency with current SDK patterns.