GitHub Stats

    Stars

    0

    Forks

    3

    Release Date

    3/14/2025

    about 3 months ago

    Detailed Description

    BetterMCPFileServer

    A reimagined Model Context Protocol (MCP) server for filesystem access with privacy-preserving path aliases and an optimized LLM-friendly API.

    Why BetterMCPFileServer?

    The original MCP file server was functional but not optimized for how LLMs actually interact with filesystems. This project delivers a complete redesign focused on simplicity, privacy, and efficiency.

    Key Innovations

    • Path Aliasing System - Protects privacy by hiding full system paths
    • LLM-Optimized Interface - Reduced from 11 to 6 functions while maintaining full capability
    • Smarter Search - One unified tool for directory listings and complex file searches
    • Privacy-First Design - No more exposing usernames or system paths to AI models

    Quick Start

    # Install from source (npm package coming soon)
    git clone https://github.com/martinschlott/BetterMCPFileServer.git
    cd BetterMCPFileServer
    npm install
    npm run build
    
    # Run with aliases
    BetterMCPFileServer code:~/projects docs:~/documents
    

    That's it! Now Claude can access your files through privacy-preserving aliases like code/src/main.js instead of /Users/yourusername/projects/src/main.js.

    Path Aliasing System

    Traditional file servers expose full system paths:

    /home/martin/Documents/PrivateProject/financial-data.txt
    

    Our aliasing system keeps your privacy intact:

    projects/financial-data.txt
    

    Benefits:

    • Privacy Protection: No usernames or sensitive directory names exposed
    • Simplification: LLMs work with clean, logical paths
    • Security: Strict boundaries for filesystem access

    API Design Rationale

    Redesigning the MCP File Server Interface

    This project represents a significant redesign of the standard MCP file server interface. While the original implementation provided a functional foundation, we identified several areas for improvement to create a more intuitive, efficient, and LLM-friendly interface.

    Key Improvements

    1. Intuitive Function Naming

    The original interface used snake_case naming with basic verbs like read_file and write_file. We've adopted more idiomatic camelCase naming with clearer, more specific function names:

    • read_filereadFileContent
    • write_filewriteFile
    • list_directorysearchFilesAndFolders (with pattern="*")

    These names explicitly communicate their purpose and follow standard programming conventions, making them more intuitive for both AI models and human developers.

    2. Grouped Functionality for Reduced Complexity

    Instead of having separate functions for each individual file or directory operation, we've consolidated related operations:

    • manageFile with an action parameter replaces separate move_file, copy_file, and delete_file functions
    • manageFolder handles folder creation, renaming, and deletion in one function

    This approach reduces API surface area while increasing flexibility, making it easier for LLMs to understand the complete range of available operations.

    3. Concise, Purposeful Descriptions

    The original interface included lengthy descriptions with redundant information, such as repeatedly stating "Only works within allowed directories" for each function. Our redesigned API features concise descriptions that:

    • Focus on what the function does
    • Avoid stating the obvious
    • Highlight distinctive capabilities
    • Eliminate marketing-style language that doesn't provide technical value

    4. Path Aliasing System

    One of the most significant improvements is our path aliasing system. The original approach required:

    • Specifying full allowed directories at startup
    • LLMs to use complete, absolute paths in every request
    • Exposing potentially sensitive information in directory paths (like usernames)

    Our new approach maps aliases to real paths:

    ~/Documents/MyProjects → projects
    ~/Documents/Letters → letters
    

    Benefits include:

    • LLMs work with simple, logical paths (projects/backend instead of /home/username/Documents/MyProjects/backend)
    • Privacy is enhanced by hiding actual paths containing usernames or sensitive directory structures
    • System configuration can change without impacting how LLMs interact with the server

    5. More Efficient Combined Operations

    We've added strategic combined operations to reduce round-trips and simplify common tasks:

    • searchFilesAndFolders with improved description and includeMetadata option completely replaces the need for a separate readFolderContent function
    • editFile retains the useful targeted text replacement functionality from the original implementation but with a clearer parameter structure

    A key achievement of this redesign is reducing the number of tools from 11 to 6 while maintaining full functionality. This simplification:

    • Makes the API easier to learn and remember
    • Reduces the cognitive load for LLMs when choosing appropriate tools
    • Minimizes redundancy between operations

    Design Philosophy

    This redesign follows several core principles:

    1. AI-First Interface: Optimized for LLM consumption and usage patterns
    2. Minimal Cognitive Load: Reduced number of functions with consistent naming and behavior
    3. Information Hiding: Abstracted implementation details that don't benefit the consumer
    4. Progressive Disclosure: Simple operations are simple, advanced features are available when needed

    Optimized Search Functionality

    Our redesigned search function is both powerful and easy to use:

    searchFilesAndFolders({
      pattern: "**/*.js",                   // Find all JavaScript files
      includeMetadata: true,                // Include file sizes and dates (use sparingly)
      ignore: ["node_modules", "*.min.js"]  // Skip unwanted matches
    })
    

    Key patterns:

    • "*" - List top-level items (like a simple directory listing)
    • "projects/*.js" - All JavaScript files in the projects directory
    • "**/*.md" - All markdown files recursively across all directories

    ⚠️ Pro Tip: Only set includeMetadata: true when you specifically need file sizes or dates to keep responses efficient.

    API Reference

    The BetterMCPFileServer exposes just 6 powerful functions that handle all filesystem operations:

    1. writeFile

    Create or update a file with the given content.

    writeFile({
      filePath: "projects/README.md",
      content: "# My Project\n\nThis is a readme file."
    })
    

    2. readFileContent

    Read the contents of a file.

    readFileContent({
      filePath: "projects/README.md"
    })
    

    3. editFile

    Make targeted changes to specific portions of a file.

    editFile({
      filePath: "projects/README.md",
      edits: [
        {
          oldText: "# My Project",
          newText: "# Awesome Project"
        }
      ],
      dryRun: false
    })
    

    4. manageFile

    Perform actions like move, rename, copy, or delete a file.

    manageFile({
      action: "move",
      filePath: "projects/old.js",
      newFilePath: "projects/new.js"
    })
    

    5. manageFolder

    Create, rename, or delete a folder.

    manageFolder({
      action: "create",
      folderPath: "projects/new-directory"
    })
    

    6. searchFilesAndFolders

    Search for files and folders using glob patterns.

    searchFilesAndFolders({
      pattern: "projects/**/*.ts",
      includeMetadata: false
    })
    

    Usage Examples

    Working with the Virtual Root

    // List all available aliases
    searchFilesAndFolders({ pattern: "*" })
    
    // Result:
    [
      { path: "projects", type: "directory" },
      { path: "docs", type: "directory" }
    ]
    

    Basic File Operations

    // Read a file
    const content = await readFileContent({ filePath: "projects/README.md" });
    
    // Write a file
    await writeFile({
      filePath: "projects/notes.txt",
      content: "Important meeting notes."
    });
    
    // Edit a file
    await editFile({
      filePath: "projects/config.json",
      edits: [
        {
          oldText: '"version": "1.0.0"',
          newText: '"version": "1.0.1"'
        }
      ]
    });
    

    Directory Operations

    // Create a new directory
    await manageFolder({
      action: "create",
      folderPath: "projects/new-feature"
    });
    
    // List directory contents
    const files = await searchFilesAndFolders({
      pattern: "projects/src/*"
    });
    

    Installation

    # From npm (coming soon)
    npm install -g BetterMCPFileServer  # Not yet available
    
    # From source (current method)
    git clone https://github.com/martinschlott/BetterMCPFileServer.git
    cd BetterMCPFileServer
    npm install
    npm run build
    npm link  # Optional, makes command available globally
    

    Usage

    Start the server with at least one alias:directory pair:

    BetterMCPFileServer alias:directory [alias2:directory2 ...]
    

    Examples:

    # Single directory
    BetterMCPFileServer code:~/projects
    
    # Multiple directories
    BetterMCPFileServer code:~/Development docs:~/Documents/Technical notes:~/Notes
    

    Advanced Configuration

    Create a simple shell script for consistent configuration:

    #!/bin/bash
    # start-server.sh
    BetterMCPFileServer \
      code:~/Development/MyProjects \
      docs:~/Documents/Technical \
      data:~/Data/Samples \
      config:~/Configuration
    

    Troubleshooting

    • Error: Invalid alias:path format: Ensure each parameter uses the format alias:directory
    • Error: Directory doesn't exist: The specified directory must exist
    • Access denied error: Attempted access outside allowed directories
    • Unknown alias: The referenced alias wasn't defined at server startup

    Credits

    This project was a collaboration between Martin Schlott (concept and design) and AI assistants:

    • Claude 3.7 Sonnet (API design consultation and documentation)
    • Cursor AI (implementation)

    README crafted by Claude 3.7 Sonnet

    License

    MIT License

    About the Project

    This app has not been claimed by its owner yet.

    Claim Ownership

    Receive Updates

    Security Updates

    Get notified about trust rating changes

    to receive email notifications.