MCP ACS Filesystem Manager

Advanced filesystem operations for AI agents with MCP integration and strict security boundaries. Part of the Digital Defiance AI Capabilities Suite.

Features

🚀 Advanced File Operations

• Batch Operations: Execute multiple file operations (copy, move, delete) atomically
• Directory Watching: Monitor directories for real-time file system changes
• File Search: Search by filename, content, or metadata with fast indexing
• Checksum Computation: Verify file integrity with MD5, SHA-1, SHA-256, SHA-512
• Disk Usage Analysis: Analyze directory sizes and identify large files

🔒 Security First

• Workspace Jail: All operations confined to workspace root
• 10-Layer Path Validation: Multiple security checks prevent path traversal
• Hardcoded Blocklists: System paths and sensitive files always blocked
• Rate Limiting: Prevents abuse with configurable operation limits
• Audit Logging: Complete operation tracking for forensics
• Platform-Specific Security: Automatic detection and enforcement of OS-specific security boundaries

🤖 AI Integration

• Copilot Chat Participant: Use @filesystem in Copilot chat
• Language Model Tools: Direct AI agent access to filesystem operations
• MCP Protocol: Standard Model Context Protocol integration
• Security Boundaries: AI agents operate within strict, configurable limits
• Language Server Protocol: Intelligent code completion, hover information, and diagnostics for filesystem operations

🛠️ Developer Experience

• Type-Safe Settings: Centralized configuration management with TypeScript types
• Intelligent Error Handling: Categorized errors with user-friendly messages and recovery suggestions
• LSP Integration: Hover over paths for metadata, get completion suggestions, and see diagnostics
• Cross-Platform Support: Automatic platform detection and path normalization for Windows, macOS, and Linux

Installation

1. Install from VS Code Marketplace

2. Or install via command line:

   code --install-extension DigitalDefiance.mcp-acs-filesystem
   

Quick Start

Using with Copilot

Ask Copilot to perform file operations:

@filesystem batch copy all *.ts files from src to backup
@filesystem search for files containing "TODO"
@filesystem compute sha256 checksum for package.json
@filesystem analyze disk usage in node_modules
@filesystem watch src directory for changes

Using Commands

• Ctrl+Shift+F Ctrl+Shift+S: Search files
• Ctrl+Shift+F Ctrl+Shift+B: Batch operations
• Or use Command Palette: MCP Filesystem: ...

Configuration

Security Settings

{
  "mcp-filesystem.security.workspaceRoot": "${workspaceFolder}",
  "mcp-filesystem.security.allowedSubdirectories": [],
  "mcp-filesystem.security.blockedPaths": [
    ".git",
    ".env",
    "node_modules",
    ".ssh"
  ],
  "mcp-filesystem.security.blockedPatterns": [
    "*.key",
    "*.pem",
    "*.env",
    "*secret*",
    "*password*"
  ]
}

Server Settings

{
  "mcp-filesystem.server.autoStart": true,
  "mcp-filesystem.server.timeout": 30000,
  "mcp-filesystem.server.logLevel": "info"
}

Resource Limits

{
  "mcp-filesystem.resources.maxFileSize": 104857600,
  "mcp-filesystem.resources.maxBatchSize": 1073741824,
  "mcp-filesystem.resources.maxOperationsPerMinute": 100
}

UI Settings

{
  "mcp-filesystem.ui.refreshInterval": 5000,
  "mcp-filesystem.ui.showNotifications": true,
  "mcp-filesystem.ui.showSecurityWarnings": true,
  "mcp-filesystem.ui.confirmDangerousOperations": true
}

Operations Settings

{
  "mcp-filesystem.operations.enableBatch": true,
  "mcp-filesystem.operations.enableWatch": true,
  "mcp-filesystem.operations.enableSearch": true,
  "mcp-filesystem.operations.enableChecksum": true
}

Available Operations

Batch Operations

Execute multiple file operations atomically with automatic rollback on failure:

• Copy multiple files/directories
• Move multiple files/directories
• Delete multiple files/directories

Directory Watching

Monitor directories for changes with event filtering:

• Recursive watching
• Event type filtering (create, modify, delete, rename)
• Pattern-based filtering

File Search

Fast file search with multiple modes:

• Filename pattern matching
• Content search (full-text)
• Metadata filtering (size, date, type)
• Indexed search for large codebases

Checksum Operations

Verify file integrity:

• MD5, SHA-1, SHA-256, SHA-512 algorithms
• Batch checksum computation
• Checksum verification

Disk Usage Analysis

Analyze storage usage:

• Recursive directory size calculation
• Largest files/directories identification
• File type breakdown
• Available disk space queries

Security Boundaries

What AI Agents CANNOT Do

• ❌ Access files outside the workspace root
• ❌ Access system directories (/etc, /sys, C:\Windows, etc.)
• ❌ Access SSH keys, AWS credentials, or other sensitive files
• ❌ Create symlinks pointing outside the workspace
• ❌ Bypass rate limits
• ❌ Disable audit logging
• ❌ Modify the workspace root

What AI Agents CAN Do (Within Workspace)

• ✅ Read, write, and delete files
• ✅ Create and navigate directories
• ✅ Search for files by name or content
• ✅ Watch directories for changes
• ✅ Compute checksums
• ✅ Create symlinks (within workspace)
• ✅ Batch operations
• ✅ Sync directories

MCP Server Configuration

The extension automatically configures the MCP server for Copilot integration. To manually add to your workspace:

1. Run command: MCP Filesystem: Add to Copilot MCP Servers
2. Or manually add to .vscode/mcp.json:

{
  "servers": {
    "mcp-filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ai-capabilities-suite/mcp-filesystem"]
    }
  }
}

Examples

Batch Copy Files

// Ask Copilot:
@filesystem batch copy all TypeScript files from src to backup

// Or use the MCP tool directly:
{
  "operations": [
    { "type": "copy", "source": "src/file1.ts", "destination": "backup/file1.ts" },
    { "type": "copy", "source": "src/file2.ts", "destination": "backup/file2.ts" }
  ],
  "atomic": true
}

Watch Directory

// Ask Copilot:
@filesystem watch src directory recursively for TypeScript files

// Or use the MCP tool:
{
  "path": "src",
  "recursive": true,
  "filters": ["*.ts", "*.tsx"]
}

Search Files

// Ask Copilot:
@filesystem search for files containing "TODO" in src directory

// Or use the MCP tool:
{
  "query": "TODO",
  "searchType": "content",
  "fileTypes": [".ts", ".tsx", ".js"]
}

Language Server Features

The extension includes a Language Server Protocol (LSP) implementation that provides intelligent code assistance:

Hover Information

Hover over filesystem paths in your code to see:

• File metadata (size, permissions, modification time)
• Security boundary information
• Available MCP filesystem tools

Code Completion

Get intelligent completion suggestions for:

• MCP filesystem tool names
• Common filesystem paths
• Operation parameters

Diagnostics

Real-time warnings and errors for:

• Paths outside workspace root
• Blocked paths and patterns
• Dangerous filesystem operations
• Symlink operations requiring validation

Code Actions

Quick fixes for common issues:

• Convert to workspace-relative paths
• Remove blocked path references
• Convert sync operations to async
• Open security settings

Troubleshooting

Server Not Starting

1. Check output panel: View > Output > MCP ACS Filesystem Manager
2. Verify Node.js is installed: node --version
3. Check server path in settings
4. Try restarting VS Code
5. Review server logs for detailed error information

Permission Errors

1. Verify workspace root is accessible
2. Check blocked paths configuration
3. Review audit log for security violations
4. Ensure files are within workspace boundaries
5. Check platform-specific security boundaries

Performance Issues

1. Reduce maxOperationsPerMinute for rate limiting
2. Use indexed search for large codebases
3. Limit directory watching depth
4. Check disk space and file sizes
5. Adjust ui.refreshInterval to reduce UI updates

Configuration Errors

1. Open settings: Ctrl+, (or Cmd+, on macOS)
2. Search for "mcp-filesystem"
3. Verify all settings have valid values
4. Check for validation errors in the output panel
5. Reset to defaults if needed

LSP Not Working

1. Check that the language server is running in the output panel
2. Verify activation events are triggered (open a TypeScript/JavaScript file)
3. Try reloading the window: Developer: Reload Window
4. Check for conflicting extensions
5. Review LSP logs in the output panel

Error Messages

The extension provides categorized error messages:

• User Errors: Invalid input or file not found - check your paths and permissions
• System Errors: Disk space or memory issues - check system resources
• Network Errors: MCP server connection issues - restart the server
• Security Errors: Blocked paths or boundary violations - review security settings
• Configuration Errors: Invalid settings - check configuration values

Each error includes recovery suggestions to help you resolve the issue quickly.

Support

• Issues: GitHub Issues
• Documentation: GitHub Repository
• Email: info@digitaldefiance.org

License

MIT License - see LICENSE file for details.

Part of AI Capabilities Suite

This extension is part of the Digital Defiance AI Capabilities Suite, which includes:

• MCP ACS Process Manager: Process management with security boundaries
• MCP ACS Screenshot: Cross-platform screenshot capture
• MCP ACS Debugger: Advanced debugging capabilities
• MCP ACS Filesystem Manager: Advanced file operations (this extension)

Visit Digital Defiance for more information.