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.