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.

{
  "path": "src"
}

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

2. read_file

Read file contents with automatic pagination for large files.

{
  "path": "src/large-file.ts",
  "start_line": 0
}

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):

{
  "pattern": "\\b(class|struct|interface|enum)\\s+ServiceName\\b",
  "filePattern": "*.ts"
}

Find method with any access modifier:

{
  "pattern": "\\b(public|private|protected).*\\s+methodName\\s*\\(",
  "path": "src/directory"
}

Find all async functions:

{
  "pattern": "async\\s+.*\\s*\\(",
  "caseInsensitive": true,
  "contextLines": 3
}

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).

{
  "path": "src/server.ts",
  "pattern": "app\\.use\\(",
  "contextLines": 3
}

5. find_files

Find files by name pattern.

{
  "pattern": "*Handler*.ts"
}

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.

{
  "path": "src/large-file.ts"
}

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)

# Build image
docker build -t mcp-filesystem-smart .

# Run with workspace mounted
docker run -i --rm \
  -v /path/to/your/project:/workspace:ro \
  mcp-filesystem-smart

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

Local Installation

npm install
npm run build
node dist/index.js /path/to/allowed/directory

Usage with MCP Clients

Configuration Example

{
  "mcpServers": {
    "filesystem-smart": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/user/projects/myapp:/workspace:ro",
        "mcp-filesystem-smart"
      ]
    }
  }
}

Multiple Allowed Directories

# Local
node dist/index.js /path/to/dir1 /path/to/dir2

# Docker (mount multiple volumes)
docker run -i --rm \
  -v /path/to/dir1:/workspace1:ro \
  -v /path/to/dir2:/workspace2:ro \
  mcp-filesystem-smart /workspace1 /workspace2

LLM Usage Patterns

Pattern 1: Find Type Declaration (Unknown Kind)

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

search_code({
  pattern: "\\b(class|struct|record|interface|enum)\\s+MyType\\b",
  filePattern: "*.cs"
})

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

// Find any type
"\\b(class|struct|record|interface|enum)\\s+TypeName\\b"

// Find method
"\\b(public|private|protected|internal).*\\s+MethodName\\s*\\("

// Find async methods
"async\\s+(Task|ValueTask)<.*>\\s+\\w+\\s*\\("

TypeScript / JavaScript

// Find function/method
"(function|const|let|var)\\s+\\w+\\s*=.*=>|function\\s+\\w+\\s*\\("

// Find class/interface
"(class|interface)\\s+\\w+"

// Find async functions
"async\\s+(function|\\w+\\s*=>|\\(.*\\)\\s*=>)"

Python

// Find class
"class\\s+\\w+.*:"

// Find function
"def\\s+\\w+\\s*\\("

// Find async function
"async\\s+def\\s+\\w+"

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

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Test locally
node dist/index.js $(pwd)

License

MIT

Credits

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