https://docs.rs/airs-mcpserver-fs

airs-mcpserver-fs

A security-first filesystem bridge that enables Claude Desktop and other MCP-compatible AI tools to intelligently read, write, and manage files in local development environments.

Overview

airs-mcpserver-fs transforms AI assistance from passive consultation to active collaboration by providing secure, standardized filesystem operations through the Model Context Protocol (MCP). AI agents can now both understand your project context and create tangible artifacts directly in your local environment.

Key Features

• 🔐 Security-First Design: Human-in-the-loop approval workflows with configurable security policies
• 📁 Complete Filesystem Operations: Read, write, create, delete, move, and copy files and directories
• �️ Binary File Restriction: Text-only processing with comprehensive binary file blocking
• ⚡ Performance Optimized: Sub-100ms response times with efficient memory management
• 🔧 AIRS Ecosystem Integration: Seamless compatibility with other AIRS MCP tools
• 🛡️ Security Implementation: Path validation, audit logging, threat detection, and binary file protection

Quick Start

Prerequisites

• Rust 1.88.0 or later
• Claude Desktop or another MCP-compatible client

Installation

From crates.io (Recommended)

cargo install airs-mcpserver-fs

From Source

git clone https://github.com/airsstack/airsstack.git
cd airsstack
cargo build --release --package airs-mcpserver-fs

Basic Setup

Step 1: Setup Directory Structure (Optional)

# Create directory structure with proper permissions
airs-mcpserver-fs setup

# Or specify custom directories
airs-mcpserver-fs setup --config-dir ~/.config/airs-mcpserver-fs --logs-dir ~/.local/share/airs-mcpserver-fs/logs

Step 2: Generate Configuration

# Generate development configuration
airs-mcpserver-fs config

# Generate config for specific environment
airs-mcpserver-fs config --env development

# Generate config in specific directory
airs-mcpserver-fs config --output ~/.config/airs-mcpserver-fs

Step 3: Configure Claude Desktop

Add to your Claude Desktop MCP configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "airs-mcpserver-fs": {
      "command": "/path/to/airs-mcpserver-fs",
      "env": {
        "AIRS_MCPSERVER_FS_ENV": "development",
        "AIRS_MCPSERVER_FS_CONFIG_DIR": "/Users/yourusername/.config/airs-mcpserver-fs",
        "AIRS_MCPSERVER_FS_LOG_DIR": "/Users/yourusername/.local/share/airs-mcpserver-fs/logs"
      }
    }
  }
}

Important: Replace /path/to/airs-mcpserver-fs with the actual path to your binary:

• If installed via cargo: ~/.cargo/bin/airs-mcpserver-fs (or airs-mcpserver-fs if ~/.cargo/bin is in your PATH)
• If built from source: path/to/airsstack/target/release/airs-mcpserver-fs

Also replace yourusername with your actual username.

Step 4: Restart Claude Desktop

Restart Claude Desktop to load the new MCP server configuration.

Example Configurations

We provide comprehensive configuration examples for different use cases:

• Configuration Examples - Environment-specific and use-case configurations

  • claude-desktop.toml - Optimized for Claude Desktop integration
  • secure.toml - High-security for sensitive environments
  • educational.toml - Permissive for learning and tutorials
  • development.toml, production.toml, staging.toml - Environment-specific settings

• Claude Desktop Integration - Complete setup examples

  • claude_desktop_config.json - Ready-to-use MCP configuration
  • docker-compose.yml - Container deployment example
  • systemd.service - Linux service configuration
  • Comprehensive setup and troubleshooting guide

Test Your Setup

Once Claude Desktop restarts, try these commands:

User: "List the files in my Documents directory"
Claude: *uses list_directory tool* → shows your Documents contents

User: "Read my project's README.md file"
Claude: *uses read_file tool* → displays the README content

User: "Create a new file called hello.txt with 'Hello World' in my Documents"
Claude: *uses write_file tool* → creates the file with approval prompt

Core Capabilities

File Operations

• read_file: Read text files with automatic encoding detection
• write_file: Create or update files with approval workflows
• list_directory: Browse filesystem with metadata and filtering
• create_directory: Create directory structures recursively
• delete_file/delete_directory: Safe deletion with confirmation
• move_file/copy_file: File manipulation with atomic operations

Security Features

• Binary File Restriction: Comprehensive blocking of binary files to eliminate binary-based security risks
• Human Approval: Interactive confirmation for write/delete operations
• Path Validation: Prevent directory traversal and unauthorized access
• Access Control: Configurable allowlists and denylists for file paths
• Audit Logging: Comprehensive operation tracking for compliance
• Threat Detection: Enhanced security monitoring with binary file rejection

Configuration

AIRS MCP-FS uses a sophisticated multi-layered configuration system that automatically adapts to different environments while maintaining security and flexibility.

Quick Configuration

For development work, your configuration should include your project directories:

# ~/.config/airs-mcpserver-fs/development.toml
[security.filesystem]
allowed_paths = [
    "~/projects/**/*",           # All your projects
    "~/Documents/**/*",          # Documents directory (both directory and contents)
    "~/Desktop/**/*",            # Desktop files
    "./**/*"                     # Current directory when running from project
]

[security.operations]
read_allowed = true
write_requires_policy = false    # Allow writes in development
delete_requires_explicit_allow = true

# Named policies for different file types
[security.policies.journal_files]
patterns = ["/Users/yourusername/Documents/**/*"]
operations = ["read", "write", "list"]
risk_level = "low"
description = "Personal journal and document files"

Important: When configuring directory access, you need both the directory path itself AND its contents:

• ~/Documents - Access to the directory itself
• ~/Documents/**/* - Access to files within the directory

Environment-Specific Configuration

AIRS MCP-FS automatically detects your environment and loads appropriate configurations:

• Development: ~/.config/airs-mcpserver-fs/development.toml - Permissive settings for productivity
• Staging: ~/.config/airs-mcpserver-fs/staging.toml - Production-like settings for testing
• Production: ~/.config/airs-mcpserver-fs/production.toml - Secure settings for deployment

Configuration Documentation

For comprehensive configuration guidance, see our detailed documentation:

• Quick Start Guide: Get up and running in 5 minutes
• Configuration Guide: Complete configuration system overview
• Environment Setup: Environment detection and management
• Security Policies: Advanced security configuration
• Claude Desktop Integration: MCP client setup
• Troubleshooting: Common issues and solutions

Use Cases

Development Workflow Enhancement

• Code Analysis: "Analyze all TypeScript files for potential performance issues"
• Documentation Generation: "Create API docs from my source code comments"
• Automated Refactoring: "Convert React class components to functional components"
• Project Setup: "Create a new Next.js project structure with best practices"

Content & Document Management

• Configuration Management: "Update configuration files with new environment settings"
• Documentation Processing: "Extract and organize README files from all project directories"
• File Organization: "Organize source code files by feature and module"
• Backup Creation: "Create a backup of essential project configuration files"

Research & Analysis

• Code Metadata Extraction: "Extract function signatures and documentation from source files"
• Content Analysis: "Analyze the structure and content of technical documentation"
• Text Processing: "Process and standardize all markdown documentation files"
• Duplicate Detection: "Find and organize duplicate configuration files across directories"

Security Best Practices

Recommended Security Settings

• Always enable approval workflows for write operations
• Use restrictive path allowlists for sensitive environments
• Regularly review audit logs for suspicious activity
• Keep forbidden patterns updated with sensitive file types
• Binary file processing is disabled by default for maximum security

Path Security

• Use absolute paths in configuration when possible
• Avoid wildcard patterns that might expose sensitive directories
• Regularly audit allowed paths and remove unnecessary access
• Monitor for path traversal attempts in logs

Binary File Security

• Binary file processing is completely disabled for enhanced security
• All binary file operations return security validation errors
• Focus on text-based file operations for AI-assisted development
• Eliminates entire classes of binary-based security vulnerabilities
• Provides clear security boundaries for enterprise deployments

Advanced Features

Security-First Architecture

The system prioritizes security through comprehensive binary file restriction and enhanced validation:

[security]
# Binary processing is completely disabled for security
binary_processing_disabled = true
text_only_mode = true

Plugin System

Extend functionality with custom text file processors:

• Register custom text format handlers
• Add domain-specific processing logic for development files
• Integrate with external tools and services for text processing
• Create organization-specific workflows for code and documentation

AIRS Ecosystem Integration

• airs-mcp: Leverage shared MCP infrastructure
• airs-memspec: Manage memory bank files
• airs-mcp-kb: Populate knowledge bases from documents
• Shared Security: Consistent policies across AIRS tools

Performance & Scalability

Performance Characteristics

• Response Time: <100ms for typical file operations
• Large Files: Streaming support for files up to 1GB
• Concurrent Operations: Handle 10+ simultaneous requests
• Memory Usage: <50MB baseline with linear scaling

Optimization Features

• Intelligent caching for frequently accessed files
• Streaming for large file transfers
• Background processing for heavy operations
• Connection pooling for multiple clients

Troubleshooting

Common Issues

"Permission Denied" Errors

• Cause: Path not included in allowed_paths configuration or blocked by denied_paths
• Solution: Update your configuration to include the required directory and its contents:

  [security.filesystem]
  allowed_paths = [
      "~/Documents",        # Directory itself
      "~/Documents/**/*"    # Directory contents
  ]
  

"Security validation failed" Errors

• Cause: Glob patterns not matching the requested path
• Solution: Ensure your patterns include both directory access and content access
• Debug: Check your configuration file and verify the path patterns

"Configuration file not found" Warnings

• Cause: No environment-specific configuration file exists
• Solution: Generate configuration for your environment:

  airs-mcpserver-fs config --env development
  

"Invalid server response" in Claude Desktop

• Cause: Incorrect environment variables or binary path in Claude Desktop configuration
• Solution: Verify your Claude Desktop JSON configuration includes correct paths and environment variables

For comprehensive troubleshooting guidance, see Configuration Troubleshooting.

Debug Mode

RUST_LOG=debug airs-mcpserver-fs --config ./debug-config.toml

Log Analysis

• Check ~/.local/share/airs-mcpserver-fs/logs/ for detailed operation logs
• Review audit trail for security-related events
• Monitor performance metrics for optimization opportunities

Contributing

Development Setup

# Clone the repository
git clone https://github.com/airsstack/airsstack.git
cd airsstack/mcp-servers/airs-mcpserver-fs

# Install dependencies
cargo build

# Run tests
cargo test

# Run with development config
cargo run -- --config ./dev-config.toml

Testing

• Unit Tests: cargo test
• Integration Tests: cargo test --test integration
• Security Tests: cargo test --test security
• Performance Tests: cargo test --test performance

Code Standards

• Follow Rust API guidelines and formatting standards
• Write comprehensive tests for all new functionality
• Document public APIs with rustdoc
• Follow security best practices for file operations

Security Implementation

Implemented Security Standards

• Path Traversal Protection: Comprehensive canonicalization and sandbox enforcement preventing directory traversal attacks
• Binary File Restriction: Multi-layer detection system blocking all binary file formats (JPEG, PNG, GIF, PDF, executables)
• Human-in-the-Loop Approval: Interactive approval workflows for high-risk filesystem operations
• Configurable Security Policies: Allowlist/denylist path restrictions with operation-specific controls
• Threat Detection Framework: Risk assessment and pattern recognition for suspicious activity
• Comprehensive Audit Logging: All operations logged with context for compliance and forensics

Security Architecture

The security framework implements a defense-in-depth approach with five distinct layers:

1. Path Validation: Canonicalization, symlink resolution, and sandbox enforcement
2. Content Analysis: File type validation, size limits, and encoding verification
3. Operation Approval: Risk-based approval requirements with human oversight
4. Binary File Filtering: Extension and content-based binary format detection and rejection
5. Audit & Monitoring: Comprehensive logging and threat correlation

Security Testing

• Path Traversal Tests: 22 attack vectors covering encoding bypass, Unicode attacks, and separator confusion
• Binary Detection Tests: Content-based detection preventing disguised binary files
• Input Validation Tests: Comprehensive validation of all user inputs and file paths
• Security Audit Score: 97.5/100 with regular vulnerability assessments

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

See CONTRIBUTING.md for detailed contribution guidelines.

Documentation

For comprehensive guides and advanced configuration:

• 📚 Complete Documentation - Full mdbook documentation
• 🚀 Quick Start Guide - Get running in 5 minutes
• ⚙️ Configuration Guide - Complete configuration system
• 🔒 Security Policies - Advanced security configuration
• 🔧 Troubleshooting - Common issues and solutions

Building Documentation

# Install mdbook
cargo install mdbook

# Build and serve documentation
cd crates/airs-mcpserver-fs/docs
mdbook serve

# Open http://localhost:3000 in your browser

Support

• Documentation: Full documentation and guides
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Community: Discord Server

Related Projects

• airs-mcp: Core MCP protocol implementation
• airs-memspec: Memory bank management CLI
• AIRS Platform: Complete AI & Rust technology stack

---

Built with ❤️ using Rust and the Model Context Protocol