fastmcp 2.13.0rc2__py3-none-any.whl → 2.13.0rc3__py3-none-any.whl

fastmcp/cli/cli.py

@@ -772,6 +772,7 @@ async def inspect(
                 "server_spec": server_spec,
                 "error": str(e),
             },
+            exc_info=True,
         )
         console.print(f"[bold red]✗[/bold red] Failed to inspect server: {e}")
         sys.exit(1)

fastmcp/cli/install/claude_code.py

@@ -125,15 +125,15 @@ def install_claude_code(
     full_command = env_config.build_command(["fastmcp", "run", server_spec])
 
     # Build claude mcp add command
-    cmd_parts = [claude_cmd, "mcp", "add"]
+    cmd_parts = [claude_cmd, "mcp", "add", name]
 
-    # Add environment variables if specified (before the name and command)
+    # Add environment variables if specified
     if env_vars:
         for key, value in env_vars.items():
             cmd_parts.extend(["-e", f"{key}={value}"])
 
     # Add server name and command
-    cmd_parts.extend([name, "--"])
+    cmd_parts.append("--")
     cmd_parts.extend(full_command)
 
     try:

fastmcp/client/oauth_callback.py

@@ -46,9 +46,13 @@ def create_callback_html(
     # Add detail info box for both success and error cases
     detail_info = ""
     if is_success and server_url:
-        detail_info = create_info_box(f"Connected to: {server_url}", centered=True)
+        detail_info = create_info_box(
+            f"Connected to: {server_url}", centered=True, monospace=True
+        )
     elif not is_success:
-        detail_info = create_info_box(message, is_error=True, centered=True)
+        detail_info = create_info_box(
+            message, is_error=True, centered=True, monospace=True
+        )
 
     # Build the page content
     content = f"""

fastmcp/client/transports.py

@@ -748,6 +748,7 @@ class UvxStdioTransport(StdioTransport):
         env: dict[str, str] | None = None
         if env_vars:
             env = os.environ.copy()
+            env.update(env_vars)
 
         super().__init__(
             command="uvx",

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/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

fastmcp/server/auth/jwt_issuer.py

@@ -9,82 +9,66 @@ from __future__ import annotations
 
 import base64
 import time
-from typing import Any
+from typing import Any, overload
 
 from authlib.jose import JsonWebToken
 from authlib.jose.errors import JoseError
-from cryptography.fernet import Fernet
 from cryptography.hazmat.primitives import hashes
 from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
 
 from fastmcp.utilities.logging import get_logger
 
 logger = get_logger(__name__)
 
+KDF_ITERATIONS = 1000000
 
-def derive_jwt_key(upstream_secret: str, server_salt: str) -> bytes:
-    """Derive JWT signing key from upstream client secret and server salt.
 
-    Uses HKDF (RFC 5869) to derive a cryptographically secure signing key from
-    the upstream OAuth client secret combined with a server-specific salt.
+@overload
+def derive_jwt_key(*, high_entropy_material: str, salt: str) -> bytes:
+    """Derive JWT signing key from a high-entropy key material and server salt."""
 
-    Args:
-        upstream_secret: The OAuth client secret from upstream provider
-        server_salt: Random salt unique to this server instance
 
-    Returns:
-        32-byte key suitable for HS256 JWT signing
-    """
-    return HKDF(
-        algorithm=hashes.SHA256(),
-        length=32,
-        salt=f"fastmcp-jwt-signing-v1-{server_salt}".encode(),
-        info=b"HS256",
-    ).derive(upstream_secret.encode())
-
-
-def derive_encryption_key(upstream_secret: str) -> bytes:
-    """Derive Fernet encryption key from upstream client secret.
-
-    Uses HKDF to derive a cryptographically secure encryption key for
-    encrypting upstream tokens at rest.
+@overload
+def derive_jwt_key(*, low_entropy_material: str, salt: str) -> bytes:
+    """Derive JWT signing key from a low-entropy key material and server salt."""
 
-    Args:
-        upstream_secret: The OAuth client secret from upstream provider
 
-    Returns:
-        32-byte Fernet key (base64url-encoded)
-    """
-    key_material = HKDF(
-        algorithm=hashes.SHA256(),
-        length=32,
-        salt=b"fastmcp-token-encryption-v1",
-        info=b"Fernet",
-    ).derive(upstream_secret.encode())
-    return base64.urlsafe_b64encode(key_material)
+def derive_jwt_key(
+    *,
+    high_entropy_material: str | None = None,
+    low_entropy_material: str | None = None,
+    salt: str,
+) -> bytes:
+    """Derive JWT signing key from a high-entropy or low-entropy key material and server salt."""
+    if high_entropy_material is not None and low_entropy_material is not None:
+        raise ValueError(
+            "Either high_entropy_material or low_entropy_material must be provided, but not both"
+        )
 
+    if high_entropy_material is not None:
+        derived_key = HKDF(
+            algorithm=hashes.SHA256(),
+            length=32,
+            salt=salt.encode(),
+            info=b"Fernet",
+        ).derive(key_material=high_entropy_material.encode())
 
-def derive_key_from_secret(secret: str | bytes, salt: str, info: bytes) -> bytes:
-    """Derive 32-byte key from user-provided secret (string or bytes).
+        return base64.urlsafe_b64encode(derived_key)
 
-    Accepts any length input and derives a proper cryptographic key.
-    Uses HKDF to stretch weak inputs into strong keys.
+    if low_entropy_material is not None:
+        pbkdf2 = PBKDF2HMAC(
+            algorithm=hashes.SHA256(),
+            length=32,
+            salt=salt.encode(),
+            iterations=KDF_ITERATIONS,
+        ).derive(key_material=low_entropy_material.encode())
 
-    Args:
-        secret: User-provided secret (any string or bytes)
-        salt: Application-specific salt string
-        info: Key purpose identifier
+        return base64.urlsafe_b64encode(pbkdf2)
 
-    Returns:
-        32-byte key suitable for HS256 JWT signing or Fernet encryption
-    """
-    secret_bytes = secret.encode() if isinstance(secret, str) else secret
-    return HKDF(
-        algorithm=hashes.SHA256(),
-        length=32,
-        salt=salt.encode(),
-        info=info,
-    ).derive(secret_bytes)
+    raise ValueError(
+        "Either high_entropy_material or low_entropy_material must be provided"
+    )
 
 
 class JWTIssuer:
@@ -250,40 +234,3 @@ class JWTIssuer:
         except JoseError as e:
             logger.debug("Token validation failed: %s", e)
             raise
-
-
-class TokenEncryption:
-    """Handles encryption/decryption of upstream OAuth tokens at rest."""
-
-    def __init__(self, encryption_key: bytes):
-        """Initialize token encryption.
-
-        Args:
-            encryption_key: Fernet encryption key (32 bytes, base64url-encoded)
-        """
-        self._fernet = Fernet(encryption_key)
-
-    def encrypt(self, token: str) -> bytes:
-        """Encrypt a token for storage.
-
-        Args:
-            token: Plain text token
-
-        Returns:
-            Encrypted token bytes
-        """
-        return self._fernet.encrypt(token.encode())
-
-    def decrypt(self, encrypted_token: bytes) -> str:
-        """Decrypt a token from storage.
-
-        Args:
-            encrypted_token: Encrypted token bytes
-
-        Returns:
-            Plain text token
-
-        Raises:
-            cryptography.fernet.InvalidToken: If token is corrupted or key is wrong
-        """
-        return self._fernet.decrypt(encrypted_token).decode()