feat: Add compare_directories tool for directory comparison

[nagual2]

Summary

Adds compare_directories tool to filesystem MCP server for comparing two directory structures.

New Tool: compare_directories

Compares two directories and returns:

• onlyInDir1: Files only in first directory
• onlyInDir2: Files only in second directory
• differentContent: Files with different size/mtime
• identical: Identical files

Changes

• src/filesystem/lib.ts - Added compareDirectories() function
• src/filesystem/index.ts - Registered tool
• src/filesystem/__tests__/lib.test.ts - Added 6 tests

Tests

✅ Files unique to each directory
✅ Content difference detection
✅ Identical file identification
✅ Empty directory handling
✅ Nested structures

All tests pass with npm test.

[olaservo]

Thanks for the contribution. A couple of implementation issues and a scope question:

Implementation issues:

1. The compareContent parameter is accepted in the schema and function signature but never used — comparison always uses size/mtime regardless of the flag. Either implement content comparison or remove the parameter.
2. Files with identical content but different timestamps will be reported as "different," and files with different content but the same size/mtime will be reported as "identical." This should at least be documented clearly, or addressed with actual content hashing when compareContent is true.

Scope question:
Per our CONTRIBUTING.md, we're selective about new features that aren't core to a server's purpose. Directory comparison feels like it could be composed by an LLM using existing tools (directory_tree, read_file), or handled by a dedicated server. Would you consider publishing this as a standalone MCP server on the Registry instead?

---

This review was assisted by Claude Code.

[nagual2]

@olaservo Thanks for the detailed review! I've addressed the implementation issues:

Fixed: compareContent parameter now works

Before: The parameter was accepted but ignored — comparison always used size/mtime.

After:

• compareContent=false (default): Uses size/mtime for quick comparison
• compareContent=true: Reads and compares actual file contents byte-by-byte

When compareContent=true:

• Files with identical content but different timestamps are correctly reported as identical (content is what matters)
• Files with different content but same size are correctly detected as different (no false positives)

Implementation details

Added compareFileContents() helper that:

1. Reads both files as buffers (parallel via Promise.all)
2. Early exit if sizes differ
3. Uses Buffer.equals() for efficient byte-by-byte comparison

Why this belongs in core filesystem server

While directory comparison could theoretically be composed by an LLM using existing tools, this argument applies to many other tools already in the server (e.g., search_files, get_file_info). The practical reality:

1. Performance: Comparing two directories with 1000 files each would require:

   • 2× directory_tree calls
   • Potentially hundreds of read_file calls for content comparison
   • Thousands of tokens and significant time

2. Atomicity: The comparison needs to be consistent (directory state shouldn't change mid-comparison)

3. Real-world usage: Directory comparison is a fundamental filesystem operation — essential for backups, deployments, sync operations, and integrity verification

4. Ecosystem gap: FAR is Windows-only and not scriptable. Most developers lack a cross-platform directory comparison tool that integrates with their workflow

This follows the pattern of other "composed" tools already in the server — providing efficient, atomic operations that would be impractical to build from lower-level primitives.

---

Commits:

• 5ea9b667 — Implement content comparison in compareDirectories
• 96172ba9 — Add tests for compareContent parameter

All tests pass with npm test. The changes are minimal and focused on fixing the unused parameter issue while maintaining backward compatibility.

[cliffhall]

@claude review

[claude]

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

---

PR Review: compare_directories tool

• Gather context
• Read changed files (lib.ts, index.ts, test file)
• Review implementation quality and correctness
• Check security considerations
• Assess test coverage
• Post final review

---

The compareContent parameter is now properly implemented and the tests are comprehensive. Good progress overall. However there are several issues that need to be addressed before this can merge.

---

Critical: Global state mutation creates a concurrency vulnerability

src/filesystem/lib.ts lines 453–455 and 544:

const previousAllowed = getAllowedDirectories();
setAllowedDirectories([dir1, dir2]);
// ...
setAllowedDirectories(previousAllowed);

This temporarily overwrites the server-wide allowedDirectories list. In an async JavaScript context, concurrent MCP tool calls will interleave at every await point. If two compare_directories requests arrive simultaneously, each can clobber the other's in-flight allowedDirectories — and, more seriously, any other tool call (e.g. write_file) in flight at the same time will validate paths against the temporarily narrowed or widened set.

The root cause is that searchFilesWithValidation accepts an allowedDirectories parameter but never uses it — it always reads the global. The parameter on searchFilesWithValidation should be wired through to validatePath (or the comparison should use fs.readdir directly without going through global validation state). Fix this →

---

Critical: Silent error suppression in compareFileContents

src/filesystem/lib.ts lines 418–433:

async function compareFileContents(file1: string, file2: string): Promise<boolean> {
  try {
    ...
  } catch {
    return false;  // ← any I/O error silently returns "different"
  }
}

A permission error, disk failure, or unexpected condition causes the function to return false (files appear different) with no indication anything went wrong. Errors should be propagated so callers can surface them to the user. Fix this →

---

Major: Subdirectories appear in comparison results

searchFilesWithValidation with pattern **/* matches both files and directories. As a result, subdirectory entries end up in onlyInDir1, onlyInDir2, and identical. A user comparing two project roots will see entries like node_modules listed as "identical" alongside files — misleading and noisy. Filter results to files only (e.g. check entry.isFile() in searchFilesWithValidation, or filter the returned paths with fs.stat before comparing). Fix this →

---

Major: outputSchema and structuredContent mismatch

src/filesystem/index.ts lines 718–719 and 758:

outputSchema: { content: z.string() },    // schema claims a string
...
structuredContent: { result }             // but returns an object

Every other tool returns structuredContent: { content: text } matching its outputSchema. This tool returns { result } (the raw comparison object), which diverges from the declared schema and every other tool's pattern. Either expose the rich object via the schema (define a proper Zod schema for DirectoryComparisonResult) or return { content: text } consistently. Fix this →

---

Minor issues

No validation that inputs are directories — if a file path is passed for dir1 or dir2, searchFilesWithValidation will call fs.readdir on a file and throw a confusing error. A check like (await fs.stat(validDir1)).isDirectory() before proceeding would give a clear message.

compareContent lacks a .describe() — every other schema parameter has one. LLMs rely on descriptions for correct tool use:

// src/filesystem/index.ts line 717
compareContent: z.boolean().optional()
// should be:
compareContent: z.boolean().optional().describe("If true, compare actual file contents byte-by-byte instead of size/mtime")

Tool description is stale — it still says "files with different content (size/mtime)" which doesn't reflect that compareContent=true now does actual byte comparison.

No file size guard for content comparison — compareFileContents reads both files fully into memory with no size limit. Comparing two 2 GB files would allocate 4 GB. Consider adding a size threshold above which content comparison is refused, or stream-compare in chunks.

---

Scope consideration

The previous reviewer asked whether this belongs in the core server. The PR author's justification (performance atomicity, ecosystem gap) is reasonable, but the contributing guidelines call for features that demonstrate MCP protocol features (Resources, Prompts, Roots) rather than just new Tools. Directory comparison is a useful utility but doesn't add new protocol surface. Publishing it as a standalone server remains a valid alternative worth considering.

[LuuOW]

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

[nagual2]

Why built‑in directory comparison in MCP dramatically reduces token usage

It is true that a modern LLM can, in theory, compare two directories by using basic tools like list_directory, get_file_info, and read_file. The model could script the comparison step by step or even generate code on the fly. However, in practice this approach leads to massive token waste and inefficiency for several reasons.

1. Multiple tool calls
   To compare two directories each containing, say, 100 files, the LLM would need to:

Retrieve the file list for both directories – 2 calls.

For every pair of identically named files, obtain metadata or read content – up to 100 additional read_file or get_file_info calls.

Result: over 100 tool calls and thousands of tokens just to fetch file lists and contents.

2. Transmitting excessive data
   Even when files are identical, the LLM still receives their full content (or metadata) to perform the comparison. For typical text files of 1–10 KB, this quickly becomes tens or hundreds of KB of incoming tokens per session. For binary files, the situation is even worse.

3. Computational load on the LLM
   The model must keep both file lists and the content of each compared file in its context window. Then it has to perform manual matching, difference detection, and report generation. This consumes not only tokens but also “thinking capacity”, increasing the risk of errors when many files are involved.

4. Repeatability and reliability
   Every time the LLM runs, it may generate a slightly different sequence of calls or ad‑hoc comparison logic. This leads to non‑deterministic results. A built‑in server‑side function, on the other hand, works deterministically and efficiently, without involving the model in low‑level comparison steps.

With a native compare_directories tool in the MCP server, token consumption is reduced by 1–2 orders of magnitude:

Instead of dozens or hundreds of tool calls and kilobytes of data, a single call with parameters (directory paths, comparison flags) is sufficient.

The server returns a compact, structured result – only the lists of differences (missing files, files with differing content, identical files, etc.). No full content of identical files is transmitted.

The LLM is freed from performing step‑by‑step comparison logic. This reduces the chance of mistakes and frees context for higher‑level reasoning.

Analogy: Of course an LLM could add two numbers by repeatedly calling a get_digit tool, but a native add tool is orders of magnitude more efficient. compare_directories is exactly that kind of “native operation” for a file system.

Therefore, although directory comparison can be emulated with basic primitives, from the perspective of token economy, latency, and reliability, it fully deserves a place in a reference MCP server – as an example of using MCP for resource‑intensive operations that are too expensive to delegate to the LLM step by step.