MCP Smart Filesystem Server

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

• 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

• 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

• Strict directory access control
• Symlink attack prevention
• Path traversal protection
• Only accesses files within allowed directories

• Helpful suggestions in responses
• Examples for common search patterns
• Reading strategy recommendations for large files
• Clear error messages with actionable guidance

List directory contents with metadata.

{
  "path": "src"
}

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

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.

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

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

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

Find files by name pattern.

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

Pattern examples:

• config.json - Exact name
• *.config - Wildcard
• *Service* - Contains "Service"
• *.{ts,tsx,js} - Multiple extensions

Get file metadata without reading contents.

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

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

Show accessible directories (security boundaries).

{}

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

Customize behavior with environment variables:

docker run -i --rm \
  -e MCP_LINES_PER_PAGE=1000 \
  -e MCP_MAX_SEARCH_RESULTS=200 \
  -v /path/to/your/project:/workspace:ro \
  mcp-filesystem-smart

Available Variables:

• MCP_LINES_PER_PAGE - Lines per page when reading files (default: 500)
• MCP_MAX_SEARCH_RESULTS - Search results per page (default: 100)

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

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

# 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

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"
})

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)

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

1. Find files: find_files(pattern="*Service*.ts")
2. Search within results: search_code(pattern="constructor", path="src/services")

// 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*\\("

// 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*=>)"

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

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

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

• 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

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

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

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

MIT

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