# 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
## Installation
```bash
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:
| Model | Dimensions | Description |
|-------|------------|-------------|
| `nomic-v1.5` | 768 | High-quality general-purpose (default) |
| `mxbai-large` | 1024 | Large model with excellent performance |
| `all-minilm` | 384 | Lightweight and fast |
| `bge-small` | 384 | BAAI general embedding, small version |
| `gte-base` | 768 | General Text Embeddings model |
### Configuration Structure
```yaml
# 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](docs/CONFIGURATION.md).
## 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](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](GITHUB_ISSUES.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:
```json
{
"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
## 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
```bash
npm run build
```
### Running the Server
```bash
npm start
```
### Development Mode
```bash
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](ROADMAP.md) for visual progress and [GITHUB_ISSUES.md](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](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!** 🚀
