fastmcp.server.providers.filesystem_discovery

File discovery and module import utilities for filesystem-based routing.

This module provides functions to:

1. Discover Python files in a directory tree
2. Import modules (as packages if init.py exists, else directly)
3. Extract decorated components (Tool, Resource, Prompt objects) from imported modules

Functions

discover_files ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/filesystem_discovery.py#L34" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

discover_files(root: Path) -> list[Path]

Recursively discover all Python files under a directory.

Excludes init.py files (they're for package structure, not components).

Args:

• root: Root directory to scan.

Returns:

• List of .py file paths, sorted for deterministic order.

import_module_from_file ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/filesystem_discovery.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

import_module_from_file(file_path: Path, provider_root: Path | None = None) -> ModuleType

Import a Python file as a module.

If the file is part of a package (directory has init.py), imports it as a proper package member (relative imports work). Otherwise, imports directly using spec_from_file_location.

sys.path is modified only for the duration of the import and restored immediately after, so no permanent pollution occurs.

Args:

• file_path: Path to the Python file.
• provider_root: The provider's root directory. Prevents package root discovery from walking above this boundary into ancestor packages.

Returns:

• The imported module.

Raises:

• ImportError: If the module cannot be imported.

extract_components ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/filesystem_discovery.py#L235" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

extract_components(module: ModuleType) -> list[FastMCPComponent]

Extract all MCP components from a module.

Scans all module attributes for instances of Tool, Resource, ResourceTemplate, or Prompt objects created by standalone decorators, or functions decorated with @tool/@resource/@prompt that have fastmcp metadata.

Args:

• module: The imported module to scan.

Returns:

• List of component objects (Tool, Resource, ResourceTemplate, Prompt).

discover_and_import ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/filesystem_discovery.py#L359" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

discover_and_import(root: Path) -> DiscoveryResult

Discover files, import modules, and extract components.

This is the main entry point for filesystem-based discovery.

Args:

• root: Root directory to scan.

Returns:

• DiscoveryResult with components and any failed files.

Classes

DiscoveryResult ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/providers/filesystem_discovery.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Result of filesystem discovery.