fastmcp 2.13.0rc2__py3-none-any.whl → 2.13.0.1__py3-none-any.whl

fastmcp/prompts/prompt.py

@@ -207,10 +207,7 @@ class FunctionPrompt(Prompt):
         # Auto-detect context parameter if not provided
 
         context_kwarg = find_kwarg_by_type(fn, kwarg_type=Context)
-        if context_kwarg:
-            prune_params = [context_kwarg]
-        else:
-            prune_params = None
+        prune_params = [context_kwarg] if context_kwarg else None
 
         parameters = compress_schema(parameters, prune_params=prune_params)
 
@@ -290,10 +287,7 @@ class FunctionPrompt(Prompt):
                 if (
                     param.annotation == inspect.Parameter.empty
                     or param.annotation is str
-                ):
-                    converted_kwargs[param_name] = param_value
-                # If argument is not a string, pass as-is (already properly typed)
-                elif not isinstance(param_value, str):
+                ) or not isinstance(param_value, str):
                     converted_kwargs[param_name] = param_value
                 else:
                     # Try to convert string argument using type adapter
@@ -314,7 +308,7 @@ class FunctionPrompt(Prompt):
                         raise PromptError(
                             f"Could not convert argument '{param_name}' with value '{param_value}' "
                             f"to expected type {param.annotation}. Error: {e}"
-                        )
+                        ) from e
             else:
                 # Parameter not in function signature, pass as-is
                 converted_kwargs[param_name] = param_value
@@ -376,10 +370,12 @@ class FunctionPrompt(Prompt):
                                 content=TextContent(type="text", text=content),
                             )
                         )
-                except Exception:
-                    raise PromptError("Could not convert prompt result to message.")
+                except Exception as e:
+                    raise PromptError(
+                        "Could not convert prompt result to message."
+                    ) from e
 
             return messages
-        except Exception:
+        except Exception as e:
             logger.exception(f"Error rendering prompt {self.name}")
-            raise PromptError(f"Error rendering prompt {self.name}.")
+            raise PromptError(f"Error rendering prompt {self.name}.") from e

fastmcp/resources/__init__.py

@@ -10,13 +10,13 @@ from .types import (
 from .resource_manager import ResourceManager
 
 __all__ = [
-    "Resource",
-    "TextResource",
     "BinaryResource",
-    "FunctionResource",
+    "DirectoryResource",
     "FileResource",
+    "FunctionResource",
     "HttpResource",
-    "DirectoryResource",
-    "ResourceTemplate",
+    "Resource",
     "ResourceManager",
+    "ResourceTemplate",
+    "TextResource",
 ]

fastmcp/resources/resource.py

@@ -217,9 +217,7 @@ class FunctionResource(Resource):
 
         if isinstance(result, Resource):
             return await result.read()
-        elif isinstance(result, bytes):
-            return result
-        elif isinstance(result, str):
+        elif isinstance(result, bytes | str):
             return result
         else:
             return pydantic_core.to_json(result, fallback=str).decode()

fastmcp/resources/resource_manager.py

@@ -235,7 +235,7 @@ class ResourceManager:
 
         # Then check templates (local and mounted) only if not found in concrete resources
         templates = await self.get_resource_templates()
-        for template_key in templates.keys():
+        for template_key in templates:
             if match_uri_template(uri_str, template_key):
                 return True
 

fastmcp/resources/types.py

@@ -5,11 +5,11 @@ from __future__ import annotations
 import json
 from pathlib import Path
 
-import anyio
-import anyio.to_thread
 import httpx
 import pydantic.json
+from anyio import Path as AsyncPath
 from pydantic import Field, ValidationInfo
+from typing_extensions import override
 
 from fastmcp.exceptions import ResourceError
 from fastmcp.resources.resource import Resource
@@ -54,6 +54,10 @@ class FileResource(Resource):
         description="MIME type of the resource content",
     )
 
+    @property
+    def _async_path(self) -> AsyncPath:
+        return AsyncPath(self.path)
+
     @pydantic.field_validator("path")
     @classmethod
     def validate_absolute_path(cls, path: Path) -> Path:
@@ -71,12 +75,13 @@ class FileResource(Resource):
         mime_type = info.data.get("mime_type", "text/plain")
         return not mime_type.startswith("text/")
 
+    @override
     async def read(self) -> str | bytes:
         """Read the file content."""
         try:
             if self.is_binary:
-                return await anyio.to_thread.run_sync(self.path.read_bytes)
-            return await anyio.to_thread.run_sync(self.path.read_text)
+                return await self._async_path.read_bytes()
+            return await self._async_path.read_text()
         except Exception as e:
             raise ResourceError(f"Error reading file {self.path}") from e
 
@@ -89,11 +94,12 @@ class HttpResource(Resource):
         default="application/json", description="MIME type of the resource content"
     )
 
+    @override
     async def read(self) -> str | bytes:
         """Read the HTTP content."""
         async with httpx.AsyncClient() as client:
             response = await client.get(self.url)
-            response.raise_for_status()
+            _ = response.raise_for_status()
             return response.text
 
 
@@ -111,6 +117,10 @@ class DirectoryResource(Resource):
         default="application/json", description="MIME type of the resource content"
     )
 
+    @property
+    def _async_path(self) -> AsyncPath:
+        return AsyncPath(self.path)
+
     @pydantic.field_validator("path")
     @classmethod
     def validate_absolute_path(cls, path: Path) -> Path:
@@ -119,33 +129,29 @@ class DirectoryResource(Resource):
             raise ValueError("Path must be absolute")
         return path
 
-    def list_files(self) -> list[Path]:
+    async def list_files(self) -> list[Path]:
         """List files in the directory."""
-        if not self.path.exists():
+        if not await self._async_path.exists():
             raise FileNotFoundError(f"Directory not found: {self.path}")
-        if not self.path.is_dir():
+        if not await self._async_path.is_dir():
             raise NotADirectoryError(f"Not a directory: {self.path}")
 
+        pattern = self.pattern or "*"
+
+        glob_fn = self._async_path.rglob if self.recursive else self._async_path.glob
         try:
-            if self.pattern:
-                return (
-                    list(self.path.glob(self.pattern))
-                    if not self.recursive
-                    else list(self.path.rglob(self.pattern))
-                )
-            return (
-                list(self.path.glob("*"))
-                if not self.recursive
-                else list(self.path.rglob("*"))
-            )
+            return [Path(p) async for p in glob_fn(pattern) if await p.is_file()]
         except Exception as e:
-            raise ResourceError(f"Error listing directory {self.path}: {e}")
+            raise ResourceError(f"Error listing directory {self.path}") from e
 
+    @override
     async def read(self) -> str:  # Always returns JSON string
         """Read the directory listing."""
         try:
-            files = await anyio.to_thread.run_sync(self.list_files)
-            file_list = [str(f.relative_to(self.path)) for f in files if f.is_file()]
+            files: list[Path] = await self.list_files()
+
+            file_list = [str(f.relative_to(self.path)) for f in files]
+
             return json.dumps({"files": file_list}, indent=2)
-        except Exception:
-            raise ResourceError(f"Error reading directory {self.path}")
+        except Exception as e:
+            raise ResourceError(f"Error reading directory {self.path}") from e

fastmcp/server/__init__.py

@@ -3,4 +3,4 @@ from .context import Context
 from . import dependencies
 
 
-__all__ = ["FastMCP", "Context"]
+__all__ = ["Context", "FastMCP"]

fastmcp/server/auth/__init__.py

@@ -10,14 +10,14 @@ from .oauth_proxy import OAuthProxy
 
 
 __all__ = [
+    "AccessToken",
     "AuthProvider",
-    "OAuthProvider",
-    "TokenVerifier",
     "JWTVerifier",
-    "StaticTokenVerifier",
-    "RemoteAuthProvider",
-    "AccessToken",
+    "OAuthProvider",
     "OAuthProxy",
+    "RemoteAuthProvider",
+    "StaticTokenVerifier",
+    "TokenVerifier",
 ]
 
 

fastmcp/server/auth/auth.py

@@ -23,7 +23,7 @@ from mcp.server.auth.settings import (
     ClientRegistrationOptions,
     RevocationOptions,
 )
-from pydantic import AnyHttpUrl
+from pydantic import AnyHttpUrl, Field
 from starlette.middleware import Middleware
 from starlette.middleware.authentication import AuthenticationMiddleware
 from starlette.routing import Route
@@ -32,7 +32,7 @@ from starlette.routing import Route
 class AccessToken(_SDKAccessToken):
     """AccessToken that includes all JWT claims."""
 
-    claims: dict[str, Any] = {}
+    claims: dict[str, Any] = Field(default_factory=dict)
 
 
 class AuthProvider(TokenVerifierProtocol):

fastmcp/server/auth/handlers/authorize.py

@@ -0,0 +1,324 @@
+"""Enhanced authorization handler with improved error responses.
+
+This module provides an enhanced authorization handler that wraps the MCP SDK's
+AuthorizationHandler to provide better error messages when clients attempt to
+authorize with unregistered client IDs.
+
+The enhancement adds:
+- Content negotiation: HTML for browsers, JSON for API clients
+- Enhanced JSON responses with registration endpoint hints
+- Styled HTML error pages with registration links/forms
+- Link headers pointing to registration endpoints
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mcp.server.auth.handlers.authorize import (
+    AuthorizationHandler as SDKAuthorizationHandler,
+)
+from pydantic import AnyHttpUrl
+from starlette.requests import Request
+from starlette.responses import Response
+
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.ui import (
+    INFO_BOX_STYLES,
+    TOOLTIP_STYLES,
+    create_logo,
+    create_page,
+    create_secure_html_response,
+)
+
+if TYPE_CHECKING:
+    from mcp.server.auth.provider import OAuthAuthorizationServerProvider
+
+logger = get_logger(__name__)
+
+
+def create_unregistered_client_html(
+    client_id: str,
+    registration_endpoint: str,
+    discovery_endpoint: str,
+    server_name: str | None = None,
+    server_icon_url: str | None = None,
+    title: str = "Client Not Registered",
+) -> str:
+    """Create styled HTML error page for unregistered client attempts.
+
+    Args:
+        client_id: The unregistered client ID that was provided
+        registration_endpoint: URL of the registration endpoint
+        discovery_endpoint: URL of the OAuth metadata discovery endpoint
+        server_name: Optional server name for branding
+        server_icon_url: Optional server icon URL
+        title: Page title
+
+    Returns:
+        HTML string for the error page
+    """
+    import html as html_module
+
+    client_id_escaped = html_module.escape(client_id)
+
+    # Main error message
+    error_box = f"""
+        <div class="info-box error">
+            <p>The client ID <code>{client_id_escaped}</code> was not found in the server's client registry.</p>
+        </div>
+    """
+
+    # What to do - yellow warning box
+    warning_box = """
+        <div class="info-box warning">
+            <p>Your MCP client opened this page to complete OAuth authorization,
+            but the server did not recognize its client ID. To fix this:</p>
+            <ul>
+                <li>Close this browser window</li>
+                <li>Clear authentication tokens in your MCP client (or restart it)</li>
+                <li>Try connecting again - your client should automatically re-register</li>
+            </ul>
+        </div>
+    """
+
+    # Help link with tooltip (similar to consent screen)
+    help_link = """
+        <div class="help-link-container">
+            <span class="help-link">
+                Why am I seeing this?
+                <span class="tooltip">
+                    OAuth 2.0 requires clients to register before authorization.
+                    This server returned a 400 error because the provided client
+                    ID was not found.
+                    <br><br>
+                    In browser-delegated OAuth flows, your application cannot
+                    detect this error automatically; it's waiting for a
+                    callback that will never arrive. You must manually clear
+                    auth tokens and reconnect.
+                </span>
+            </span>
+        </div>
+    """
+
+    # Build page content
+    content = f"""
+        <div class="container">
+            {create_logo(icon_url=server_icon_url, alt_text=server_name or "FastMCP")}
+            <h1>{title}</h1>
+            {error_box}
+            {warning_box}
+        </div>
+        {help_link}
+    """
+
+    # Use same styles as consent page
+    additional_styles = (
+        INFO_BOX_STYLES
+        + TOOLTIP_STYLES
+        + """
+        /* Error variant for info-box */
+        .info-box.error {
+            background: #fef2f2;
+            border-color: #f87171;
+        }
+        .info-box.error strong {
+            color: #991b1b;
+        }
+        /* Warning variant for info-box (yellow) */
+        .info-box.warning {
+            background: #fffbeb;
+            border-color: #fbbf24;
+        }
+        .info-box.warning strong {
+            color: #92400e;
+        }
+        .info-box code {
+            background: rgba(0, 0, 0, 0.05);
+            padding: 2px 6px;
+            border-radius: 3px;
+            font-family: 'SF Mono', Monaco, 'Cascadia Code', monospace;
+            font-size: 0.9em;
+        }
+        .info-box ul {
+            margin: 10px 0;
+            padding-left: 20px;
+        }
+        .info-box li {
+            margin: 6px 0;
+        }
+        """
+    )
+
+    return create_page(
+        content=content,
+        title=title,
+        additional_styles=additional_styles,
+    )
+
+
+class AuthorizationHandler(SDKAuthorizationHandler):
+    """Authorization handler with enhanced error responses for unregistered clients.
+
+    This handler extends the MCP SDK's AuthorizationHandler to provide better UX
+    when clients attempt to authorize without being registered. It implements
+    content negotiation to return:
+
+    - HTML error pages for browser requests
+    - Enhanced JSON with registration hints for API clients
+    - Link headers pointing to registration endpoints
+
+    This maintains OAuth 2.1 compliance (returns 400 for invalid client_id)
+    while providing actionable guidance to fix the error.
+    """
+
+    def __init__(
+        self,
+        provider: OAuthAuthorizationServerProvider,
+        base_url: AnyHttpUrl | str,
+        server_name: str | None = None,
+        server_icon_url: str | None = None,
+    ):
+        """Initialize the enhanced authorization handler.
+
+        Args:
+            provider: OAuth authorization server provider
+            base_url: Base URL of the server for constructing endpoint URLs
+            server_name: Optional server name for branding
+            server_icon_url: Optional server icon URL for branding
+        """
+        super().__init__(provider)
+        self._base_url = str(base_url).rstrip("/")
+        self._server_name = server_name
+        self._server_icon_url = server_icon_url
+
+    async def handle(self, request: Request) -> Response:
+        """Handle authorization request with enhanced error responses.
+
+        This method extends the SDK's authorization handler and intercepts
+        errors for unregistered clients to provide better error responses
+        based on the client's Accept header.
+
+        Args:
+            request: The authorization request
+
+        Returns:
+            Response (redirect on success, error response on failure)
+        """
+        # Call the SDK handler
+        response = await super().handle(request)
+
+        # Check if this is a client not found error
+        if response.status_code == 400:
+            # Try to extract client_id from request for enhanced error
+            client_id = None
+            if request.method == "GET":
+                client_id = request.query_params.get("client_id")
+            else:
+                form = await request.form()
+                client_id = form.get("client_id")
+
+            # If we have a client_id and the error is about it not being found,
+            # enhance the response
+            if client_id:
+                try:
+                    # Check if response body contains "not found" error
+                    if hasattr(response, "body"):
+                        import json
+
+                        body = json.loads(response.body)
+                        if (
+                            body.get("error") == "invalid_request"
+                            and "not found" in body.get("error_description", "").lower()
+                        ):
+                            return await self._create_enhanced_error_response(
+                                request, client_id, body.get("state")
+                            )
+                except Exception:
+                    # If we can't parse the response, just return the original
+                    pass
+
+        return response
+
+    async def _create_enhanced_error_response(
+        self, request: Request, client_id: str, state: str | None
+    ) -> Response:
+        """Create enhanced error response with content negotiation.
+
+        Args:
+            request: The original request
+            client_id: The unregistered client ID
+            state: The state parameter from the request
+
+        Returns:
+            HTML or JSON error response based on Accept header
+        """
+        registration_endpoint = f"{self._base_url}/register"
+        discovery_endpoint = f"{self._base_url}/.well-known/oauth-authorization-server"
+
+        # Extract server metadata from app state (same pattern as consent screen)
+        from fastmcp.server.server import FastMCP
+
+        fastmcp = getattr(request.app.state, "fastmcp_server", None)
+
+        if isinstance(fastmcp, FastMCP):
+            server_name = fastmcp.name
+            icons = fastmcp.icons
+            server_icon_url = icons[0].src if icons else None
+        else:
+            server_name = self._server_name
+            server_icon_url = self._server_icon_url
+
+        # Check Accept header for content negotiation
+        accept = request.headers.get("accept", "")
+
+        # Prefer HTML for browsers
+        if "text/html" in accept:
+            html = create_unregistered_client_html(
+                client_id=client_id,
+                registration_endpoint=registration_endpoint,
+                discovery_endpoint=discovery_endpoint,
+                server_name=server_name,
+                server_icon_url=server_icon_url,
+            )
+            response = create_secure_html_response(html, status_code=400)
+        else:
+            # Return enhanced JSON for API clients
+            from mcp.server.auth.handlers.authorize import AuthorizationErrorResponse
+
+            error_data = AuthorizationErrorResponse(
+                error="invalid_request",
+                error_description=(
+                    f"Client ID '{client_id}' is not registered with this server. "
+                    f"MCP clients should automatically re-register by sending a POST request to "
+                    f"the registration_endpoint and retry authorization. "
+                    f"If this persists, clear cached authentication tokens and reconnect."
+                ),
+                state=state,
+            )
+
+            # Add extra fields to help clients discover registration
+            error_dict = error_data.model_dump(exclude_none=True)
+            error_dict["registration_endpoint"] = registration_endpoint
+            error_dict["authorization_server_metadata"] = discovery_endpoint
+
+            from starlette.responses import JSONResponse
+
+            response = JSONResponse(
+                status_code=400,
+                content=error_dict,
+                headers={"Cache-Control": "no-store"},
+            )
+
+        # Add Link header for registration endpoint discovery
+        response.headers["Link"] = (
+            f'<{registration_endpoint}>; rel="http://oauth.net/core/2.1/#registration"'
+        )
+
+        logger.info(
+            "Unregistered client_id=%s, returned %s error response",
+            client_id,
+            "HTML" if "text/html" in accept else "JSON",
+        )
+
+        return response