folder-mcp (Under Development, will be released soon enough)

Model Context Protocol Server for Folder Operations

A Model Context Protocol (MCP) server that provides tools for reading and analyzing folder structures, enabling LLMs to interact with local file systems safely and efficiently.

Overview

folder-mcp was created for a simple but powerful purpose: take your local folder and make it accessible to Large Language Models (LLMs) running anywhere. You don't need to upload your files to the cloud or use a third-party service.

it creates RAG (Retrieval-Augmented Generation) capabilities for your local files, allowing LLMs to read, search, and analyze documents in a secure and structured way. This server implements the Model Context Protocol (MCP) standard, allowing LLMs to interact with local file systems through a set of defined tools. This project is designed to work with MCP clients like Claude Desktop, Cursor, VsCode and others, providing a secure and efficient way to access and manipulate files within specified folders.

Features

✅ Secure File Access

• Read files from specified folders with path validation
• Security checks to prevent directory traversal attacks
• Support for various file types and encodings

✅ File System Operations

• List all files in a folder recursively
• Search files by name patterns (glob support)
• Get folder information and metadata
• Exclude common directories like node_modules and .git

✅ MCP Integration

• Standard Model Context Protocol server implementation
• Works with Claude Desktop and other MCP clients
• Stdio transport for seamless integration
• Structured tool definitions with JSON schemas

✅ Developer Friendly

• TypeScript implementation with full type safety
• Clear error handling and informative responses
• Simple CLI interface for testing and development

Current Status

🚀 Version 1.0 - Basic MCP Server (13/30 planned features complete)

This is the foundation release providing secure file system access through MCP. The full vision includes semantic search, embeddings, and intelligent document parsing - see ROADMAP.md for the complete development plan.

What works now:

• ✅ Basic file reading and folder operations
• ✅ Security validation and path protection
• ✅ Pattern-based file searching
• ✅ MCP protocol integration

Coming next: Smart text chunking, semantic embeddings, vector search (see all 30 planned features)

Architecture

MCP Server Implementation

The server implements the Model Context Protocol standard with the following components:

📡 MCP Client (Claude Desktop) ↔ 📞 Stdio Transport ↔ 🖥️ MCP Server ↔ 📁 File System

File Access Pattern

1. Client Request → 2. Tool Validation → 3. Path Security Check → 4. File Operation → 5. Response

Server Components

• Tool Handlers: Process read_file, search_files, list_files, and get_folder_info requests
• Security Layer: Validates paths and prevents directory traversal
• File Operations: Uses Node.js fs and glob for efficient file system access
• Transport Layer: Stdio transport for communication with MCP clients

Technical Details

Dependencies

• @modelcontextprotocol/sdk: MCP protocol implementation
• glob: Pattern-based file searching
• typescript: Type-safe development
• Additional libraries for future file parsing capabilities

File Patterns

The server uses glob patterns for file searching:

• * - All files
• *.md - Markdown files only
• **/*.js - JavaScript files recursively
• config.* - Any file starting with "config"

Excluded Directories

Automatically excluded from all operations:

• **/node_modules/**
• **/.git/**
• **/.folder-mcp/**

Development

Building the Project

npm run build

Running the Server

npm start

Development Mode

npm run dev

Testing with MCP Clients

The server can be tested with any MCP-compatible client. For Claude Desktop, add the configuration to your settings file.

Future Enhancements

📋 Development Roadmap: See ROADMAP.md for visual progress and GITHUB_ISSUES.md for detailed task breakdown.

Planned Features (17 remaining tasks):

• Phase 3: Smart text chunking and semantic embeddings
• Phase 4: FAISS vector search and similarity matching
• Phase 5: Enhanced MCP integration with semantic search
• Phase 6: Real-time file watching and configuration system
• Phase 7: Performance optimization and comprehensive testing
• Phase 8: Documentation and npm release

Vision: Universal Folder-to-MCP Tool

Transform any folder into an intelligent knowledge base with:

• Multi-format parsing: PDF, Word, Excel, PowerPoint with structure preservation
• Semantic embeddings: Nomic Embed model for intelligent content understanding
• Vector search: FAISS-powered similarity search for context-aware retrieval
• Smart chunking: Meaning-based content segmentation
• Real-time updates: File watching with automatic re-indexing
• RAG capabilities: Enable LLMs to query folder contents intelligently

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Acknowledgments

• Built with the Model Context Protocol SDK
• Uses TypeScript for type safety and developer experience
• Designed for secure and efficient file system access
• Compatible with Claude Desktop and other MCP clients

Enable your LLM to work with local folders through the Model Context Protocol! 🚀

Installation

git clone https://github.com/okets/folder-mcp.git
cd folder-mcp
npm install
npm run build

Configuration

folder-mcp uses a centralized configuration system stored in config.yaml at the project root. This YAML file contains settings for embeddings, caching, processing, API, logging, and development configurations.

Embedding Models

The system supports multiple embedding models with GPU acceleration via Ollama:

Configuration Structure

# Embedding Model Configuration
embeddings:
  defaultModel: "nomic-v1.5"
  ollamaApiUrl: "http://127.0.0.1:11434"
  batchSize: 32
  timeoutMs: 30000
  models:
    # Model definitions with dimensions, descriptions, etc.

# Cache Configuration  
cache:
  defaultCacheDir: "~/.cache/folder-mcp"
  maxCacheSize: "10GB"
  cleanupIntervalHours: 24

# Text Processing Configuration
processing:
  defaultChunkSize: 1000
  defaultOverlap: 200
  maxConcurrentOperations: 10

# Development & Logging options
logging:
  level: "info"
  format: "json"
  
development:
  enableDebugOutput: false
  mockOllamaApi: false

For detailed configuration options, see CONFIGURATION.md.

Usage

As an MCP Server

This server is designed to be used with MCP clients like Claude Desktop. Add it to your Claude Desktop configuration:

{
  "mcpServers": {
    "folder-mcp": {
      "command": "node",
      "args": [
        "C:\\Path\\To\\folder-mcp\\dist\\mcp-server.js",
        "C:\\Path\\To\\folder-mcp"
      ],
      "env": {}
    }
  }
}

⚠️ Critical Claude Desktop Integration Note: The MCP protocol requires that ONLY valid JSON-RPC messages go to stdout. Any logging or debugging output to stdout will break the connection. All logs should be redirected to stderr only. See CLAUDE_DESKTOP_SETUP.md for detailed troubleshooting tips.

Available Tools

The server currently provides the following tools:

1. get_status - A system status tool that returns processing information to verify connection
   • Optional parameter: name - A name to include in the greeting

1. read_file

Read the contents of a specific file within a folder.

Parameters:

• folder_path: Path to the folder containing the file
• file_path: Relative path to the file within the folder

2. search_files

Search for files matching a specific pattern.

Parameters:

• folder_path: Path to the folder to search
• pattern: File pattern (e.g., ".md", ".txt", "config.*")

3. list_files

List all files in a folder recursively.

Parameters:

• folder_path: Path to the folder to list

4. get_folder_info

Get information about a folder including file count and metadata.

Parameters:

• folder_path: Path to the folder to analyze

Security Features

• Path Validation: Prevents access to files outside the specified folder
• Directory Exclusions: Automatically excludes node_modules, .git, and cache folders
• Error Handling: Graceful handling of permission errors and invalid paths