IntelliDiff MCP Server

# 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 ```bash # 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 ```json { "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 ```json { "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 ```json { "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 ```python # 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 ```python 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 ```python 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 ```python # 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 ```python # 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.