commit updates for fastmcp 2.14.1

tspicer · tspicer · commit 76a288cafc5d · 2025-12-29T10:37:22.000-05:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -232,6 +232,46 @@ export MCP_MASK_ERROR_DETAILS=true
 export MCP_ON_DUPLICATE_TOOLS=warn
 ```
 
+### Security-Related Environment Variables
+
+```bash
+# Token Persistence (disabled by default for security)
+# When false (default): Tokens stored in memory only, lost on restart
+# When true: Refresh tokens cached to disk/volume, persist across restarts
+export AMAZON_ADS_TOKEN_PERSIST="false"  # Set to "true" to enable persistence
+
+# Token Encryption (required when AMAZON_ADS_TOKEN_PERSIST=true)
+# If not set, a random key is auto-generated and stored alongside tokens
+# For production: Generate with `python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`
+export AMAZON_ADS_ENCRYPTION_KEY="your-44-char-base64-key"
+
+# Plaintext Storage (INSECURE - testing only!)
+# Only enable if cryptography library is unavailable AND you accept the risk
+export AMAZON_ADS_ALLOW_PLAINTEXT_PERSIST="false"  # Never set to "true" in production
+```
+
+**Security Implications of Token Persistence:**
+
+When `AMAZON_ADS_TOKEN_PERSIST=true`:
+- ✅ Convenience: Refresh tokens survive container restarts (no re-authentication)
+- ⚠️ Risk: Tokens are encrypted but stored with their decryption key on same volume
+- ⚠️ Risk: Anyone with filesystem/volume access can potentially extract tokens
+- 🔒 Mitigation: Set `AMAZON_ADS_ENCRYPTION_KEY` from external secrets manager
+- 🔒 Best Practice: Use in-memory storage (default) unless persistence is required
+
+**Recommended Configurations:**
+
+```bash
+# Development (local laptop): In-memory is usually sufficient
+AMAZON_ADS_TOKEN_PERSIST=false
+
+# Shared/Production: Either in-memory OR persistence with external key
+AMAZON_ADS_TOKEN_PERSIST=false  # Preferred if feasible
+# OR
+AMAZON_ADS_TOKEN_PERSIST=true
+AMAZON_ADS_ENCRYPTION_KEY=${VAULT_SECRET}  # From secrets manager
+```
+
 ### Code Standards
 
 - Python ≥ 3.10 with full type annotations
diff --git a/README.md b/README.md
@@ -408,7 +408,7 @@ In this example, we show how to use the bearer token using the Openbridge API ke
         "http://${HOSTNAME}:${PORT}/mcp/",
         "--allow-http",
         "--header",
-        "Authorization:Bearer ${OPENBRIDGE_REFRESH_TOKEN}",
+        "Authorization:Bearer ${OPENBRIDGE_API_KEY}",
         "--header",
         "Accept:application/json,text/event-stream",
         "--debug"
@@ -423,7 +423,7 @@ In this example, we show how to use the bearer token using the Openbridge API ke
         "MCP_SERVER_REQUEST_TIMEOUT": "60000",
         "MCP_TOOL_TIMEOUT": "120000",
         "MCP_REQUEST_WARNING_THRESHOLD": "10000",
-        "OPENBRIDGE_REFRESH_TOKEN": "your_openbridge_token_here"
+        "OPENBRIDGE_API_KEY": "your_openbridge_token_here"
       }
     }
   }
@@ -468,7 +468,7 @@ The config would look something like this:
 }
 ```
 
-Here is another example, which can be used if you are using OAuth since the `OPENBRIDGE_REFRESH_TOKEN` is not needed:
+Here is another example, which can be used if you are using OAuth since the `OPENBRIDGE_API_KEY` is not needed:
 
 ```json
 {
diff --git a/docker-compose.yaml b/docker-compose.yaml
@@ -13,11 +13,20 @@ services:
       - HOST=0.0.0.0
       - PORT=9080
       - LOG_LEVEL=INFO
-      - AMAZON_AD_PACKAGES=profiles,accounts-ads-accounts
-      - AMAZON_ADS_TOKEN_PERSIST=true
+      # Note: This is overridden by .env if AMAZON_AD_API_PACKAGES is set there
+      - AMAZON_AD_API_PACKAGES=profiles,accounts-ads-accounts,exports-snapshots
+      # Token persistence (disabled by default for security)
+      # Set to 'true' to cache refresh tokens across restarts (see docs for security implications)
+      - AMAZON_ADS_TOKEN_PERSIST=false
       - AMAZON_ADS_CACHE_DIR=/app/.cache/amazon-ads-mcp
-      # Authentication (configure as needed for your environment)
-      # - AUTH_METHOD=openbridge
+      # Authentication method - REQUIRED for header-based auth!
+      # Set to 'openbridge' when passing credentials via Authorization header from client
+      - AMAZON_ADS_AUTH_METHOD=openbridge
+      # REQUIRED: Enable refresh token middleware to process Authorization headers
+      - REFRESH_TOKEN_ENABLED=true
+      - AUTH_ENABLED=true
+      # Disable JWT validation (OpenBridge handles authentication)
+      - JWT_VALIDATION_ENABLED=false
 
     ports:
       - "9080:9080"
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ version = "0.1.15"
 description = "Amazon Ads API MCP Server - Implementation for Amazon Advertising API"
 readme = "README.md"
 requires-python = ">=3.10,<4.0"
-dependencies = [ "fastmcp>=2.11.3", "python-dotenv>=1.0.0", "pydantic>=2.5.0", "pydantic-settings>=2.0.0", "httpx>=0.27.0", "pyjwt>=2.8.0", "cryptography>=41.0.0", "openai>=1.0.0", "PyYAML>=6.0.0",]
+dependencies = [ "fastmcp>=2.14.1", "python-dotenv>=1.2.1", "pydantic>=2.12.5", "pydantic-settings>=2.12.0", "httpx>=0.28.1", "pyjwt>=2.10.1", "cryptography>=41.0.0", "openai>=1.109.1", "PyYAML>=6.0.2",]
 [[project.authors]]
 name = "Amazon Ads API MCP SDK"
 
@@ -13,7 +13,7 @@ requires = [ "poetry-core",]
 build-backend = "poetry.core.masonry.api"
 
 [dependency-groups]
-dev = [ "black>=25.1.0", "isort>=6.0.1", "mypy>=1.18.1", "pytest>=8.4.2", "pytest-asyncio>=1.2.0", "ruff>=0.13.0",]
+dev = [ "black>=25.12.0", "isort>=7.0.0", "mypy>=1.19.1", "pytest>=9.0.2", "pytest-asyncio>=1.3.0", "ruff>=0.14.10",]
 
 [project.license]
 text = "MIT"
@@ -78,15 +78,15 @@ asyncio_mode = "auto"
 
 [tool.poetry.dependencies]
 python = ">=3.10,<4.0"
-fastmcp = "^2.11.3"
-python-dotenv = "^1.0.0"
-pydantic = "^2.5.0"
-pydantic-settings = "^2.0.0"
-httpx = ">=0.27.0"
-pyjwt = "^2.8.0"
+fastmcp = "^2.14.1"
+python-dotenv = "^1.2.1"
+pydantic = "^2.12.5"
+pydantic-settings = "^2.12.0"
+httpx = ">=0.28.1"
+pyjwt = "^2.10.1"
 cryptography = "^41.0.0"
-openai = "^1.0.0"
-PyYAML = "^6.0.0"
+openai = "^1.109.1"
+PyYAML = "^6.0.2"
 
 [tool.poetry.scripts]
 amazon-ads-mcp = "amazon_ads_mcp.server.mcp_server:main"
@@ -103,11 +103,11 @@ omit = [ "*/tests/*", "*/debug/*",]
 exclude_lines = [ "pragma: no cover", "def __repr__", "if self.debug:", "if settings.DEBUG", "raise AssertionError", "raise NotImplementedError", "if 0:", "if __name__ == .__main__.:", "class .*\\bProtocol\\):", "@(abc\\.)?abstractmethod",]
 
 [tool.poetry.group.dev.dependencies]
-pytest = "^8.4.2"
-pytest-asyncio = "^1.2.0"
-black = "^25.1.0"
-isort = "^6.0.1"
-ruff = "^0.13.0"
-mypy = "^1.18.1"
+pytest = "^9.0.2"
+pytest-asyncio = "^1.3.0"
+black = "^25.12.0"
+isort = "^7.0.0"
+ruff = "^0.14.10"
+mypy = "^1.19.1"
 types-pyjwt = "^1.7.1"
 types-python-dotenv = "^1.0.0"
diff --git a/requirements.txt b/requirements.txt
@@ -1,13 +1,13 @@
 # Core dependencies
-fastmcp>=2.12.2
+fastmcp>=2.14.1
 httpx[http2]>=0.28.1
-pydantic>=2.11.9
-pydantic-settings>=2.10.1
-python-dotenv>=1.1.1
+pydantic>=2.12.5
+pydantic-settings>=2.12.0
+python-dotenv>=1.2.1
 PyJWT>=2.10.1
 PyYAML>=6.0.2
 jsonschema>=4.25.1
-openai>=1.108.0
+openai>=1.109.1
 
 # Development dependencies (optional)
 # Install with: pip install -r requirements-dev.txt
diff --git a/src/amazon_ads_mcp/auth/hooks.py b/src/amazon_ads_mcp/auth/hooks.py
@@ -152,7 +152,7 @@ async def after_response(
             try:
                 error_body = response.json()
                 error_detail = f" - Error: {error_body}"
-            except:
+            except Exception:
                 error_detail = f" - Response: {response.text[:200]}"
 
             logger.error(f"Received 401 Unauthorized - token may be expired or invalid{error_detail}")
diff --git a/src/amazon_ads_mcp/auth/manager.py b/src/amazon_ads_mcp/auth/manager.py
@@ -192,7 +192,7 @@ def _determine_auth_method(self) -> str:
         raise ValueError(
             "No authentication method configured. Please set one of:\n"
             "- For direct auth: AD_API_CLIENT_ID, AD_API_CLIENT_SECRET, AD_API_REFRESH_TOKEN\n"
-            "- For OpenBridge: OPENBRIDGE_REFRESH_TOKEN\n"
+            "- For OpenBridge: OPENBRIDGE_REFRESH_TOKEN (or OPENBRIDGE_API_KEY)\n"
             "- Or explicitly set AUTH_METHOD environment variable"
         )
 
diff --git a/src/amazon_ads_mcp/auth/providers/openbridge.py b/src/amazon_ads_mcp/auth/providers/openbridge.py
@@ -157,7 +157,7 @@ async def get_token(self) -> Token:
 
         if not self.refresh_token:
             raise ValueError(
-                "No refresh token available. Provide it via config or Authorization header."
+                "No OpenBridge token available. Set OPENBRIDGE_REFRESH_TOKEN (or OPENBRIDGE_API_KEY), or pass it via Authorization header."
             )
 
         return await self._refresh_jwt_token()
diff --git a/src/amazon_ads_mcp/auth/token_store.py b/src/amazon_ads_mcp/auth/token_store.py
@@ -372,6 +372,16 @@ def __init__(
         # Load existing tokens on startup
         self._load_from_disk()
 
+        # Warn about security implications of token persistence
+        logger.info(
+            f"Token persistence ENABLED. Refresh tokens will be stored at {self._storage_path}\n"
+            f"Security considerations:\n"
+            f"  - Tokens are encrypted at rest, but the encryption key is stored alongside\n"
+            f"  - Anyone with access to the volume/filesystem can potentially decrypt tokens\n"
+            f"  - For production use, set AMAZON_ADS_ENCRYPTION_KEY externally\n"
+            f"  - Consider in-memory-only storage (AMAZON_ADS_TOKEN_PERSIST=false) if possible"
+        )
+
     async def set(self, key: TokenKey, entry: TokenEntry) -> None:
         """Store token, persisting refresh tokens to disk."""
         await super().set(key, entry)
diff --git a/src/amazon_ads_mcp/config/settings.py b/src/amazon_ads_mcp/config/settings.py
@@ -7,7 +7,7 @@
 
 from typing import Literal, Optional
 
-from pydantic import Field, field_validator
+from pydantic import AliasChoices, Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from ..utils.region_config import RegionConfig
@@ -29,7 +29,7 @@ class Settings(BaseSettings):
     :type amazon_ads_client_secret: Optional[str]
     :param amazon_ads_refresh_token: Amazon Ads API Refresh Token for direct auth
     :type amazon_ads_refresh_token: Optional[str]
-    :param openbridge_refresh_token: OpenBridge refresh token (key:secret format)
+    :param openbridge_refresh_token: OpenBridge API key (aka refresh token)
     :type openbridge_refresh_token: Optional[str]
     :param openbridge_remote_identity_id: OpenBridge remote identity ID
     :type openbridge_remote_identity_id: Optional[str]
@@ -100,7 +100,9 @@ class Settings(BaseSettings):
 
     # Openbridge Configuration
     openbridge_refresh_token: Optional[str] = Field(
-        None, description="Openbridge Refresh Token (format: key:secret)"
+        None,
+        validation_alias=AliasChoices("OPENBRIDGE_REFRESH_TOKEN", "OPENBRIDGE_API_KEY"),
+        description="OpenBridge API key (aka refresh token)",
     )
     openbridge_remote_identity_id: Optional[str] = Field(
         None, description="Openbridge Remote Identity ID for Amazon Ads"
diff --git a/src/amazon_ads_mcp/middleware/authentication.py b/src/amazon_ads_mcp/middleware/authentication.py
@@ -521,54 +521,54 @@ async def on_request(self, context: MiddlewareContext, call_next):
             >>> # This method is called automatically by FastMCP
             >>> # when requests are processed through the middleware chain
         """
-        if not self.config.enabled or not self.config.refresh_token_enabled:
-            return await call_next(context)
-
         try:
             # Get headers from the context if available
             auth_header = ""
-            if context.fastmcp_context:
+            if context.fastmcp_context and context.fastmcp_context.request_context:
                 request = context.fastmcp_context.request_context.request
                 if request and hasattr(request, "headers"):
                     auth_header = request.headers.get("authorization", "")
 
-            if not auth_header:
-                return await call_next(context)
-
-            # Extract token more robustly - handle case variations and extra whitespace
-            parts = auth_header.split(" ", 1)
-            if len(parts) != 2 or parts[0].lower() != "bearer":
-                return await call_next(context)
-
-            token = parts[1].strip()  # Remove any leading/trailing whitespace
-
-            # Check if this matches the refresh token pattern
-            if self.config.refresh_token_pattern and self.config.refresh_token_pattern(
-                token
-            ):
-                self.logger.debug("Detected refresh token format, checking cache...")
-
-                # If auth_manager with OpenBridge provider is available, update its refresh token
-                if self.auth_manager and hasattr(self.auth_manager, "provider"):
-                    provider = self.auth_manager.provider
-                    if hasattr(provider, "set_refresh_token"):
-                        self.logger.debug(
-                            "Setting refresh token in OpenBridge provider"
-                        )
-                        provider.set_refresh_token(token)
-
-                jwt_token = await self._get_cached_or_convert_jwt(token)
-                if jwt_token:
-                    self.logger.debug("JWT token ready (cached or converted)")
-                    # Store the JWT in context-safe storage for the JWT middleware to use
-                    jwt_token_var.set(jwt_token)
-                else:
-                    self.logger.error("Failed to convert refresh token to JWT")
-            else:
-                self.logger.debug(
-                    "Token does not match refresh token pattern - skipping conversion"
-                )
+            if auth_header:
+                # Extract token more robustly - handle case variations and extra whitespace
+                parts = auth_header.split(" ", 1)
+                if len(parts) == 2 and parts[0].lower() == "bearer":
+                    token = parts[1].strip()  # Remove any leading/trailing whitespace
+
+                    # CRITICAL: Always set refresh token in provider if available (for OpenBridge)
+                    # This MUST happen even if config.enabled is False, so tools can use the token
+                    # The provider needs the refresh token to authenticate API calls
+                    if self.auth_manager and hasattr(self.auth_manager, "provider"):
+                        provider = self.auth_manager.provider
+                        if hasattr(provider, "set_refresh_token"):
+                            self.logger.debug(
+                                "Setting refresh token in OpenBridge provider from Authorization header"
+                            )
+                            provider.set_refresh_token(token)
+
+                    # JWT conversion processing (only if enabled)
+                    if self.config.enabled and self.config.refresh_token_enabled:
+                        # Check if this matches the refresh token pattern for JWT conversion
+                        if self.config.refresh_token_pattern and self.config.refresh_token_pattern(
+                            token
+                        ):
+                            self.logger.debug("Detected refresh token format, checking cache...")
+
+                            jwt_token = await self._get_cached_or_convert_jwt(token)
+                            if jwt_token:
+                                self.logger.debug("JWT token ready (cached or converted)")
+                                # Store the JWT in context-safe storage for the JWT middleware to use
+                                jwt_token_var.set(jwt_token)
+                            else:
+                                self.logger.error("Failed to convert refresh token to JWT")
+                        else:
+                            self.logger.debug(
+                                "Token does not match refresh token pattern - skipping JWT conversion"
+                            )
 
+        except ToolError:
+            # Let ToolError propagate - it's handled by FastMCP
+            raise
         except Exception as e:
             self.logger.error(f"RefreshTokenMiddleware error: {e}")
 
@@ -739,7 +739,7 @@ async def on_request(self, context: MiddlewareContext, call_next):
             else:
                 # Get token from headers via context
                 auth_header = ""
-                if context.fastmcp_context:
+                if context.fastmcp_context and context.fastmcp_context.request_context:
                     request = context.fastmcp_context.request_context.request
                     if request and hasattr(request, "headers"):
                         auth_header = request.headers.get("authorization", "")
@@ -1380,6 +1380,9 @@ def create_openbridge_config() -> AuthConfig:
     config.jwt_verify_iss = False  # Don't validate issuer for OpenBridge
     config.jwt_verify_aud = False  # Don't validate audience for OpenBridge
 
+    # Respect AUTH_ENABLED environment variable
+    config.load_from_env()
+
     return config
 
 
diff --git a/tests/integration/__init__.py b/tests/integration/__init__.py
diff --git a/tests/integration/test_auth_header_propagation.py b/tests/integration/test_auth_header_propagation.py
diff --git a/tests/unit/test_settings_openbridge_alias.py b/tests/unit/test_settings_openbridge_alias.py

Original file line number	Diff line number	Diff line change
`@@ -408,7 +408,7 @@ In this example, we show how to use the bearer token using the Openbridge API ke`
`408`	`408`	`"http://${HOSTNAME}:${PORT}/mcp/",`
`409`	`409`	`"--allow-http",`
`410`	`410`	`"--header",`
`411`		`- "Authorization:Bearer ${OPENBRIDGE_REFRESH_TOKEN}",`
	`411`	`+ "Authorization:Bearer ${OPENBRIDGE_API_KEY}",`
`412`	`412`	`"--header",`
`413`	`413`	`"Accept:application/json,text/event-stream",`
`414`	`414`	`"--debug"`
`@@ -423,7 +423,7 @@ In this example, we show how to use the bearer token using the Openbridge API ke`
`423`	`423`	`"MCP_SERVER_REQUEST_TIMEOUT": "60000",`
`424`	`424`	`"MCP_TOOL_TIMEOUT": "120000",`
`425`	`425`	`"MCP_REQUEST_WARNING_THRESHOLD": "10000",`
`426`		`- "OPENBRIDGE_REFRESH_TOKEN": "your_openbridge_token_here"`
	`426`	`+ "OPENBRIDGE_API_KEY": "your_openbridge_token_here"`
`427`	`427`	`}`
`428`	`428`	`}`
`429`	`429`	`}`
`@@ -468,7 +468,7 @@ The config would look something like this:`
`468`	`468`	`}`
`469`	`469`	```
`470`	`470`
`471`		-Here is another example, which can be used if you are using OAuth since the `OPENBRIDGE_REFRESH_TOKEN` is not needed:
	`471`	+Here is another example, which can be used if you are using OAuth since the `OPENBRIDGE_API_KEY` is not needed:
`472`	`472`
`473`	`473`	```json
`474`	`474`	`{`
Original file line number	Diff line number	Diff line change
`@@ -192,7 +192,7 @@ def _determine_auth_method(self) -> str:`
`192`	`192`	`raise ValueError(`
`193`	`193`	`"No authentication method configured. Please set one of:\n"`
`194`	`194`	`"- For direct auth: AD_API_CLIENT_ID, AD_API_CLIENT_SECRET, AD_API_REFRESH_TOKEN\n"`
`195`		`- "- For OpenBridge: OPENBRIDGE_REFRESH_TOKEN\n"`
	`195`	`+ "- For OpenBridge: OPENBRIDGE_REFRESH_TOKEN (or OPENBRIDGE_API_KEY)\n"`
`196`	`196`	`"- Or explicitly set AUTH_METHOD environment variable"`
`197`	`197`	`)`
`198`	`198`
Original file line number	Diff line number	Diff line change
`@@ -157,7 +157,7 @@ async def get_token(self) -> Token:`
`157`	`157`
`158`	`158`	`if not self.refresh_token:`
`159`	`159`	`raise ValueError(`
`160`		`- "No refresh token available. Provide it via config or Authorization header."`
	`160`	`+ "No OpenBridge token available. Set OPENBRIDGE_REFRESH_TOKEN (or OPENBRIDGE_API_KEY), or pass it via Authorization header."`
`161`	`161`	`)`
`162`	`162`
`163`	`163`	`return await self._refresh_jwt_token()`