Configuration Troubleshooting

This section provides comprehensive troubleshooting guidance for common AIRS MCP-FS configuration issues, complete with diagnostic steps and solutions.

Quick Diagnostic Checklist

When experiencing issues, run through this checklist:

1. ✅ Binary Accessibility: Can you run airsprotocols-mcpserver-filesystem --help?
2. ✅ Configuration File: Does your config file exist and have correct syntax?
3. ✅ Environment Detection: Is AIRS_MCP_FS_ENV set correctly?
4. ✅ Path Permissions: Are your allowed paths accessible?
5. ✅ Claude Desktop Config: Is the JSON configuration syntactically correct?
6. ✅ Log Files: Are there error messages in the log files?

Configuration Loading Issues

Problem: Configuration File Not Found

Symptoms:

📋 Configuration loaded from production environment
   Configuration files: []
   Environment variables: 0 overrides

⚠️  Using built-in defaults - no configuration file found

Diagnostic Steps:

# Check if environment is detected correctly
echo $AIRS_MCP_FS_ENV

# Check if config directory exists
ls -la ~/.config/airsprotocols-mcpserver-filesystem/

# Check if config file exists for your environment
ls -la ~/.config/airsprotocols-mcpserver-filesystem/development.toml

Solutions:

1. Generate Missing Configuration

   # Generate development configuration
   airsprotocols-mcpserver-filesystem generate-config --env development
   
   # Generate for specific environment
   airsprotocols-mcpserver-filesystem generate-config --env production --output ~/.config/airsprotocols-mcpserver-filesystem
   

2. Set Explicit Config Directory

   {
     "mcpServers": {
       "airsprotocols-mcpserver-filesystem": {
         "env": {
           "AIRS_MCP_FS_CONFIG_DIR": "/Users/username/.config/airsprotocols-mcpserver-filesystem"
         }
       }
     }
   }
   

3. Create Manual Configuration

   # Create config directory
   mkdir -p ~/.config/airsprotocols-mcpserver-filesystem
   
   # Create basic development configuration
   cat > ~/.config/airsprotocols-mcpserver-filesystem/development.toml << 'EOF'
   [security.filesystem]
   allowed_paths = ["~/Documents/**/*", "~/projects/**/*"]
   
   [security.operations]
   read_allowed = true
   write_requires_policy = false
   delete_requires_explicit_allow = true
   EOF
   

Problem: Configuration Syntax Errors

Symptoms:

❌ Configuration loading failed: TOML parse error at line 5, column 1

Diagnostic Steps:

# Validate TOML syntax
python3 -c "import tomllib; tomllib.load(open('~/.config/airsprotocols-mcpserver-filesystem/development.toml', 'rb'))"

# Or use a TOML validator
toml-validator ~/.config/airsprotocols-mcpserver-filesystem/development.toml

Solutions:

1. Fix Common TOML Errors

   # ❌ Missing quotes around strings
   allowed_paths = [~/Documents/**/*]
   
   # ✅ Correct string quoting
   allowed_paths = ["~/Documents/**/*"]
   
   # ❌ Invalid section header
   [security][filesystem]
   
   # ✅ Correct nested section
   [security.filesystem]
   

2. Validate Configuration Structure

   # Test configuration loading manually
   RUST_LOG=debug airsprotocols-mcpserver-filesystem 2>&1 | grep -i config
   

Permission and Security Issues

Problem: "Security validation failed: Access denied"

Symptoms:

❌ Security validation failed: Access denied for path: /Users/username/Documents/file.txt

Diagnostic Steps:

# Check current configuration
cat ~/.config/airsprotocols-mcpserver-filesystem/development.toml | grep -A 5 allowed_paths

# Test path matching manually
RUST_LOG=debug airsprotocols-mcpserver-filesystem 2>&1 | grep -i "path validation"

Root Causes and Solutions:

1. Path Not in Allowed Paths

   # ❌ Path not included
   [security.filesystem]
   allowed_paths = ["~/projects/**/*"]
   
   # ✅ Add required path
   [security.filesystem]
   allowed_paths = [
       "~/projects/**/*",
       "~/Documents/**/*"  # Add this line
   ]
   

2. Glob Pattern Doesn't Match

   # ❌ Pattern doesn't match directory itself
   allowed_paths = ["~/Documents/**/*"]  # Matches contents but not directory
   
   # ✅ Include both directory and contents
   allowed_paths = [
       "~/Documents",        # Directory itself
       "~/Documents/**/*"    # Directory contents
   ]
   

3. Denied Paths Taking Precedence

   # Check if path is in denied_paths
   [security.filesystem]
   allowed_paths = ["~/Documents/**/*"]
   denied_paths = ["~/.*/**"]  # This might block ~/Documents
   
   # ✅ Make denied paths more specific
   denied_paths = [
       "**/.git/**",
       "**/.env*",
       "~/Library/**"  # More specific than ~/.*/**
   ]
   

Problem: "Write operation requires policy"

Symptoms:

❌ Write operation denied: No matching policy found for /Users/username/Documents/file.txt

Diagnostic Steps:

# Check operation configuration
cat ~/.config/airsprotocols-mcpserver-filesystem/development.toml | grep -A 5 operations

# Check security policies
cat ~/.config/airsprotocols-mcpserver-filesystem/development.toml | grep -A 10 policies

Solutions:

1. Disable Policy Requirement for Development

   [security.operations]
   read_allowed = true
   write_requires_policy = false  # Allow writes without policy
   delete_requires_explicit_allow = true
   

2. Create Appropriate Security Policy

   [security.policies.document_files]
   patterns = ["~/Documents/**/*.{txt,md,doc}"]
   operations = ["read", "write"]
   risk_level = "low"
   description = "Personal document files"
   

3. Use Environment Variables Override

   {
     "mcpServers": {
       "airsprotocols-mcpserver-filesystem": {
         "env": {
           "AIRS_MCP_FS_SECURITY_OPERATIONS_WRITE_REQUIRES_POLICY": "false"
         }
       }
     }
   }
   

Environment Detection Issues

Problem: Wrong Environment Detected

Symptoms:

📋 Configuration loaded from production environment

(When you expected development)

Diagnostic Steps:

# Check environment variables
echo "AIRS_MCP_FS_ENV: $AIRS_MCP_FS_ENV"
echo "NODE_ENV: $NODE_ENV"
echo "ENVIRONMENT: $ENVIRONMENT"

# Check if running in debug mode
cargo --version
rustc --version

Solutions:

1. Set Explicit Environment Variable

   {
     "mcpServers": {
       "airsprotocols-mcpserver-filesystem": {
         "env": {
           "AIRS_MCP_FS_ENV": "development"
         }
       }
     }
   }
   

2. Check for Conflicting Environment Variables

   # Unset conflicting variables
   unset NODE_ENV
   unset ENVIRONMENT
   
   # Set AIRS-specific variable
   export AIRS_MCP_FS_ENV=development
   

Claude Desktop Integration Issues

Problem: MCP Server Not Loading

Symptoms: Claude Desktop doesn't show filesystem tools available

Diagnostic Steps:

# Check if binary exists and is executable
ls -la /path/to/airsprotocols-mcpserver-filesystem
file /path/to/airsprotocols-mcpserver-filesystem

# Test binary directly
/path/to/airsprotocols-mcpserver-filesystem --help

# Validate JSON configuration
python3 -m json.tool < "~/Library/Application Support/Claude/claude_desktop_config.json"

Solutions:

1. Fix Binary Path

   # Find correct binary path
   which airsprotocols-mcpserver-filesystem
   
   # Or use absolute path
   realpath target/release/airsprotocols-mcpserver-filesystem
   

2. Fix JSON Configuration

   {
     "mcpServers": {
       "airsprotocols-mcpserver-filesystem": {
         "command": "/correct/absolute/path/to/airsprotocols-mcpserver-filesystem",
         "env": {
           "AIRS_MCP_FS_ENV": "development"
         }
       }
     }
   }
   

3. Check Binary Permissions

   # Make binary executable
   chmod +x /path/to/airsprotocols-mcpserver-filesystem
   
   # Check architecture compatibility
   file /path/to/airsprotocols-mcpserver-filesystem
   

Problem: "Invalid server response" Errors

Symptoms: Claude Desktop shows MCP communication errors

Diagnostic Steps:

# Check log files
tail -f ~/.local/share/airsprotocols-mcpserver-filesystem/logs/airsprotocols-mcpserver-filesystem.log

# Test server communication manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | /path/to/airsprotocols-mcpserver-filesystem

Solutions:

1. Check Log Directory Permissions

   # Create log directory if it doesn't exist
   mkdir -p ~/.local/share/airsprotocols-mcpserver-filesystem/logs
   
   # Set proper permissions
   chmod 755 ~/.local/share/airsprotocols-mcpserver-filesystem/logs
   

2. Set Explicit Log Directory

   {
     "mcpServers": {
       "airsprotocols-mcpserver-filesystem": {
         "env": {
           "AIRS_MCP_FS_LOG_DIR": "/Users/username/.local/share/airsprotocols-mcpserver-filesystem/logs"
         }
       }
     }
   }
   

Path and Glob Pattern Issues

Problem: Glob Patterns Not Matching Expected Files

Symptoms: Files you expect to be accessible are denied

Diagnostic Steps:

# Test glob patterns manually
find ~/Documents -name "*.txt" | head -5

# Check pattern syntax
echo "Pattern: ~/Documents/**/*.txt"
echo "Test file: ~/Documents/notes/todo.txt"

Pattern Testing Tool:

# Create a simple pattern tester
cat > test_pattern.py << 'EOF'
import glob
import sys

pattern = sys.argv[1]
test_path = sys.argv[2]

matches = glob.glob(pattern, recursive=True)
print(f"Pattern: {pattern}")
print(f"Test path: {test_path}")
print(f"Matches: {test_path in matches}")
print(f"All matches: {matches[:10]}")  # Show first 10 matches
EOF

python3 test_pattern.py "~/Documents/**/*.txt" "~/Documents/notes/todo.txt"

Solutions:

1. Fix Common Glob Pattern Issues

   # ❌ Missing recursive wildcard
   allowed_paths = ["~/Documents/*.txt"]  # Only matches direct children
   
   # ✅ Use recursive wildcard
   allowed_paths = ["~/Documents/**/*.txt"]  # Matches all subdirectories
   
   # ❌ Forgetting directory access
   allowed_paths = ["~/Documents/**/*"]  # Matches contents but not directory
   
   # ✅ Include directory and contents
   allowed_paths = [
       "~/Documents",        # Directory itself
       "~/Documents/**/*"    # Directory contents
   ]
   

2. Test Different Pattern Approaches

   # Specific file types
   allowed_paths = ["~/Documents/**/*.{txt,md,doc,pdf}"]
   
   # All files in specific directories
   allowed_paths = ["~/Documents/projects/**/*"]
   
   # Multiple directory patterns
   allowed_paths = [
       "~/Documents/**/*",
       "~/projects/**/*",
       "~/Desktop/**/*"
   ]
   

File Size and Binary Processing Issues

Problem: "File too large" Errors

Symptoms:

❌ File too large: 150MB exceeds maximum size of 100MB

Solutions:

1. Increase File Size Limit

   [binary]
   max_file_size = 209715200  # 200MB
   

2. Use Environment Variable Override

   {
     "mcpServers": {
       "airsprotocols-mcpserver-filesystem": {
         "env": {
           "AIRS_MCP_FS_BINARY_MAX_FILE_SIZE": "209715200"
         }
       }
     }
   }
   

Problem: Binary Processing Failures

Symptoms: Images or PDFs not processing correctly

Diagnostic Steps:

# Check if binary processing is enabled
cat ~/.config/airsprotocols-mcpserver-filesystem/development.toml | grep -A 5 binary

# Test file format
file ~/Documents/image.jpg

Solutions:

1. Enable Binary Processing

   [binary]
   enable_image_processing = true
   enable_pdf_processing = true
   

2. Check File Format Support

   # Supported image formats: JPEG, PNG, GIF, WebP, TIFF, BMP
   # Supported document formats: PDF
   

Advanced Debugging

Enable Debug Logging

{
  "mcpServers": {
    "airsprotocols-mcpserver-filesystem": {
      "env": {
        "RUST_LOG": "debug",
        "AIRS_MCP_FS_ENV": "development"
      }
    }
  }
}

This provides detailed logging of: - Configuration loading process - Environment detection logic - Security validation decisions - Path pattern matching - Policy evaluation results

Log Analysis

# Monitor logs in real-time
tail -f ~/.local/share/airsprotocols-mcpserver-filesystem/logs/airsprotocols-mcpserver-filesystem.log

# Search for specific errors
grep -i "error\|denied\|failed" ~/.local/share/airsprotocols-mcpserver-filesystem/logs/airsprotocols-mcpserver-filesystem.log

# Filter security-related logs
grep -i "security\|validation\|policy" ~/.local/share/airsprotocols-mcpserver-filesystem/logs/airsprotocols-mcpserver-filesystem.log

Configuration Validation Tool

# Create configuration validator script
cat > validate_config.sh << 'EOF'
#!/bin/bash

CONFIG_FILE="$1"
if [ -z "$CONFIG_FILE" ]; then
    echo "Usage: $0 <config_file>"
    exit 1
fi

echo "Validating configuration: $CONFIG_FILE"

# Check file exists
if [ ! -f "$CONFIG_FILE" ]; then
    echo "❌ Configuration file not found"
    exit 1
fi

# Check TOML syntax
if python3 -c "import tomllib; tomllib.load(open('$CONFIG_FILE', 'rb'))" 2>/dev/null; then
    echo "✅ TOML syntax valid"
else
    echo "❌ TOML syntax error"
    python3 -c "import tomllib; tomllib.load(open('$CONFIG_FILE', 'rb'))"
    exit 1
fi

# Test with AIRS MCP-FS
TEMP_ENV=$(mktemp)
echo "AIRS_MCP_FS_CONFIG_DIR=$(dirname "$CONFIG_FILE")" > "$TEMP_ENV"
echo "AIRS_MCP_FS_ENV=$(basename "$CONFIG_FILE" .toml)" >> "$TEMP_ENV"

if env -i bash -c "source $TEMP_ENV && timeout 5s airsprotocols-mcpserver-filesystem" 2>/dev/null; then
    echo "✅ Configuration loads successfully"
else
    echo "❌ Configuration loading failed"
    echo "Check logs for details:"
    echo "  tail ~/.local/share/airsprotocols-mcpserver-filesystem/logs/airsprotocols-mcpserver-filesystem.log"
fi

rm "$TEMP_ENV"
EOF

chmod +x validate_config.sh

# Use the validator
./validate_config.sh ~/.config/airsprotocols-mcpserver-filesystem/development.toml

Getting Help

Log Collection for Support

# Collect diagnostic information
cat > collect_diagnostics.sh << 'EOF'
#!/bin/bash

echo "AIRS MCP-FS Diagnostic Information"
echo "=================================="
echo "Date: $(date)"
echo "OS: $(uname -a)"
echo ""

echo "Environment Variables:"
echo "AIRS_MCP_FS_ENV: $AIRS_MCP_FS_ENV"
echo "AIRS_MCP_FS_CONFIG_DIR: $AIRS_MCP_FS_CONFIG_DIR"
echo "AIRS_MCP_FS_LOG_DIR: $AIRS_MCP_FS_LOG_DIR"
echo ""

echo "Binary Information:"
which airsprotocols-mcpserver-filesystem
airsprotocols-mcpserver-filesystem --version 2>/dev/null || echo "Binary not found or not executable"
echo ""

echo "Configuration Files:"
find ~/.config/airsprotocols-mcpserver-filesystem -name "*.toml" 2>/dev/null | head -5
echo ""

echo "Recent Log Entries:"
tail -20 ~/.local/share/airsprotocols-mcpserver-filesystem/logs/airsprotocols-mcpserver-filesystem.log 2>/dev/null || echo "No log file found"
EOF

chmod +x collect_diagnostics.sh
./collect_diagnostics.sh > diagnostics.txt

Common Support Requests

1. Configuration Help: Share your configuration file (remove sensitive paths)
2. Error Logs: Include recent log entries with error messages
3. Environment Info: Share environment detection and variable settings
4. Claude Desktop Config: Share MCP server configuration (remove sensitive paths)

Related Sections

• Configuration Overview: Understanding the configuration system
• Environment Setup: Environment-specific configuration
• Security Policies: Security policy troubleshooting
• Claude Desktop Integration: MCP integration issues