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.