Struct FilesystemProvider 

pub struct FilesystemProvider { /* private fields */ }

A resource provider that exposes filesystem directories.

Files under the configured root directory are exposed as MCP resources with local file URIs like file:///{prefix}/{relative_path}.

Security

• Path traversal attempts (e.g., ../../../etc/passwd) are blocked
• Final and intermediate symlinks are always blocked
• Multi-link files are blocked because another name may exist outside the root
• Maximum file size limits prevent memory exhaustion
• Hidden files (starting with .) can be excluded

Example

use fastmcp_server::providers::FilesystemProvider;

let provider = FilesystemProvider::new("/app/data")
    .with_prefix("data")
    .with_patterns(&["*.json", "*.yaml"])
    .with_recursive(true);

Implementations

impl FilesystemProvider

pub fn new(root: impl AsRef<Path>) -> Self

Creates a new filesystem provider for the given root directory.

Arguments

• root - The root directory to expose

Example

let provider = FilesystemProvider::new("/data/docs");

pub fn with_prefix(self, prefix: impl Into<String>) -> Self

Sets the URI prefix for resources.

Files will have URIs like file:///{prefix}/{path}.

Example

let provider = FilesystemProvider::new("/data")
    .with_prefix("mydata");
// Results in URIs like file:///mydata/readme.md

pub fn with_patterns(self, patterns: &[&str]) -> Self

Sets glob patterns to include.

Only files matching at least one of these patterns will be exposed. Empty patterns means all files are included.

Example

let provider = FilesystemProvider::new("/data")
    .with_patterns(&["*.md", "*.txt", "**/*.json"]);

pub fn with_exclude(self, patterns: &[&str]) -> Self

Sets glob patterns to exclude.

Files matching any of these patterns will be excluded. By default, hidden files (starting with .) are excluded.

Example

let provider = FilesystemProvider::new("/data")
    .with_exclude(&["**/secret/**", "*.bak"]);

pub fn with_recursive(self, enabled: bool) -> Self

Enables or disables recursive directory traversal.

When enabled, files in subdirectories are also exposed.

Example

let provider = FilesystemProvider::new("/data")
    .with_recursive(true);

pub fn with_max_size(self, bytes: usize) -> Self

Sets the maximum file size in bytes.

Files larger than this limit will return an error when read. Default is 10 MB.

Example

let provider = FilesystemProvider::new("/data")
    .with_max_size(5 * 1024 * 1024); // 5 MB

pub fn with_max_entries(self, entries: usize) -> Self

Sets the maximum number of directory entries inspected by one listing.

pub fn with_max_depth(self, depth: usize) -> Self

Sets the maximum recursive directory depth beneath the provider root. The root itself has depth zero.

pub fn with_max_listing_bytes(self, bytes: usize) -> Self

Sets the maximum UTF-8 byte size of a generated directory listing.

pub fn with_description(self, description: impl Into<String>) -> Self

Sets the description for the resource template.

Example

let provider = FilesystemProvider::new("/data")
    .with_description("Documentation files");

pub fn build(self) -> Result<FilesystemResourceHandler, FilesystemProviderError>

Validates this provider and constructs a production handler.

Linux and macOS acquire a handle-relative directory capability and return a handler. Listing and reads run on the caller-owned asupersync blocking pool when one is installed. Other targets remain fail-closed.

Errors

Returns configuration errors, root-acquisition failures, or FilesystemProviderError::FeatureUnavailable on unqualified targets.

Trait Implementations

impl Clone for FilesystemProvider

fn clone(&self) -> FilesystemProvider

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FilesystemProvider

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.