MCP Smart Filesystem Server

An LLM-optimized Model Context Protocol (MCP) filesystem server with intelligent features designed for effective AI agent interaction.

Features

🚀 Intelligent File Pagination

• Automatically chunks large files (>500 lines) into manageable pieces

• Simple start_line parameter for easy navigation

• Clear indicators when more content is available

• Prevents context overflow in LLM conversations

⚡ Ripgrep Integration

• Lightning-fast code searching across entire codebase

• Regex pattern support with helpful examples

• File-specific searching (like Ctrl+F with regex)

• Flexible filtering by file type, path, and more

🔒 Security Sandboxing

• Strict directory access control

• Symlink attack prevention

• Path traversal protection

• Only accesses files within allowed directories

🎯 LLM-Friendly Design

• Helpful suggestions in responses

• Examples for common search patterns

• Reading strategy recommendations for large files

• Clear error messages with actionable guidance

Tools

1. list_directory

List directory contents with metadata.

Returns: Files, directories, sizes, line counts, and summary statistics.

2. read_file

Read file contents with automatic pagination for large files.

For files >500 lines, returns first 500 lines with hasMore: true and nextStartLine.
Read next chunk with start_line: 500, then 1000, etc.

3. search_code

Search for code patterns using ripgrep (very fast).

Examples:

Find any type declaration (class/struct/interface/enum):

Find method with any access modifier:

Find all async functions:

Options:

• pattern (required): Regex pattern

• path: Limit to specific directory

• filePattern: File glob (e.g., *.js, *.{ts,tsx}, !*test*)

• caseInsensitive: Ignore case

• contextLines: Lines of context (default: 2)

• maxResults: Max results (default: 50)

• literalString: Treat as literal, not regex

• wordBoundary: Match whole words only

4. search_in_file

Search within a specific file (like Ctrl+F with regex).

5. find_files

Find files by name pattern.

Pattern examples:

• config.json - Exact name

• *.config - Wildcard

• *Service* - Contains "Service"

• *.{ts,tsx,js} - Multiple extensions

6. get_file_info

Get file metadata without reading contents.

Returns: Size, line count, language, binary status, and reading strategy for large files.

7. list_allowed_directories

Show accessible directories (security boundaries).

Installation

Docker (Recommended)

The :ro flag makes the directory read-only for extra security.

Configuration via Environment Variables

Customize behavior with environment variables:

Available Variables:

• MCP_LINES_PER_PAGE - Lines per page when reading files (default: 500)

• MCP_MAX_SEARCH_RESULTS - Search results per page (default: 100)

Local Installation

Usage with MCP Clients

Configuration Example

Multiple Allowed Directories

LLM Usage Patterns

Pattern 1: Find Type Declaration (Unknown Kind)

When you don't know if something is a class, struct, interface, or record:

Pattern 2: Explore Then Read

1. Search for what you need: search_code(pattern="functionName")

2. Get file info: get_file_info(path="src/module.ts")

3. Read strategically: read_file(path="src/module.ts", start_line=0)

Pattern 3: Large File Navigation

1. Check size: get_file_info(path="big-file.ts") → "1500 lines"

2. Search within: search_in_file(path="big-file.ts", pattern="export class")

3. Read around matches: Use line numbers from search to read specific chunks

Pattern 4: Find Files, Then Search

1. Find files: find_files(pattern="*Service*.ts")

2. Search within results: search_code(pattern="constructor", path="src/services")

Common Search Patterns

C# / .NET

TypeScript / JavaScript

Python

Requirements

• Node.js: 22 or higher

• ripgrep: Must be installed and available in PATH

  • Alpine Linux: apk add ripgrep

  • Ubuntu/Debian: apt install ripgrep

  • macOS: brew install ripgrep

  • Windows: choco install ripgrep

Security

This server implements multiple security layers:

1. Directory Sandboxing: Only accesses files within allowed directories

2. Symlink Resolution: Prevents symlink attacks by checking real paths

3. Path Validation: Blocks path traversal attempts (../, etc.)

4. Read-Only Docker: Mount volumes as :ro for read-only access

Development

License

MIT

Credits

Built on top of the Model Context Protocol (MCP) SDK and ripgrep.