fastmcp 2.14.4__py3-none-any.whl → 3.0.0b1__py3-none-any.whl

fastmcp/server/providers/filesystem.py

@@ -0,0 +1,226 @@
+"""FileSystemProvider for filesystem-based component discovery.
+
+FileSystemProvider scans a directory for Python files, imports them, and
+registers any Tool, Resource, ResourceTemplate, or Prompt objects found.
+
+Components are created using the standalone decorators from fastmcp.tools,
+fastmcp.resources, and fastmcp.prompts:
+
+Example:
+    ```python
+    # In mcp/tools.py
+    from fastmcp.tools import tool
+
+    @tool
+    def greet(name: str) -> str:
+        return f"Hello, {name}!"
+
+    # In main.py
+    from pathlib import Path
+
+    from fastmcp import FastMCP
+    from fastmcp.server.providers import FileSystemProvider
+
+    mcp = FastMCP("MyServer", providers=[FileSystemProvider(Path(__file__).parent / "mcp")])
+    ```
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+from pathlib import Path
+
+from fastmcp.prompts.prompt import Prompt
+from fastmcp.resources.resource import Resource
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.providers.filesystem_discovery import discover_and_import
+from fastmcp.server.providers.local_provider import LocalProvider
+from fastmcp.tools.tool import Tool
+from fastmcp.utilities.components import FastMCPComponent
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.versions import VersionSpec
+
+logger = get_logger(__name__)
+
+
+class FileSystemProvider(LocalProvider):
+    """Provider that discovers components from the filesystem.
+
+    Scans a directory for Python files and registers any Tool, Resource,
+    ResourceTemplate, or Prompt objects found. Components are created using
+    the standalone decorators:
+    - @tool from fastmcp.tools
+    - @resource from fastmcp.resources
+    - @prompt from fastmcp.prompts
+
+    Args:
+        root: Root directory to scan. Defaults to current directory.
+        reload: If True, re-scan files on every request (dev mode).
+            Defaults to False (scan once at init, cache results).
+
+    Example:
+        ```python
+        # In mcp/tools.py
+        from fastmcp.tools import tool
+
+        @tool
+        def greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        # In main.py
+        from pathlib import Path
+
+        from fastmcp import FastMCP
+        from fastmcp.server.providers import FileSystemProvider
+
+        # Path relative to this file
+        mcp = FastMCP("MyServer", providers=[FileSystemProvider(Path(__file__).parent / "mcp")])
+
+        # Dev mode - re-scan on every request
+        mcp = FastMCP("MyServer", providers=[FileSystemProvider(Path(__file__).parent / "mcp", reload=True)])
+        ```
+    """
+
+    def __init__(
+        self,
+        root: str | Path = ".",
+        reload: bool = False,
+    ) -> None:
+        super().__init__(on_duplicate="replace")
+        self._root = Path(root).resolve()
+        self._reload = reload
+        self._loaded = False
+        # Track files we've warned about: path -> mtime when warned
+        # Re-warn if file changes (mtime differs)
+        self._warned_files: dict[Path, float] = {}
+        # Lock for serializing reload operations (created lazily)
+        self._reload_lock: asyncio.Lock | None = None
+
+        # Always load once at init to catch errors early
+        self._load_components()
+
+    def _load_components(self) -> None:
+        """Discover and register all components from the filesystem."""
+        # Clear existing components if reloading
+        if self._loaded:
+            self._components.clear()
+
+        result = discover_and_import(self._root)
+
+        # Log warnings for failed files (only once per file version)
+        for file_path, error in result.failed_files.items():
+            try:
+                current_mtime = file_path.stat().st_mtime
+            except OSError:
+                current_mtime = 0.0
+
+            # Warn if we haven't warned about this file, or if it changed
+            last_warned_mtime = self._warned_files.get(file_path)
+            if last_warned_mtime is None or last_warned_mtime != current_mtime:
+                logger.warning(f"Failed to import {file_path}: {error}")
+                self._warned_files[file_path] = current_mtime
+
+        # Clear warnings for files that now import successfully
+        successful_files = {fp for fp, _ in result.components}
+        for fp in successful_files:
+            self._warned_files.pop(fp, None)
+
+        for file_path, component in result.components:
+            try:
+                self._register_component(component)
+            except Exception:
+                logger.exception(
+                    "Failed to register %s from %s",
+                    getattr(component, "name", repr(component)),
+                    file_path,
+                )
+
+        self._loaded = True
+        logger.debug(
+            f"FileSystemProvider loaded {len(self._components)} components from {self._root}"
+        )
+
+    def _register_component(self, component: FastMCPComponent) -> None:
+        """Register a single component based on its type."""
+        if isinstance(component, Tool):
+            self.add_tool(component)
+        elif isinstance(component, ResourceTemplate):
+            self.add_template(component)
+        elif isinstance(component, Resource):
+            self.add_resource(component)
+        elif isinstance(component, Prompt):
+            self.add_prompt(component)
+        else:
+            logger.debug("Ignoring unknown component type: %r", type(component))
+
+    async def _ensure_loaded(self) -> None:
+        """Ensure components are loaded, reloading if in reload mode.
+
+        Uses a lock to serialize concurrent reload operations and runs
+        filesystem I/O off the event loop using asyncio.to_thread.
+        """
+        if not self._reload and self._loaded:
+            return
+
+        # Create lock lazily (can't create in __init__ without event loop)
+        if self._reload_lock is None:
+            self._reload_lock = asyncio.Lock()
+
+        async with self._reload_lock:
+            # Double-check after acquiring lock
+            if self._reload or not self._loaded:
+                await asyncio.to_thread(self._load_components)
+
+    # Override provider methods to support reload mode
+
+    async def _list_tools(self) -> Sequence[Tool]:
+        """Return all tools, reloading if in reload mode."""
+        await self._ensure_loaded()
+        return await super()._list_tools()
+
+    async def _get_tool(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get a tool by name, reloading if in reload mode."""
+        await self._ensure_loaded()
+        return await super()._get_tool(name, version)
+
+    async def _list_resources(self) -> Sequence[Resource]:
+        """Return all resources, reloading if in reload mode."""
+        await self._ensure_loaded()
+        return await super()._list_resources()
+
+    async def _get_resource(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> Resource | None:
+        """Get a resource by URI, reloading if in reload mode."""
+        await self._ensure_loaded()
+        return await super()._get_resource(uri, version)
+
+    async def _list_resource_templates(self) -> Sequence[ResourceTemplate]:
+        """Return all resource templates, reloading if in reload mode."""
+        await self._ensure_loaded()
+        return await super()._list_resource_templates()
+
+    async def _get_resource_template(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> ResourceTemplate | None:
+        """Get a resource template, reloading if in reload mode."""
+        await self._ensure_loaded()
+        return await super()._get_resource_template(uri, version)
+
+    async def _list_prompts(self) -> Sequence[Prompt]:
+        """Return all prompts, reloading if in reload mode."""
+        await self._ensure_loaded()
+        return await super()._list_prompts()
+
+    async def _get_prompt(
+        self, name: str, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        """Get a prompt by name, reloading if in reload mode."""
+        await self._ensure_loaded()
+        return await super()._get_prompt(name, version)
+
+    def __repr__(self) -> str:
+        return f"FileSystemProvider(root={self._root!r}, reload={self._reload})"

fastmcp/server/providers/filesystem_discovery.py

@@ -0,0 +1,327 @@
+"""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
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import ModuleType
+
+from fastmcp.utilities.components import FastMCPComponent
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class DiscoveryResult:
+    """Result of filesystem discovery."""
+
+    # Components are real objects (Tool, Resource, ResourceTemplate, Prompt)
+    components: list[tuple[Path, FastMCPComponent]] = field(default_factory=list)
+    failed_files: dict[Path, str] = field(default_factory=dict)  # path -> error message
+
+
+def 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.
+    """
+    if not root.exists():
+        return []
+
+    if not root.is_dir():
+        # If root is a file, just return it (if it's a .py file)
+        if root.suffix == ".py" and root.name != "__init__.py":
+            return [root]
+        return []
+
+    files: list[Path] = []
+    for path in root.rglob("*.py"):
+        # Skip __init__.py files
+        if path.name == "__init__.py":
+            continue
+        # Skip __pycache__ directories
+        if "__pycache__" in path.parts:
+            continue
+        files.append(path)
+
+    # Sort for deterministic discovery order
+    return sorted(files)
+
+
+def _is_package_dir(directory: Path) -> bool:
+    """Check if a directory is a Python package (has __init__.py)."""
+    return (directory / "__init__.py").exists()
+
+
+def _find_package_root(file_path: Path) -> Path | None:
+    """Find the root of the package containing this file.
+
+    Walks up the directory tree until we find a directory without __init__.py.
+
+    Returns:
+        The package root directory, or None if not in a package.
+    """
+    current = file_path.parent
+    package_root = None
+
+    while current != current.parent:  # Stop at filesystem root
+        if _is_package_dir(current):
+            package_root = current
+            current = current.parent
+        else:
+            break
+
+    return package_root
+
+
+def _compute_module_name(file_path: Path, package_root: Path) -> str:
+    """Compute the dotted module name for a file within a package.
+
+    Args:
+        file_path: Path to the Python file.
+        package_root: Root directory of the package.
+
+    Returns:
+        Dotted module name (e.g., "mcp.tools.greet").
+    """
+    relative = file_path.relative_to(package_root.parent)
+    parts = list(relative.parts)
+    # Remove .py extension from last part
+    parts[-1] = parts[-1].removesuffix(".py")
+    return ".".join(parts)
+
+
+def import_module_from_file(file_path: Path) -> 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.
+
+    Args:
+        file_path: Path to the Python file.
+
+    Returns:
+        The imported module.
+
+    Raises:
+        ImportError: If the module cannot be imported.
+    """
+    file_path = file_path.resolve()
+
+    # Check if this file is part of a package
+    package_root = _find_package_root(file_path)
+
+    if package_root is not None:
+        # Import as part of a package
+        module_name = _compute_module_name(file_path, package_root)
+
+        # Ensure package root's parent is in sys.path
+        package_parent = str(package_root.parent)
+        if package_parent not in sys.path:
+            sys.path.insert(0, package_parent)
+
+        # Import using standard import machinery
+        # If already imported, reload to pick up changes (for reload mode)
+        try:
+            if module_name in sys.modules:
+                return importlib.reload(sys.modules[module_name])
+            return importlib.import_module(module_name)
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to import {module_name} from {file_path}: {e}"
+            ) from e
+    else:
+        # Import directly using spec_from_file_location
+        module_name = file_path.stem
+
+        # Ensure parent directory is in sys.path for imports
+        parent_dir = str(file_path.parent)
+        if parent_dir not in sys.path:
+            sys.path.insert(0, parent_dir)
+
+        spec = importlib.util.spec_from_file_location(module_name, file_path)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Cannot load spec for {file_path}")
+
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+
+        try:
+            spec.loader.exec_module(module)
+        except Exception as e:
+            # Clean up sys.modules on failure
+            sys.modules.pop(module_name, None)
+            raise ImportError(f"Failed to execute module {file_path}: {e}") from e
+
+        return module
+
+
+def 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).
+    """
+    # Import here to avoid circular imports
+    import inspect
+
+    from fastmcp.decorators import get_fastmcp_meta
+    from fastmcp.prompts.function_prompt import PromptMeta
+    from fastmcp.prompts.prompt import Prompt
+    from fastmcp.resources.function_resource import ResourceMeta
+    from fastmcp.resources.resource import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.server.dependencies import without_injected_parameters
+    from fastmcp.tools.function_tool import ToolMeta
+    from fastmcp.tools.tool import Tool
+
+    component_types = (Tool, Resource, ResourceTemplate, Prompt)
+    components: list[FastMCPComponent] = []
+
+    for name in dir(module):
+        # Skip private/magic attributes
+        if name.startswith("_"):
+            continue
+
+        try:
+            obj = getattr(module, name)
+        except AttributeError:
+            continue
+
+        # Check if this object is a component type
+        if isinstance(obj, component_types):
+            components.append(obj)
+            continue
+
+        # Check for functions with __fastmcp__ metadata
+        meta = get_fastmcp_meta(obj)
+        if meta is not None:
+            if isinstance(meta, ToolMeta):
+                resolved_task = meta.task if meta.task is not None else False
+                tool = Tool.from_function(
+                    obj,
+                    name=meta.name,
+                    title=meta.title,
+                    description=meta.description,
+                    icons=meta.icons,
+                    tags=meta.tags,
+                    output_schema=meta.output_schema,
+                    annotations=meta.annotations,
+                    meta=meta.meta,
+                    task=resolved_task,
+                    exclude_args=meta.exclude_args,
+                    serializer=meta.serializer,
+                    auth=meta.auth,
+                )
+                components.append(tool)
+            elif isinstance(meta, ResourceMeta):
+                resolved_task = meta.task if meta.task is not None else False
+                has_uri_params = "{" in meta.uri and "}" in meta.uri
+                wrapper_fn = without_injected_parameters(obj)
+                has_func_params = bool(inspect.signature(wrapper_fn).parameters)
+
+                if has_uri_params or has_func_params:
+                    resource = ResourceTemplate.from_function(
+                        fn=obj,
+                        uri_template=meta.uri,
+                        name=meta.name,
+                        title=meta.title,
+                        description=meta.description,
+                        icons=meta.icons,
+                        mime_type=meta.mime_type,
+                        tags=meta.tags,
+                        annotations=meta.annotations,
+                        meta=meta.meta,
+                        task=resolved_task,
+                        auth=meta.auth,
+                    )
+                else:
+                    resource = Resource.from_function(
+                        fn=obj,
+                        uri=meta.uri,
+                        name=meta.name,
+                        title=meta.title,
+                        description=meta.description,
+                        icons=meta.icons,
+                        mime_type=meta.mime_type,
+                        tags=meta.tags,
+                        annotations=meta.annotations,
+                        meta=meta.meta,
+                        task=resolved_task,
+                        auth=meta.auth,
+                    )
+                components.append(resource)
+            elif isinstance(meta, PromptMeta):
+                resolved_task = meta.task if meta.task is not None else False
+                prompt = Prompt.from_function(
+                    obj,
+                    name=meta.name,
+                    title=meta.title,
+                    description=meta.description,
+                    icons=meta.icons,
+                    tags=meta.tags,
+                    meta=meta.meta,
+                    task=resolved_task,
+                    auth=meta.auth,
+                )
+                components.append(prompt)
+
+    return components
+
+
+def 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.
+
+    Note:
+        Files that fail to import are tracked in failed_files, not logged.
+        The caller is responsible for logging/handling failures.
+        Files with no components are silently skipped.
+    """
+    result = DiscoveryResult()
+
+    for file_path in discover_files(root):
+        try:
+            module = import_module_from_file(file_path)
+        except ImportError as e:
+            result.failed_files[file_path] = str(e)
+            continue
+        except Exception as e:
+            result.failed_files[file_path] = str(e)
+            continue
+
+        components = extract_components(module)
+        for component in components:
+            result.components.append((file_path, component))
+
+    return result

fastmcp/server/providers/local_provider/__init__.py

@@ -0,0 +1,11 @@
+"""LocalProvider for locally-defined MCP components.
+
+This module provides the `LocalProvider` class that manages tools, resources,
+templates, and prompts registered via decorators or direct methods.
+"""
+
+from fastmcp.server.providers.local_provider.local_provider import (
+    LocalProvider,
+)
+
+__all__ = ["LocalProvider"]

fastmcp/server/providers/local_provider/decorators/__init__.py

@@ -0,0 +1,15 @@
+"""Decorator mixins for LocalProvider.
+
+This module provides mixin classes that add decorator functionality
+to LocalProvider for tools, resources, templates, and prompts.
+"""
+
+from .prompts import PromptDecoratorMixin
+from .resources import ResourceDecoratorMixin
+from .tools import ToolDecoratorMixin
+
+__all__ = [
+    "PromptDecoratorMixin",
+    "ResourceDecoratorMixin",
+    "ToolDecoratorMixin",
+]