ai-filesystem-mcp by proofmath-owner - MCP Server

AI FileSystem MCP v2.0 🚀

AI-optimized Model Context Protocol (MCP) server for intelligent file system operations with 10 major improvements!

🆕 What's New in v2.0

1. Performance Improvements ⚡

Smart Caching: LRU cache with dynamic TTL based on file size
Parallel Processing: Worker threads for bulk operations
Stream API: Efficient handling of large files

2. Advanced Diff & Comparison 🔍

Smart Diff: Compare files with unified, side-by-side, or inline formats
3-way Merge: Intelligent conflict resolution
File Comparison: Binary comparison with hash verification

3. Compression & Archive Management 📦

Multiple Formats: ZIP, TAR, TAR.GZ support
Batch Compression: Compress multiple files/directories
Smart Extraction: Auto-detect archive format

4. Enhanced Search Capabilities 🔎

Date-based Search: Find files by creation/modification date
Size-based Search: Search files by size range
Fuzzy Search: Find files with similar names
Semantic Search: Natural language file search

5. Code Quality & Refactoring 🛠️

Refactoring Suggestions: AI-powered code improvements
Auto Formatting: Project-wide code formatting
Code Quality Metrics: Complexity, maintainability scores
Duplicate Detection: Find and remove code duplication

6. Security Features 🔐

File Encryption: AES-256 encryption with password
Secret Scanning: Detect hardcoded credentials
Security Audit: Comprehensive security report
Permission Management: Safe permission changes
Shell Execution: Secure command execution with validation (NEW!)

7. Batch Operations 📋

Bulk Processing: Rename, move, copy, delete in batch
Pattern Matching: Operations based on file patterns
Transaction Support: Atomic multi-file operations
Progress Tracking: Real-time operation progress

8. Integration & Sync 🔗

Cloud Storage: S3, GCS synchronization
Multi-VCS Support: Git, SVN, Mercurial
Auto-commit Rules: Pattern-based automatic commits
Remote FS Mount: SSHFS, NFS, SMB support

9. Monitoring & Analytics 📊

Performance Metrics: Operation timing and statistics
Error Analysis: Detailed error patterns and recovery
System Stats: Disk usage, I/O monitoring
Operation History: Complete audit trail

10. Enhanced Error Handling 🚨

Smart Recovery: Automatic error recovery suggestions
Did You Mean: File path suggestions
Permission Hints: Solutions for permission issues
Detailed Context: Rich error information

🎯 Language-Specific Features (NEW in v2.2!)

Enhanced Code Analysis 🔬

The system now provides deep language-specific analysis for multiple programming languages:

Python 🐍

Decorators: Analyze function/class decorators with parameters
Data Classes: Extract fields and types from @dataclass
Enums: Parse enum classes and their values
Type Hints: Full support for Python type annotations

Java ☕

Annotations: Parse all Java annotations with parameters
Interfaces: Extract interface methods and properties
Enums: Analyze enum types with constructors

Go 🚹

Interfaces: Parse Go interfaces and their method signatures
Struct Tags: Analyze struct field tags
Embedded Types: Handle interface composition

Rust 🦀

Traits: Full trait analysis with associated types
Macros: Detect and categorize macro definitions
Enums: Parse complex enums with variants

Swift 🦉

Protocols: Analyze protocol requirements
Extensions: Track type extensions and their methods
Enums: Parse enums with associated values and raw types
Generics: Extract generic parameters and constraints

Kotlin 🎯

Data Classes: Parse data class fields with types
Sealed Classes: Track sealed class hierarchies
Annotations: Full annotation support
Interfaces: Analyze interface methods and properties

Scala 🔧

Traits: Analyze traits and mixins
Case Classes: Parse case class parameters
Sealed Traits: Track ADT hierarchies

Elixir 💧

Behaviours: Parse behaviour callbacks
Protocols: Analyze protocol definitions
Macros: Detect macro definitions

Code Modification Support 📝

Extended code modification capabilities beyond JavaScript/TypeScript:

Supported Languages for Modification:

✅ JavaScript/TypeScript: Full AST-based modifications
✅ Python: Text-based intelligent modifications
✅ Java: Smart pattern-based updates
✅ Go: Structure-aware modifications
✅ Rust: Safe code transformations
✅ Swift: Protocol-oriented updates
✅ Kotlin: Null-safe modifications

Modification Types:

Symbol Renaming: Rename functions, classes, variables
Import Management: Add/remove imports intelligently
Function Updates: Replace or add functions
Property Addition: Add class/struct properties
Pattern Replacement: Advanced regex-based updates

Core Features (Enhanced)

Intelligent File Operations

Cached Reading: Read files with smart caching
Safe Writing: Automatic backups before overwrites
Pattern Search: Advanced glob and regex patterns
Content Search: Full-text search with context

Code Intelligence

AST Analysis: Deep code structure understanding
Smart Modifications: Safe code transformations
Dependency Analysis: Project dependency graphs
Import Management: Automatic import optimization

Version Control (Enhanced in v2.1.1) 🆕

Git Repository Management:
- git_init: Initialize new repositories (regular or bare)
- git_clone: Clone repositories from URLs
Staging & Commits:
- git_add: Stage files or all changes
- git_commit: Commit with messages
- git_status: Check repository status
Branch Operations:
- git_branch: List, create, delete, checkout branches
- git_checkout: Switch between branches
- git_merge: Merge branches (coming soon)
Remote Operations:
- git_push: Push to remote repositories
- git_pull: Pull from remote repositories
- git_remote: Manage remotes (coming soon)
History & Inspection:
- git_log: View commit history
- git_diff: View changes (coming soon)
GitHub Integration:
- github_create_pr: Create pull requests via GitHub CLI
- github_create_repo: Create GitHub repositories (coming soon)
- github_list_prs: List pull requests (coming soon)
Advanced Git Features:
- git_stash: Stash changes (coming soon)
- git_rebase: Rebase branches (coming soon)
- git_tag: Tag management (coming soon)

Installation

# Clone the repository
git clone https://github.com/yourusername/ai-filesystem-mcp.git
cd ai-filesystem-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "ai-filesystem": {
      "command": "node",
      "args": ["/path/to/ai-filesystem-mcp/dist/index.js"]
    }
  }
}

New Usage Examples

Language-Specific Analysis

Use analyze_code with:
- path: "src/main.py"

Returns:
{
  "imports": [...],
  "functions": [...],
  "classes": [...],
  "languageSpecific": {
    "decorators": [
      {
        "name": "dataclass",
        "target": "User",
        "parameters": []
      }
    ],
    "dataClasses": [
      {
        "name": "User",
        "fields": [
          {"name": "id", "type": "int"},
          {"name": "name", "type": "str"}
        ]
      }
    ]
  }
}

Code Modification (Multi-Language)

Use modify_code with:
- path: "src/user.py"
- modifications: [
    {
      "type": "rename",
      "target": "get_user",
      "newName": "fetch_user"
    },
    {
      "type": "addImport",
      "importName": "Optional",
      "importPath": "typing"
    }
  ]

Smart Diff

Use diff_files with:
- file1: "src/old.js"
- file2: "src/new.js"
- format: "unified"

File Compression

Use compress_files with:
- files: ["src", "docs", "README.md"]
- outputPath: "backup.zip"
- format: "zip"

Semantic Search

Use semantic_search with:
- query: "find all configuration files related to database"
- directory: "."

Security Scan

Use scan_secrets with:
- directory: "."

Batch Operations

Use batch_operations with:
- operations: [
    {
      op: "rename",
      files: [{from: "*.tmp", pattern: "tmp$", replacement: "bak"}]
    },
    {
      op: "move",
      files: [{from: "old/*", to: "archive/"}]
    }
  ]

Code Refactoring

Use suggest_refactoring with:
- path: "src/index.js"

File Encryption

Use encrypt_file with:
- path: "sensitive.txt"
- password: "your-secure-password"

Shell Execution (Enhanced!) 🔒

Full Control with `execute_shell`:

Use execute_shell with:
- command: "npm"
- args: ["run", "build"]
- securityLevel: "moderate"  // Choose security level
- timeout: 30000
- cwd: "./project"          // Working directory
- env: {NODE_ENV: "production"} // Environment variables
- interactive: false        // Interactive mode

// Security levels:
// - "strict": Very restrictive
// - "moderate": Allows development tools (default)
// - "permissive": Minimal restrictions

Quick Execution with `shell` (NEW!):

Use shell with:
- cmd: "git status --short"
- cwd: "./project"  // Optional

// Examples:
- cmd: "ls -la | head -5"
- cmd: "npm run test"
- cmd: "echo Hello World"

// Always runs in permissive mode
// Perfect for quick development tasks

Git Operations (New!)

# Initialize a new repository
Use git_init with:
- path: "./my-project"

# Stage all changes
Use git_add with:
- files: "."

# Commit changes
Use git_commit with:
- message: "feat: add new feature"
- files: ["src/feature.js", "test/feature.test.js"]

# Push to remote
Use git_push with:
- remote: "origin"
- branch: "main"

# Create a pull request
Use github_create_pr with:
- title: "Add awesome feature"
- body: "This PR adds..."

# View commit history
Use git_log with:
- limit: 20

# Branch operations
Use git_branch with:
- action: "create"
- name: "feature/new-feature"

Performance Benchmarks

Cache Hit Rate: Up to 90% for frequently accessed files
Batch Operations: 10x faster than sequential processing
Large File Handling: Stream processing for files >100MB
Search Performance: Indexed search 50x faster

Security Best Practices

Always scan for secrets before committing code
Use encryption for sensitive files
Regular security audits of your codebase
Permission validation before system operations
Sandboxed operations for untrusted paths

Advanced Configuration

Cache Settings

// Customize cache behavior
const cacheOptions = {
  maxSize: 200 * 1024 * 1024, // 200MB
  ttl: 600000, // 10 minutes
  updateAgeOnGet: true
};

Monitoring Setup

// Enable real-time monitoring
const monitoringOptions = {
  logFile: './filesystem.log',
  metricsInterval: 5000,
  maxLogSize: 10000
};

Supported Languages

Analysis Support (Full)

JavaScript/TypeScript (.js, .jsx, .ts, .tsx, .mjs, .cjs)
Python (.py, .pyw)
Java (.java)
Go (.go)
Rust (.rs)
Swift (.swift)
Kotlin (.kt, .kts)
Scala (.scala)
Elixir (.ex, .exs)
Ruby (.rb)
PHP (.php)
C/C++ (.c, .cpp, .cc, .cxx)
C# (.cs)

Modification Support

JavaScript/TypeScript (AST-based)
Python (Pattern-based)
Java (Pattern-based)
Go (Pattern-based)
Rust (Pattern-based)
Swift (Pattern-based)
Kotlin (Pattern-based)

Troubleshooting

Common Issues

Permission Denied
- Check file permissions with get_file_metadata
- Use change_permissions with appropriate values
- Run security audit to identify issues
Large File Performance
- Enable streaming for files >10MB
- Use compression for archival
- Consider cloud sync for backup
Search Not Finding Files
- Try fuzzy search with lower threshold
- Use semantic search for natural queries
- Check file patterns and exclusions
Code Analysis Issues
- Ensure file has proper extension
- Check for syntax errors in code
- Use language-specific analyzers

Contributing

We welcome contributions! Areas of focus:

Performance optimizations
New cloud storage integrations
Additional security patterns
Language-specific refactoring rules
More language analyzers and modifiers

Roadmap 🗺️

✅ Phase 1: Command Pattern (Complete)

Migrated all 39 commands to Command Pattern
Removed monolithic switch statement
Improved code organization and testability

✅ Phase 2: Language Support (Complete in v2.2)

Added language-specific analyzers for 9+ languages
Extended code modification to 7 languages
Deep analysis of language features

🔄 Phase 3: Service Architecture (In Planning)

Decompose FileSystemManager into 10 services
Implement dependency injection
Add Zod for runtime type validation
Unified error handling system

🚀 Phase 4: Performance Optimization (Future)

Event-based file watching (100x latency improvement)
Stream processing for large files (20x memory efficiency)
Worker thread pool for parallel operations (6x speed improvement)
Smart caching and memory management

See for detailed progress.

Core Commands

Shell Commands 🚀

execute_shell - Execute shell commands with multi-level security controls
- Three security levels: strict, moderate (default), permissive
- Full control over execution environment
- Support for timeout, environment variables, working directory
shell - Quick shell command execution (always permissive mode)
- Simple syntax: just pass the full command as a string
- Perfect for development tasks and quick commands
- Example: shell cmd="git status --short"

Security Commands

scan_secrets - Scan directory for hardcoded secrets
encrypt_file - Encrypt files with password
decrypt_file - Decrypt encrypted files
security_audit - Perform security audit on directory

Changelog

v2.3.2 (2025-05-31) - New Shell Commands! 🚀

🆕 New shell Command:
- Quick and easy shell execution
- Always runs in permissive mode
- Simple syntax: shell cmd="your command"
- Perfect for development workflows
🌟 Enhanced execute_shell Command:
- Now properly registered as MCP command
- Improved error messages and hints
- Better Node.js tool detection
📝 Documentation:
- Added examples for both shell commands
- Updated Core Commands section
- Clear usage instructions

v2.3.1 (2025-05-30) - Enhanced Shell Security! 🔐

🎯 Multi-level Security System:
- Three security levels: strict, moderate, permissive
- Development-friendly "moderate" level
- Customizable security policies
🚀 Improved Developer Experience:
- Automatic Node.js tool path detection
- Better error messages with hints
- Support for npm, npx, yarn, pnpm out of the box
🛡️ Smart Security:
- Context-aware command validation
- Whitelist for development tools
- Temporary permission elevation
📝 Documentation:
- Comprehensive shell security guide
- Build and run guide
- Migration instructions

v2.2.0 (2025-01-27) - Language Intelligence Update! 🧠

🎯 Language-Specific Features:
- Added analyzers for Python, Java, Go, Rust, Swift, Kotlin, Scala, Elixir
- Deep analysis of decorators, annotations, interfaces, traits, protocols
- Support for data classes, sealed classes, enums, generics
📝 Extended Code Modification:
- Code modification now supports 7 languages beyond JS/TS
- Pattern-based intelligent modifications
- Safe symbol renaming, import management, function updates
🔬 Enhanced Code Analysis:
- Language-specific feature extraction
- Better understanding of code structure
- Support for 13+ programming languages
📚 Documentation:
- Added comprehensive language feature documentation
- New usage examples for language-specific features

v2.1.1 (2025-01-26) - Enhanced Git Integration! 🔀

🎯 New Git Commands Added:
- Core Git operations: init, add, push, pull, clone
- Branch management: create, delete, switch, list
- GitHub integration: create pull requests
- History viewing: commit logs
🔧 Improved GitIntegration Class:
- Extended with 25+ new methods
- GitHub CLI integration
- Better error handling
📚 Documentation Updates:
- Added Git command examples
- Updated feature list
🏗️ Project Structure Improvements:
- Reorganized files into logical directories
- Cleaned up test structure
- Updated package.json scripts

v2.1.0 (2025-01-26) - Phase 1 Complete! 🎉

✅ Phase 1: 100% Complete
- All 39 commands migrated to Command Pattern
- All tests passing (100% success rate)
- Fixed all edge cases (transaction, extract_archive)
- Added comprehensive test suite
- Documentation fully updated
📄 Key improvements:
- Transaction now uses system temp directory (no permission issues)
- Extract archive handles absolute paths correctly
- Git commands work properly in actual repositories
🧪 Test coverage:
- Unit tests for core components
- Integration tests for all 39 commands
- Edge case tests for transactions
🚀 Ready for Phase 2: Service Architecture decomposition

v2.0.0 (2025-01-26)

🎉 10 major improvements implemented
⚡ Performance enhancements with caching
🔐 Security features added
📊 Monitoring and analytics
🔍 Advanced search capabilities
📦 Compression support
🛠️ Code refactoring tools
📋 Batch operations
🔗 Cloud integration
🚨 Enhanced error handling

v1.0.0

Initial release with core features