file-operation-mcp-server by anand34577 - MCP Server

Advanced File Operations MCP Server

A comprehensive Java-based Model Context Protocol (MCP) server that provides extensive file system operations, text processing, data analysis, and structured data handling capabilities. Built with enterprise-grade architecture following industry best practices.

🚀 Features

Core File Operations

File Management: Create, read, write, delete, copy, move, and rename files
Directory Operations: Create, delete, rename, and list directories with advanced filtering
File Information: Get detailed metadata, permissions, timestamps, and file statistics
Search & Discovery: Pattern-based file searching with regex support

Advanced Operations

Text Processing: Find/replace text, file comparison, line counting with statistics
Checksum Calculation: Support for MD5, SHA1, SHA256 algorithms
Archive Creation: Create ZIP archives with compression level control
Batch Operations: Bulk file renaming with pattern matching and preview mode

Structured Data Support

JSON Processing: Read, validate, and pretty-print JSON files with error reporting
CSV Handling: Advanced CSV parsing with proper quote handling and delimiter support
Data Analysis: File statistics, directory size calculation, and content analysis

Enterprise Features

Logging: Comprehensive SLF4J logging with configurable levels
Error Handling: Robust error handling with descriptive messages
Security: Built-in validation and safe file operations
Performance: Optimized for large files and directories
Extensibility: Modular architecture for easy feature additions

📋 Prerequisites

Java: JDK 11 or higher
Maven: 3.6 or higher
Memory: Minimum 512MB RAM (recommended: 1GB+)
Storage: Varies based on file operations

🛠️ Installation & Setup

1. Clone/Download the Project

git clone <repository-url>
cd mcp-file-operations

2. Build the Project

mvn clean compile

3. Run Tests (Optional)

mvn test

4. Create Executable JAR

mvn package

This creates: target/mcp-file-operations-2.0.0.jar

5. Quick Test

java -jar target/mcp-file-operations-2.0.0.jar

🎯 Use Cases & Examples

Development & Code Management

1. Project File Analysis

# Count lines of code in a project
tools/call: count_lines
Arguments: {"filePath": "src/main/java/Main.java"}

# Search for TODO comments
tools/call: find_in_file
Arguments: {"filePath": "Main.java", "searchText": "TODO", "caseSensitive": false}

# Get project directory size
tools/call: get_directory_size
Arguments: {"directoryPath": "src/", "includeHidden": true}

2. Code Refactoring

# Replace deprecated method calls
tools/call: replace_in_file
Arguments: {
  "filePath": "Service.java", 
  "searchText": "oldMethod()", 
  "replaceText": "newMethod()",
  "replaceAll": true
}

# Compare files after refactoring
tools/call: compare_files
Arguments: {
  "file1Path": "Service_old.java", 
  "file2Path": "Service.java",
  "ignoreWhitespace": true
}

Data Management & Analysis

3. CSV Data Processing

# Read financial statements
tools/call: read_csv
Arguments: {
  "filePath": "Statements.csv", 
  "delimiter": ",", 
  "maxRows": 50
}

# Analyze large datasets
tools/call: get_file_info
Arguments: {"filePath": "large_dataset.csv"}

4. JSON Configuration Management

# Validate configuration files
tools/call: validate_json
Arguments: {"filePath": "config/app-config.json"}

# Pretty-print JSON for review
tools/call: read_json
Arguments: {"filePath": "api-response.json"}

System Administration

5. Log File Management

# Search error logs
tools/call: search_files
Arguments: {
  "directoryPath": "/var/log/", 
  "pattern": "error.*\\.log", 
  "recursive": true
}

# Archive old logs
tools/call: create_archive
Arguments: {
  "sourcePath": "/var/log/old/", 
  "archivePath": "/backup/logs-2024.zip",
  "compressionLevel": 9
}

6. System Monitoring

# Monitor directory sizes
tools/call: get_directory_size
Arguments: {"directoryPath": "/home/user/", "includeHidden": false}

# Check file integrity
tools/call: calculate_checksum
Arguments: {"filePath": "important-file.txt", "algorithm": "SHA256"}

Content Management

7. Batch File Operations

# Rename image files with date pattern
tools/call: batch_rename
Arguments: {
  "directoryPath": "photos/", 
  "pattern": "IMG_(\\d+)", 
  "replacement": "Photo_$1",
  "preview": true
}

# Organize files by extension
tools/call: search_files
Arguments: {
  "directoryPath": "downloads/", 
  "pattern": ".*\\.pdf$", 
  "recursive": false
}

8. Document Processing

# Read configuration with line numbers
tools/call: read_file_with_line_numbers
Arguments: {
  "filePath": "nginx.conf", 
  "startLine": 1, 
  "endLine": 50
}

# Create project backup
tools/call: copy_file
Arguments: {
  "sourcePath": "project/", 
  "destinationPath": "backup/project-backup/"
}

🔧 Integration Guide

MCP Client Integration

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "file-operations": {
      "command": "java",
      "args": ["-jar", "/path/to/mcp-file-operations-2.0.0.jar"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

VS Code Extension

{
  "mcp.servers": {
    "file-ops": {
      "command": ["java", "-jar", "mcp-file-operations-2.0.0.jar"],
      "transport": "stdio"
    }
  }
}

Custom Application

import subprocess
import json

# Start MCP server
process = subprocess.Popen([
    'java', '-jar', 'mcp-file-operations-2.0.0.jar'
], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True)

# Send initialization request
init_request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
        "protocolVersion": "2024-11-05",
        "capabilities": {},
        "clientInfo": {"name": "my-app", "version": "1.0.0"}
    }
}

process.stdin.write(json.dumps(init_request) + '\n')

📊 Available Tools

Category	Tool	Description	Key Parameters
Basic	`read_file`	Read file contents	`filePath`
	`create_file`	Create new file with content	`filePath`, `content`
	`write_file`	Write/append to file	`filePath`, `content`, `append`
	`delete_file`	Delete a file	`filePath`
Directory	`create_directory`	Create directory	`directoryPath`
	`delete_directory`	Delete directory and contents	`directoryPath`
	`list_files`	List directory contents	`directoryPath`, `recursive`, `includeHidden`
Movement	`copy_file`	Copy files/directories	`sourcePath`, `destinationPath`
	`move_file`	Move files/directories	`sourcePath`, `destinationPath`
	`rename_file`	Rename files	`oldPath`, `newPath`
Information	`find_file`	Check file existence	`filePath`
	`get_file_info`	Get detailed file info	`filePath`
	`search_files`	Search with patterns	`directoryPath`, `pattern`, `recursive`
Advanced	`calculate_checksum`	Calculate file hashes	`filePath`, `algorithm`
	`get_directory_size`	Calculate directory size	`directoryPath`, `includeHidden`
	`create_archive`	Create ZIP archives	`sourcePath`, `archivePath`
	`count_lines`	Count lines/words/chars	`filePath`
Text	`find_in_file`	Search text in file	`filePath`, `searchText`, `caseSensitive`
	`replace_in_file`	Replace text in file	`filePath`, `searchText`, `replaceText`
	`compare_files`	Compare two files	`file1Path`, `file2Path`
Batch	`batch_rename`	Batch rename files	`directoryPath`, `pattern`, `replacement`
Data	`read_json`	Read and format JSON	`filePath`
	`validate_json`	Validate JSON syntax	`filePath`
	`read_csv`	Read CSV with proper parsing	`filePath`, `delimiter`, `maxRows`

⚙️ Configuration

Environment Variables

# Logging level
export LOG_LEVEL=DEBUG

# Maximum file size for operations (bytes)
export MAX_FILE_SIZE=104857600

# Working directory
export WORK_DIR=/home/user/workspace

JVM Options

# For large file operations
java -Xmx2G -XX:+UseG1GC -jar mcp-file-operations-2.0.0.jar

# For production deployment
java -server -Xms512m -Xmx1G -jar mcp-file-operations-2.0.0.jar

Logging Configuration

Create logback.xml in the classpath:

<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
    
    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        <file>mcp-server.log</file>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
    
    <root level="INFO">
        <appender-ref ref="CONSOLE" />
        <appender-ref ref="FILE" />
    </root>
</configuration>

🧪 Testing

Manual Testing with MCP Inspector

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run inspector
mcp-inspector java -jar target/mcp-file-operations-2.0.0.jar

# Open browser to localhost:5173

Command Line Testing

# Test basic functionality
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | java -jar target/mcp-file-operations-2.0.0.jar

# Test file creation
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"create_file","arguments":{"filePath":"test.txt","content":"Hello World"}}}' | java -jar target/mcp-file-operations-2.0.0.jar

Automated Testing Script

#!/bin/bash
# test-mcp-server.sh

SERVER_JAR="target/mcp-file-operations-2.0.0.jar"
TEST_DIR="test-workspace"

# Setup test environment
mkdir -p $TEST_DIR
cd $TEST_DIR

# Test file operations
echo "Testing file operations..."
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_file","arguments":{"filePath":"sample.txt","content":"Sample content"}}}' | java -jar ../$SERVER_JAR

# Test CSV reading
echo "Testing CSV operations..."
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"read_csv","arguments":{"filePath":"../Statements.csv","maxRows":5}}}' | java -jar ../$SERVER_JAR

echo "Tests completed!"

🔒 Security Considerations

File System Access

Sandboxing: Consider running in a containerized environment
Path Validation: Server validates file paths to prevent directory traversal
Permission Checks: Respects file system permissions
Size Limits: Implement size limits for large file operations

Production Deployment

# Run with restricted user
sudo -u mcp-user java -jar mcp-file-operations-2.0.0.jar

# Use Docker for isolation
docker run -v /safe/directory:/workspace -u 1000:1000 mcp-server

Access Control

# Limit file access to specific directories
export MCP_ALLOWED_PATHS="/home/user/documents,/tmp"
export MCP_FORBIDDEN_PATTERNS=".*\.key,.*\.pem,/etc/.*"

🐛 Troubleshooting

Common Issues

1. Permission Denied

# Check file permissions
ls -la /path/to/file

# Fix permissions
chmod 644 file.txt
chmod 755 directory/

2. Out of Memory

# Increase heap size
java -Xmx4G -jar mcp-file-operations-2.0.0.jar

# Monitor memory usage
jstat -gc <process-id>

3. CSV Parsing Issues

# Test with specific delimiter
{"filePath": "data.csv", "delimiter": ";"}

# Check file encoding
file -bi data.csv

4. JSON Validation Errors

# Pretty-print for debugging
cat file.json | python -m json.tool

# Check for BOM
hexdump -C file.json | head

Debug Mode

# Enable debug logging
export LOG_LEVEL=DEBUG
java -jar mcp-file-operations-2.0.0.jar 2>debug.log

# Trace MCP communication
export MCP_TRACE=true

🚀 Performance Optimization

Large File Handling

# For files > 100MB
java -Xmx4G -XX:+UseG1GC -XX:G1HeapRegionSize=16m -jar mcp-file-operations-2.0.0.jar

# Stream processing for very large files
export STREAM_THRESHOLD=52428800  # 50MB

Batch Operations

# Optimize for batch processing
export BATCH_SIZE=1000
export PARALLEL_PROCESSING=true

📈 Monitoring & Metrics

Health Check

# Check server status
echo '{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}' | java -jar mcp-file-operations-2.0.0.jar

Performance Metrics

File operation latency
Memory usage patterns
Error rates by operation type
Throughput for batch operations

🤝 Contributing

Development Setup

git clone <repository>
cd mcp-file-operations
mvn clean install

Adding New Features

Create new service class implementing FileOperationService
Add tool definition to ToolRegistry
Register service in ServiceFactory
Add tests and documentation

Code Standards

Follow Java 11+ conventions
Use SLF4J for logging
Implement proper error handling
Add comprehensive JavaDoc

📜 License

This project is provided as-is for educational and development purposes. Please review and comply with your organization's security policies before using in production environments.

🆘 Support

For issues and questions:

Check the troubleshooting section
Review logs in debug mode
Test with MCP Inspector
Create detailed issue reports

Version: 2.0.0
Last Updated: September 2025
Compatibility: MCP Protocol 2024-11-05 and later