3.0.0
FileSystemProvider scans a directory for Python files and automatically registers functions decorated with @tool, @resource, or @prompt. This enables a file-based organization pattern similar to Next.js routing, where your project structure becomes your component registry.
Why Filesystem Discovery
Traditional FastMCP servers require coordination between files. Either your tool files import the server to call@server.tool(), or your server file imports all the tool modules. Both approaches create coupling that some developers prefer to avoid.
FileSystemProvider eliminates this coordination. Each file is self-contained—it uses standalone decorators (@tool, @resource, @prompt) that don’t require access to a server instance. The provider discovers these files at startup, so you can add new tools without modifying your server file.
This is a convention some teams prefer, not necessarily better for all projects. The tradeoffs:
- No coordination: Files don’t import the server; server doesn’t import files
- Predictable naming: Function names become component names (unless overridden)
- Development mode: Optionally re-scan files on every request for rapid iteration
Quick Start
Create a provider pointing to your components directory, then pass it to your server. UsePath(__file__).parent to make the path relative to your server file.
components/ directory, create Python files with decorated functions.
FileSystemProvider scans the directory, imports all Python files, and registers any decorated functions it finds.
Decorators
FastMCP provides standalone decorators that mark functions for discovery:@tool from fastmcp.tools, @resource from fastmcp.resources, and @prompt from fastmcp.prompts. These support the full syntax of server-bound decorators—all the same parameters work identically.
@tool
Mark a function as a tool. The function name becomes the tool name by default.name, title, description, icons, tags, output_schema, annotations, meta, version, timeout, auth, task, and run_in_thread.
@resource
Mark a function as a resource. Unlike@tool, the @resource decorator requires a URI argument.
{parameters} or the function has arguments.
uri (required), name, title, description, icons, mime_type, tags, annotations, meta, version, auth, and security.
@prompt
Mark a function as a prompt template.name, title, description, icons, tags, meta, version, and auth.
Directory Structure
The directory structure is purely organizational. The provider recursively scans all.py files regardless of which subdirectory they’re in. Subdirectories like tools/, resources/, and prompts/ are optional conventions that help you organize code.
Discovery Rules
The provider follows these rules when scanning:Package Imports
If your directory contains an__init__.py file, the provider imports files as proper Python package members. This means relative imports work correctly within your components directory.
__init__.py, files are imported directly using importlib.util.spec_from_file_location.
Reload Mode
During development, you may want changes to component files to take effect without restarting the server. Enable reload mode to re-scan the directory on every request.reload=True, the provider:
- Re-discovers all Python files on each request
- Re-imports every discovered module
- Updates the component registry with any new, modified, or removed components
Error Handling
When a file fails to import or construct its components (syntax error, missing dependency, unsupported tool signature, etc.), the provider logs a warning, skips that file, and continues scanning other files. Components from other files remain available at startup and during reloads.provider.failed_files for a snapshot of failures from the most recent load, including component registration errors. Each entry maps a file path to its error message. You can use this to enforce a stricter startup policy without importing the files again.
Example Project
A complete example is available in the repository atexamples/filesystem-provider/. The structure demonstrates the recommended organization.
fastmcp run examples/filesystem-provider/server.py or inspect with fastmcp inspect examples/filesystem-provider/server.py.