IntelliDiff MCP Server

An intelligent file and folder comparison MCP server with advanced text normalization and duplicate detection capabilities.

Features

File Comparison: CRC32-based exact comparison and smart text comparison with normalization
Folder Comparison: Recursive directory comparison with orphan detection
Duplicate Detection: Find identical files within directories
Text Normalization: Handle case, whitespace, tabs, line endings, and Unicode differences
Line-Level Analysis: Detailed diff output with line ranges and targeted file reading
Clean Output: Markdown-formatted text responses instead of JSON bloat
Security: Workspace root validation prevents path traversal attacks
Performance: Streaming for large files, configurable limits, symlink loop prevention

Installation

# Clone or download the project
cd intellidiff-mcp

# Install with uv
uv init --python 3.12
uv add "fastmcp>=2.11"

# Run the server
uv run python intellidiff_server.py /path/to/workspace/root

Project Structure

The server is built with a clean modular architecture:

intellidiff_server.py (52 lines) - Main server entry point and tool registration
workspace_security.py - Path validation and workspace boundary enforcement
file_operations.py - Core file utilities (CRC32, text detection, normalization)
tools.py - Individual MCP tool implementations
folder_operations.py - Folder comparison and duplicate detection logic

MCP Configuration

Local/stdio Configuration

{
  "mcpServers": {
    "intellidiff": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/intellidiff-mcp", "python", "intellidiff_server.py", "/workspace/root"]
    }
  }
}

Local/stdio Configuration with Environment Variables

{
  "mcpServers": {
    "intellidiff": {
      "type": "stdio",
      "command": "uv", 
      "args": ["run", "--directory", "/path/to/intellidiff-mcp", "python", "intellidiff_server.py", "/workspace/root"],
      "env": {
        "INTELLIDIFF_MAX_TEXT_SIZE": "5242880",
        "INTELLIDIFF_MAX_BINARY_SIZE": "1073741824",
        "INTELLIDIFF_MAX_DEPTH": "15",
        "INTELLIDIFF_CHUNK_SIZE": "32768"
      }
    }
  }
}

Remote/HTTP Configuration

{
  "mcpServers": {
    "intellidiff": {
      "type": "http",
      "url": "http://localhost:8000/mcp/"
    }
  }
}

Place this configuration in:

VS Code: .vscode/mcp.json (project) or user settings
Claude Desktop: claude_desktop_config.json
Cursor: .cursor/mcp.json (project) or ~/.cursor/mcp.json (user)
LM Studio: ~/.lmstudio/mcp.json

Environment Variables

Variable	Default	Description
`INTELLIDIFF_MAX_TEXT_SIZE`	10485760 (10MB)	Maximum size for text file comparison
`INTELLIDIFF_MAX_BINARY_SIZE`	1073741824 (1GB)	Maximum size for binary file CRC32
`INTELLIDIFF_MAX_DEPTH`	10	Maximum directory recursion depth
`INTELLIDIFF_CHUNK_SIZE`	65536 (64KB)	File reading chunk size

Tools

`validate_workspace_path`

Validate that a path is within the workspace root.

Parameters:

path (string): Path to validate

`get_file_hash`

Get CRC32 hash and basic information about a file.

Parameters:

file_path (string): Path to the file

`compare_files`

Compare two files with various modes and options.

Parameters:

left_path (string): Path to first file
right_path (string): Path to second file
mode (string): Comparison mode - "exact", "smart_text", or "binary"
ignore_blank_lines (boolean): Skip empty lines during comparison
ignore_newline_differences (boolean): Normalize line endings
ignore_whitespace (boolean): Ignore leading/trailing whitespace
ignore_case (boolean): Case-insensitive comparison
normalize_tabs (boolean): Convert tabs to spaces
unicode_normalize (boolean): Apply Unicode NFKC normalization

`compare_folders`

Compare two folder structures recursively.

Parameters:

left_path (string): Path to first folder
right_path (string): Path to second folder
max_depth (integer): Maximum recursion depth (default: from env var)
include_binary (boolean): Include binary files in comparison
comparison_mode (string): "exact" or "smart_text"

`find_identical_files`

Find files with identical content within a folder.

Parameters:

folder_path (string): Path to folder to scan
max_depth (integer): Maximum recursion depth (default: from env var)

`read_file_lines`

Read specific line ranges from a text file with optional context.

Parameters:

file_path (string): Path to the text file
start_line (integer): Starting line number (1-based, default: 1)
end_line (integer): Ending line number (1-based, default: end of file)
context_lines (integer): Additional context lines before/after range (default: 0)

Usage Examples

Compare Two Files

# Exact comparison - clean markdown output
result = await client.call_tool("compare_files", {
    "left_path": "file1.txt",
    "right_path": "file2.txt", 
    "mode": "exact"
})
print(result.content[0].text)
# Output: ✅ **Exact Comparison**
#         📁 Left: file1.txt (CRC32: abc123)
#         📁 Right: file2.txt (CRC32: abc123)
#         🔍 Result: Identical

# Smart text comparison with normalization
result = await client.call_tool("compare_files", {
    "left_path": "file1.txt",
    "right_path": "file2.txt",
    "mode": "smart_text",
    "ignore_case": True,
    "ignore_whitespace": True,
    "normalize_tabs": True
})
print(result.content[0].text)
# Output: ✅ **Smart Text Comparison - Identical**
#         📁 Left: file1.txt (1.2KB)
#         📁 Right: file2.txt (1.3KB)
#         🔍 Result: Identical (normalized: case, whitespace, tabs)

Compare Folders

result = await client.call_tool("compare_folders", {
    "left_path": "folder_a",
    "right_path": "folder_b",
    "max_depth": 5
})

# Folder comparison returns structured data for programmatic access
summary = result.data["summary"]
orphans = result.data["orphans"]
identical_files = result.data["identical_files"]

Find Duplicates

result = await client.call_tool("find_identical_files", {
    "folder_path": "my_folder",
    "max_depth": 10
})

# Duplicate detection returns structured data for analysis
duplicates = result.data["duplicates"]
wasted_bytes = result.data["summary"]["total_wasted_bytes"]

Read Specific Lines

# Read lines 10-20 with 2 lines of context
result = await client.call_tool("read_file_lines", {
    "file_path": "my_file.txt",
    "start_line": 10,
    "end_line": 20,
    "context_lines": 2
})

# Clean line-numbered output with >>> markers for requested range
print(result.content[0].text)
# Output:     8| function setup() {
#            9|     console.log("Starting...");
#         >>> 10|     const data = loadData();
#         >>> 11|     if (!data) {
#         >>> 12|         throw new Error("No data");
#         >>> 13|     }
#            14| }

Working with Diff Results

# Compare files and get detailed diff information
result = await client.call_tool("compare_files", {
    "left_path": "file1.txt",
    "right_path": "file2.txt",
    "mode": "smart_text"
})

# Access structured diff data
if not result.structured_content["identical"]:
    change_summary = result.structured_content["change_summary"]
    
    # Get affected line ranges
    left_ranges = change_summary["line_ranges"]["left_affected"]
    right_ranges = change_summary["line_ranges"]["right_affected"]
    
    # Read specific sections that changed
    for range_info in left_ranges:
        lines_result = await client.call_tool("read_file_lines", {
            "file_path": "file1.txt",
            "start_line": range_info["start"],
            "end_line": range_info["end"],
            "context_lines": 3
        })
        print(f"Changed section: {lines_result.content[0].text}")

Security

All file paths are validated against the workspace root
Path traversal attacks are prevented through path resolution
Symlink loops are detected and avoided
File size limits prevent memory exhaustion
Read-only operations only

Performance

Streaming I/O for large files
Early exit on size mismatches
CRC32 caching for repeated operations
Configurable chunk sizes and limits
Progress reporting for large operations

License

MIT License - see LICENSE file for details.

IntelliDiff MCP Server