fastmcp 2.12.3__py3-none-any.whl → 2.12.5__py3-none-any.whl

fastmcp/utilities/logging.py

@@ -1,11 +1,14 @@
 """Logging utilities for FastMCP."""
 
+import contextlib
 import logging
-from typing import Any, Literal
+from typing import Any, Literal, cast
 
 from rich.console import Console
 from rich.logging import RichHandler
 
+import fastmcp
+
 
 def get_logger(name: str) -> logging.Logger:
     """Get a logger nested under FastMCP namespace.
@@ -16,13 +19,13 @@ def get_logger(name: str) -> logging.Logger:
     Returns:
         a configured logger instance
     """
-    return logging.getLogger(f"FastMCP.{name}")
+    return logging.getLogger(f"fastmcp.{name}")
 
 
 def configure_logging(
     level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | int = "INFO",
     logger: logging.Logger | None = None,
-    enable_rich_tracebacks: bool = True,
+    enable_rich_tracebacks: bool | None = None,
     **rich_kwargs: Any,
 ) -> None:
     """
@@ -33,9 +36,16 @@ def configure_logging(
         level: the log level to use
         rich_kwargs: the parameters to use for creating RichHandler
     """
+    # Check if logging is disabled in settings
+    if not fastmcp.settings.log_enabled:
+        return
+
+    # Use settings default if not specified
+    if enable_rich_tracebacks is None:
+        enable_rich_tracebacks = fastmcp.settings.enable_rich_tracebacks
 
     if logger is None:
-        logger = logging.getLogger("FastMCP")
+        logger = logging.getLogger("fastmcp")
 
     # Only configure the FastMCP logger namespace
     handler = RichHandler(
@@ -56,3 +66,55 @@ def configure_logging(
 
     # Don't propagate to the root logger
     logger.propagate = False
+
+
+@contextlib.contextmanager
+def temporary_log_level(
+    level: str | None,
+    logger: logging.Logger | None = None,
+    enable_rich_tracebacks: bool | None = None,
+    **rich_kwargs: Any,
+):
+    """Context manager to temporarily set log level and restore it afterwards.
+
+    Args:
+        level: The temporary log level to set (e.g., "DEBUG", "INFO")
+        logger: Optional logger to configure (defaults to FastMCP logger)
+        enable_rich_tracebacks: Whether to enable rich tracebacks
+        **rich_kwargs: Additional parameters for RichHandler
+
+    Usage:
+        with temporary_log_level("DEBUG"):
+            # Code that runs with DEBUG logging
+            pass
+        # Original log level is restored here
+    """
+    if level:
+        # Get the original log level from settings
+        original_level = fastmcp.settings.log_level
+
+        # Configure with new level
+        # Cast to proper type for type checker
+        log_level_literal = cast(
+            Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+            level.upper(),
+        )
+        configure_logging(
+            level=log_level_literal,
+            logger=logger,
+            enable_rich_tracebacks=enable_rich_tracebacks,
+            **rich_kwargs,
+        )
+        try:
+            yield
+        finally:
+            # Restore original configuration using configure_logging
+            # This will respect the log_enabled setting
+            configure_logging(
+                level=original_level,
+                logger=logger,
+                enable_rich_tracebacks=enable_rich_tracebacks,
+                **rich_kwargs,
+            )
+    else:
+        yield

fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py

@@ -403,7 +403,8 @@ class MCPServerConfig(BaseModel):
                 run_args["port"] = self.deployment.port
             if self.deployment.path:
                 run_args["path"] = self.deployment.path
-            # Note: log_level not currently supported by run_async
+            if self.deployment.log_level:
+                run_args["log_level"] = self.deployment.log_level
 
         # Override with any provided kwargs
         run_args.update(kwargs)

fastmcp/utilities/storage.py

@@ -0,0 +1,204 @@
+"""Key-value storage utilities for persistent data management."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Protocol
+
+import pydantic_core
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class KVStorage(Protocol):
+    """Protocol for key-value storage of JSON data."""
+
+    async def get(self, key: str) -> dict[str, Any] | None:
+        """Get a JSON dict by key."""
+        ...
+
+    async def set(self, key: str, value: dict[str, Any]) -> None:
+        """Store a JSON dict by key."""
+        ...
+
+    async def delete(self, key: str) -> None:
+        """Delete a value by key."""
+        ...
+
+
+class JSONFileStorage:
+    """File-based key-value storage for JSON data with automatic metadata tracking.
+
+    Each key-value pair is stored as a separate JSON file on disk.
+    Keys are sanitized to be filesystem-safe.
+
+    The storage automatically wraps all data with metadata:
+    - timestamp: Timestamp when the entry was last written
+
+    Args:
+        cache_dir: Directory for storing JSON files
+    """
+
+    def __init__(self, cache_dir: Path):
+        """Initialize JSON file storage."""
+        self.cache_dir = cache_dir
+        self.cache_dir.mkdir(exist_ok=True, parents=True)
+
+    def _get_safe_key(self, key: str) -> str:
+        """Convert key to filesystem-safe string."""
+        safe_key = key
+
+        # Replace problematic characters with underscores
+        for char in [".", "/", "\\", ":", "*", "?", '"', "<", ">", "|", " "]:
+            safe_key = safe_key.replace(char, "_")
+
+        # Compress multiple underscores into one
+        while "__" in safe_key:
+            safe_key = safe_key.replace("__", "_")
+
+        # Strip leading and trailing underscores
+        safe_key = safe_key.strip("_")
+
+        return safe_key
+
+    def _get_file_path(self, key: str) -> Path:
+        """Get the file path for a given key."""
+        safe_key = self._get_safe_key(key)
+        return self.cache_dir / f"{safe_key}.json"
+
+    async def get(self, key: str) -> dict[str, Any] | None:
+        """Get a JSON dict from storage by key.
+
+        Args:
+            key: The key to retrieve
+
+        Returns:
+            The stored dict or None if not found
+        """
+        path = self._get_file_path(key)
+        try:
+            wrapper = json.loads(path.read_text())
+
+            # Expect wrapped format with metadata
+            if not isinstance(wrapper, dict) or "data" not in wrapper:
+                logger.warning(f"Invalid storage format for key '{key}'")
+                return None
+
+            logger.debug(f"Loaded data for key '{key}'")
+            return wrapper["data"]
+
+        except FileNotFoundError:
+            logger.debug(f"No data found for key '{key}'")
+            return None
+        except json.JSONDecodeError as e:
+            logger.warning(f"Failed to load data for key '{key}': {e}")
+            return None
+
+    async def set(self, key: str, value: dict[str, Any]) -> None:
+        """Store a JSON dict with metadata.
+
+        Args:
+            key: The key to store under
+            value: The dict to store
+        """
+        import time
+
+        path = self._get_file_path(key)
+        current_time = time.time()
+
+        # Create wrapper with metadata
+        wrapper = {
+            "data": value,
+            "timestamp": current_time,
+        }
+
+        # Use pydantic_core for consistent JSON serialization
+        json_data = pydantic_core.to_json(wrapper, fallback=str)
+        path.write_bytes(json_data)
+        logger.debug(f"Saved data for key '{key}'")
+
+    async def delete(self, key: str) -> None:
+        """Delete a value from storage.
+
+        Args:
+            key: The key to delete
+        """
+        path = self._get_file_path(key)
+        if path.exists():
+            path.unlink()
+            logger.debug(f"Deleted data for key '{key}'")
+
+    async def cleanup_old_entries(
+        self,
+        max_age_seconds: int = 30 * 24 * 60 * 60,  # 30 days default
+    ) -> int:
+        """Remove entries older than the specified age.
+
+        Uses the timestamp field to determine age.
+
+        Args:
+            max_age_seconds: Maximum age in seconds (default 30 days)
+
+        Returns:
+            Number of entries removed
+        """
+        import time
+
+        current_time = time.time()
+        removed_count = 0
+
+        for json_file in self.cache_dir.glob("*.json"):
+            try:
+                # Read the file and check timestamp
+                wrapper = json.loads(json_file.read_text())
+
+                # Check wrapped format
+                if not isinstance(wrapper, dict) or "data" not in wrapper:
+                    continue  # Invalid format, skip
+
+                if "timestamp" not in wrapper:
+                    continue  # No timestamp field, skip
+
+                entry_age = current_time - wrapper["timestamp"]
+                if entry_age > max_age_seconds:
+                    json_file.unlink()
+                    removed_count += 1
+                    logger.debug(
+                        f"Removed old entry '{json_file.stem}' (age: {entry_age:.0f}s)"
+                    )
+
+            except (json.JSONDecodeError, KeyError) as e:
+                logger.debug(f"Error reading {json_file.name}: {e}")
+                continue
+
+        if removed_count > 0:
+            logger.info(f"Cleaned up {removed_count} old entries from storage")
+
+        return removed_count
+
+
+class InMemoryStorage:
+    """In-memory key-value storage for JSON data.
+
+    Simple dict-based storage that doesn't persist across restarts.
+    Useful for testing or environments where file storage isn't available.
+    """
+
+    def __init__(self):
+        """Initialize in-memory storage."""
+        self._data: dict[str, dict[str, Any]] = {}
+
+    async def get(self, key: str) -> dict[str, Any] | None:
+        """Get a JSON dict from memory by key."""
+        return self._data.get(key)
+
+    async def set(self, key: str, value: dict[str, Any]) -> None:
+        """Store a JSON dict in memory."""
+        self._data[key] = value
+
+    async def delete(self, key: str) -> None:
+        """Delete a value from memory."""
+        self._data.pop(key, None)

fastmcp/utilities/tests.py

@@ -109,7 +109,7 @@ def run_server_in_process(
     proc.start()
 
     # Wait for server to be running
-    max_attempts = 10
+    max_attempts = 30
     attempt = 0
     while attempt < max_attempts and proc.is_alive():
         try:
@@ -117,10 +117,12 @@ def run_server_in_process(
                 s.connect((host, port))
                 break
         except ConnectionRefusedError:
-            if attempt < 3:
-                time.sleep(0.01)
-            else:
+            if attempt < 5:
+                time.sleep(0.05)
+            elif attempt < 15:
                 time.sleep(0.1)
+            else:
+                time.sleep(0.2)
             attempt += 1
     else:
         raise RuntimeError(f"Server failed to start after {max_attempts} attempts")
@@ -141,10 +143,10 @@ def run_server_in_process(
 def caplog_for_fastmcp(caplog):
     """Context manager to capture logs from FastMCP loggers even when propagation is disabled."""
     caplog.clear()
-    logger = logging.getLogger("FastMCP")
+    logger = logging.getLogger("fastmcp")
     logger.addHandler(caplog.handler)
     try:
-        yield
+        yield caplog
     finally:
         logger.removeHandler(caplog.handler)
 

{fastmcp-2.12.3.dist-info → fastmcp-2.12.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.12.3
+Version: 2.12.5
 Summary: The fast, Pythonic way to build MCP servers and clients.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp
@@ -21,7 +21,7 @@ Requires-Dist: authlib>=1.5.2
 Requires-Dist: cyclopts>=3.0.0
 Requires-Dist: exceptiongroup>=1.2.2
 Requires-Dist: httpx>=0.28.1
-Requires-Dist: mcp<2.0.0,>=1.12.4
+Requires-Dist: mcp<1.17.0,>=1.12.4
 Requires-Dist: openapi-core>=0.19.5
 Requires-Dist: openapi-pydantic>=0.5.1
 Requires-Dist: pydantic[email]>=2.11.7
@@ -37,6 +37,13 @@ Description-Content-Type: text/markdown
 <div align="center">
 
 <!-- omit in toc -->
+
+<picture>
+  <source width="550" media="(prefers-color-scheme: dark)" srcset="docs/assets/brand/wordmark-watercolor-waves-dark.png">
+  <source width="550" media="(prefers-color-scheme: light)" srcset="docs/assets/brand/wordmark-watercolor-waves.png">
+  <img width="550" alt="FastMCP Logo" src="docs/assets/brand/wordmark-watercolor-waves.png">
+</picture>
+
 # FastMCP v2 🚀
 
 <strong>The fast, Pythonic way to build MCP servers and clients.</strong>
@@ -53,19 +60,19 @@ Description-Content-Type: text/markdown
 
 > [!Note]
 >
-> #### Beyond the Protocol
->
-> FastMCP is the standard framework for working with the Model Context Protocol. FastMCP 1.0 was incorporated into the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) in 2024.
+> #### FastMCP 2.0: The Standard Framework
 >
-> This is FastMCP 2.0, the **actively maintained version** that provides a complete toolkit for working with the MCP ecosystem.
+> FastMCP pioneered Python MCP development, and FastMCP 1.0 was incorporated into the [official MCP SDK](https://github.com/modelcontextprotocol/python-sdk) in 2024.
 >
-> FastMCP 2.0 has a comprehensive set of features that go far beyond the core MCP specification, all in service of providing **the simplest path to production**. These include deployment, auth, clients, server proxying and composition, generating servers from REST APIs, dynamic tool rewriting, built-in testing tools, integrations, and more.
+> **This is FastMCP 2.0** — the actively maintained, production-ready framework that extends far beyond basic protocol implementation. While the SDK provides core functionality, FastMCP 2.0 delivers everything needed for production: advanced MCP patterns (server composition, proxying, OpenAPI/FastAPI generation, tool transformation), enterprise auth (Google, GitHub, WorkOS, Azure, Auth0, and more), deployment tools, testing utilities, and comprehensive client libraries.
 >
-> Ready to upgrade or get started? Follow the [installation instructions](https://gofastmcp.com/getting-started/installation), which include steps for upgrading from the official MCP SDK.
+> **For production MCP applications, install FastMCP:** `pip install fastmcp`
 
 ---
 
-The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is a new, standardized way to provide context and tools to your LLMs, and FastMCP makes building MCP servers and clients simple and intuitive. Create tools, expose resources, define prompts, and connect components with clean, Pythonic code.
+**FastMCP is the standard framework for building MCP applications**, providing the fastest path from idea to production.
+
+The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is a standardized way to provide context and tools to LLMs. FastMCP makes building production-ready MCP servers simple, with enterprise auth, deployment tools, and a complete ecosystem built in.
 
 ```python
 # server.py
@@ -104,28 +111,33 @@ There are two ways to access the LLM-friendly documentation:
 <!-- omit in toc -->
 ## Table of Contents
 
-- [What is MCP?](#what-is-mcp)
-- [Why FastMCP?](#why-fastmcp)
-- [Installation](#installation)
-- [Core Concepts](#core-concepts)
-  - [The `FastMCP` Server](#the-fastmcp-server)
-  - [Tools](#tools)
-  - [Resources \& Templates](#resources--templates)
-  - [Prompts](#prompts)
-  - [Context](#context)
-  - [MCP Clients](#mcp-clients)
-- [Advanced Features](#advanced-features)
-  - [Proxy Servers](#proxy-servers)
-  - [Composing MCP Servers](#composing-mcp-servers)
-  - [OpenAPI \& FastAPI Generation](#openapi--fastapi-generation)
-  - [Authentication \& Security](#authentication--security)
-- [Running Your Server](#running-your-server)
-- [Contributing](#contributing)
-  - [Prerequisites](#prerequisites)
-  - [Setup](#setup)
-  - [Unit Tests](#unit-tests)
-  - [Static Checks](#static-checks)
-  - [Pull Requests](#pull-requests)
+- [FastMCP v2 🚀](#fastmcp-v2-)
+  - [📚 Documentation](#-documentation)
+  - [What is MCP?](#what-is-mcp)
+  - [Why FastMCP?](#why-fastmcp)
+  - [Installation](#installation)
+  - [Core Concepts](#core-concepts)
+    - [The `FastMCP` Server](#the-fastmcp-server)
+    - [Tools](#tools)
+    - [Resources \& Templates](#resources--templates)
+    - [Prompts](#prompts)
+    - [Context](#context)
+    - [MCP Clients](#mcp-clients)
+  - [Authentication](#authentication)
+    - [Enterprise Authentication, Zero Configuration](#enterprise-authentication-zero-configuration)
+  - [Deployment](#deployment)
+    - [From Development to Production](#from-development-to-production)
+  - [Advanced Features](#advanced-features)
+    - [Proxy Servers](#proxy-servers)
+    - [Composing MCP Servers](#composing-mcp-servers)
+    - [OpenAPI \& FastAPI Generation](#openapi--fastapi-generation)
+  - [Running Your Server](#running-your-server)
+  - [Contributing](#contributing)
+    - [Prerequisites](#prerequisites)
+    - [Setup](#setup)
+    - [Unit Tests](#unit-tests)
+    - [Static Checks](#static-checks)
+    - [Pull Requests](#pull-requests)
 
 ---
 
@@ -142,11 +154,7 @@ FastMCP provides a high-level, Pythonic interface for building, managing, and in
 
 ## Why FastMCP?
 
-The MCP protocol is powerful but implementing it involves a lot of boilerplate - server setup, protocol handlers, content types, error management. FastMCP handles all the complex protocol details and server management, so you can focus on building great tools. It's designed to be high-level and Pythonic; in most cases, decorating a function is all you need.
-
-FastMCP 2.0 has evolved into a comprehensive platform that goes far beyond basic protocol implementation. While 1.0 provided server-building capabilities (and is now part of the official MCP SDK), 2.0 offers a complete ecosystem including client libraries, authentication systems, deployment tools, integrations with major AI platforms, testing frameworks, and production-ready infrastructure patterns.
-
-FastMCP aims to be:
+FastMCP handles all the complex protocol details so you can focus on building. In most cases, decorating a Python function is all you need — FastMCP handles the rest.
 
 🚀 **Fast:** High-level interface means less code and faster development
 
@@ -154,7 +162,9 @@ FastMCP aims to be:
 
 🐍 **Pythonic:** Feels natural to Python developers
 
-🔍 **Complete:** A comprehensive platform for all MCP use cases, from dev to prod
+🔍 **Complete:** Everything for production — enterprise auth (Google, GitHub, Azure, Auth0, WorkOS), deployment tools, testing frameworks, client libraries, and more
+
+FastMCP provides the shortest path from idea to production. Deploy locally, to the cloud with [FastMCP Cloud](https://fastmcp.cloud), or to your own infrastructure.
 
 ## Installation
 
@@ -324,9 +334,82 @@ async def main():
 
 Learn more in the [**Client Documentation**](https://gofastmcp.com/clients/client) and [**Transports Documentation**](https://gofastmcp.com/clients/transports).
 
+## Authentication
+
+### Enterprise Authentication, Zero Configuration
+
+FastMCP provides comprehensive authentication support that sets it apart from basic MCP implementations. Secure your servers and authenticate your clients with the same enterprise-grade providers used by major corporations.
+
+**Built-in OAuth Providers:**
+
+- **Google**
+- **GitHub**
+- **Microsoft Azure**
+- **Auth0**
+- **WorkOS**
+- **Descope**
+- **JWT/Custom**
+- **API Keys**
+
+Protecting a server takes just two lines:
+
+```python
+from fastmcp.server.auth import GoogleProvider
+
+auth = GoogleProvider(client_id="...", client_secret="...", base_url="https://myserver.com")
+mcp = FastMCP("Protected Server", auth=auth)
+```
+
+Connecting to protected servers is even simpler:
+
+```python
+async with Client("https://protected-server.com/mcp", auth="oauth") as client:
+    # Automatic browser-based OAuth flow
+    result = await client.call_tool("protected_tool")
+```
+
+**Why FastMCP Auth Matters:**
+
+- **Production-Ready:** Persistent storage, token refresh, comprehensive error handling
+- **Zero-Config OAuth:** Just pass `auth="oauth"` for automatic setup
+- **Enterprise Integration:** WorkOS SSO, Azure Active Directory, Auth0 tenants
+- **Developer Experience:** Automatic browser launch, local callback server, environment variable support
+- **Advanced Architecture:** Full OIDC support, Dynamic Client Registration (DCR), and unique OAuth proxy pattern that enables DCR with any provider
+
+*Authentication this comprehensive is unique to FastMCP 2.0.*
+
+Learn more in the **Authentication Documentation** for [servers](https://gofastmcp.com/servers/auth) and [clients](https://gofastmcp.com/clients/auth).
+
+## Deployment
+
+### From Development to Production
+
+FastMCP supports every deployment scenario from local development to global scale:
+
+**Development:** Run locally with a single command
+
+```bash
+fastmcp run server.py
+```
+
+**Production:** Deploy to [**FastMCP Cloud**](https://fastmcp.cloud) — Remote MCP that just works
+
+- Instant HTTPS endpoints
+- Built-in authentication
+- Zero configuration
+- Free for personal servers
+
+**Self-Hosted:** Use HTTP or SSE transports for your own infrastructure
+
+```python
+mcp.run(transport="http", host="0.0.0.0", port=8000)
+```
+
+Learn more in the [**Deployment Documentation**](https://gofastmcp.com/deployment).
+
 ## Advanced Features
 
-FastMCP introduces powerful ways to structure and deploy your MCP applications.
+FastMCP introduces powerful ways to structure and compose your MCP applications.
 
 ### Proxy Servers
 
@@ -346,16 +429,6 @@ Automatically generate FastMCP servers from existing OpenAPI specifications (`Fa
 
 Learn more: [**OpenAPI Integration**](https://gofastmcp.com/integrations/openapi) | [**FastAPI Integration**](https://gofastmcp.com/integrations/fastapi).
 
-### Authentication & Security
-
-FastMCP provides built-in authentication support to secure both your MCP servers and clients in production environments. Protect your server endpoints from unauthorized access and authenticate your clients against secured MCP servers using industry-standard protocols.
-
-- **Server Protection**: Secure your FastMCP server endpoints with configurable authentication providers
-- **Client Authentication**: Connect to authenticated MCP servers with automatic credential management
-- **Production Ready**: Support for common authentication patterns used in enterprise environments
-
-Learn more in the **Authentication Documentation** for [servers](https://gofastmcp.com/servers/auth) and [clients](https://gofastmcp.com/clients/auth).
-
 ## Running Your Server
 
 The main way to run a FastMCP server is by calling the `run()` method on your server instance: