npm package: @iflow-mcp/proofmath-owner-ai-filesystem-mcp
Description: AI-optimized FileSystem MCP with advanced features for intelligent file manipulation
Author: AI FileSystem Team
Latest version: 2.0.0

# 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**:
1. **Symbol Renaming**: Rename functions, classes, variables
2. **Import Management**: Add/remove imports intelligently
3. **Function Updates**: Replace or add functions
4. **Property Addition**: Add class/struct properties
5. **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

```bash
# 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:

```json
{
  "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

1. **Always scan for secrets** before committing code
2. **Use encryption** for sensitive files
3. **Regular security audits** of your codebase
4. **Permission validation** before system operations
5. **Sandboxed operations** for untrusted paths

## Advanced Configuration

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

### Monitoring Setup
```javascript
// 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

1. **Permission Denied**
   - Check file permissions with `get_file_metadata`
   - Use `change_permissions` with appropriate values
   - Run security audit to identify issues

2. **Large File Performance**
   - Enable streaming for files >10MB
   - Use compression for archival
   - Consider cloud sync for backup

3. **Search Not Finding Files**
   - Try fuzzy search with lower threshold
   - Use semantic search for natural queries
   - Check file patterns and exclusions

4. **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 [REFACTORING.md](./REFACTORING.md) 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