fastmcp 2.13.0rc3__tar.gz → 2.13.0.2__tar.gz

{fastmcp-2.13.0rc3 → fastmcp-2.13.0.2}/.github/workflows/run-tests.yml

@@ -59,6 +59,31 @@ jobs:
       - name: Run client process tests separately
         run: uv run pytest --inline-snapshot=disable tests -m "client_process" -x
 
+  run_tests_lowest_direct:
+    name: "Run tests with lowest-direct dependencies"
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          python-version: "3.10"
+
+      - name: Install FastMCP with lowest-direct resolution
+        # run with lowest-direct to test against the minimum allowed dependency versions
+        run: uv sync --resolution lowest-direct
+
+      - name: Run tests (excluding integration and client_process)
+        run: uv run pytest --inline-snapshot=disable tests -m "not integration and not client_process" --numprocesses auto --maxprocesses 4 --dist worksteal
+
+      - name: Run client process tests separately
+        run: uv run pytest --inline-snapshot=disable tests -m "client_process" -x
+
   run_integration_tests:
     name: "Run integration tests"
     runs-on: ubuntu-latest

{fastmcp-2.13.0rc3 → fastmcp-2.13.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.13.0rc3
+Version: 2.13.0.2
 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
@@ -22,11 +22,11 @@ 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: jsonschema-path>=0.3.4
 Requires-Dist: mcp<2.0.0,>=1.17.0
-Requires-Dist: openapi-core>=0.19.5
 Requires-Dist: openapi-pydantic>=0.5.1
 Requires-Dist: platformdirs>=4.0.0
-Requires-Dist: py-key-value-aio[disk,keyring,memory]<0.3.0,>=0.2.6
+Requires-Dist: py-key-value-aio[disk,keyring,memory]<0.3.0,>=0.2.8
 Requires-Dist: pydantic[email]>=2.11.7
 Requires-Dist: pyperclip>=1.9.0
 Requires-Dist: python-dotenv>=1.1.0

{fastmcp-2.13.0rc3 → fastmcp-2.13.0.2}/docs/changelog.mdx

@@ -4,6 +4,40 @@ icon: "list-check"
 rss: true
 ---
 
+<Update label="v2.13.0" description="2025-10-25">
+
+**[v2.13.0: Cache Me If You Can](https://github.com/jlowin/fastmcp/releases/tag/v2.13.0)**
+
+FastMCP 2.13 "Cache Me If You Can" represents a fundamental maturation of the framework. After months of community feedback on authentication and state management, this release delivers the infrastructure FastMCP needs to handle production workloads: persistent storage, response caching, and pragmatic OAuth improvements that reflect real-world deployment challenges.
+
+💾 **Pluggable storage backends** bring persistent state to FastMCP servers. Built on [py-key-value-aio](https://github.com/strawgate/py-key-value), a new library from FastMCP maintainer Bill Easton ([@strawgate](https://github.com/strawgate)), the storage layer provides encrypted disk storage by default, platform-aware token management, and a simple key-value interface for application state. We're excited to bring this elegantly designed library into the FastMCP ecosystem - it's both powerful and remarkably easy to use, including wrappers to add encryption, TTLs, caching, and more to backends ranging from Elasticsearch, Redis, DynamoDB, filesystem, in-memory, and more! OAuth providers now automatically persist tokens across restarts, and developers can store arbitrary state without reaching for external databases. This foundation enables long-running sessions, cached credentials, and stateful applications built on MCP.
+
+🔐 **OAuth maturity** brings months of production learnings into the framework. The new consent screen prevents confused deputy and authorization bypass attacks discovered in earlier versions while providing a clean UX with customizable branding. The OAuth proxy now issues its own tokens with automatic key derivation from client secrets, and RFC 7662 token introspection support enables enterprise auth flows. Path prefix mounting enables OAuth-protected servers to integrate into existing web applications under custom paths like `/api`, and MCP 1.17+ compliance with RFC 9728 ensures protocol compatibility. Combined with improved error handling and platform-aware token storage, OAuth is now production-ready and security-hardened for serious applications.
+
+FastMCP now supports out-of-the-box authentication with:
+- **[WorkOS](https://gofastmcp.com/integrations/workos)** and **[AuthKit](https://gofastmcp.com/integrations/authkit)**
+- **[GitHub](https://gofastmcp.com/integrations/github)**
+- **[Google](https://gofastmcp.com/integrations/google)**
+- **[Azure](https://gofastmcp.com/integrations/azure)** (Entra ID)
+- **[AWS Cognito](https://gofastmcp.com/integrations/aws-cognito)**
+- **[Auth0](https://gofastmcp.com/integrations/auth0)**
+- **[Descope](https://gofastmcp.com/integrations/descope)**
+- **[Scalekit](https://gofastmcp.com/integrations/scalekit)**
+- **[JWTs](https://gofastmcp.com/servers/auth/token-verification#jwt-token-verification)**
+- **[RFC 7662 token introspection](https://gofastmcp.com/servers/auth/token-verification#token-introspection-protocol)**
+
+⚡ **Response Caching Middleware** dramatically improves performance for expensive operations. Cache tool and resource responses with configurable TTLs, reducing redundant API calls and speeding up repeated queries.
+
+🔄 **Server lifespans** provide proper initialization and cleanup hooks that run once per server instance instead of per client session. This fixes a long-standing source of confusion in the MCP SDK and enables proper resource management for database connections, background tasks, and other server-level state. Note: this is a breaking behavioral change if you were using the `lifespan` parameter.
+
+✨ **Developer experience improvements** include Pydantic input validation for better type safety, icon support for richer UX, RFC 6570 query parameters for resource templates, improved Context API methods (list_resources, list_prompts, get_prompt), and async file/directory resources.
+
+This release includes contributions from **20** new contributors and represents the largest feature set in a while. Thank you to everyone who tested preview builds and filed issues - your feedback shaped these improvements!
+
+**Full Changelog**: [v2.12.5...v2.13.0](https://github.com/jlowin/fastmcp/compare/v2.12.5...v2.13.0)
+
+</Update>
+
 <Update label="v2.12.5" description="2025-10-17">
 
 **[v2.12.5: Safety Pin](https://github.com/jlowin/fastmcp/releases/tag/v2.12.5)**

{fastmcp-2.13.0rc3 → fastmcp-2.13.0.2}/docs/docs.json

@@ -20,7 +20,10 @@
     "primary": "#2d00f7"
   },
   "contextual": {
-    "options": ["copy", "view"]
+    "options": [
+      "copy",
+      "view"
+    ]
   },
   "description": "The fast, Pythonic way to build MCP servers and clients.",
   "errors": {
@@ -146,7 +149,10 @@
               {
                 "group": "Essentials",
                 "icon": "cube",
-                "pages": ["clients/client", "clients/transports"]
+                "pages": [
+                  "clients/client",
+                  "clients/transports"
+                ]
               },
               {
                 "group": "Core Operations",
@@ -172,7 +178,10 @@
               {
                 "group": "Authentication",
                 "icon": "user-shield",
-                "pages": ["clients/auth/oauth", "clients/auth/bearer"]
+                "pages": [
+                  "clients/auth/oauth",
+                  "clients/auth/bearer"
+                ]
               }
             ]
           },
@@ -226,7 +235,10 @@
               {
                 "group": "API Integration",
                 "icon": "globe",
-                "pages": ["integrations/fastapi", "integrations/openapi"]
+                "pages": [
+                  "integrations/fastapi",
+                  "integrations/openapi"
+                ]
               }
             ]
           },
@@ -333,6 +345,7 @@
                       "python-sdk/fastmcp-server-auth-__init__",
                       "python-sdk/fastmcp-server-auth-auth",
                       "python-sdk/fastmcp-server-auth-jwt_issuer",
+                      "python-sdk/fastmcp-server-auth-middleware",
                       "python-sdk/fastmcp-server-auth-oauth_proxy",
                       "python-sdk/fastmcp-server-auth-oidc_proxy",
                       {
@@ -371,7 +384,8 @@
                       "python-sdk/fastmcp-server-middleware-logging",
                       "python-sdk/fastmcp-server-middleware-middleware",
                       "python-sdk/fastmcp-server-middleware-rate_limiting",
-                      "python-sdk/fastmcp-server-middleware-timing"
+                      "python-sdk/fastmcp-server-middleware-timing",
+                      "python-sdk/fastmcp-server-middleware-tool_injection"
                     ]
                   },
                   "python-sdk/fastmcp-server-openapi",
@@ -458,17 +472,17 @@
   "search": {
     "prompt": "Search the docs..."
   },
-  "theme": "almond",
-  "thumbnails": {
-    "appearance": "light",
-    "background": "/assets/brand/thumbnail-background.png"
-  },
   "styling": {
     "codeblocks": {
       "theme": {
-        "light": "snazzy-light",
-        "dark": "dark-plus"
+        "dark": "dark-plus",
+        "light": "snazzy-light"
       }
     }
+  },
+  "theme": "almond",
+  "thumbnails": {
+    "appearance": "light",
+    "background": "/assets/brand/thumbnail-background.png"
   }
 }

{fastmcp-2.13.0rc3 → fastmcp-2.13.0.2}/docs/integrations/azure.mdx

@@ -122,7 +122,7 @@ auth_provider = AzureProvider(
     client_secret="your-client-secret",                 # Your Azure App Client Secret
     tenant_id="08541b6e-646d-43de-a0eb-834e6713d6d5", # Your Azure Tenant ID (REQUIRED)
     base_url="http://localhost:8000",                   # Must match your App registration
-    required_scopes=["your-scope"],                 # Name of scope created when configuring your App
+    required_scopes=["your-scope"],                 # At least one scope REQUIRED - name of scope from your App
     # identifier_uri defaults to api://{client_id}
     # identifier_uri="api://your-api-id",
     # Optional: request additional upstream scopes in the authorize request
@@ -159,6 +159,10 @@ async def get_user_info() -> dict:
 Using your specific tenant ID is recommended for better security and control.
 </Note>
 
+<Note>
+**Important**: The `required_scopes` parameter is **REQUIRED** and must include at least one scope. Azure's OAuth API requires the `scope` parameter in all authorization requests - you cannot authenticate without specifying at least one scope. Use the unprefixed scope names from your Azure App registration (e.g., `["read", "write"]`). These scopes must be created under **Expose an API** in your App registration.
+</Note>
+
 ## Testing
 
 ### Running the Server
@@ -296,8 +300,12 @@ Issuer URL for OAuth metadata (defaults to `BASE_URL`). Set to root-level URL wh
 Redirect path configured in your Azure App registration
 </ParamField>
 
-<ParamField path="FASTMCP_SERVER_AUTH_AZURE_REQUIRED_SCOPES" default="">
-Comma-, space-, or JSON-separated list of required scopes for your API. These are validated on tokens and used as defaults if the client does not request specific scopes.
+<ParamField path="FASTMCP_SERVER_AUTH_AZURE_REQUIRED_SCOPES" required>
+Comma-, space-, or JSON-separated list of required scopes for your API (at least one scope required). These are validated on tokens and used as defaults if the client does not request specific scopes. Use unprefixed scope names from your Azure App registration (e.g., `read,write`).
+
+<Note>
+Azure's OAuth API requires the `scope` parameter - you must provide at least one scope.
+</Note>
 </ParamField>
 
 <ParamField path="FASTMCP_SERVER_AUTH_AZURE_ADDITIONAL_AUTHORIZE_SCOPES" default="">

{fastmcp-2.13.0rc3 → fastmcp-2.13.0.2}/docs/python-sdk/fastmcp-cli-cli.mdx

@@ -105,7 +105,7 @@ fastmcp inspect  # auto-detect fastmcp.json
 - `server_spec`: Python file to inspect, optionally with \:object suffix, or fastmcp.json
 
 
-### `prepare` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/cli/cli.py#L785" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `prepare` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/cli/cli.py#L786" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 prepare(config_path: Annotated[str | None, cyclopts.Parameter(help='Path to fastmcp.json configuration file')] = None, output_dir: Annotated[str | None, cyclopts.Parameter(help='Directory to create the persistent environment in')] = None, skip_source: Annotated[bool, cyclopts.Parameter(help='Skip source preparation (e.g., git clone)')] = False) -> None

{fastmcp-2.13.0rc3 → fastmcp-2.13.0.2}/docs/python-sdk/fastmcp-resources-types.mdx

@@ -54,7 +54,7 @@ Set is_binary=True to read file as binary data instead of text.
 
 **Methods:**
 
-#### `validate_absolute_path` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L59" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `validate_absolute_path` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 validate_absolute_path(cls, path: Path) -> Path
@@ -63,7 +63,7 @@ validate_absolute_path(cls, path: Path) -> Path
 Ensure path is absolute.
 
 
-#### `set_binary_from_mime_type` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `set_binary_from_mime_type` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 set_binary_from_mime_type(cls, is_binary: bool, info: ValidationInfo) -> bool
@@ -72,7 +72,7 @@ set_binary_from_mime_type(cls, is_binary: bool, info: ValidationInfo) -> bool
 Set is_binary based on mime_type if not explicitly set.
 
 
-#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 read(self) -> str | bytes
@@ -81,7 +81,7 @@ read(self) -> str | bytes
 Read the file content.
 
 
-### `HttpResource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L84" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `HttpResource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 
 A resource that reads from an HTTP endpoint.
@@ -89,7 +89,7 @@ A resource that reads from an HTTP endpoint.
 
 **Methods:**
 
-#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 read(self) -> str | bytes
@@ -98,7 +98,7 @@ read(self) -> str | bytes
 Read the HTTP content.
 
 
-### `DirectoryResource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+### `DirectoryResource` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 
 A resource that lists files in a directory.
@@ -106,7 +106,7 @@ A resource that lists files in a directory.
 
 **Methods:**
 
-#### `validate_absolute_path` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L116" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `validate_absolute_path` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L126" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 validate_absolute_path(cls, path: Path) -> Path
@@ -115,7 +115,7 @@ validate_absolute_path(cls, path: Path) -> Path
 Ensure path is absolute.
 
 
-#### `list_files` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L122" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `list_files` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L132" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 list_files(self) -> list[Path]
@@ -124,7 +124,7 @@ list_files(self) -> list[Path]
 List files in the directory.
 
 
-#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L144" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+#### `read` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/resources/types.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
 
 ```python
 read(self) -> str

fastmcp-2.13.0.2/docs/python-sdk/fastmcp-server-auth-jwt_issuer.mdx

@@ -0,0 +1,104 @@
+---
+title: jwt_issuer
+sidebarTitle: jwt_issuer
+---
+
+# `fastmcp.server.auth.jwt_issuer`
+
+
+JWT token issuance and verification for FastMCP OAuth Proxy.
+
+This module implements the token factory pattern for OAuth proxies, where the proxy
+issues its own JWT tokens to clients instead of forwarding upstream provider tokens.
+This maintains proper OAuth 2.0 token audience boundaries.
+
+
+## Functions
+
+### `derive_jwt_key` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/jwt_issuer.py#L37" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+derive_jwt_key() -> bytes
+```
+
+
+Derive JWT signing key from a high-entropy or low-entropy key material and server salt.
+
+
+## Classes
+
+### `JWTIssuer` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/jwt_issuer.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Issues and validates FastMCP-signed JWT tokens using HS256.
+
+This issuer creates JWT tokens for MCP clients with proper audience claims,
+maintaining OAuth 2.0 token boundaries. Tokens are signed with HS256 using
+a key derived from the upstream client secret.
+
+
+**Methods:**
+
+#### `issue_access_token` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/jwt_issuer.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+issue_access_token(self, client_id: str, scopes: list[str], jti: str, expires_in: int = 3600) -> str
+```
+
+Issue a minimal FastMCP access token.
+
+FastMCP tokens are reference tokens containing only the minimal claims
+needed for validation and lookup. The JTI maps to the upstream token
+which contains actual user identity and authorization data.
+
+**Args:**
+- `client_id`: MCP client ID
+- `scopes`: Token scopes
+- `jti`: Unique token identifier (maps to upstream token)
+- `expires_in`: Token lifetime in seconds
+
+**Returns:**
+- Signed JWT token
+
+
+#### `issue_refresh_token` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/jwt_issuer.py#L147" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+issue_refresh_token(self, client_id: str, scopes: list[str], jti: str, expires_in: int) -> str
+```
+
+Issue a minimal FastMCP refresh token.
+
+FastMCP refresh tokens are reference tokens containing only the minimal
+claims needed for validation and lookup. The JTI maps to the upstream
+token which contains actual user identity and authorization data.
+
+**Args:**
+- `client_id`: MCP client ID
+- `scopes`: Token scopes
+- `jti`: Unique token identifier (maps to upstream token)
+- `expires_in`: Token lifetime in seconds (should match upstream refresh expiry)
+
+**Returns:**
+- Signed JWT token
+
+
+#### `verify_token` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/jwt_issuer.py#L195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+verify_token(self, token: str) -> dict[str, Any]
+```
+
+Verify and decode a FastMCP token.
+
+Validates JWT signature, expiration, issuer, and audience.
+
+**Args:**
+- `token`: JWT token to verify
+
+**Returns:**
+- Decoded token payload
+
+**Raises:**
+- `JoseError`: If token is invalid, expired, or has wrong claims
+

fastmcp-2.13.0.2/docs/python-sdk/fastmcp-server-auth-middleware.mdx

@@ -0,0 +1,26 @@
+---
+title: middleware
+sidebarTitle: middleware
+---
+
+# `fastmcp.server.auth.middleware`
+
+
+Enhanced authentication middleware with better error messages.
+
+This module provides enhanced versions of MCP SDK authentication middleware
+that return more helpful error messages for developers troubleshooting
+authentication issues.
+
+
+## Classes
+
+### `RequireAuthMiddleware` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/auth/middleware.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+
+Enhanced authentication middleware with detailed error messages.
+
+Extends the SDK's RequireAuthMiddleware to provide more actionable
+error messages when authentication fails. This helps developers
+understand what went wrong and how to fix it.
+